.. _physics-mergerTreeBuildController: Merger Tree Build Controllers ============================= Class providing merger tree build controllers---logic objects that govern when and how the tree builder places new nodes during tree construction. A controller decides whether a given node should be continued (branched further), constrains the range of allowed "times" (:math:`w(t) = \delta_\mathrm{c}(t)/D(t)`) at each node, forces node insertion at specified times, and supplies the branching probability object to use. Controllers enable constrained trees, main-branch-only trees, and other specialized constructions. **Default implementation:** ``mergerTreeBuildControllerUncontrolled`` Methods ------- ``control`` → ``logical`` Control the behavior of a tree build. * ``type (treeNode ), intent(inout), pointer :: node`` * ``class(mergerTreeWalkerClass), intent(inout), optional :: treeWalker_`` ``timeMinimum`` → ``double precision`` Return the minimum "time" (using the usual :math:`w` variable for merger tree building) allowed for this node. * ``type (treeNode), intent(inout) :: node`` * ``double precision , intent(in ) :: massBranch, criticalOverdensityBranch`` ``timeMaximum`` → ``double precision`` Return the maximum "time" (using the usual :math:`w` variable for merger tree building) allowed for this node. * ``type (treeNode), intent(inout) :: node`` * ``double precision , intent(in ) :: massBranch, criticalOverdensityBranch, timeReference`` * ``logical , intent( out) :: insertNode`` ``controlTimeMaximum`` → ``logical`` Control the behavior of a tree build when the maximum time for a node is reached. * ``type (treeNode ), intent(inout), target :: node`` * ``double precision , intent(in ) :: massBranch, criticalOverdensityBranch`` * ``integer (kind_int8), intent(inout) :: nodeIndex`` ``branchingProbabilityObject`` → ``class(mergerTreeBranchingProbabilityClass)`` Return a branching probability object to use in tree building. * ``type(treeNode), intent(inout) :: node`` ``nodesInserted`` → ``void`` Alert the controller when new nodes are inserted into the tree. * ``type (treeNode), intent(inout) :: nodeCurrent , nodeProgenitor1`` * ``type (treeNode), intent(inout), optional :: nodeProgenitor2`` * ``logical , intent(in ), optional :: didBranch`` .. _physics-mergerTreeBuildControllerBranchless: ``mergerTreeBuildControllerBranchless`` --------------------------------------- A merger tree build controller class which builds branchless trees. .. _physics-mergerTreeBuildControllerConstrained: ``mergerTreeBuildControllerConstrained`` ---------------------------------------- A merger tree build controller class which builds constrained merger trees using a Brownian bridge approach, enforcing specified overdensity and mass constraints at a target redshift. Controls which branches are built via the ``[constructionOption]`` parameter, with Brownian bridge endpoints set by ``[criticalOverdensity]``, ``[variance]``, ``[redshift]``, and ``[haloMass]``. **Parameters** * ``[trialCountMaximum]`` (default ``huge(1_c_size_t)``) — The maximum number of trials to attempt before failing. * ``[label]`` (default ``var_str(' ')``) — A label to apply to the constrained node. * ``[labelDescription]`` — A human-readable description of the label applied to constrained nodes in the merger tree, used to document what physical property or criterion the label represents. * ``[constructionOption]`` — Controls which branches of the tree to build. * ``[criticalOverdensityConstrained]`` — The critical overdensity at the end of the Brownian bridge. * ``[varianceConstrained]`` — The variance at the end of the Brownian bridge. * ``[redshiftConstrained]`` — The redshift at the end of the Brownian bridge. * ``[massConstrained]`` — The halo mass at the end of the Brownian bridge. .. _physics-mergerTreeBuildControllerFiltered: ``mergerTreeBuildControllerFiltered`` ------------------------------------- A merger tree build controller class which builds filtered trees. .. _physics-mergerTreeBuildControllerMainBranch: ``mergerTreeBuildControllerMainBranch`` --------------------------------------- A merger tree build controller class which builds trees containing only the main branch and progenitors of the node on the main branch above a certain mass fraction. Specifically, if a progenitor node of the node on the main branch has a mass below a certain mass fraction relative to the main branch node, the branch will not grow any further. **Parameters** * ``[massFraction]`` (default ``0.0d0``) — Mass fraction relative to the descendant node on the main branch below which the progenitor branch does not grow any further. * ``[invertFilter]`` (default ``.false.``) — If true, the filter is inverted to pass only nodes *not* on the main branch. * ``[includeSubhalos]`` (default ``.false.``) — If set to true then subhalos of the main branch halo are also assigned a value of 1 (with subhalos of non-main branch halos assigned a value of 0). Otherwise, all subhalos are assigned a value of 0. .. _physics-mergerTreeBuildControllerMassTimeWindow: ``mergerTreeBuildControllerMassTimeWindow`` ------------------------------------------- A merger tree build controller class which follows branches only if they lie within a window of time and mass. **Methods** * ``passes`` — Returns true if the given node lies within the allowed window. **Parameters** * ``[massMinimum]`` — The minimum mass to which branches should be followed. * ``[timeMinimum]`` — The minimum time to which branches should be followed. * ``[redshiftMaximum]`` — The maximum redshift to which branches should be followed. .. _physics-mergerTreeBuildControllerMulti: ``mergerTreeBuildControllerMulti`` ---------------------------------- A merger tree build controller class which applies multiple other controllers. **Methods** * ``columnDescriptions`` — Return a description of the columns. * ``elementCount`` — Return the number of properties in the tuple. * ``extractDouble`` — Extract the double properties from the given ``node``. * ``extractInteger`` — Extract the integer properties from the given ``node``. * ``names`` — Return the names of the properties extracted. * ``descriptions`` — Return descriptions of the properties extracted. * ``unitsInSI`` — Return the units of the properties extracted in the SI system. * ``units`` — Return an object containing units metadata for the properties. * ``ranks`` — Return the ranks of the properties extracted. * ``metaData`` — Populate a hash with meta-data for the property. .. _physics-mergerTreeBuildControllerOutputTimeSnap: ``mergerTreeBuildControllerOutputTimeSnap`` ------------------------------------------- A merger tree build controller class that forces tree time steps to exactly coincidence with output times. .. _physics-mergerTreeBuildControllerSingleStep: ``mergerTreeBuildControllerSingleStep`` --------------------------------------- A merger tree build controller class which limits the building of a merger tree to a single step, advancing to a specified target redshift set by ``[redshift]``. After the step, tree building either halts or continues without further step limitations depending on the ``[haltAfterStep]`` parameter. **Parameters** * ``[redshiftStep]`` — The redshift to which to take a single step. * ``[haltAfterStep]`` (default ``.true.``) — If true, cease building the tree after the first step. Otherwise, continue to build with no further step limitations. .. _physics-mergerTreeBuildControllerSubsample: ``mergerTreeBuildControllerSubsample`` -------------------------------------- A merger tree build controller class which performs probabilistic subsampling of branches during tree construction, retaining low-mass branches with a mass-dependent probability :math:`P(M) = P_0 (M/M_0)^\alpha` for :math:`M < M_0`. The mass threshold :math:`M_0`, sampling rate :math:`P_0`, and exponent :math:`\alpha` are set by ``[massThreshold]``, ``[subsamplingRateAtThreshold]``, and ``[exponent]``, with node weights adjusted to compensate. **Parameters** * ``[massThreshold]`` — The mass threshold, :math:`M_0`, below which subsampling is applied. * ``[fractionMassThreshold]`` — The fractional (relative to the tree mass) mass threshold, :math:`f_0`, below which subsampling is applied. * ``[subsamplingRateAtThreshold]`` — The subsampling rate at the mass threshold, :math:`P_0`. * ``[exponent]`` — The exponent, :math:`\alpha`, of mass in the subsampling probability, i.e. :math:`P(M) = P_0 (M/M_0)^\alpha` for :math:`M < M_0`. * ``[factorMassGrowthConsolidate]`` (default ``0.0d0``) — The maximum factor by which the mass is allowed to grow between child and parent when consolidating nodes. A non-positive value prevents consolidation. * ``[destroyStubs]`` (default ``var_str('always')``) — Parameter controlling when to destroy stub branches. Options are `always`, `never`, and `sideBranchesOnly`. * ``[rate]`` — The probability (between 0 and 1) that each particle is retained; particles are drawn independently from a uniform distribution to achieve the target subsampling fraction. .. _physics-mergerTreeBuildControllerUncontrolled: ``mergerTreeBuildControllerUncontrolled`` ----------------------------------------- A merger tree build controller class which provides no control. **(Default implementation)**