Skip to content

Overview

In this section we provide several example scripts of how to interface with the data generated by HBT-HERONS. We also use the examples we provide to illustrate some of the less-trivial concepts within HBT-HERONS.

We have written the code so that you can apply it to any HBT-HERONS catalogue, including your own. However, if you do not have any such catalogue available yet, we provide an example that you can download following the steps below.

HBTReader

The HBT-HERONS repository comes with a Python file (/toolbox/HBTReader.py) that contains functions to interface with the catalogues. To import, add the directory containing HBTReader.py to your path:

import sys
sys.path.append(f"{HBT_HERONS_PATH}/toolbox")
from HBTReader import HBTReader
Opening the catalogue for a given simulation can be done using: 

catalogue = HBTReader(f"{CATALOGUE_PATH}", sorted_catalogues=False)
Opening the catalogue will automatically read which simulation outputs have a saved HBT-HERONS catalogue. The boolean parameter sorted_catalogues indicates whether the catalogues have been post-processed with toolbox/catalogue_cleanup/SortCatalogues.py. We strongly recommend executing that script, as it will speed up operations.

The code examples we provide in this section always use the class HBTReader to load data. However, it can be preferrable to read the HDF5 files directly once you become more familiar with the catalogue formatting and the way in which different datasets can be used. The reason why it is recommended to use HDF5 files directly for very big simulations is that a parallel script can be implemented, whereas no such functionality is available in HBTReader.

Methods

The methods implemented in HBTReader are designed to be used for the following common tasks:

  • LoadSubhaloProperties: load one or more properties of all or specific subhaloes at a specific output number.
  • LoadSubhaloEvolution: load the evolution of one or more properties of specific subhaloes. It returns the evolution from the time when they were first resolved until the last available HBT-HERONS output, even if the subhaloes have become an orphan.
  • GetAllProgenitors: identify the direct and indirect secondary progenitors of a subhalo. The direct and indirect classification reflects whether the subhalo progenitor merged directly with the specified subhalo or not.
  • GetSinkProgenitors: identify the direct secondary progenitors of a subhalo that became orphans by sinking.
  • GetDisruptedProgenitors: identify the direct secondary progenitors of a subhalo that became orphans by disruption.

Example catalogue

We have generated an example HBT-HERONS catalogue from a dark-matter-only simulation of a \((25\,\mathrm{Mpc}^{3})\) volume with a particle mass of \(m_{\rm p} = 10^{9}\,\mathrm{M}_{\odot}\). Outputs are logaritmically-spaced in expansion factor, and 64 of them are saved from redshift \(z = 10\) to \(z = 0\).

To download, run the following:

wget https://hbt-herons.strw.leidenuniv.nl/data/ExampleCatalogues.tar.gz
tar -xzvf ExampleCatalogues.tar.gz

Once unzipped, there will be two directories:

  • RawCatalogues: This folder contains the actual outputs of runnning HBT-HERONS, except for particle information (SubhaloParticles) and restart files (SrcSnap). Each simulation output has a dedicated folder named {SnapNumber:03d}, which contains four files named SubSnap_{SnapNumber:03d}.{MPI_rank}.hdf5. The number of files reflects the fact that 4 MPI ranks were used to run this HBT-HERONS example.
  • SortedCatalogues: This folder contains the recommended way of interfacing with HBT-HERONS catalogues, but it requires a post-processing step that involves running toolbox/catalogue_cleanup/SortCatalogues.py. This script merges all files generated by MPI ranks, so that there is only a single file per simulation output (OrderedSubSnap_{SnapNumber:03d}.hdf5). It additionally sorts the subhalo entries according to their TrackId, which is benefitial because there is a direct correspondence between TrackId and its positional index within the dataset.

The code we provide can be used to use to load either format, so we recommend playing around with both to get a feeling about what the advantages of using one versus the other are.