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 precisionReturn the time to which the
nodecan be evolved. The current limiting time is provided astimeEnd. Optionally, the procedure pointertaskcan 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. ThetaskSelfpointer may be set to point to the timestep object and will be made available to the timestep task subroutine. Note that thetaskwill 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 ThedeadlockStatusargument should be set toisNotDeadlocked(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 thereportargument istruethen the function should report the value oftimestepprior to exiting. (This is used in reporting on timestepping criteri in deadlocked trees.) It is recommended that the report be made using theEvolve_To_Time_Report()function. Additionally, if the optionallockNodeandlockTypearguments are present then additional information can be supplied to aid in diagnosing deadlock conditions. If the current task is limiting the timestep then thelockNodepointer should be set to point to whichever node is causing the limit (which may benodeor some other node, e.g. a satellite ofnode, etc.), andlockTypeshould be set to a short description label identifying the type of limit.double precision , intent(in ) :: timeEndtype (treeNode ), intent(inout) , target :: nodeprocedure (timestepTask ), intent( out) , pointer :: taskclass (* ), intent( out) , pointer :: taskSelflogical , intent(in ) :: reporttype (treeNode ), intent( out), optional, pointer :: lockNodetype (varying_string), intent( out), optional :: lockType
refuseToEvolve→logicalReturn 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:
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:
historyTimeCosmic time (in Gyr);
historyExpansionExpansion factor;
historyStarFormationRateVolume averaged star formation rate (in \(\mathrm{M}_\odot/\)Gyr/Mpc\(^3\)).
historyDiskStarFormationRateVolume averaged star formation rate in disks (in \(\mathrm{M}_\odot/\)Gyr/Mpc\(^3\)).
historySpheroidStarFormationRateVolume averaged star formation rate in spheroids (in \(\mathrm{M}_\odot/\)Gyr/Mpc\(^3\)).
historyStellarDensityVolume averaged stellar mass density (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).
historyDiskStellarDensityVolume averaged stellar mass density in disks (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).
historySpheroidStellarDensityVolume averaged stellar mass density in spheroids (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).
historyGasDensityVolume averaged cooled gas density (in \(\mathrm{M}_\odot/\)Mpc\(^3\)).
historyNodeDensityVolume 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
[acceptedStateCount](default100) — The number of states to use in acceptance rate statistics.[timeBegin](default0.05d0*ageUniverse) — The earliest time at which to tabulate the volume averaged history of galaxies (in Gyr).[timeEnd](defaultageUniverse) — The latest time at which to tabulate the volume averaged history of galaxies (in Gyr).[historyCount](default30) — 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
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](default0.1d0) — The maximum allowed relative change in time for a single step in the evolution of a node.[fractionTimestepMinimum](default0.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]— 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 givennode.extractInteger— Extract the integer properties from the givennode.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
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](default0.05d0*ageUniverse) — The earliest time at which to tabulate the evolution of main branch progenitor galaxies (in Gyr).[timeEnd](defaultageUniverse) — The latest time at which to tabulate the evolution of main branch progenitor galaxies (in Gyr).[countSteps](default100) — 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
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
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](default0.010d0) — The maximum absolute time difference (in Gyr) allowed between merging pairs of galaxies.[timeOffsetMaximumRelative](default0.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
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
[efficiencyWind](default2.2157d-3) — The coupling efficiency of the black hole accretion-driven wind, defined as the fraction of the accreted rest-mass energy that is deposited as kinetic or thermal energy into the surrounding gas via AGN-driven outflows.[redshiftReionization](default9.97d0) — The redshift of reionization below which baryonic accretion onto halos is suppressed due to the ionizing background heating the intergalactic medium and preventing gas from accreting onto low-mass halos.[opticalDepthReionization]— The optical depth to electron scattering below which baryonic accretion is suppressed.[velocitySuppressionReionization](default35.0d0) — The velocity scale below which baryonic accretion is suppressed.[accretionNegativeAllowed](default.true.) — Specifies whether negative accretion (mass loss) is allowed in the simple halo accretion model.[accretionNewGrowthOnly](default.false.) — Specifies whether accretion from the IGM is allowed only when a halo is growing past its previous greatest mass.[acceptedStateCount](default100) — The number of states to use in acceptance rate statistics.[timeStepRelative](default0.1d0) — The maximum allowed relative change in time for a single step in the evolution of a node.[timeStepAbsolute](default1.0d0) — The maximum allowed absolute change in time (in Gyr) for a single step in the evolution of a node.[timeStepMinimum](default1.0d-6) — The smallest timestep to use in profiling ODE solver steps.[timeStepMaximum](default1.0d+1) — The largest timestep to use in profiling ODE solver steps.[timeStepPointsPerDecade](default3) — The number of bins per decade of timestep to use when profiling ODE solver steps.[wavelength](default1.0d4) — The wavelength of the photon packet (in AA).[wavelengthMinimum](default0.5d4) — The minimum wavelength of the photon packet (in AA).[wavelengthMaximum](default2.0d4) — The maximum wavelength of the photon packet (in AA).[luminosity](default1.0d0) — The luminosity of the photon packet (in \(L_\odot\)).[massRatioMajorMerger](default0.25d0) — The mass ratio above which mergers are considered to be “major”.[destinationGasMinorMerger](defaultvar_str('spheroid')) — The component to which satellite galaxy gas moves to as a result of a minor merger.[destinationStarsMinorMerger](defaultvar_str('spheroid')) — The component to which satellite galaxy stars move to as a result of a minor merger.[degreesOfFreedom](default3.0d0) — Number of degrees of freedom to assume when computing the energy density of cooling gas in the “simple” cooling time class.[timeScale](default1.0d0) — The timescale (in Gyr) for cooling in the simple cooling rate model.[reionizationRedshift](default9.97d0) — The redshift of reionization in the simple IGM state model.[reionizationTemperature](default1.0d4) — The post-reionization temperature (in units of Kelvin) in the simple IGM state model.[preReionizationTemperature](default10.0d0) — The pre-reionization temperature (in units of Kelvin) in the simple IGM state model.[useFormationHalo](default.false.) — Specifies whether or not the “formation halo” should be used when solving for the radii of galaxies.[solveForInactiveProperties](default.true.) — If true, galactic structure is solved for during evaluation of inactive property integrals. Otherwise, structure is not solved for during this phase—this should only be used if the inactive property integrands do not depend on galactic structure.[rateFractionalMaximum](default10.0d0) — The maximum fractional mass loss rate per dynamical time in the simple model of mass loss due to tidal stripping.[beta](default1.0d0) — The scaling factor which multiplies the tidal mass loss rate.[OmegaMatter](default0.3153d0) — The density of matter in the Universe in units of the critical density.[OmegaBaryon](default0.04930d0) — The density of baryons in the Universe in units of the critical density.[OmegaDarkEnergy](default0.6847d0) — The density of dark energy in the Universe in units of the critical density.[temperatureCMB](default2.72548d0) — The present day temperature of the CMB in units of Kelvin.[HubbleConstant](default67.36d0) — The present day value of the Hubble parameter in units of km/s/Mpc.
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.
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. Iffalse, then the velocity dispersions are assumed to equal the characteristic velocity of dark matter and spheroid.[bondiHoyleAccretionEnhancementSpheroid](default5.0d0) — The factor by which the Bondi-Hoyle accretion rate of spheroid gas onto black holes is enhanced.[bondiHoyleAccretionEnhancementHotHalo](default6.0d0) — The factor by which the Bondi-Hoyle accretion rate of hot halo gas onto black holes is enhanced.[bondiHoyleAccretionEnhancementNuclearStarCluster](default5.0d0) — The factor by which the Bondi-Hoyle accretion rate of 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](default1.0d2) — The assumed temperature (in Kelvin) of gas in the spheroid when computing Bondi-Hoyle accretion rates onto black holes.[bondiHoyleAccretionTemperatureNuclearStarCluster](default1.0d2) — The assumed temperature (in Kelvin) of gas in the 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](default1.0d0) — The mass below which stars are assumed to be infinitely long-lived in the instantaneous approximation for stellar evolution.[ageEffective](default13.8d0) — The effective age to use for computing SNeIa yield when using the instantaneous stellar evolution approximation.[recycledFraction](default0.0d0) — The recycled fraction to use in the instantaneous stellar evolution approximation. (If not specified it will be computed internally.)[metalYield](default0.0d0) — The metal yield to use in the instantaneous stellar evolution approximation. (If not specified it will be computed internally.)[integrationToleranceRelative](default4.0d-3) — The relative tolerance used when integrating the flux of stellar populations through filters.[integrationToleranceDegrade](default.false.) — Iftrue, 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](defaultinputPath(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](default0.01d0) — The absolute tolerance used in solving differential equations for node evolution.[odeToleranceRelative](default1.0d-2) — The relative tolerance used in solving differential equations for node evolution.[odeJacobianStepSizeRelative](default0.01d0) — The relative step size to use when perturbing properties for purposes of computing a finite difference approximation to the ODE system Jacobian.[odeAlgorithm](defaultvar_str('rungeKuttaCashKarp')) — The algorithm to use in the ODE solver.[odeAlgorithmNonJacobian](defaultvar_str('rungeKuttaCashKarp')) — The algorithm to use in the ODE solver.[odeLatentIntegratorType](defaultvar_str('trapezoidal')) — The type of integrator to use for latent variables.[odeLatentIntegratorOrder](default15) — The order of the integrator for latent variables.[odeLatentIntegratorIntervalsMaximum](default1000) — 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](default0.1d0) — The maximum allowed relative timestep for node evolution relative to the time of the host halo.[timestepHostAbsolute](default1.0d0) — The maximum allowed absolute timestep (in Gyr) for node evolution relative to the time of the host halo.[fractionTimestepSatelliteMinimum](default0.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](defaultvar_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](defaultvar_str('x')) — Axis label for the property (x-axis) of the output analysis.[yAxisLabel](defaultvar_str('y')) — Axis label for the function value (y-axis) of the output analysis.[targetLabel](defaultvar_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 thevalueTargetarray.[initialMassForSupernovaeTypeII](default8.0d0) — The minimum mass that a star must have in order that is result in a Type II supernova.[supernovaEnergy](default1.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 \(10^{51}\) erg corresponds to the standard core-collapse supernova energy.[efficiency](default0.1d0) — Specifies the efficiency with which outflowing gas is stripped from the hot halo, following the prescription of Font et al. (2008; i.e. this is the parameter \(\epsilon_\mathrm{strip}\) in their eqn. 6).
mergerTreeEvolveTimestepStarFormationHistory¶
A merger tree evolution timestepping class that limits the timestep to the next bin in the star formation history.
Parameters
[component]— The component from which to extract star formation history.