Merger Tree Importer

Class providing functions for importing merger trees. When merger trees are to be read from file, a number of different file formats are supported. This “importer” class is used to read these files and place the contents into internal data structures that Galacticus can then manipulate.

Default implementation: mergerTreeImporterGalacticus

Methods

open → void

Opens the merger tree file specified by fileName for reading, initializing any internal state required by the importer before data can be loaded.

  • type(varying_string), intent(in ) :: fileName

treesHaveSubhalos → integer

Returns a Boolean integer specifying whether or not the trees have subhalos.

massesIncludeSubhalos → logical

Returns a Boolean specifying whether halo masses include the contribution from their subhalos.

angularMomentaIncludeSubhalos → logical

Returns a Boolean specifying whether halo angular momenta (or spins) include the contribution from their subhalos.

treesAreSelfContained → integer

Returns a Boolean integer specifying whether trees are self-contained.

velocitiesIncludeHubbleFlow → integer

Returns a Boolean integer specifying whether velocities include the Hubble flow.

positionsArePeriodic → integer

Returns a Boolean integer specifying whether positions are periodic.

canReadSubsets → logical

Returns true if arbitrary subsets of halos from a forest can be read.

cubeLength → double precision

Returns the comoving side length (in Mpc) of the periodic simulation cube at the given time; used to apply periodic boundary conditions when reading positions.

  • double precision, intent(in ) :: time

  • integer , intent( out), optional :: status

treeCount → integer(kind=c_size_t)

Returns a count of the number of trees available.

treeIndex → integer(kind=kind_int8)

Returns the unique integer identifier of the \(i^\mathrm{th}\) tree in the file, used to label the tree in output datasets.

  • integer, intent(in ) :: i

nodeCount → integer(kind=c_size_t)

Returns the number of nodes in the \(i^\mathrm{th}\) tree.

  • integer, intent(in ) :: i

treeWeight → double precision

Returns the weight to assign to the \(i^\mathrm{th}\) tree.

  • integer, intent(in ) :: i

positionsAvailable → logical

Return true if positions and/or velocities are available.

  • logical, intent(in ) :: positions, velocities

scaleRadiiAvailable → logical

Return true if halo scale radii are available in this merger tree file, so the importer can populate scaleRadius fields when loading nodes.

particleCountAvailable → logical

Return true if particle counts per halo are available in this merger tree file, so the importer can populate particleCount fields when loading nodes.

velocityMaximumAvailable → logical

Return true if rotation curve velocity maxima are available.

velocityDispersionAvailable → logical

Return true if halo velocity dispersions are available.

angularMomentaAvailable → logical

Return true if angular momenta (magnitudes) are available.

angularMomenta3DAvailable → logical

Return true if angular momenta (vectors) are available.

spinAvailable → logical

Return true if spin (magnitudes) are available.

spin3DAvailable → logical

Return true if 3D spin vectors are available in this merger tree file, so the importer can populate spin3D fields when loading nodes.

import → void

Imports all nodes for the \(i^\mathrm{th}\) tree from the open file into the nodes array, reading only those fields requested via the optional arguments.

  • integer , intent(in ) :: i

  • class (nodeDataMinimal), intent( out), allocatable, dimension(:) :: nodes

  • integer(c_size_t ), intent(in ), optional , dimension(:) :: nodeSubset

  • logical , intent(in ), optional :: requireScaleRadii, requireAngularMomenta, requireAngularMomenta3D, requireSpin, requireSpin3D, requirePositions, structureOnly

  • type (varying_string ), intent(in ), optional , dimension(:) :: requireNamedReals, requireNamedIntegers

subhaloTrace → void

Supplies epochs, positions, and velocities for traced subhalos.

  • class (nodeData), intent(in ) :: node

  • double precision , intent( out), dimension(: ) :: time

  • double precision , intent( out), dimension(:,:) :: position, velocity

subhaloTraceCount → integer(kind=c_size_t)

Returns the number of snapshot epochs recorded in the subhalo trace for the given node, i.e.the length of the time, position, and velocity arrays to be allocated before calling subhaloTrace.

  • class(nodeData), intent(in ) :: node

mergerTreeImporterGalacticus

A merger tree importer class which imports trees from an HDF5 file. HDF5 file should follow the general purpose format described here. To generate HDF5 files in this format from merger tree data produced by a variety of tree builders (e.g.Rockstar/ConsistentTrees), the astrosylva tool (GitHub; PyPI; documentation) can be used.

(Default implementation)

Parameters

  • [fatalMismatches] (boolean; default .true.) — Specifies whether mismatches in cosmological parameter values between Galacticus and the merger tree file should be considered fatal.

  • [reweightTrees] (boolean; default .false.) — Specifies whether merger tree weights should be recomputed from the halo mass function.

  • [validateData] (boolean; default .false.) — If true perform some validation of imported data to identify possible problems.

mergerTreeImporterSussing

Importer for merger tree files in the “Sussing Merger Trees” format (Srisawat et al., 2013), reading halo properties from N-body simulation snapshots and constructing halo merger histories. Supports spatial subvolume splitting via [subvolumeCount] and [subvolumeIndex], with cosmological parameter mismatch handling controlled by [fatalMismatches].

Methods

  • tabulate — Tabulate the virial density contrast as a function of mass and time.

  • restoreTable — Restore a tabulated solution from file.

  • storeTable — Store a tabulated solution to file.

Parameters

  • [fatalMismatches] (boolean; default .true.) — Specifies whether mismatches in cosmological parameter values between Galacticus and “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree files should be considered fatal.

  • [fatalNonTreeNode] (boolean; default .true.) — Specifies whether nodes in snapshot files but not in the merger tree file should be considered fatal when importing from the “Sussing Merger Trees” format (Srisawat et al., 2013).

  • [subvolumeCount] (integer; default 1) — Specifies the number of subvolumes along each axis into which a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree files should be split for processing through Galacticus.

  • [subvolumeBuffer] (real; default 0.0d0) — Specifies the buffer region (in units of Mpc\(/h\) to follow the format convention) around subvolumes of a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree file which should be read in to ensure that no halos are missed from trees.

  • [subvolumeIndex] (integer; default [0,0,0]) — Specifies the index (in each dimension) of the subvolume of a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree file to process. Indices range from 0 to [subvolumeCount]\(-1\).

  • [badValue] (real; default -0.5d0) — Use for bad value detection in “Sussing” merger trees. Values for scale radius and halo spin which exceed this threshold are assumed to be bad.

  • [badValueTest] (string; one of lessThan, greaterThan; default lessThan) — Use for bad value detection in “Sussing” merger trees. Values which exceed the threshold in ths specified direction are assumed to be bad.

  • [treeSampleRate] (real; default 1.0d0) — Specify the probability that any given tree should processed (to permit subsampling).

  • [massOptions] (string; one of default, FoF, 200Mean, 200Crit, topHat; default default) — Mass option for Sussing merger trees.

mergerTreeImporterSussingASCII

A merger tree importer class for “Sussing Merger Trees” ASCII format merger tree files (Srisawat et al., 2013), along with AHF format halo catalogs. A descriptor file must be specified via the [mergerTreeReadFileName] parameter. This descriptor file should have the following format:

simulation.txt
MergerTree+AHF.txt
snapidzred.txt
AHF/62.5_dm_000.z50.000.AHF_halos
AHF/62.5_dm_001.z30.000.AHF_halos
AHF/62.5_dm_002.z19.916.AHF_halos
.
.
.
AHF/62.5_dm_061.z0.000.AHF_halos

in which each line specifies a file to be read (by default path names are relative to the location of the descriptor file—fully-qualified path names can also be given).

The first line identifies a file which specifies properties of the simulation. This file should look like:

WMAP7 cosmology:
----------------
Omega0          =       0.272
OmegaLambda0    =       0.728
h               =       0.704

simulation:
-----------
B               =       62.5 Mpc/h
N               =       270^3 particles

Currently only the cosmological parameter and box length are read from this file.

The second line identifies the merger tree file which must be in the format specified by Srisawat et al. (2013).

The third line of the descriptor file specifies a snapshot file which should have the following format:

#    snapnum       a             z           t(t0)      t(year)
           0    0.0196080      49.9996   0.00354284  4.87485e+07
           1    0.0322580      30.0001   0.00747572  1.02864e+08
           2    0.0478110      19.9157    0.0134888  1.85602e+08
           3    0.0519650      18.2437    0.0152842  2.10306e+08
           4    0.0564190      16.7245    0.0172905  2.37912e+08
           5    0.0611880      15.3431    0.0195280  2.68700e+08
           6    0.0662870      14.0859    0.0220186  3.02969e+08
             .
             .
             .

This file must contain one line for each snapshot of the simulation, giving the snapshot number, expansion factor, redshift, fractional time (relative to present day), and age of the universe (in years).

Subsequent lines identify the AHF halo files for each snapshot (files can be listed in any order).

Merger tree files of this type can be split into subvolumes before processing. This is useful if the file is too large to read into memory in one go. The number of subvolumes to use (in each of the three dimensions of the simulation cube) is specified by the [subvolumeCount] parameter. The specific subvolume to process is specified by the [subvolumeIndex] parameter, which should give the index (running from \(0\) to [subvolumeCount]\(-1\)) in each dimension (whitespace separated). To ensure that no halos are missed from trees near the edge of the subvolume, a buffer region around the subvolume is also read. The width of this buffer (in units of Mpc\(/h\) to follow the format convention) is specified via the [subvolumeBuffer] parameter.

Methods

  • initialize — Initialize the object after construction.

Parameters

  • [convertToBinary] (boolean; default .true.) — Specifies whether halo and tree files in the “Sussing” format should be converted to binary the first time they are read and stored to file. This allows rapid re-reading in future.

  • [binaryFormatOld] (boolean; default .false.) — Specifies whether the old binary format is to be used (for reading only).

  • [forestFile] (string; default none) — Name of file containing data on number of halos in each forest.

  • [forestFirst] (integer; default 1) — The 1-based index of the first forest in the file to include when reading a subset of forests; forests before this index are skipped.

  • [forestLast] (integer; default -1) — The 1-based index of the last forest in the file to include when reading a subset of forests; a value of \(-1\) includes all forests through the end of the file.

  • [forestReverseSnapshotOrder] (boolean; default .false.) — If true, the order of forest snapshots will be reversed after being read. This may be necessary to cause them to match the order of snapshot files.

  • [fatalMismatches] (boolean; default .true.) — Specifies whether mismatches in cosmological parameter values between Galacticus and “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree files should be considered fatal. (inherited from mergerTreeImporterSussing)

  • [fatalNonTreeNode] (boolean; default .true.) — Specifies whether nodes in snapshot files but not in the merger tree file should be considered fatal when importing from the “Sussing Merger Trees” format (Srisawat et al., 2013). (inherited from mergerTreeImporterSussing)

  • [subvolumeCount] (integer; default 1) — Specifies the number of subvolumes along each axis into which a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree files should be split for processing through Galacticus. (inherited from mergerTreeImporterSussing)

  • [subvolumeBuffer] (real; default 0.0d0) — Specifies the buffer region (in units of Mpc\(/h\) to follow the format convention) around subvolumes of a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree file which should be read in to ensure that no halos are missed from trees. (inherited from mergerTreeImporterSussing)

  • [subvolumeIndex] (integer; default [0,0,0]) — Specifies the index (in each dimension) of the subvolume of a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree file to process. Indices range from 0 to [subvolumeCount]\(-1\). (inherited from mergerTreeImporterSussing)

  • [badValue] (real; default -0.5d0) — Use for bad value detection in “Sussing” merger trees. Values for scale radius and halo spin which exceed this threshold are assumed to be bad. (inherited from mergerTreeImporterSussing)

  • [badValueTest] (string; one of lessThan, greaterThan; default lessThan) — Use for bad value detection in “Sussing” merger trees. Values which exceed the threshold in ths specified direction are assumed to be bad. (inherited from mergerTreeImporterSussing)

  • [treeSampleRate] (real; default 1.0d0) — Specify the probability that any given tree should processed (to permit subsampling). (inherited from mergerTreeImporterSussing)

  • [massOptions] (string; one of default, FoF, 200Mean, 200Crit, topHat; default default) — Mass option for Sussing merger trees. (inherited from mergerTreeImporterSussing)

mergerTreeImporterSussingHDF5

Importer for “Sussing Merger Trees” HDF5 format merger tree files (Srisawat et al., 2013).

Parameters

  • [fatalMismatches] (boolean; default .true.) — Specifies whether mismatches in cosmological parameter values between Galacticus and “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree files should be considered fatal. (inherited from mergerTreeImporterSussing)

  • [fatalNonTreeNode] (boolean; default .true.) — Specifies whether nodes in snapshot files but not in the merger tree file should be considered fatal when importing from the “Sussing Merger Trees” format (Srisawat et al., 2013). (inherited from mergerTreeImporterSussing)

  • [subvolumeCount] (integer; default 1) — Specifies the number of subvolumes along each axis into which a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree files should be split for processing through Galacticus. (inherited from mergerTreeImporterSussing)

  • [subvolumeBuffer] (real; default 0.0d0) — Specifies the buffer region (in units of Mpc\(/h\) to follow the format convention) around subvolumes of a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree file which should be read in to ensure that no halos are missed from trees. (inherited from mergerTreeImporterSussing)

  • [subvolumeIndex] (integer; default [0,0,0]) — Specifies the index (in each dimension) of the subvolume of a “Sussing Merger Trees” format (Srisawat et al., 2013) merger tree file to process. Indices range from 0 to [subvolumeCount]\(-1\). (inherited from mergerTreeImporterSussing)

  • [badValue] (real; default -0.5d0) — Use for bad value detection in “Sussing” merger trees. Values for scale radius and halo spin which exceed this threshold are assumed to be bad. (inherited from mergerTreeImporterSussing)

  • [badValueTest] (string; one of lessThan, greaterThan; default lessThan) — Use for bad value detection in “Sussing” merger trees. Values which exceed the threshold in ths specified direction are assumed to be bad. (inherited from mergerTreeImporterSussing)

  • [treeSampleRate] (real; default 1.0d0) — Specify the probability that any given tree should processed (to permit subsampling). (inherited from mergerTreeImporterSussing)

  • [massOptions] (string; one of default, FoF, 200Mean, 200Crit, topHat; default default) — Mass option for Sussing merger trees. (inherited from mergerTreeImporterSussing)