Merger Tree Evolution Timesteps

Class providing timestep control during merger tree evolution—objects that determine the maximum time to which a given node can be evolved in a single ODE integration step. Each implementation imposes a constraint on the timestep (e.g.a fraction of the dynamical time, the time to the next snapshot, the time to a satellite merger event) and optionally registers a callback task to execute at the end of the timestep. The shortest timestep from all registered instances determines the actual integration step.

Default implementation: mergerTreeEvolveTimestepStandard

Methods

timeEvolveTo → double precision

Return the time to which the node can be evolved. The current limiting time is provided as timeEnd. Optionally, the procedure pointer task can be set to point to a subroutine which will be called after the node is evolved to the end of the timestep. It is acceptable for this pointer to be null. The taskSelf pointer may be set to point to the timestep object and will be made available to the timestep task subroutine. Note that the task will only be called for the task which provided the shortest timestep—other tasks can always request to be called again when the next timestep is determined. The subroutine to be called at the end of the timestep must have the form: .. code-block:: none subroutine timestepTask(self,tree,node,deadlockStatus) implicit none class(* ), intent(inout) :: self type (mergerTree ), intent(inout) :: tree type (treeNode ), intent(inout), pointer :: node type (enumerationDeadlockStatusType), intent(inout) :: deadlockStatus … return end subroutine timestepTask The deadlockStatus argument should be set to isNotDeadlocked (provided by the Merger_Trees_Evolve_Deadlock_Status module) if, and only if, the end of timestep task makes some change to the state of the tree (e.g. merging a node), to indicate that the tree was not deadlocked in this pass (i.e. something actually changed in the tree). If the report argument is true then the function should report the value of timestep prior to exiting. (This is used in reporting on timestepping criteri in deadlocked trees.) It is recommended that the report be made using the Evolve_To_Time_Report() function. Additionally, if the optional lockNode and lockType arguments are present then additional information can be supplied to aid in diagnosing deadlock conditions. If the current task is limiting the timestep then the lockNode pointer should be set to point to whichever node is causing the limit (which may be node or some other node, e.g. a satellite of node, etc.), and lockType should be set to a short description label identifying the type of limit.

• double precision , intent(in ) :: timeEnd

• type (treeNode ), intent(inout) , target :: node

• procedure (timestepTask ), intent( out) , pointer :: task

• class (* ), intent( out) , pointer :: taskSelf

• logical , intent(in ) :: report

• type (treeNode ), intent( out), optional, pointer :: lockNode

• type (varying_string), intent( out), optional :: lockType

refuseToEvolve → logical

Return true if evolution should be refused.

• type(treeNode), intent(inout) :: node

mergerTreeEvolveTimestepHistory

A merger tree evolution timestepping class which records and outputs volume averaged properties of the model universe as a function of time. Timesteps are enforced such that:

\[\Delta t \le t_{\mathrm{history},i} - t\]

where \(t\) is the current time, \(t_{\mathrm{history},i}\) is the \(i^\mathrm{th}\) time at which the global history of galaxies is to be output and \(i\) is chosen to be the smallest \(i\) such that \(t_{\mathrm{history},i} > t\). If there is no \(i\) for which \(t_{\mathrm{history},i} > t\) this criterion is not applied. If this criterion is the limiting criterion for \(\Delta t\) then the properties of the galaxy will be accumulated to the global history arrays at the end of the timestep.

Volume-averaged properties are stored to the globalHistory group of the output file. Currently, the properties stored are:

historyTime

Cosmic time (in Gyr);

historyExpansion

Expansion factor;

historyStarFormationRate

Volume averaged star formation rate (in \(\mathrm{M}_\odot/\)Gyr/Mpc\(^3\)).

historyDiskStarFormationRate

Volume averaged star formation rate in disks (in \(\mathrm{M}_\odot/\)Gyr/Mpc\(^3\)).

historySpheroidStarFormationRate

Volume averaged star formation rate in spheroids (in \(\mathrm{M}_\odot/\)Gyr/Mpc\(^3\)).

historyStellarDensity

Volume averaged stellar mass density (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).

historyDiskStellarDensity

Volume averaged stellar mass density in disks (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).

historySpheroidStellarDensity

Volume averaged stellar mass density in spheroids (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).

historyGasDensity

Volume averaged cooled gas density (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).

historyNodeDensity

Volume averaged resolved node density (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).

Dimensionful datasets have a unitsInSI attribute which gives their units in the SI system.

Methods

• operator(+) — Addition operator.

• operator(-) — Subtraction operator.

• operator(/) — Division operator.

• operator(*) — Multiplication operator.

• isZero — Returns true if the history is entirely zero.

• create — Creates a history object with a specified range of times.

• builder — Build a history object from an XML definition.

• dump — Dump a history object.

• dumpRaw — Dump a history object in binary.

• readRaw — Read a history object in binary.

• clone — Clone a history object.

• destroy — Destroys a history object.

• trim — Removes any times in a history which have become outdated.

• trimForward — Removes any times in a history after the given time. Optionally returns a history object with the removed history.

• increment — Adds two histories, possibly with different time series.

• interpolatedIncrement — Adds two histories, possibly with different time series, by interpolating the second onto the times of the first and adding the interpolated values.

• extend — Extends the time range of a history to encompass the specified limits.

• reset — Resets all entries in a history to zero.

• setToUnity — Set all entries in a history to unity.

• exists — Returns true if the given history has been created.

• timeSteps — Returns an array with the timesteps (i.e. the intervals between successive times) in the given history.

• serializeCount — Return a count of the number of properties in a serialized history object.

• serialize — Serialize a history object to an array.

• deserialize — Deserialize a history object from an array.

• append — Append a history or single instant onto the end of a history.

• nonStaticSizeOf — Returns the size of any non-static components of the type.

• create — Creates a history object with a specified range of times.

• builder — Build a history object from an XML definition.

• dump — Dump a history object.

• dumpRaw — Dump a history object in binary.

• readRaw — Read a history object in binary.

• clone — Clone a history object.

• destroy — Destroys a history object.

• trim — Removes any times in a history which have become outdated.

• trimForward — Removes any times in a history after the given time. Optionally returns a history object with the removed history.

• reset — Resets all entries in a history to zero.

• exists — Returns true if the given history has been created.

• append — Append a history or single instant onto the end of a history.

• nonStaticSizeOf — Returns the size of any non-static components of the type.

Parameters

• [timeBegin] (real; default 0.05d0*ageUniverse) — The earliest time at which to tabulate the volume averaged history of galaxies (in Gyr).

• [timeEnd] (real; default ageUniverse) — The latest time at which to tabulate the volume averaged history of galaxies (in Gyr).

• [historyCount] (integer; default 30) — The number of steps (spaced logarithmically in cosmic time) at which to tabulate the volume averaged history of galaxies.

mergerTreeEvolveTimestepHostTidalMassLoss

A merger tree evolution timestepping class that enforces

\[\Delta t \le \epsilon_\mathrm{hostTidalMassLoss} (M_\mathrm{host}/\dot{M}_\mathrm{host}|),\]

where \(\epsilon_\mathrm{hostTidalMassLoss}=\)[timeStepRelative], and \(M_\mathrm{host}\) is the bound mass of the host satellite. This criterion is intended to prevent any satellite evolving over an excessively large time in one step ahead of its host satellite.

Parameters

• [timeStepRelative] (real; default 0.1d0) — The maximum allowed relative change in time for a single step in the evolution of a node.

• [fractionTimestepMinimum] (real; default 0.1d0) — The minimum fraction of the timestep imposed by this timestepper 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.

mergerTreeEvolveTimestepLightconeCrossing

A merger tree evolution timestepping class which limits the integration timestep so that nodes are output precisely when they cross a lightcone boundary, enabling the construction of mock lightcone catalogs. The lightcone geometry is provided by the [geometryLightcone] object, with optional diagnostic reporting for specific node indices listed in [nodeIndicesReport].

Parameters

• [nodeIndicesReport] (integer) — A list of node indices for which reporting should be performed.

mergerTreeEvolveTimestepMulti

A merger tree evolution timestepping class which takes the minimum over multiple other timesteppers.

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.

mergerTreeEvolveTimestepRecordEvolution

A merger tree evolution timestepping class which enforces that

\[\Delta t \le t_{\mathrm{record},i} - t\]

where \(t\) is the current time, \(t_{\mathrm{record},i}\) is the \(i^\mathrm{th}\) time at which the evolution of main branch galaxies is to be output and \(i\) is chosen to be the smallest \(i\) such that \(t_{\mathrm{record},i} > t\). If there is no \(i\) for which \(t_{\mathrm{record},i} > t\) this criterion is not applied. If this criterion is the limiting criterion for \(\Delta t\) then the properties of the galaxy will be recorded at the end of the timestep.

Timesteps are logarithmically spaced in cosmic time between [timeBegin] and newline [timeEnd], with the total number of timesteps specified by [countSteps].

This recorded evolution will be written to the group mainProgenitorEvolution in the Galacticus output file. Within that group two datasets, time and expansionFactor, give the times and expansion factors at which evolution was recorded. Then for each merger tree two datasets, stellarMass<N> and totalMass<N> (where <N> is the merger tree index), give the stellar and total baryonic mass of the main branch progenitor at each timestep.

Methods

• reset — Reset the record of galaxy evolution.

Parameters

• [timeBegin] (real; default 0.05d0*ageUniverse) — The earliest time at which to tabulate the evolution of main branch progenitor galaxies (in Gyr).

• [timeEnd] (real; default ageUniverse) — The latest time at which to tabulate the evolution of main branch progenitor galaxies (in Gyr).

• [countSteps] (integer; default 100) — The number of steps (spaced logarithmically in cosmic time) at which to tabulate the evolution of main branch progenitor galaxies.

mergerTreeEvolveTimestepSatellite

A merger tree evolution timestepping class which enforces the following for satellite node. If the satellite’s merge target has been advanced to at least a time of \(t_\mathrm{required} = t_\mathrm{satellite} + \Delta t_\mathrm{merge} - \delta t_\mathrm{merge,maximum}\) then

\[\Delta t \le \Delta t_\mathrm{merge},\]

where \(t_\mathrm{satellite}\) is the current time for the satellite node, \(\Delta t_\mathrm{merge}\) is the time until the satellite is due to merge and \(\delta t_\mathrm{merge,maximum}\) is the maximum allowed time difference between merging galaxies. This ensures that the satellite is not evolved past the time at which it is due to merge. If this criterion is the limiting criteria for \(\Delta t\) then the merging of the satellite will be triggered at the end of the timestep.

If the merge target has not been advanced to at least \(t_\mathrm{required}\) then instead

\[\Delta t \le \hbox{max}(\Delta t_\mathrm{merge}-\delta t_\mathrm{merge,maximum}/2,0),\]

is asserted to ensure that the satellite does not reach the time of merging until its merge target is sufficiently close (within \(\delta t_\mathrm{merge,maximum}\)) of the time of merging.

Parameters

• [timeOffsetMaximumAbsolute] (real; default 0.010d0) — The maximum absolute time difference (in Gyr) allowed between merging pairs of galaxies.

• [timeOffsetMaximumRelative] (real; default 0.001d0) — The maximum time difference (relative to the cosmic time at the merger epoch) allowed between merging pairs of galaxies.

mergerTreeEvolveTimestepSatelliteDestruction

A merger tree evolution timestepping class which limits the step to the next satellite destruction event.

mergerTreeEvolveTimestepSimple

A merger tree evolution timestepping class enforces that

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

where \(t_\mathrm{simple}=\)[timestepSimpleAbsolute], \(\epsilon_\mathrm{simple}=\)[timestepSimpleRelative], and \(a\) is expansion factor. These criteria are intended to prevent any one node evolving over an excessively large time in one step. In general, these criteria are not necessary, as nodes should be free to evolve as far as possible unless prevented by some physical requirement. These criteria are therefore present to provide a simple example of how timestep criteria work.

Methods

• calculationReset — Reset memoized calculations.

Parameters

• [timeStepRelative] (real; default 0.1d0) — The maximum allowed relative change in time for a single step in the evolution of a node.

• [timeStepAbsolute] (real; default 1.0d0) — The maximum allowed absolute change in time (in Gyr) for a single step in the evolution of a node.

mergerTreeEvolveTimestepStandard

A merger tree evolution timestepping class which limits the step to the minimum of that given by the simple, satellite, and satelliteDestruction timesteps.

(Default implementation)

Methods

• factors — Compute factors needed for tidal tensor calculation.

• tidalTensorGet — Get the tidal tensor.

mergerTreeEvolveTimestepStarFormationHistory

A merger tree evolution timestepping class that limits the timestep to the next bin in the star formation history.