.. _physics-mergerTreeImporter: 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 :math:`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 :math:`i^\mathrm{th}` tree. * ``integer, intent(in ) :: i`` ``treeWeight`` → ``double precision`` Returns the weight to assign to the :math:`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 :math:`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`` .. _physics-mergerTreeImporterGalacticus: ``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. .. _physics-mergerTreeImporterSussing: ``mergerTreeImporterSussing`` ----------------------------- Importer for merger tree files in the "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_2013`. * ``[subvolumeCount]`` (integer; default ``1``) — Specifies the number of subvolumes *along each axis* into which a "Sussing Merger Trees" format :cite:p:`srisawat_sussing_2013` merger tree files should be split for processing through Galacticus. * ``[subvolumeBuffer]`` (real; default ``0.0d0``) — Specifies the buffer region (in units of Mpc\ :math:`/h` to follow the format convention) around subvolumes of a "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_2013` merger tree file to process. Indices range from 0 to ``[subvolumeCount]``\ :math:`-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. .. _physics-mergerTreeImporterSussingASCII: ``mergerTreeImporterSussingASCII`` ---------------------------------- A merger tree importer class for "Sussing Merger Trees" ASCII format merger tree files :cite:p:`srisawat_sussing_2013`, along with :term:`AHF` format halo catalogs. A descriptor file must be specified via the ``[mergerTreeReadFileName]`` parameter. This descriptor file should have the following format: .. code-block:: none 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: .. code-block:: none 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 :cite:t:`srisawat_sussing_2013`. The third line of the descriptor file specifies a snapshot file which should have the following format: .. code-block:: none # 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 :term:`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 :math:`0` to ``[subvolumeCount]``\ :math:`-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\ :math:`/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 :math:`-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 :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_2013`. *(inherited from* ``mergerTreeImporterSussing``\ *)* * ``[subvolumeCount]`` (integer; default ``1``) — Specifies the number of subvolumes *along each axis* into which a "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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\ :math:`/h` to follow the format convention) around subvolumes of a "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_2013` merger tree file to process. Indices range from 0 to ``[subvolumeCount]``\ :math:`-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``\ *)* .. _physics-mergerTreeImporterSussingHDF5: ``mergerTreeImporterSussingHDF5`` --------------------------------- Importer for "Sussing Merger Trees" HDF5 format merger tree files :cite:p:`srisawat_sussing_2013`. **Parameters** * ``[fatalMismatches]`` (boolean; default ``.true.``) — Specifies whether mismatches in cosmological parameter values between Galacticus and "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_2013`. *(inherited from* ``mergerTreeImporterSussing``\ *)* * ``[subvolumeCount]`` (integer; default ``1``) — Specifies the number of subvolumes *along each axis* into which a "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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\ :math:`/h` to follow the format convention) around subvolumes of a "Sussing Merger Trees" format :cite:p:`srisawat_sussing_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 :cite:p:`srisawat_sussing_2013` merger tree file to process. Indices range from 0 to ``[subvolumeCount]``\ :math:`-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``\ *)*