Merger Tree Operators¶

Class providing operators that act on complete merger trees at well-defined points in the simulation pipeline: before construction, before initialization, before evolution, and after evolution. Tree operators enable arbitrary post-processing, analysis, or modification of merger trees at each stage. Examples include adding constrained perturbations, computing halo statistics, applying tree pruning, or writing intermediate outputs. Multiple operators can be chained via the multi-operator implementation.

Default implementation: mergerTreeOperatorNull

Methods¶

operatePreConstruction → void

Perform an operation on the merger tree prior to construction.

operatePreInitialization → void

Perform an operation on the merger tree prior to initialization.

type(mergerTree), intent(inout), target :: tree

operatePreEvolution → void

Perform an operation on the merger tree prior to evolution.

type(mergerTree), intent(inout), target :: tree

operatePostEvolution → void

Perform an operation on the merger tree after evolution.

finalize → void

Finalize the merger tree operator at the end of the simulation, performing any required cleanup, flushing accumulated statistics, and releasing resources held by the operator.

`mergerTreeOperatorAssignOrbits`¶

Provides a merger tree operator which assigns orbits to non-primary progenitor nodes.

`mergerTreeOperatorAugment`¶

Provides a merger tree operator which augments the mass resolution of existing merger trees by inserting high-resolution branches built to match the original tree structure. Resolution limits for new branches are set by the delegate mass resolution object, with tolerance and retry behavior controlled by [toleranceScale], [attemptsBeforeRescale], and [attemptsMaximum].

Methods

buildTreeFromNode — Build a merger tree starting from the given node.
acceptTree — Determine if a newly built tree is an acceptable match.
extendNonOverlapNodes — Graft new branches onto all end-nodes of a newly built tree.
sortChildren — Sort child nodes into descending mass order.
nonOverlapReinsert — Reinsert a linked list of non-overlap nodes into their parent tree.

Parameters

[massCutOff] (real; default 1.0d10) — For the augment operator a description of resolution limit for new trees.
[performChecks] (boolean; default .false.) — If true, perform checks of the augmentation process.
[toleranceScale] (real; default 0.15d0) — The tolerance scale used in deciding if a trial tree is an acceptable match.
[retryMaximum] (integer; default 50) — The number of tree build attempts to complete before rescaling the tolerance.
[rescaleMaximum] (integer; default 20) — The maximum allowed number of tolerance rescalings.
[attemptsMaximum] (integer; default 10000) — The maximum allowed number of tree build attempts.
[massCutOffAttemptsMaximum] (integer; default 50) — The number of trees with nodes above the mass resolution to allow before adjusting the mass cut-off tolerance.
[massCutOffScaleFactor] (real; default 0.05d0) — The amount by which to increase the mass cut-off scale tolerance after exhausting tree build attempts.
[massOvershootAttemptsMaximum] (integer; default 50) — The number of failed trees to allow before increasing the mass of the parent node.
[massOvershootScaleFactor] (real; default 0.05d0) — The amount by which to increase the mass overshoot factor after exhausting tree build attempts.
[useOneNodeTrees] (boolean; default .false.) — If true, trees only consisting of their base node will be augmented.
[snapshotRedshifts] (real) — For augment description of redshift snapshots.

`mergerTreeOperatorConditionalMF`¶

Provides a merger tree operator which accumulates conditional mass functions for trees. In addition to the cumulative mass function, 1\(^\mathrm{st}\) through \(n^\mathrm{th}\) most-massive progenitor mass functions, formation rate functions, and unevolved subhalo mass functions (Jiang and van den Bosch, 2014) split by hierarchy depth are computed and output. Mass functions are accumulated in logarithmically-spaced bins of parent halo mass, logarithmically-spaced bins of mass ratio (the ratio of progenitor to parent halo mass), and at pairs of parent/progenitor redshifts. The following parameters control the operator:

countMassParent: The number of bins in parent halo mass to use;
massParentMinimum: The minimum parent halo mass to consider;
massParentMaximum: The maximum parent halo mass to consider;
massRatioCount: The number of bins in mass ratio to use;
massRatioMinimum: The minimum mass ratio to consider;
massRatioMaximum: The maximum mass ratio to consider;
redshiftsParent: A list of redshifts at which to identify parent halos;
redshiftsProgenitor: A corresponding list of redshifts at which to identify progenitor halos;
depthProgenitorPrimary: The number of \(i^\mathrm{th}\) most-massive progenitor mass functions to compute (starting from the 1\(^\mathrm{st}\) most-massive);
depthHierarchySubhalo: The maximum depth in the subhalo hierarchy for which to compute the unevolved subhalo mass function;
fractionTimeFormationRate: The fraction of the current time over which to estimate the formation rate of halos when computing merger tree statistics;
nameGroupOutput: The name of the HDF5 group to which mass functions will be written.

If the operator finds the named HDF5 group already in existence, it will accumulate its mass functions to those already written to the group, weighting by the inverse of the variance in each bin. The structure of the HDF5 group is as follows:

{
  DATASET "conditionalMassFunction" {
  COMMENT "Conditional mass functions []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nratio, Nparent, Nz ) }
  }
  DATASET "conditionalMassFunctionError" {
  COMMENT "Conditional mass function errors []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nratio, Nparent, Nz ) }
  }
  DATASET "conditionalMassFunctionCovariance" {
  COMMENT "Conditional mass function covariances []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nratio, Nparent, Nz, Nratio, Nparent, Nz ) }
  }
  DATASET "formationRateFunction" {
  COMMENT "Formation rate functions []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( 2, Nratio, Nparent, Nz ) }
  }
  DATASET "formationRateFunctionError" {
  COMMENT "Formation rate function errors []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( 2, Nratio, Nparent, Nz ) }
  }
  DATASET "massParent" {
  COMMENT "Mass of parent node [Msolar]"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nparent ) }
     ATTRIBUTE "unitsInSI" {
        DATATYPE  H5T_IEEE_F64LE
        DATASPACE  SCALAR
        DATA {
        (0): 1.98892e+30
        }
      }
  }
  DATASET "massRatio" {
  COMMENT "Mass of ratio node [Msolar]"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nratio ) }
     ATTRIBUTE "unitsInSI" {
        DATATYPE  H5T_IEEE_F64LE
        DATASPACE  SCALAR
        DATA {
        (0): 1.98892e+30
        }
     }
  }
  DATASET "primaryProgenitorMassFunction" {
  COMMENT "Primary progenitor mass functions []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Ndepth, Nratio, Nparent, Nz ) }
  }
  DATASET "primaryProgenitorMassFunctionError" {
  COMMENT "Primary progenitor mass function errors []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Ndepth, Nratio, Nparent, Nz ) }
  }
  DATASET "redshiftParent" {
  COMMENT "Redshift of parent node []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nz ) }
  }
  DATASET "redshiftProgenitor" {
  COMMENT "Redshift of progenitor node []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nz ) }
  }
  DATASET "subhaloMassFunction" {
  COMMENT "Unevolved subhalo mass functions []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nhierarchy, Nratio, Nparent ) }
  }
  DATASET "subhaloMassFunctionError" {
  COMMENT "Unevolved subhalo mass function errors []"
     DATATYPE  H5T_IEEE_F64LE
     DATASPACE  SIMPLE { ( Nhierarchy, Nratio, Nparent ) }
  }
}

Where Nratio is the number of bins in mass ratio, Nparent is the number of bins in mass ratio, Nz is the number of parent/progenitor redshift pairs, Ndepth is the maximum depth in the ranking of most-massive progenitor mass functions, Nhierarchy is the maximum depth in the subhalo hierarchy for subhalo mass functions. The first dimension of the formationRateFunction dataset stores two different versions of the formation rate function. The first uses the mass of the forming halo at the time of formation, the second uses the mass of the node immediately prior to it becoming a subhalo.

Mass functions are output as \(\mathrm{d}N/\mathrm{d}\log_{10}m\) where \(N\) is the number of halos per parent halo, and \(m\) is the mass ratio.

Methods

binWeights — Compute weights for a halo in each bin of the mass function.
binWeights2D — Compute weights for a halo in each bin of a 2D mass function.

Parameters

[countMassParent] (integer; default 10) — The number of bins in parent mass when constructing conditional halo mass functions.
[massParentMinimum] (real; default 1.0d10) — The minimum parent halo mass to bin when constructing conditional halo mass functions.
[massParentMaximum] (real; default 1.0d15) — The maximum parent halo mass to bin when constructing conditional halo mass functions.
[massRatioCount] (integer; default 10) — The number of bins in mass ratio when constructing conditional halo mass functions.
[massRatioMinimum] (real; default 1.0d-4) — The minimum mass ratio to bin when constructing conditional halo mass functions.
[massRatioMaximum] (real; default 1.0d1) — The maximum mass ratio to bin when constructing conditional halo mass functions.
[redshiftsParent] (real; default [0.0d0]) — The set of parent halo redshifts to use when constructing conditional halo mass functions.
[redshiftsProgenitor] (real; default [1.0d0]) — The set of progenitor halo redshifts to use when constructing conditional halo mass functions.
[depthProgenitorPrimary] (integer; default 2) — The depth in progenitor ranking for which to store ranked progenitor mass functions. For example, a value of 2 means store mass functions for the most massive, and second most massive progenitor.
[depthHierarchySubhalo] (integer; default 2) — The depth in the subhalo hierarchy for which to store unevolved subhalo mass functions.
[fractionTimeFormationRate] (real; default 0.01d0) — The fraction of the current time over which to estimate the formation rate of halos when computing merger tree statistics.
[alwaysIsolatedHalosOnly] (boolean; default .false.) — Include only halos which have always been isolated when computing merger tree statistics?
[extendedStatistics] (boolean; default .true.) — Compute extended statistics (formation rate function, \(N^\mathrm{th}\) most-massive progenitor mass functions, etc.)?
[computeCovariances] (boolean; default .false.) — Compute covariances for accumulated statistics?
[nameGroupOutput] (string; default conditionalMassFunction) — The name of the HDF5 group to which the conditional mass function should be output.

`mergerTreeOperatorConsolidateBranches`¶

A merger tree operator class that consolidates branches spanning a given amount of time or mass growth. Starting from the tip of each branch, the branch is broken into segments for which the mass growth is less than \(1+\)[fractionGrowthMass] and the time growth is less than \(1+\)[fractionGrowthTime]. Any intermediate nodes in each segment are removed, with their siblings (if any) being made siblings of the node at the end of the segment. This reduces the time resolution along branches which can make evolution more efficient (at the cost of some loss of precision).

Parameters

[fractionGrowthMass] (real) — The fraction of growth in mass over which branches may be consolidated.
[fractionGrowthTime] (real) — The fraction of growth in time over which branches may be consolidated.

`mergerTreeOperatorDeforest`¶

Provides a deforestation operator for merger trees. Given a forest, this operator will destroy all but the first tree in the forest.

`mergerTreeOperatorDumpToGraphViz`¶

A merger tree operator class which dumps the full structure of each merger tree to a file using the GraphViz format. All trees with root node basic mass between [massMinimum] and [massMaximum] will be dumped to a file named “mergerTreeDump:<treeIndex>:1.gv” in the directory specified by [path]. If [scaleNodesByLogMass]\(=\)true then the size of each GraphViz node is scaled in proportion to the logarithm of the halo mass. If [edgeLengthsToTimes]\(=\)true then the lengths of edges in the GraphViz graph are scaled in proportion to the time difference between the connected nodes.

Parameters

[path] (string; default .) — Specifies the directory to which merger tree structure should be dumped.
[massMinimum] (real; default 0.0d0) — Specifies the minimum root mass for which merger tree structure should be dumped.
[massMaximum] (real; default huge(0.0d0)) — Specifies the minimum root mass for which merger tree structure should be dumped.
[redshiftMinimum] (real; default 0.0d0) — Specifies the minimum redshift for which merger tree structure should be dumped.
[redshiftMaximum] (real; default 100.0d0) — Specifies the maximum redshift for which merger tree structure should be dumped.
[scaleNodesByLogMass] (boolean; default .true.) — Specifies whether or not node sizes should be scaled by the logarithm of their mass.
[edgeLengthsToTimes] (boolean; default .true.) — Specifies whether or not the lengths of edges in the graph should be scaled to time differences between nodes.
[useNodeLabels] (boolean; default .false.) — If true, label nodes in the graph with any node labels. Otherwise, label using node IDs.

`mergerTreeOperatorExport`¶

This operator will export merger trees to a file specified by the [outputFileName] using the format specified by [exportFormat]. Currently, node indices (plus host indices, which are assumed identical to the node indices), descendant indices, masses and redshifts are exported. Positions and velocities are exported if available. If IRATE-format output is requested then “snapshot” numbers will be assigned to nodes based on the time at which they exist. This usually only makes sense if the nodes are defined on a time grid (i.e. if merger trees were extracted from an N-body simulation, or if trees were re-gridded onto such a time grid; see mergerTreeOperatorRegridTimes). Export happens during the merger tree pre-evolution phase.

Node positions and velocities will be exported if they are available.

If [skipSingleNodeTrees] is true then trees consisting of a single node (which are typically left over from pruning operators, and which are effectively inert) are not output. If [includeScaleRadii] is true then scale radii will be included in the output (if they are available and have been set). If [includeAngularMomenta] is true then halo angular momenta will be included in the output (if they are available and have been set).

If [includeSubhalos] is true then subhalos are included in the exported data. Note that if particle positions were used to track subhalos after their destruction in an N-body simulation, attempting to output subhalos may lead to errors.

Parameters

[outputFileName] (string; default galacticusExportedTrees.hdf5) — The name of the file to which merger trees should be exported.
[exportFormat] (string; one of galacticus, irate; default galacticus) — The output format to use when exporting merger trees.
[skipSingleNodeTrees] (boolean; default .true.) — If true, trees consisting of a single node (which are inert in Galacticus) are not output.
[includeScaleRadii] (boolean; default .false.) — If true, include scale radii (if available) in the output.
[includeAngularMomenta] (boolean; default .false.) — If true, include angular momenta (if available) in the output.
[includeSubhalos] (boolean; default .true.) — If true, subhalos are included in the exported data. (Note that subhalo export is not supported in cases where particle data was used to track halos after they are destroyed in an N-body simulation.)

`mergerTreeOperatorInformationContent`¶

A merger tree operator which computes the cladistic information content Thorley et al. (1998) of merger trees. This is output to a group in the output file with name specified by the [outputGroupName] parameter. Two datasets are written to this group: treeIndex which gives the index of each tree, and informationContent which gives the cladistic information content in units of bits.

Parameters

[outputGroupName] (string; default treeInformationContent) — The name of an HDF5 group to which tree information content should be written.

`mergerTreeOperatorMassAccretionHistory`¶

A merger tree operator class which outputs mass accretion histories (i.e. the mass of the node on the primary branch as a function of time). Histories are written into the Galacticus output file in a group with name given by [outputGroupName]. Within that group, each merger tree has its own group named mergerTree<N> where <N> is the tree index. Within each such merger tree group datasets giving the node index (”nodeIndex”), time (”nodeTime”), basic mass (”nodeMass”), expansion factor (”nodeExpansionFactor”) are written. Optionally, datasets giving the spin parameter (”nodeSpin”) and its vector components (”nodeSpinVector”) are included if [includeSpin] and [includeSpinVector] respectively are set to true.

Parameters

[outputGroupName] (string; default massAccretionHistories) — The name of the HDF5 group to output mass accretion histories to.
[includeSpin] (boolean; default .false.) — If true, include the spin of the halo in the output.
[includeSpinVector] (boolean; default .false.) — If true, include the spin vector of the halo in the output.

`mergerTreeOperatorMonotonizeMassGrowth`¶

A merger tree operator class which enforces monotonic growth a halo mass along each branch of each merger tree. It does this by searching the tree for nodes which are less massive than the sum of the masses of their immediate progenitors, and increasing the mass of such nodes to equal the sum of the masses of their immediate progenitors.

`mergerTreeOperatorNull`¶

Provides a null operator on merger trees.

(Default implementation)

`mergerTreeOperatorOutputRootMasses`¶

A merger tree operator which outputs a file containing the root halo masses and statistical weights of all merger trees, enabling post-processing analysis of the sampled halo mass distribution. The output redshift is set by [redshift], optionally restricted to always-isolated halos via [alwaysIsolatedOnly], with the output filename specified by [fileName].

Parameters

[redshift] (real; default 0.0d0) — The redshift at which to gather tree root masses.
[alwaysIsolatedHalosOnly] (boolean; default .true.) — Include only always-isolated halos when gathering tree root masses?
[fileName] (string) — The name of the file to which tree masses should be written.

`mergerTreeOperatorOutputStructure`¶

A merger tree operator class which dumps pre-evolution tree structure to the output file. The node properties to be included in the dump are controlled by a nodePropertyExtractorClass object provided to this class. Structures are written to a new group, mergerTreeStructures, in the Galacticus output file. This group will contain groups called mergerTreeN where N is the merger tree index. Each such group will contain datasets corresponding to all extracted properties.

`mergerTreeOperatorParticulate`¶

Provides a merger tree operator which creates particle representations of Galacticus dark matter halos by sampling N-body particles from the halo density profile at a specified snapshot time. Particle mass is set by [massParticle], the snapshot time by [time], the truncation radius by [radiusTruncateOverRadiusVirial], and output by [outputFileName].

Parameters

[outputFileName] (string) — Name of the file to which particle data should be written.
[idMultiplier] (integer; default 0_kind_int8) — If this parameter is greater than zero, particle IDs begin at nodeIndex\*[idMultiplier] for each node. The multiplier should be chosen to be large enough that duplicate IDs can not occur.
[massParticle] (real) — Mass of particles to be used to represent halos.
[timeSnapshot] (real) — The time at which to snapshot the tree.
[radiusTruncateOverRadiusVirial] (real) — Radius (in units of the virial radius) at which to truncate halo profiles.
[satelliteOffset] (boolean; default .true.) — If true, offset particle representations to the positions/velocities of satellites.
[positionOffset] (boolean; default .false.) — If true, offset particle representations to the positions/velocities of nodes.
[subtractRandomOffset] (boolean; default .false.) — If true, the center-of-mass positions and velocities of the host and satellite are enforced to be matched with the values specified by the offset parameters. If false, due to limited number of particles in the representations, the center-of-mass positions and velocities may deviate slightly from the specified values, i.e. have small random offsets.
[energyDistributionPointsPerDecade] (real; default 30.0d0) — The number of points per decade of radius to use when building the table of energy distribution function.
[toleranceRelativeSmoothing] (real; default 1.0d-7) — The relative tolerance to use in the integrals used in finding the smoothed density profile defined by Barnes (2012) to account for gravitational softening.
[toleranceMass] (real; default 1.0d-8) — The relative tolerance to use in the integrals over the mass distribution used in finding the smoothed density profile defined by Barnes (2012) to account for gravitational softening.
[tolerancePotential] (real; default 1.0d-9) — The relative tolerance to use in the integrals over the potential used in finding the smoothed density profile defined by Barnes (2012) to account for gravitational softening.
[selection] (string; one of all, hosts, satellites; default all) — Selects the type of halo to output. Allowed options are “all”, “hosts”, and “satellites”.
[kernelSoftening] (string; one of delta, plummer, gadget; default plummer) — Selects the softening kernel to use. Allowed options are “plummer”, and “gadget”.
[nonCosmological] (boolean; default .false.) — If true, a non-cosmological snapshot file will be created.
[addHubbleFlow] (boolean; default .false.) — If true, Hubble flow will be added to velocity offsets of halos (if applied).
[haloIdToParticleType] (boolean; default .false.) — If true, the halo ID will be used to assign particles from each halo to a different Gadget particle type group.
[sampleParticleNumber] (boolean; default .false.) — If true, the number of particles in each halo will be sampled from a Poisson distribution with the expected mean. Otherwise, the number is set equal to that expectation.
[lengthSoftening] (real) — The Plummer-equivalent softening length. That is, the parameter \(\epsilon\) in the softening gravitational potential \(\phi(r) = -\mathrm{G}m/\sqrt{r^2+\epsilon^2}\). If set to zero, softening is ignored when constructing the particle representation of the halo. For non-zero values softening is accounted for when constructing the velocity distribution following the procedure of Barnes (2012).
[chunkSize] (integer; default -1) — The HDF5 dataset chunk size (in number of particles) used when writing particle data to the output file; set to \(-1\) to disable chunking and write all particles in a single contiguous dataset.

`mergerTreeOperatorPerturbMasses`¶

A merger tree operator which perturbs halo masses by some error model.

`mergerTreeOperatorProfiler`¶

A merger tree operator which profiles merger tree structure by counting nodes and non-primary progenitors as a function of mass and redshift, characterizing the statistical properties of the merger history. Mass and redshift binning is controlled by [massMinimum], [massMaximum], [massBinsPerDecade], [redshiftMinimum], [redshiftMaximum], and [timeBinsPerDecade].

Parameters

[massMinimum] (real; default 1.0d10) — The minimum mass of non-primary progenitor to count.
[massMaximum] (real; default 1.0d15) — The maximum mass of non-primary progenitor to count.
[massBinsPerDecade] (integer; default 10) — The number of bins per decade of non-primary progenitor mass.
[redshiftMinimum] (real; default 0.0d0) — The minimum redshift at which to count non-primary progenitors.
[redshiftMaximum] (real; default 10.0d0) — The maximum redshift at which to count non-primary progenitors.
[timeBinsPerDecade] (integer; default 10) — The number of bins per decade of time at which to count non-primary progenitors.

`mergerTreeOperatorPruneBaryons`¶

Provides a pruning operator on merger trees that removes all branches that can not contain any baryons.

`mergerTreeOperatorPruneBranchComplement`¶

A merger tree operator class which prunes all branches of a merger tree except the single branch rooted at the node identified by [branchNodeID], isolating one lineage for detailed analysis. This enables focused study of a specific halo’s merger history by removing all unrelated branches from the tree structure.

Parameters

[branchNodeID] (integer) — ID of the node at the bash of the branch to avoid pruning.

`mergerTreeOperatorPruneBranchTips`¶

Complements a merger tree operator which prunes tips of branches (i.e. sections from the leaf node to the first node with a sibling).

`mergerTreeOperatorPruneByMass`¶

A merger tree operator class which allows for branches of merger trees to be pruned—i.e. nodes below a specified mass limit are removed from the tree prior to any evolution. This can be useful for convergence studies for example. Set [massThreshold] to the desired mass threshold below which nodes will be pruned.

Parameters

[massThreshold] (real; default 0.0d0) — Threshold mass below which merger tree branches should be pruned.
[preservePrimaryProgenitor] (boolean; default .true.) — If true, primary progenitor status is preserved even if the primary progenitor is pruned from the tree.

`mergerTreeOperatorPruneByMassAndTime`¶

A merger tree operator class that prunes branches below some maximum mass, and all of the tree after the final output time.

Parameters

[massThreshold] (real) — Threshold mass below which merger tree branches should be pruned.

`mergerTreeOperatorPruneByTime`¶

Provides a merger tree operator which prunes merger tree branches by truncating them at a fixed cosmic time, removing nodes earlier than the specified epoch from the tree. The truncation epoch is set by [redshift], with optional mass-based selection via [massMinimum] and [massMaximum] to restrict pruning to a specific halo mass range.

Parameters

[redshiftEarliest] (real; default 0.0d0) — Redshift at which to truncate merger tree branches.
[massMinimum] (real; default 0.0d0) — Minimum mass for which to consider merger tree branches for truncation.
[massMaximum] (real; default huge(0.0d0)) — Maximum mass for which to consider merger tree branches for truncation.

`mergerTreeOperatorPruneClones`¶

Provides a clone pruning operator on merger trees.

`mergerTreeOperatorPruneHierarchy`¶

A merger tree operator class module which prunes branches below a given level in the substructure hierarchy. In any tree, the primary progenitor of the base node has substructure hierarchy depth 0. A branch which connects directly to this primary progenitor branch has substructure hierarchy depth 1, while a branch which connects directly to that branch has substructure hierarchy depth 2, and so on. The tree is pruned of all branches of hierarchy depth equal to or greater than the value provided by the [hierarchyDepth] parameter.

Parameters

[hierarchyDepth] (integer; ≥ 1; default 1) — The depth in the substructure hierarchy at which to prune a tree.

`mergerTreeOperatorPruneLightcone`¶

Provides a pruning-by-lightcone operator on merger trees, intended for use with the newer approach, in which galaxies are evolved to precisely the time of lightcone crossing. For the older approach (in which galaxies were evolved to one of a fixed set of snapshots, and then output into the section of the lightcone corresponding to that snapshot) see the mergerTreeOperatorPruneLightconeSnapshots merger tree operator class.

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

[splitTrees] (boolean; default .false.) — If true, prune away any nodes of the tree that are not needed to determine evolution up to the latest time at which a node is present inside the lightcone. This typically leads to a tree splitting into a forest of trees.
[bufferIsolatedHalos] (boolean; default .false.) — If true, intersection of a tree with the lightcone will be determined using the positions of non-isolated (a.k.a. “satellite”) halos, and of isolated halos (a.k.a “centrals”) with a buffer region (with radius equal to the extent of the orphan satellite distribution—see satelliteOrphanDistribution) placed around each such halo, and any intersection of that region with the lightcone is sufficient to prevent pruning of the tree. If this parameter is false then (unbuffered) positions of all halos are used for determining intersection with the lightcone—this requires complete (i.e. throughout the extent of their existence) knowledge of non-isolated halos prior to application of this operator. (inherited from mergerTreeOperatorPruneLightconeSnapshots)

`mergerTreeOperatorPruneLightconeSnapshots`¶

Provides a pruning-by-lightcone operator on merger trees, intended for use with the older approach in which galaxies were evolved to one of a fixed set of snapshots, and then output into the section of the lightcone corresponding to that snapshot. For the newer approach (in which galaxies are evolved to precisely the time of lightcone crossing) see the mergerTreeOperatorPruneLightcone merger tree operator class.

Trees which have no nodes which lie within the lightcone are completely pruned away. If the parameter [splitTrees] is set to true then any parts of a merger tree which does intersect the lightcone that exist after the latest time at which a constituent node of the tree intersects the lightcone will be pruned away also (possibly causing the tree to be split into multiple trees in a forest). If the parameter [bufferIsolatedHalos] is set to true then, when testing whether an isolated halo intersects the lightcone a buffer radius equal in size to the extent of any possible orphan galaxies associated with the halo is added around the lightcone—this ensures that if orphan galaxies of the halo might possibly intersect the lightcone the halo will not be pruned away.

Methods

processNode — Return true if the current node is to be processed for intersection with the lightcone.
timeIntersect — Return the latest time at which the current node intersects the lightcone.

Parameters

[bufferIsolatedHalos] (boolean; default .false.) — If true, intersection of a tree with the lightcone will be determined using the positions of non-isolated (a.k.a. “satellite”) halos, and of isolated halos (a.k.a “centrals”) with a buffer region (with radius equal to the extent of the orphan satellite distribution—see satelliteOrphanDistribution) placed around each such halo, and any intersection of that region with the lightcone is sufficient to prevent pruning of the tree. If this parameter is false then (unbuffered) positions of all halos are used for determining intersection with the lightcone—this requires complete (i.e. throughout the extent of their existence) knowledge of non-isolated halos prior to application of this operator.
[splitTrees] (boolean; default .false.) — If true, prune away any nodes of the tree that are not needed to determine evolution up to the latest time at which a node is present inside the lightcone. This typically leads to a tree splitting into a forest of trees.

`mergerTreeOperatorPruneNonEssential`¶

A merger tree operator class which prunes branches that do not directly influence an “essential” node. Any branch which does not connect to the branch into which the node identified by ID [essentialNodeID] descends by time essentialNodeTime] will be pruned. Specifying the time is important—if the node is a satellite at this time, then the pruning will not remove any progenitors of the parent node in which the essential node lives at the specified time.

Parameters

[essentialNodeID] (integer) — ID of the essential node to avoid pruning.
[essentialNodeTime] (real) — Time of the essential node to avoid pruning.

`mergerTreeOperatorRegridTimes`¶

A merger tree operator class which will interpolate the merger tree structure onto a new array of timesteps. The timestep array is specified via an outputTimesClass object. Along each branch of the tree, new halos are inserted at times corresponding to the times in the resulting array. The masses of these nodes are linearly interpolated between the existing nodes on the branch. Once these new nodes have been added, all other nodes are removed from the treefootnoteThe base node of the tree is never removed, even if it does not lie on one of the times in the constructed array. The processing is useful to construct representations of trees as they would be if only sparse time sampling were available. As such, it is useful for exploring how the number of snapshots in merger trees extracted from N-body simulations affects the properties of galaxies that form in them.

Parameters

[dumpTrees] (boolean; default .false.) — Specifies whether or not to dump merger trees as they are regridded.
[removeUngridded] (boolean; default .true.) — If true, remove nodes not at gridded times. Otherwise, leave them in place.
[propagateLabels] (boolean; default .true.) — If true, any labels attached to progenitor nodes are propagated to newly inserted nodes.
[snapTolerance] (real; default 0.0d0) — The fractional tolerance used in deciding if a node should be snapped to a time on the grid.

`mergerTreeOperatorRender`¶

A merger tree operator which outputs data on the structure of a merger tree and its halos useful for rendering the tree as a 3-D structure to a file named render_<treeIndex>_<outputIndex>.hdf5 where \(\langle\)treeIndex\(\rangle\) is the index of the tree and \(\langle\)outputIndex\(\rangle\) is an incremental counter that tracks the number of outputs for this tree. The output is a simple HDF5 file containing the following datasets:

nodeIndex: Index of the node;
parentIndex: Index of the parent node;
childIndex: Index of the child node;
time: Time of the node;
expansionFactor: Corresponding expansion factor;
radiusVirial: Virial radius of the node;
position: \((x,y,z)\) position of the node.

`mergerTreeOperatorScaleWeight`¶

A merger tree operator that multiplies the statistical weight of each merger tree by a user-specified constant factor, enabling rescaling of tree ensembles for combining datasets or adjusting volume normalizations. The scaling factor is specified by the [factor] parameter.

Parameters

[scaleFactor] (real) — The factor by which to scale merger tree weights.

`mergerTreeOperatorSelectWithinRange`¶

Provides a merger tree operator which selects only those trees whose base node mass falls within a specified range, discarding trees outside the bounds. The minimum and maximum accepted base node masses are set by [massMinimum] and [massMaximum], enabling mass-limited ensemble selection for statistical analyses.

Parameters

[baseMassMinimum] (real; default 0.0d0) — Base node mass below which trees should be ignored.
[baseMassMaximum] (real; default 0.0d0) — Base node mass above which trees should be ignored.

`mergerTreeOperatorSequence`¶

Provides a sequence of operators on merger trees.

Methods

prepend — Prepend an operator to a sequence of weight operators.

`mergerTreeOperatorTreeProcessingTimer`¶

A merger tree operator class which records and outputs tree processing time information. Tree timing data to be recorded and output to the metaData/treeTiming group. Three datasets are written to this group:

treeMasses: Gives the base node masses of the recorded trees (in units of \(\mathrm{M}_\odot\));
treeConstructTimes: Gives the time (in seconds) taken to construct each merger tree;
treeEvolveTimes: Gives the time (in seconds) taken to evolve each merger tree.

Parameters

[collectMemoryUsageData] (boolean; default .false.) — Specifies whether or not to collect and output data on the memory used while processing trees.

Merger Tree Operators¶

Methods¶

mergerTreeOperatorAssignOrbits¶

mergerTreeOperatorAugment¶

mergerTreeOperatorConditionalMF¶

mergerTreeOperatorConsolidateBranches¶

mergerTreeOperatorDeforest¶

mergerTreeOperatorDumpToGraphViz¶

mergerTreeOperatorExport¶

mergerTreeOperatorInformationContent¶

mergerTreeOperatorMassAccretionHistory¶

mergerTreeOperatorMonotonizeMassGrowth¶

mergerTreeOperatorNull¶

mergerTreeOperatorOutputRootMasses¶

mergerTreeOperatorOutputStructure¶

mergerTreeOperatorParticulate¶

mergerTreeOperatorPerturbMasses¶

mergerTreeOperatorProfiler¶

mergerTreeOperatorPruneBaryons¶

mergerTreeOperatorPruneBranchComplement¶

mergerTreeOperatorPruneBranchTips¶

mergerTreeOperatorPruneByMass¶

mergerTreeOperatorPruneByMassAndTime¶

mergerTreeOperatorPruneByTime¶

mergerTreeOperatorPruneClones¶

mergerTreeOperatorPruneHierarchy¶

mergerTreeOperatorPruneLightcone¶

mergerTreeOperatorPruneLightconeSnapshots¶

mergerTreeOperatorPruneNonEssential¶

mergerTreeOperatorRegridTimes¶

mergerTreeOperatorRender¶

mergerTreeOperatorScaleWeight¶

mergerTreeOperatorSelectWithinRange¶

mergerTreeOperatorSequence¶

mergerTreeOperatorTreeProcessingTimer¶

`mergerTreeOperatorAssignOrbits`¶

`mergerTreeOperatorAugment`¶

`mergerTreeOperatorConditionalMF`¶

`mergerTreeOperatorConsolidateBranches`¶

`mergerTreeOperatorDeforest`¶

`mergerTreeOperatorDumpToGraphViz`¶

`mergerTreeOperatorExport`¶

`mergerTreeOperatorInformationContent`¶

`mergerTreeOperatorMassAccretionHistory`¶

`mergerTreeOperatorMonotonizeMassGrowth`¶

`mergerTreeOperatorNull`¶

`mergerTreeOperatorOutputRootMasses`¶

`mergerTreeOperatorOutputStructure`¶

`mergerTreeOperatorParticulate`¶

`mergerTreeOperatorPerturbMasses`¶

`mergerTreeOperatorProfiler`¶

`mergerTreeOperatorPruneBaryons`¶

`mergerTreeOperatorPruneBranchComplement`¶

`mergerTreeOperatorPruneBranchTips`¶

`mergerTreeOperatorPruneByMass`¶

`mergerTreeOperatorPruneByMassAndTime`¶

`mergerTreeOperatorPruneByTime`¶

`mergerTreeOperatorPruneClones`¶

`mergerTreeOperatorPruneHierarchy`¶

`mergerTreeOperatorPruneLightcone`¶

`mergerTreeOperatorPruneLightconeSnapshots`¶

`mergerTreeOperatorPruneNonEssential`¶

`mergerTreeOperatorRegridTimes`¶

`mergerTreeOperatorRender`¶

`mergerTreeOperatorScaleWeight`¶

`mergerTreeOperatorSelectWithinRange`¶

`mergerTreeOperatorSequence`¶

`mergerTreeOperatorTreeProcessingTimer`¶