.. _physics-mergerTreeBuilder: Merger Tree Builders ==================== Class providing merger tree builders---algorithms that construct the branching history (merger tree) of a dark matter halo by stochastically sampling halo merging rates from the extended Press-Schechter formalism or similar approaches. Starting from a root halo at the present epoch, a builder walks backward in cosmic time, placing progenitor halos at each branching event until the tree reaches its mass resolution limit or a specified early time. **Default implementation:** ``mergerTreeBuilderCole2000`` Methods ------- ``build`` → ``void`` Builds and returns a merger tree given the root ``node``. * ``type(mergerTree), intent(inout), target :: tree`` ``timeEarliestSet`` → ``void`` Set the earliest time for the builder to the given value. * ``double precision, intent(in ) :: timeEarliest`` .. _physics-mergerTreeBuilderCole2000: ``mergerTreeBuilderCole2000`` ----------------------------- A merger tree builder class which uses the algorithm described by :cite:t:`cole_hierarchical_2000` (with minor modifications described below). This action of this algorithm is controlled by the following parameters: ``[mergeProbability]`` The maximum probability for a binary merger allowed in a single timestep. This allows the probability to be kept small, such the the probability for multiple mergers within a single timestep is small. ``[accretionLimit]`` The maximum fractional change in mass due to sub-resolution accretion allowed in any given timestep when building the tree. ``[redshiftMaximum]`` The highest redshift to which the tree should be built. Any branch reaching this redshift will be terminated. Typically this should be set to a high value such that branches terminate when the resolution limit it reached, but specifying a maximum redshift can be useful in some situations. ``[branchIntervalStep]`` If ``true``, instead of limiting each time step such that the probability of branching is less than ``mergerTreeBuildCole2000MergeProbability``, the interval to the next branching event will be drawn from a negative exponential with the appropriate rate. If this exceeds the maximum allowed timestep based on other considerations (e.g. the accretion limit), no branching occurs, and the timestep proceeds\footnoteNote that we do not have to concern ourselves in the subsequent timestep with the fact that no branching occurred in the previous timestep because of the memorylessness nature of the negative exponential distribution. That is, the distribution of branching intervals conditioned on the fact that no branching occurred in the previous timestep, is just the same negative exponential distribution.. If the interval is less than the maximum allowed timestep, branching occurs at that point. In the regime of high branching rates (which occur when the branch being grown is far above the mass resolution), this approach allows for larger timesteps to be taken. The minimum halo mass that the algorithm will follow is determined by the selection merger tree building mass resolution method (see :galacticus-class:`mergerTreeMassResolution`). Mass accretion below this scale is treated as smooth accretion and branches are truncated once they fall below this mass. In the original :cite:t:`cole_hierarchical_2000`, when a branch split occurred masses, :math:`M_2` and :math:`M_3`, of the two new halos were selected by first drawing the mass :math:`M_2` from the branching distribution function in the range :math:`M_\mathrm{res}` to :math:`M_1/2` (where :math:`M_1` is the mass of the parent halo, and :math:`M_\mathrm{res}` is the mass resolution being used for the tree), and then setting .. math:: M_3 = M_1 (1-F) - M_2 where :math:`F` is the fraction of the parent halo mass gained through sub-resolution accretion in this timestep. As the sub-resolution accretion is removed entirely from the mass :math:`M_3` and not from :math:`M_2` this can lead to an asymmetry in progenitor mass functions close to :math:`M_1/2`. Therefore, we instead set the progenitor masses by first drawing a mass :math:`M_2^\prime` from the mass branching distribution function and then setting .. math:: M_2 & = M_2^\prime (1-F), \nonumber \\ M_3 & = (M_1 - M_2^\prime) (1-F), which ensures a symmetric treatment of subresolution accretion close to :math:`M_1/2`. **(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** * ``[mergeProbability]`` (real; default ``0.1d0``) — The largest probability of branching allowed in a timestep in merger trees built by the :cite:t:`cole_hierarchical_2000` method. * ``[accretionLimit]`` (real; < 1.0; default ``0.1d0``) — The largest fractional mass change due to subresolution accretion allowed in a timestep in merger trees built by the :cite:t:`cole_hierarchical_2000` method. * ``[redshiftMaximum]`` (real; default ``1.0d5``) — The highest redshift to which merger trees will be built in the :cite:t:`cole_hierarchical_2000` method. * ``[toleranceTimeEarliest]`` (real; default ``2.0d-6``) — The fractional tolerance used to judge if a branch is at the earliest allowed time in the tree. * ``[branchIntervalStep]`` (boolean; default ``.true.``) — If ``false`` use the original :cite:t:`cole_hierarchical_2000` method to determine whether branching occurs in a timestep. If ``true`` draw branching intervals from a negative exponential distribution. * ``[toleranceResolutionSelf]`` (real; default ``1.0d-6``) — The fractional tolerance in node mass at the resolution limit below which branch mis-orderings will be ignored. * ``[toleranceResolutionParent]`` (real; default ``1.0d-3``) — The fractional tolerance in parent node mass at the resolution limit below which branch mis-orderings will be ignored. * ``[ignoreNoProgress]`` (boolean; default ``.false.``) — If true, failure to make progress on a branch will be ignored (and the branch terminated). * ``[ignoreWellOrdering]`` (boolean; default ``.false.``) — If true, non-well-ordered tree branches are pruned away instead of causing errors.. .. _physics-mergerTreeBuilderCole2000Parallel: ``mergerTreeBuilderCole2000Parallel`` ------------------------------------- A merger tree builder class derived fro the :galacticus-class:`mergerTreeBuilderCole2000` merger tree builder class which implements a recursive tree construction algorithm utilizing OpenMP task parallelism. **Parameters** * ``[mergeProbability]`` (real; default ``0.1d0``) — The largest probability of branching allowed in a timestep in merger trees built by the :cite:t:`cole_hierarchical_2000` method. * ``[accretionLimit]`` (real; < 1.0; default ``0.1d0``) — The largest fractional mass change due to subresolution accretion allowed in a timestep in merger trees built by the :cite:t:`cole_hierarchical_2000` method. * ``[redshiftMaximum]`` (real; default ``1.0d5``) — The highest redshift to which merger trees will be built in the :cite:t:`cole_hierarchical_2000` method. * ``[toleranceTimeEarliest]`` (real; default ``2.0d-6``) — The fractional tolerance used to judge if a branch is at the earliest allowed time in the tree. * ``[branchIntervalStep]`` (boolean; default ``.true.``) — If ``false`` use the original :cite:t:`cole_hierarchical_2000` method to determine whether branching occurs in a timestep. If ``true`` draw branching intervals from a negative exponential distribution. * ``[toleranceResolutionSelf]`` (real; default ``1.0d-6``) — The fractional tolerance in node mass at the resolution limit below which branch mis-orderings will be ignored. * ``[toleranceResolutionParent]`` (real; default ``1.0d-3``) — The fractional tolerance in parent node mass at the resolution limit below which branch mis-orderings will be ignored. * ``[ignoreNoProgress]`` (boolean; default ``.false.``) — If true, failure to make progress on a branch will be ignored (and the branch terminated). * ``[ignoreWellOrdering]`` (boolean; default ``.false.``) — If true, non-well-ordered tree branches are pruned away instead of causing errors.. *(inherited from* ``mergerTreeBuilderCole2000``\ *)* .. _physics-mergerTreeBuilderConstrained: ``mergerTreeBuilderConstrained`` -------------------------------- A merger tree builder class that enforces physical constraints on merger trees constructed by a delegate builder class, repeatedly rebuilding trees until all filter criteria are satisfied. Multiple builder-filter pairs can be specified, with ``[trialCountMaximum]`` setting the maximum number of rebuild attempts before the process fails. **Parameters** * ``[trialCountMaximum]`` (default ``huge(1_c_size_t)``) — The maximum number of trials to attempt before failing. .. _physics-mergerTreeBuilderExcursionSetSimulator: ``mergerTreeBuilderExcursionSetSimulator`` ------------------------------------------ **Warning:** *This is a proof-of-concept implementation---it should not be used to generate scientifically-reliable results.* A merger tree builder class which creates trees by simulating trajectories from the excursion set. As warned above, this is a proof-of-concept implementation of a merger tree builder using direct simulation of the excursion set. It has not been validated or calibrated to produce merger trees that accurately match the statistical properties of trees measured from N-body simulations---in fact, it is known to *not* match the statistical properties of those trees. It has also not been carefully verified to be free from errors, nor has it been optimized for speed or memory footprint. *Caveat arborist!* **Parameters** * ``[redshiftMaximum]`` (real; default ``10.0d0``) — The highest redshift to which merger trees will be built. * ``[varianceStepMinimum]`` (real; default ``1.0d-6``) — The smallest step in variance to take when simulating trajectories from the excursion set. Using a smaller step will result in less quantization of node masses. * ``[varianceStepSigmaMaximum]`` (real; default ``5.0d+0``) — Controls the size of the steps in variance when simulating trajectories from the excursion set. Specifically, the step is never smaller than :math:`\Delta S = [ ( \delta_\mathrm{i} - \delta ) / N ]^2`, where :math:`N=`\ ``[varianceStepSigmaMaximum]`` is the number of standard deviations (in a standard normal distribution) that would be required in a positive fluctuation to make the excursion exceed the initial excursion in this step. In this way, the probability of "missing" a first crossing at some earlier step should be kept small (of order the fraction of a standard normal distribution which lies more than :math:`N` standard deviations above zero). * ``[excursionStep]`` (real; default ``0.02d0``) — Sets the size of the timesteps in excursion, :math:`\delta`, to take when constructing the tree. * ``[factorMassConsolidate]`` (real; > 0.0, ≤ 1.0; default ``0.9d0``) — The maximum factor (:math:`<1`) by which the mass of a halo can have changed before consolidation is no longer permitted. * ``[factorTimeConsolidate]`` (real; > 0.0; default ``0.9d0``) — The maximum factor (:math:`<1`) by which the time of a halo can have changed before consolidation is no longer permitted. .. _physics-mergerTreeBuilderSmoothAccretion: ``mergerTreeBuilderSmoothAccretion`` ------------------------------------ A merger tree builder class which builds a branchless merger tree with a smooth accretion history using the selected :galacticus-class:`darkMatterHaloMassAccretionHistory` class. The tree has a final mass of ``massHalo`` (in units of :math:`\mathrm{M}_\odot`) at redshift ``redshiftBase`` and is continued back in time by decreasing the halo mass by a factor ``massHaloDeclineFactor`` at each new :term:`node` until a specified ``massHaloResolution`` (in units of :math:`\mathrm{M}_\odot`) is reached. **Parameters** * ``[massHaloDeclineFactor]`` (real; default ``0.9d0``) — The factor by which halo mass should decrease in each step back in time building a smoothly accreting merger tree. * ``[redshiftEarliest]`` (real) — The earliest redshift to which to build a smoothly accreting merger tree.