.. _physics-mergerTreeConstructor:
Merger Tree Constructors
========================
Class providing merger tree constructors---any process by which a representation of a dark matter halo merger tree is created and made available within Galacticus for subsequent galaxy formation calculations. Implementations include stochastic Monte Carlo tree building algorithms (which generate trees on-the-fly from excursion set merger rates), reading pre-computed trees from N-body simulations stored in HDF5 or other formats, and analytic approximations. The ``construct`` method returns a :galacticus-class:`mergerTree` pointer for the given tree index, and signals completion once all trees in the set have been constructed.
**Default implementation:** ``mergerTreeConstructorBuild``
Methods
-------
``construct`` → ``type(mergerTree), pointer``
Construct the merger tree corresponding to the given ``treeNumber``.
* ``integer(c_size_t), intent(in ) :: treeNumber``
* ``logical , intent( out) :: finished``
``randomSequenceNonDeterministicWarn`` → ``void``
Display a warning if the merger tree random number generator sequence is non-deterministic.
* ``type(mergerTree), intent(inout) :: tree``
.. _physics-mergerTreeConstructorBuild:
``mergerTreeConstructorBuild``
------------------------------
A merger tree constructor class which builds merger trees. This class first creates a distribution of tree root halo masses and then builds a merger tree from each root halo.
**(Default implementation)**
**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**
* ``[redshiftBase]`` (real; default ``0.0d0``) — The redshift at which to plant the base node when building merger trees.
* ``[timeSnapTolerance]`` (real; default ``1.0d-6``) — The fractional tolerance within which the tree base time will be snapped to a nearby output time.
* ``[treeBeginAt]`` (integer; default ``0``) — The index (in order of increasing base halo mass) of the tree at which to begin when building merger trees. A value of "0" means to begin with tree number 1 (if processing trees in ascending order), or equal to the number of trees (otherwise).
* ``[processDescending]`` (boolean; default ``.true.``) — If true, causes merger trees to be processed in order of decreasing mass.
.. _physics-mergerTreeConstructorFilter:
``mergerTreeConstructorFilter``
-------------------------------
A merger tree constructor class filters trees from another constructor. Trees which do not pass the filter are dropped. Those that do pass the filter are returned.
.. _physics-mergerTreeConstructorFullySpecified:
``mergerTreeConstructorFullySpecified``
---------------------------------------
A merger tree constructor class which constructs a merger tree given a full specification in XML. This class will construct a merger tree, and set properties of components in each node, using a description read from an XML document. The document is specified via the ``[fileName]`` input parameter.
The tree specification document looks as follows:
.. code-block:: none
21-1-11.01.0e127.9365079e90.11.0e101.0e101.0e91.0e91-12-113.81.1e127.8125e91.236.313.59
The document consists of a set of ``node`` elements, each of which defines a single node in the merger tree. Each ``node`` element must specify the ``index`` of the node, along with the index of the node's ``parent``, ``firstChild``, and ``sibling``.
Each ``node`` element may contain elements which specify the properties of a component in the node. For example, a ``basic`` element will specify properties of the "basic" component. If multiple elements for a given component type are present, then multiple instances of that component will be created in the node.
Within a component definition element scalar properties are set using an element with the same name as that property (e.g. ``mass`` in the ``basic`` components in the above example). Rank-1 properties are set using a list of elements with the same name as the property (e.g. ``position`` in the ``position`` component in the above example).
For composite properties (e.g. abundances), the specification element should contain sub-elements that specify each property of the composite. Currently only the ``abundances`` object supports specification in this way, as detailed below:
``abundances``
(See ``abundancesGas`` in the above example.) The total metal content is specified via a ``metals`` element. If other elements are being tracked, their content is specified via an element with the short-name of the element (e.g. ``Fe`` for iron).
The parameter ``[countRealizations]`` (defaulting to 1) controls how many merger tree realizations are simulated for each input tree.
**Parameters**
* ``[fileName]`` (string) — The name of the file containing the merger tree specification.
* ``[countRealizations]`` (integer; default ``1_c_size_t``) — The number of realizations of each tree to generate.
.. _physics-mergerTreeConstructorRead:
``mergerTreeConstructorRead``
-----------------------------
A merger tree constructor class from data imported from a file and processed into a form suitable for Galacticus to evolve. Merger trees are inherently complex structures, particularly when the possibility of subhalos are considered. Galacticus is currently designed to work with single descendant merger trees, i.e. ones in which the tree structure is entirely defined by specifying which :term:`node` a given :term:`node` is physically associated with at a later time. Additionally, Galacticus expects the merger tree file to contain information on the host :term:`node`, i.e. the node within which a given node is physically located. In the following, these two properties are labeled ``descendantNode`` and ``hostNode``. Galacticus assumes that nodes for which ``descendantNode``\ :math:`=`\ ``hostNode`` are isolated halos (i.e. they are their own hosts) while other nodes are subhalos (i.e. they are hosted by some other node). An example of a simple tree structure is shown in Fig. :numref:`{number} `. The particular structure would be represented by the following list of nodes and node properties (a :math:`-1` indicates that no descendant node exists):
.. list-table::
:header-rows: 1
* - ``node``
- ``descendantNode``
- ``hostNode``
* - 1
- -1
- 1
* - 2
- 1
- 2
* - 3
- 2
- 3
* - 4
- 1
- 4
* - 5
- 4
- 5
* - 6
- -1
- 1
* - 7
- 6
- 4
* - 8
- 7
- 8
.. figure:: /_figures/MergerTreeSimple.png
:name: fig-MergerTreeSimple
An example of a simple merger tree structure. Colored circles represent nodes in the merger tree. Each node has a unique index indicated by the number inside each circle. Black arrows link each node to its descendant node (as specified by the ``descendantNode`` property). Where a node is not its own host node it is placed inside its host node.
The following should be noted when constructing merger tree files:
* Note that Galacticus does not require that nodes be placed on a uniform grid of times/redshifts, nor that mass be conserved along a branch of the tree. After processing the tree in this way, Galacticus builds additional links which identify the child node of each halo and any sibling nodes. These are not required to specify the tree structure but are computationally convenient.
* It is acceptable for a node to begin its existence as a subhalo (i.e. to have never had an isolated node progenitor). Such nodes will be created as satellites in the merger tree and, providing the selected node components (see :ref:`here `) initialize their properties appropriately, will be evolved correctly.
* It is acceptable for an isolated node to have progenitors, none of which are a primary progenitor. This can happen if all progenitors descend into subhalos in the isolated node. In such cases, Galacticus will create a clone of the isolated node at a very slightly earlier time to act as the primary progenitor. This is necessary to allow the tree to be processed correctly, but does not affect the evolution of the tree.
* Normally, cases where a node's host node cannot be found in the :term:`forest` will cause Galacticus to exit with an error. Setting ``[missingHostsAreFatal]``\ :math:`=`\ ``false`` will instead circumvent this issue by making any such nodes self-hosting (i.e. they become isolated nodes rather than subhalos). Note that this behavior is not a physically correct way to treat such cases---it is intended only to allow trees to be processed in cases where the full :term:`forest` is not available.
* It is acceptable for nodes to jump between branches in a tree, or even to jump between branches in different trees. In the latter case, all trees linked by jumping nodes (a so-called ":term:`forest`" of connected trees) must be stored as a single forest (with multiple root-nodes) in the merger tree file. Galacticus will process this :term:`forest` of trees simultaneously, allowing to nodes to move between their branches.
* It is acceptable for a subhalo to later become an isolated halo (as can happen due to three-body interactions; see :cite:author:`sales_cosmic_2007` :cite:year:`sales_cosmic_2007`). If ``[allowSubhaloPromotions]``\ :math:`=`\ ``true`` then such cases will be handled correctly (i.e. the subhalo will be promoted back to being an isolated halo). If the parameter ``[alwaysPromoteMostMassive]``\ :math:`=`\ ``true`` then the most massive progenitor is treated as the primary progenitor, even if that progenitor is a subhalo. Alternatively, if ``[alwaysPromoteMostMassive]``\ :math:`=`\ ``false`` then a most massive progenitor that is a subhalo is only treated as the primary progenitor *if* no isolated progenitors exist (otherwise, the most massive of the isolated progenitors is treated as the primary progenitor). If ``[allowSubhaloPromotions]``\ :math:`=`\ ``false`` then subhalos are not permitted to become isolated halos. In this case, the following logic will be applied to remove all such cases from the tree:
* For any branch in a tree which at some point is a subhalo:
* Beginning from the earliest node in the branch that is a subhalo, repeatedly step to the next descendant node;
* If that descendant is *not* a subhalo then:
* If there is not currently any non-subhalo node which has the present node as its descendant then current node is only descendant of a subhalo. Therefore, try to make this node a subhalo, and propose the descendant of the host node of the previous node visited in the branch as the new host:
* If the proposed host exists:
* If the mass of the current node is less than that of the proposed host:
* If the proposed hosts exists before the current node, repeatedly step to its descendants until one is found which exists at or after the time of the current node. This is the new proposed host.
* If the proposed host is a subhalo, make it an isolated node.
* The current node is made a subhalo within the proposed host.
* Otherwise:
* The current node remains an isolated node, while the proposed host is instead made a subhalo within the current node.
* Otherwise:
* The proposed host does not exists, which implies the end of a branch has been reached. Therefore, flag the current node as being a subhalo with a host identical to that of the node from which it descended.
**Requirements for Galacticus Input Parameters:** The following requirements must be met for the input parameters to Galacticus when using merger trees read from file:
* The cosmological parameters (:math:`\Omega_\mathrm{M}`, :math:`\Omega_\Lambda`, :math:`\Omega_\mathrm{b}`, :math:`H_0`, :math:`\sigma_8`), if defined in the file, must be set identically in the Galacticus input file unless you set ``[mismatchIsFatal]``\ :math:`=`\ ``false`` in which case you'll just be warned about any mismatch;
* Galacticus assumes by default that all merger trees exist at the final output time---if this is not the case set ``[allTreesExistAtFinalTime]``\ :math:`=`\ ``false``.
**Dark Matter Scale Radii**: If ``[presetScaleRadii]``\ :math:`=`\ ``true`` and the ``halfMassRadius`` dataset is available within the ``haloTrees`` group (see `here `_) then the half-mass radii of nodes will be used to compute the corresponding scale length of the dark matter halo profile\footnoteThe scale radius is found by seeking a value which gives the correct half mass radius. It is therefore important that the definition of halo mass (specifically the virial overdensity) in Galacticus be the same as was used in computing the input half mass radii.. This requires a dark matter profile scale component which supports setting of the scale length (see :ref:`here `).
**Satellite Merger Times:** If ``[presetMergerTimes]``\ :math:`=`\ ``true`` then merger times for satellites will be computed directly from the merger tree data read from file. When a subhalo has an isolated halo as a descendant it is assumed to undergo a merger with that isolated halo at that time. Note that this requires a satellite orbit component method which supports setting of merger times (e.g. ``[componentSatellite]``\ :math:`=`\ ``preset``).
**Dark Matter Halo Angular Momenta:** If ``[presetAngularMomenta]``\ :math:`=`\ ``true`` and the ``angularMomentum`` dataset is available within the ``haloTrees`` group (see `here `_) then the angular momenta of nodes will be computed and set. This requires a dark matter halo spin component which supports setting of the angular momentum (see :ref:`here `).
**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**
* ``[fileNames]`` (string) — The name of the file(s) from which merger tree data should be read when using the ``[mergerTreeConstruct]``\ :math:`=`\ ``read`` tree construction method.
* ``[forestSizeMaximum]`` (integer; default ``0_c_size_t``) — The maximum number of nodes allowed in a forest before it will be broken up into trees and processed individually. A value of 0 implies that forests should never be split.
* ``[presetMergerTimes]`` (boolean; default ``.true.``) — Specifies whether merging times for subhalos should be preset when reading merger trees from a file.
* ``[presetMergerNodes]`` (boolean; default ``.true.``) — Specifies whether the target nodes for mergers should be preset (i.e. determined from descendant nodes). If they are not, merging will be with each satellite's host node.
* ``[presetSubhaloMasses]`` (boolean; default ``.true.``) — Specifies whether subhalo mass should be preset when reading merger trees from a file.
* ``[subhaloAngularMomentaMethod]`` (string; one of ``scale``, ``summation``; default ``summation``) — Specifies how to account for subhalo angular momentum when adding subhalo mass to host halo mass.
* ``[presetSubhaloIndices]`` (boolean; default ``.true.``) — Specifies whether subhalo indices should be preset when reading merger trees from a file.
* ``[presetPositions]`` (boolean; default ``.true.``) — Specifies whether node positions should be preset when reading merger trees from a file.
* ``[presetScaleRadii]`` (boolean; default ``.true.``) — Specifies whether node scale radii should be preset when reading merger trees from a file.
* ``[scaleRadiiFailureIsFatal]`` (boolean; default ``.true.``) — Specifies whether failure to set a node scale radii should be regarded as a fatal error. (If not, a fallback method to set scale radius is used in such cases.)
* ``[presetScaleRadiiConcentrationMinimum]`` (real; default ``3.0d0``) — The lowest concentration (:math:`c=r_\mathrm{vir}/r_\mathrm{s}`) allowed when setting scale radii, :math:`r_\mathrm{s}`.
* ``[presetScaleRadiiConcentrationMaximum]`` (real; default ``60.0d0``) — The largest concentration (:math:`c=r_\mathrm{vir}/r_\mathrm{s}`) allowed when setting scale radii, :math:`r_\mathrm{s}`.
* ``[presetScaleRadiiMinimumMass]`` (real; default ``0.0d0``) — The minimum halo mass for which scale radii should be preset (if ``[presetScaleRadii]``\ :math:`=`\ ``true``).
* ``[presetUnphysicalAngularMomenta]`` (boolean; default ``.false.``) — When reading merger trees from file and presetting halo angular momenta, detect unphysical (<=0) angular momenta and preset them using the selected halo spin method.
* ``[presetAngularMomenta]`` (boolean; default ``.true.``) — Specifies whether node angular momenta should be preset when reading merger trees from a file.
* ``[presetAngularMomenta3D]`` (boolean; default ``.false.``) — Specifies whether node 3-D angular momenta vectors should be preset when reading merger trees from a file.
* ``[presetOrbits]`` (boolean; default ``.true.``) — Specifies whether node orbits should be preset when reading merger trees from a file.
* ``[presetOrbitsSetAll]`` (boolean; default ``.true.``) — Forces all orbits to be set. If the computed orbit does not cross the virial radius, then select one at random instead.
* ``[presetOrbitsAssertAllSet]`` (boolean; default ``.true.``) — Asserts that all virial orbits must be preset. If any can not be set, Galacticus will stop.
* ``[presetOrbitsBoundOnly]`` (boolean; default ``.true.``) — Specifies whether only bound node orbits should be set.
* ``[beginAt]`` (integer; default ``-1_kind_int8``) — Specifies the index of the tree to begin at. (Use -1 to always begin with the first tree.)
* ``[outputTimeSnapTolerance]`` (real; default ``0.0d0``) — The relative tolerance required to "snap" a node time to the closest output time.
* ``[missingHostsAreFatal]`` (boolean; default ``.true.``) — Specifies whether nodes with missing host nodes should be considered to be fatal---see the discussion of missing host nodes in the class description above.
* ``[treeIndexToRootNodeIndex]`` (boolean; default ``.false.``) — Specifies whether tree indices should always be set to the index of their root node.
* ``[allowBranchJumps]`` (boolean; default ``.true.``) — Specifies whether nodes are allowed to jump between branches.
* ``[allowSubhaloPromotions]`` (boolean; default ``.true.``) — Specifies whether subhalos are permitted to be promoted to being isolated halos.
* ``[alwaysPromoteMostMassive]`` (boolean; default ``.false.``) — If true, the most massive progenitor is always promoted to be the primary progenitor *even if* it is a subhalo. Otherwise, isolated progenitors are given priority over subhalo progenitors, even if they are less massive.
* ``[presetNamedReals]`` (string) — Names of real datasets to be additionally read and stored in the nodes of the merger tree when using the ``[mergerTreeConstruct]``\ :math:`=`\ ``read`` tree construction method.
* ``[presetNamedIntegers]`` (string) — Names of integer datasets to be additionally read and stored in the nodes of the merger tree when using the ``[mergerTreeConstruct]``\ :math:`=`\ ``read`` tree construction method.
.. _physics-mergerTreeConstructorStateRestored:
``mergerTreeConstructorStateRestored``
--------------------------------------
A merger tree constructor class which will restore a merger tree whose complete internal state was written to file. It is intended primarily for debugging purposes to allow a tree to begin processing just prior to the point of failure. To use this method, the following procedure should be followed:
#. Identify a point in the evolution of the tree suitably close to, but before, the point of failure;
#. Insert appropriate code into Galacticus to have it call the function to store the state of the file and then stop, e.g.:
.. code-block:: none
use :: Merger_Tree_Construction, only : mergerTreeStateStore
.
.
.
if () then
call mergerTreeStateStore(tree,'storedTree.dat')
stop 'tree internal state was stored'
end if
#. Run the model ensuring that ``[stateFileRoot]`` is set to a suitable file root name to allow the internal state of Galacticus to be stored;
#. Remove the code inserted above and recompile;
#. Run Galacticus with an input parameter file identical to the one used previously except with ``[mergerTreeConstruct]``\ :math:`=`\ ``stateRestore``, ``[stateFileRoot]`` removed, ``[stateRetrieveFileRoot]`` set to the value previously used for ``[stateFileRoot]`` and ``[fileName]``\ :math:`=`\ ``storedTree.dat``.
This should restore the tree and the internal state of Galacticus precisely from the point where they were saved and produce the same subsequent evolution.
Note that currently this method does not support storing and restoring of trees which contain components that have more than one instance.
**Parameters**
* ``[fileName]`` (string; default ``storedTree.dat``) — The name of the file containing the stored merger tree.