.. _physics-mergerTreeEvolveTimestep: 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 :ref:`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`` .. _physics-mergerTreeEvolveTimestepHistory: ``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: .. math:: \Delta t \le t_{\mathrm{history},i} - t where :math:`t` is the current time, :math:`t_{\mathrm{history},i}` is the :math:`i^\mathrm{th}` time at which the global history of galaxies is to be output and :math:`i` is chosen to be the smallest :math:`i` such that :math:`t_{\mathrm{history},i} > t`. If there is no :math:`i` for which :math:`t_{\mathrm{history},i} > t` this criterion is not applied. If this criterion is the limiting criterion for :math:`\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 :math:`\mathrm{M}_\odot/`\ Gyr/Mpc\ :math:`^3`). ``historyDiskStarFormationRate`` Volume averaged star formation rate in disks (in :math:`\mathrm{M}_\odot/`\ Gyr/Mpc\ :math:`^3`). ``historySpheroidStarFormationRate`` Volume averaged star formation rate in spheroids (in :math:`\mathrm{M}_\odot/`\ Gyr/Mpc\ :math:`^3`). ``historyStellarDensity`` Volume averaged stellar mass density (in :math:`\mathrm{M}_\odot/`\ Mpc\ :math:`^3`). ``historyDiskStellarDensity`` Volume averaged stellar mass density in disks (in :math:`\mathrm{M}_\odot/`\ Mpc\ :math:`^3`). ``historySpheroidStellarDensity`` Volume averaged stellar mass density in spheroids (in :math:`\mathrm{M}_\odot/`\ Mpc\ :math:`^3`). ``historyGasDensity`` Volume averaged cooled gas density (in :math:`\mathrm{M}_\odot/`\ Mpc\ :math:`^3`). ``historyNodeDensity`` Volume averaged resolved node density (in :math:`\mathrm{M}_\odot/`\ Mpc\ :math:`^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. .. _physics-mergerTreeEvolveTimestepHostTidalMassLoss: ``mergerTreeEvolveTimestepHostTidalMassLoss`` --------------------------------------------- A merger tree evolution timestepping class that enforces .. math:: \Delta t \le \epsilon_\mathrm{hostTidalMassLoss} (M_\mathrm{host}/\dot{M}_\mathrm{host}|), where :math:`\epsilon_\mathrm{hostTidalMassLoss}=`\ ``[timeStepRelative]``, and :math:`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. .. _physics-mergerTreeEvolveTimestepLightconeCrossing: ``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. .. _physics-mergerTreeEvolveTimestepMulti: ``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. .. _physics-mergerTreeEvolveTimestepRecordEvolution: ``mergerTreeEvolveTimestepRecordEvolution`` ------------------------------------------- A merger tree evolution timestepping class which enforces that .. math:: \Delta t \le t_{\mathrm{record},i} - t where :math:`t` is the current time, :math:`t_{\mathrm{record},i}` is the :math:`i^\mathrm{th}` time at which the evolution of main branch galaxies is to be output and :math:`i` is chosen to be the smallest :math:`i` such that :math:`t_{\mathrm{record},i} > t`. If there is no :math:`i` for which :math:`t_{\mathrm{record},i} > t` this criterion is not applied. If this criterion is the limiting criterion for :math:`\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`` and ``totalMass`` (where ```` 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. .. _physics-mergerTreeEvolveTimestepSatellite: ``mergerTreeEvolveTimestepSatellite`` ------------------------------------- A merger tree evolution timestepping class which enforces the following for satellite :term:`node`. If the satellite's merge target has been advanced to at least a time of :math:`t_\mathrm{required} = t_\mathrm{satellite} + \Delta t_\mathrm{merge} - \delta t_\mathrm{merge,maximum}` then .. math:: \Delta t \le \Delta t_\mathrm{merge}, where :math:`t_\mathrm{satellite}` is the current time for the satellite :term:`node`, :math:`\Delta t_\mathrm{merge}` is the time until the satellite is due to merge and :math:`\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 :math:`\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 :math:`t_\mathrm{required}` then instead .. math:: \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 :math:`\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. .. _physics-mergerTreeEvolveTimestepSatelliteDestruction: ``mergerTreeEvolveTimestepSatelliteDestruction`` ------------------------------------------------ A merger tree evolution timestepping class which limits the step to the next satellite destruction event. .. _physics-mergerTreeEvolveTimestepSimple: ``mergerTreeEvolveTimestepSimple`` ---------------------------------- A merger tree evolution timestepping class enforces that .. math:: \Delta t & \le t_\mathrm{simple}, \\ \Delta t & \le \epsilon_\mathrm{simple} (a/\dot{a}), where :math:`t_\mathrm{simple}=`\ ``[timestepSimpleAbsolute]``, :math:`\epsilon_\mathrm{simple}=`\ ``[timestepSimpleRelative]``, and :math:`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. .. _physics-mergerTreeEvolveTimestepStandard: ``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. .. _physics-mergerTreeEvolveTimestepStarFormationHistory: ``mergerTreeEvolveTimestepStarFormationHistory`` ------------------------------------------------ A merger tree evolution timestepping class that limits the timestep to the next bin in the star formation history.