Merger Tree Evolvers

Class providing evolvers for merger trees—the top-level driver that integrates the full system of ODEs for all nodes in a merger tree from an initial time to a specified end time. The evolver loops over nodes, determines the next timestep using the mergerTreeEvolveTimestepClass, calls the node evolver to advance each node, and handles events such as node promotions and mergers. It also manages deadlock detection, work-sharing between CPU cores, and suspension of trees for I/O.

Default implementation: mergerTreeEvolverStandard

Methods

evolve → void

Evolve the given tree from its current state to timeEnd, updating all node properties by integrating ODE physics and returning treeDidEvolve and suspendTree to indicate progress and whether to defer further evolution.

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

  • double precision , intent(in ) :: timeEnd

  • logical , intent( out) :: treeDidEvolve , suspendTree

  • logical , intent(in ) :: deadlockReporting

  • integer (kind_int8 ), optional, intent(in ) :: systemClockMaximum

  • integer (omp_lock_kind), optional, intent(inout) :: initializationLock

  • integer , optional, intent( out) :: status

mergerTreeEvolverNonEvolving

A merger tree evolver which initializes the tree without performing any time evolution of galaxy properties, useful for computing purely structural or initial-condition quantities from merger trees. Optionally prunes the tree to the target evolution time after initialization, controlled by the [pruneTree] parameter.

Parameters

  • [pruneTree] (boolean; default .false.) — If true, prune the tree to the evolve-to-time after each evolution.

mergerTreeEvolverStandard

The standard merger tree evolver. Each merger tree forest is evolved by repeatedly walking the trees and evolving each node forward in time by some timestep \(\Delta t\). Nodes are evolved individually such that nodes in different branches of a tree may have reached different cosmic times at any given point in the execution of Galacticus. Each node is evolved over the interval \(\Delta t\) using an adaptive ODE solver, which adjusts the smaller timesteps, \(\delta t\), taken in evolving the system of ODE to maintain a specified precision.

The choice of \(\Delta t\) then depends on other considerations. For example, a node should not be evolved beyond the time at which it is due to merge with another galaxy. Also, we typically don’t want satellite nodes to evolve too far ahead of their host node, such that any interactions between satellite and host occur (near) synchronously.

The following timestep criteria ensure that tree evolution occurs in a way which correctly preserves tree structure and ordering of interactions between node. All criteria are considered and the largest \(\Delta t\) consistent with all criteria is selected.

Branch segment criterion

For node which are the primary progenitor of their parent, the “branch segment” criterion asserts that

\[\Delta t \le t_\mathrm{parent} - t\]

where \(t\) is current time in the node and \(t_\mathrm{parent}\) is the time of the parent node. This ensures that primary progenitor node to not evolve beyond the time at which their parent (which they will replace) exists. If this criterion is the limiting criteria for \(\Delta t\) then the node will be promoted to replace its parent at the end of the timestep.

Parent criterion

For node which are satellites in a hosting node the “parent” timestep criterion asserts that

\[\begin{split}\Delta t & \le t_\mathrm{host}, \\ \Delta t & \le \epsilon_\mathrm{host} (a/\dot{a}),\end{split}\]

where \(t_\mathrm{host}=\)[timestepHostAbsolute], \(\epsilon_\mathrm{host}=\)[timestepHostRelative], and \(a\) is expansion factor. These criteria are intended to prevent a satellite for evolving too far ahead of the host node before the host is allowed to “catch up”.

Satellite criterion

For node which host satellite node, the “satellite” criterion asserts that

\[\Delta t \le \hbox{min}(t_\mathrm{satellite}) - t,\]

where \(t\) is the time of the host node and \(t_\mathrm{satellite}\) are the times of all satellite node in the host. This criterion prevents a host from evolving ahead of any satellites.

Sibling criterion

For node which are primary progenitor, the “sibling” criterion asserts that

\[\Delta t \le \hbox{min}(t_\mathrm{sibling}) - t,\]

where \(t\) is the time of the host node and \(t_\mathrm{sibling}\) are the times of all siblings of the node. This criterion prevents a node from reaching its parent (and being promoted to replace it) before all of its siblings have reach the parent and have become satellites within it.

Mergee criterion

For node with mergee node, the “mergee” criterion asserts that

\[\Delta t \le \hbox{min}(t_\mathrm{merge}) - t,\]

where \(t\) is the time of the host node and \(t_\mathrm{merge}\) are the times at which the mergee will merge. This criterion prevents a node from evolving past the time at which a merger event takes place.

(Default implementation)

Methods

  • factors — Compute factors needed for tidal tensor calculation.

  • tidalTensorGet — Get the tidal tensor.

Parameters

  • [allTreesExistAtFinalTime] (boolean; default .true.) — Specifies whether or not all merger trees are expected to exist at the final requested output time. If set to false, then trees which finish before a given output time will be ignored.

  • [dumpTreeStructure] (boolean; default .false.) — Specifies whether merger tree structure should be dumped to a dot file.

  • [timestepHostRelative] (real; default 0.1d0) — The maximum allowed relative timestep for node evolution relative to the time of the host halo.

  • [timestepHostAbsolute] (real; default 1.0d0) — The maximum allowed absolute timestep (in Gyr) for node evolution relative to the time of the host halo.

  • [fractionTimestepSatelliteMinimum] (real; default 0.0d0) — The minimum fraction of the timestep imposed by the “satellite in host” criterion to evolve over. If the timestep allowed is smaller than this fraction, the actual timestep will be reduced to zero. This avoids forcing satellites to take a large number of very small timesteps, and instead defers evolving a satellite until a large timestep can be taken.

  • [backtrackToSatellites] (boolean; default .false.) — If true, after successfully evolving a node with satellites, revisit the satellites and attempt to evolve them again.

  • [profileSteps] (boolean; default .false.) — Specifies whether or not to profile the ODE evolver.

mergerTreeEvolverThreaded

An OpenMP threaded merger tree evolver. This class extends the mergerTreeEvolverStandard merger tree evolver class. To evolve the tree, a list of evolvable nodes is constructed and then a set of parallel threads is spawned which take nodes from that list, evolve them, and add them to a second list for postprocessing. This repeats until tree evolution is completed.

Parameters

  • [allTreesExistAtFinalTime] (boolean; default .true.) — Specifies whether or not all merger trees are expected to exist at the final requested output time. If set to false, then trees which finish before a given output time will be ignored.

  • [dumpTreeStructure] (boolean; default .false.) — Specifies whether merger tree structure should be dumped to a dot file.

  • [timestepHostRelative] (real; default 0.1d0) — The maximum allowed relative timestep for node evolution relative to the time of the host halo.

  • [timestepHostAbsolute] (real; default 1.0d0) — The maximum allowed absolute timestep (in Gyr) for node evolution relative to the time of the host halo.

  • [fractionTimestepSatelliteMinimum] (real; default 0.0d0) — The minimum fraction of the timestep imposed by the “satellite in host” criterion to evolve over. If the timestep allowed is smaller than this fraction, the actual timestep will be reduced to zero. This avoids forcing satellites to take a large number of very small timesteps, and instead defers evolving a satellite until a large timestep can be taken.

  • [profileSteps] (boolean; default .false.) — Specifies whether or not to profile the ODE evolver.

  • [reportTiming] (boolean; default .false.) — If true, report on timing of serial and parallel sections.

  • [backtrackToSatellites] (boolean; default .false.) — If true, after successfully evolving a node with satellites, revisit the satellites and attempt to evolve them again. (inherited from mergerTreeEvolverStandard)