.. _physics-mergerTreeEvolver: 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 :galacticus-class:`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`` .. _physics-mergerTreeEvolverNonEvolving: ``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]`` (default ``.false.``) — If true, prune the tree to the evolve-to-time after each evolution. .. _physics-mergerTreeEvolverStandard: ``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 :math:`\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 :math:`\Delta t` using an adaptive :term:`ODE` solver, which adjusts the smaller timesteps, :math:`\delta t`, taken in evolving the system of :term:`ODE` to maintain a specified precision. The choice of :math:`\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 :term:`node`. All criteria are considered and the largest :math:`\Delta t` consistent with all criteria is selected. Branch segment criterion For :term:`node` which are the :term:`primary progenitor` of their :term:`parent`, the "branch segment" criterion asserts that .. math:: \Delta t \le t_\mathrm{parent} - t where :math:`t` is current time in the :term:`node` and :math:`t_\mathrm{parent}` is the time of the :term:`parent` :term:`node`. This ensures that :term:`primary progenitor` :term:`node` to not evolve beyond the time at which their :term:`parent` (which they will replace) exists. If this criterion is the limiting criteria for :math:`\Delta t` then the :term:`node` will be promoted to replace its :term:`parent` at the end of the timestep. Parent criterion For :term:`node` which are satellites in a hosting :term:`node` the ":term:`parent`" timestep criterion asserts that .. math:: \Delta t & \le t_\mathrm{host}, \\ \Delta t & \le \epsilon_\mathrm{host} (a/\dot{a}), where :math:`t_\mathrm{host}=`\ ``[timestepHostAbsolute]``, :math:`\epsilon_\mathrm{host}=`\ ``[timestepHostRelative]``, and :math:`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 :term:`node` which host satellite :term:`node`, the "satellite" criterion asserts that .. math:: \Delta t \le \hbox{min}(t_\mathrm{satellite}) - t, where :math:`t` is the time of the host :term:`node` and :math:`t_\mathrm{satellite}` are the times of all satellite :term:`node` in the host. This criterion prevents a host from evolving ahead of any satellites. Sibling criterion For :term:`node` which are :term:`primary progenitor`, the "sibling" criterion asserts that .. math:: \Delta t \le \hbox{min}(t_\mathrm{sibling}) - t, where :math:`t` is the time of the host :term:`node` and :math:`t_\mathrm{sibling}` are the times of all siblings of the :term:`node`. This criterion prevents a :term:`node` from reaching its :term:`parent` (and being promoted to replace it) before all of its siblings have reach the :term:`parent` and have become satellites within it. Mergee criterion For :term:`node` with :term:`mergee` :term:`node`, the ":term:`mergee`" criterion asserts that .. math:: \Delta t \le \hbox{min}(t_\mathrm{merge}) - t, where :math:`t` is the time of the host :term:`node` and :math:`t_\mathrm{merge}` are the times at which the :term:`mergee` will merge. This criterion prevents a :term:`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** * ``[stellarDensityChangeBinaryMotion]`` (default ``.true.``) — If true, account for the change in stellar density caused by the black hole binary's motion through the stellar background when computing the hardening rate of the binary via stellar scattering. * ``[computeVelocityDispersion]`` (default ``.false.``) — Specifies whether or not the velocity dispersion of dark matter and stars should be computed using Jeans equation in black hole binary hardening calculations. If ``false``, then the velocity dispersions are assumed to equal the characteristic velocity of dark matter and spheroid. * ``[bondiHoyleAccretionEnhancementSpheroid]`` (default ``5.0d0``) — The factor by which the Bondi-Hoyle accretion rate of spheroid gas onto black holes is enhanced. * ``[bondiHoyleAccretionEnhancementHotHalo]`` (default ``6.0d0``) — The factor by which the Bondi-Hoyle accretion rate of hot halo gas onto black holes is enhanced. * ``[bondiHoyleAccretionEnhancementNuclearStarCluster]`` (default ``5.0d0``) — The factor by which the Bondi-Hoyle accretion rate of :term:`NSC` gas onto black holes is enhanced. * ``[bondiHoyleAccretionHotModeOnly]`` (default ``.true.``) — Determines whether accretion from the hot halo should only occur if the halo is in the hot accretion mode. * ``[bondiHoyleAccretionTemperatureSpheroid]`` (default ``1.0d2``) — The assumed temperature (in Kelvin) of gas in the spheroid when computing Bondi-Hoyle accretion rates onto black holes. * ``[bondiHoyleAccretionTemperatureNuclearStarCluster]`` (default ``1.0d2``) — The assumed temperature (in Kelvin) of gas in the :term:`NSC` when computing Bondi-Hoyle accretion rates onto black holes. * ``[instantaneousRecyclingApproximation]`` (default ``.false.``) — If true, then use an instantaneous recycling approximation when computing recycling rates. * ``[instantaneousYieldApproximation]`` (default ``.false.``) — If true, then use an instantaneous recycling approximation when computing yield rates. * ``[instantaneousEnergyInputApproximation]`` (default ``.false.``) — If true, then use an instantaneous recycling approximation when computing energy input rates. * ``[massLongLived]`` (default ``1.0d0``) — The mass below which stars are assumed to be infinitely long-lived in the instantaneous approximation for stellar evolution. * ``[ageEffective]`` (default ``13.8d0``) — The effective age to use for computing SNeIa yield when using the instantaneous stellar evolution approximation. * ``[recycledFraction]`` (default ``0.0d0``) — The recycled fraction to use in the instantaneous stellar evolution approximation. (If not specified it will be computed internally.) * ``[metalYield]`` (default ``0.0d0``) — The metal yield to use in the instantaneous stellar evolution approximation. (If not specified it will be computed internally.) * ``[integrationToleranceRelative]`` (default ``4.0d-3``) — The relative tolerance used when integrating the flux of stellar populations through filters. * ``[integrationToleranceDegrade]`` (default ``.false.``) — If ``true``, automatically degrade the relative tolerance used when integrating the flux of stellar populations through filters to ensure convergence. * ``[storeToFile]`` (default ``.true.``) — Specifies whether or not stellar populations luminosities (integrated under a filter) should be stored to file for rapid reuse. * ``[storeDirectory]`` (default ``inputPath(pathTypeDataDynamic)//'stellarPopulations'``) — Specifies the directory to which stellar populations luminosities (integrated under a filter) should be stored to file for rapid reuse. * ``[maximumAgeExceededIsFatal]`` (default ``.true.``) — Specifies whether or not exceeding the maximum available age of the stellar population is fatal. * ``[inactiveBoundMass]`` (default ``.false.``) — Specifies whether or not the bound mass variable of the standard satellite component is inactive (i.e. does not appear in any ODE being solved). * ``[odeToleranceAbsolute]`` (default ``0.01d0``) — The absolute tolerance used in solving differential equations for node evolution. * ``[odeToleranceRelative]`` (default ``1.0d-2``) — The relative tolerance used in solving differential equations for node evolution. * ``[odeJacobianStepSizeRelative]`` (default ``0.01d0``) — The relative step size to use when perturbing properties for purposes of computing a finite difference approximation to the ODE system Jacobian. * ``[odeAlgorithm]`` (default ``var_str('rungeKuttaCashKarp')``) — The algorithm to use in the ODE solver. * ``[odeAlgorithmNonJacobian]`` (default ``var_str('rungeKuttaCashKarp')``) — The algorithm to use in the ODE solver. * ``[odeLatentIntegratorType]`` (default ``var_str('trapezoidal')``) — The type of integrator to use for latent variables. * ``[odeLatentIntegratorOrder]`` (default ``15``) — The order of the integrator for latent variables. * ``[odeLatentIntegratorIntervalsMaximum]`` (default ``1000``) — The maximum number of intervals allowed in the integrator for latent variables. * ``[profileOdeEvolver]`` (default ``.false.``) — Specifies whether or not to profile the ODE evolver. * ``[reuseODEStepSize]`` (default ``.true.``) — If true, re-use the previous ODE step size when resuming the evolution of a node. Otherwise, the initial step size is not specified. * ``[enforceNonNegativity]`` (default ``.false.``) — If true, properties that are marked as non-negative (e.g. masses) will be evolved in such a way as to enforce that non-negativity. * ``[allTreesExistAtFinalTime]`` (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]`` (default ``.false.``) — Specifies whether merger tree structure should be dumped to a `dot `_ file. * ``[timestepHostRelative]`` (default ``0.1d0``) — The maximum allowed relative timestep for node evolution relative to the time of the host halo. * ``[timestepHostAbsolute]`` (default ``1.0d0``) — The maximum allowed absolute timestep (in Gyr) for node evolution relative to the time of the host halo. * ``[fractionTimestepSatelliteMinimum]`` (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]`` (default ``.false.``) — If true, after successfully evolving a node with satellites, revisit the satellites and attempt to evolve them again. * ``[profileSteps]`` (default ``.false.``) — Specifies whether or not to profile the ODE evolver. * ``[outputsGroupName]`` (default ``var_str('Outputs')``) — The name of the HDF5 group to which outputs will be written. * ``[outputReferences]`` (default ``.false.``) — Specifies whether or not references to individual merger tree datasets should be output. * ``[xAxisLabel]`` (default ``var_str('x')``) — Axis label for the property (x-axis) of the output analysis. * ``[yAxisLabel]`` (default ``var_str('y')``) — Axis label for the function value (y-axis) of the output analysis. * ``[targetLabel]`` (default ``var_str('')``) — Label identifying the comparison/target dataset, if any. * ``[xAxisIsLog]`` (default ``.false.``) — Whether the x-axis should be displayed on a logarithmic scale. * ``[yAxisIsLog]`` (default ``.false.``) — Whether the y-axis should be displayed on a logarithmic scale. * ``[valueTarget]`` — Target dataset values to compare against, one per bin of the output analysis. * ``[covarianceTarget]`` — Target-dataset covariance matrix corresponding to the ``valueTarget`` array. * ``[initialMassForSupernovaeTypeII]`` (default ``8.0d0``) — The minimum mass that a star must have in order that is result in a Type II supernova. * ``[supernovaEnergy]`` (default ``1.0d51``) — The canonical energy released per supernova event (in ergs), used to compute the total mechanical energy input from the supernova population; the default value of :math:`10^{51}` erg corresponds to the standard core-collapse supernova energy. * ``[efficiency]`` (default ``0.1d0``) — Specifies the efficiency with which outflowing gas is stripped from the hot halo, following the prescription of :cite:author:`font_colours_2008` (:cite:year:`font_colours_2008`; i.e. this is the parameter :math:`\epsilon_\mathrm{strip}` in their eqn. 6). .. _physics-mergerTreeEvolverThreaded: ``mergerTreeEvolverThreaded`` ----------------------------- An OpenMP threaded merger tree evolver. This class extends the :galacticus-class:`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]`` (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]`` (default ``.false.``) — Specifies whether merger tree structure should be dumped to a `dot `_ file. * ``[timestepHostRelative]`` (default ``0.1d0``) — The maximum allowed relative timestep for node evolution relative to the time of the host halo. * ``[timestepHostAbsolute]`` (default ``1.0d0``) — The maximum allowed absolute timestep (in Gyr) for node evolution relative to the time of the host halo. * ``[fractionTimestepSatelliteMinimum]`` (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]`` (default ``.false.``) — Specifies whether or not to profile the ODE evolver. * ``[reportTiming]`` (default ``.false.``) — If true, report on timing of serial and parallel sections.