.. _physics-starFormationHistory: Star Formation Histories ======================== Class providing models for recording and outputting the star formation history of galaxy components ---the star formation rate as a function of lookback time, binned by stellar age and metallicity. Implementations define how ages are discretized (fixed globally, fixed per output, or arbitrarily varying between galaxies), and provide methods to create, accumulate, and retrieve the history array. These histories are used to compute spectral energy distributions by convolving with stellar population templates, and for writing the time-resolved star formation record to output files. **Default implementation:** ``starFormationHistoryNull`` Methods ------- ``create`` → ``void`` Create and initialize the star formation history object for the given node, allocating the age and metallicity bins spanning from the specified start time to the optional end time. * ``type (treeNode), intent(inout), target :: node`` * ``type (history ), intent(inout) :: historyStarFormation`` * ``double precision , intent(in ) :: timeBegin`` * ``double precision , intent(in ), optional :: timeEnd`` ``scales`` → ``void`` Set ODE solver absolute scales for a star formation history object. * ``type (history ), intent(inout) :: historyStarFormation`` * ``type (treeNode ), intent(inout) :: node`` * ``double precision , intent(in ) :: massStellar, massGas`` * ``type (abundances), intent(in ) :: abundancesStellar`` ``rate`` → ``void`` Record the instantaneous rate of star formation in the history object for the given node, accumulating the stellar mass formed at the current time step into the appropriate age and metallicity bins. * ``type (treeNode ), intent(inout) :: node`` * ``type (history ), intent(inout) :: historyStarFormation`` * ``type (abundances), intent(in ) :: abundancesFuel`` * ``double precision , intent(in ) :: rateStarFormation`` ``metallicityBoundaries`` → ``double precision, allocatable, dimension(:)`` Return a (zero-indexed) array of metallicity boundaries for this history. ``times`` → ``double precision, allocatable, dimension(:)`` Return an array of times for this history *if* the tabulation in time is static per output. * ``type (treeNode), intent(inout), optional :: node`` * ``integer (c_size_t), intent(in ), optional :: indexOutput`` * ``type (history ), intent(in ), optional :: starFormationHistory`` * ``logical , intent(in ), optional :: allowTruncation`` * ``double precision , intent( out), optional :: timeStart`` ``timeNext`` → ``double precision`` Return the next time at which the star formation history bin structure changes for the given node, indicating when the history must be updated or extended to cover the next time interval. * ``type(treeNode), intent(inout) :: node`` * ``type(history ), intent(in ) :: starFormationHistory`` ``masses`` → ``double precision, allocatable, dimension(:,:)`` Return a 2D array (indexed by age bin and metallicity bin) of stellar masses formed for the given node's star formation history, representing the cumulative stellar mass in each age-metallicity cell. * ``type (treeNode), intent(inout) :: node`` * ``type (history ), intent(in ) :: starFormationHistory`` * ``logical , intent(in ), optional :: allowTruncation`` ``ageDistribution`` → ``type(enumerationStarFormationHistoryAgesType)`` Return an enumeration member indicating what may be assumed about the distribution of ages in the star formation histories. ``update`` → ``void`` Update the star formation history after an output time is reached. * ``type (treeNode), intent(inout), target :: node`` * ``integer(c_size_t), intent(in ) :: indexOutput`` * ``type (history ), intent(inout) :: historyStarFormation`` ``rangeIsSufficient`` → ``logical`` Return true if the star formation history spans a sufficient range of times. * ``type(history), intent(in ) :: starFormationHistory, rangeHistory`` ``extend`` → ``void`` Extend a star formation history to span a sufficient range of times. * ``type (history), intent(inout) :: starFormationHistory`` * ``double precision , intent(in ), dimension(:) :: times`` ``move`` → ``void`` Move (transfer and reset) the star formation history from one node into another, incrementing the destination history with the source data and then resetting the source to zero, as needed during galaxy mergers. * ``type(treeNode), intent(inout) :: node1 , node2`` * ``type(history ), intent(inout) :: starFormationHistory1, starFormationHistory2`` .. _physics-starFormationHistoryAdaptive: ``starFormationHistoryAdaptive`` -------------------------------- A star formation histories class which records star formation split by metallicity. The star formation history is tabulated on a grid of time and metallicity. A minimum size for the time bins is specified via :math:`\Delta t=`\ ``[timeStepMinimum]``, and a maximum number of time bins allowed is specified via ``[countTimeStepsMaximum]``. For the first output time, a set of timesteps starting from :math:`t=0` to the output time is generated with size :math:`\Delta t`. If the number of steps exceeds ``[countTimeStepsMaximum]`` then one pair of consecutive steps are merged. The pair merged is chosen to minimize the global increase in the metric :math:`(t_{i+1}-t_i)/(t\mathrm{out}-t_i)` where :math:`t_i` are the current timesteps and :math:`t_\mathrm{out}` is the output time. This process is repeated until the number of timesteps is reduced to ``[countTimeStepsMaximum]``. This results in timesteps distributed approximately uniformly in the logarithm of the age of the timestep. For subsequent output times, the prior set of times is first extended, in steps of :math:`\Delta t`, to reach the new output time, and then, if necessary, the same timestep consolidation algorithm is applied to reduce the number of steps to ``[countTimeStepsMaximum]``. Any accumulated star formation in the time bins used for the previous output time are accumulated over each consolidated pair of bins. This approach ensures that the number of timesteps never exceeds ``[countTimeStepsMaximum]``, results in timesteps that are small close to the output time, but increase (approximately logarithmically) for times earlier than the output time, and allows simple (interpolation-free) consolidation of accumulated star formation from the previous output time's timesteps to those of the current output time. The time associated with each bin is the maximum time for which star formation will be accumulated to the bin, with the minimum time corresponding to the value associated with the previous bin (or :math:`t=0` for the first bin). The metallicity bins are arranged logarithmically in metallicity with ``[countMetallicities]`` bins between ``[metallicityMinimum]`` and ``[metallicityMaximum]`` (specified in Solar units). Note that the metallicity associated with each bin is the maximum metallicity for that bin, with the minimum metallicity corresponding to the value associated with the previous bin (or zero metallicity for the first bin). Note that a final bin, extending to infinite metallicity, is always added automatically. If ``[countMetallicities]``\ :math:`=0` is set, then the star formation history is not split by metallicity (i.e. a single metallicity bin encompassing all metallicities from zero to infinity is used). Alternatively, specific metallicity bin boundaries can be set via the ``[metallicityBoundaries]`` parameter---a final boundary corresponding to infinity is always added automatically. **Parameters** * ``[timeStepMinimum]`` (real; default ``0.01d0``) — The minimum time step to use in tabulations of star formation histories [Gyr]. * ``[countTimeStepsMaximum]`` (integer; default ``10_c_size_t``) — The maximum number of timesteps to track in any star formation history. * ``[massScaleAbsolute]`` (real; default ``1.0d0``) — The absolute tolerance scale (for the mass in each bin of star formation history) to use during ODE solution. * ``[metallicityBoundaries]`` (real) — The metallicities corresponding to boundaries between metallicity bins to use when tabulating star formation histories. * ``[countMetallicities]`` (integer; default ``10_c_size_t``) — The number of bins in metallicity to use when tabulating star formation histories. * ``[metallicityMinimum]`` (real; default ``1.0d-4``) — The upper limit to the metallicity in the lowest metallicity bin when tabulating star formation histories [Solar units]. * ``[metallicityMaximum]`` (real; default ``1.0d+1``) — The upper limit to the metallicity in the highest metallicity bin when tabulating star formation histories [Solar units]. .. _physics-starFormationHistoryFixedAges: ``starFormationHistoryFixedAges`` --------------------------------- A star formation histories class which records star formation in logarithmically-sized time bins of fixed age and split by metallicity. The minimum age is specified via the ``[ageMinimum]`` parameter (the maximum age is always the age of the universe), with the number of ages specified via ``[countAges]``. (One additional bin, at age zero, is always added.) This class is intended for use with lightcone output where the lightcone crossing times for each node can be computed in advance. One star formation history is computed for each lightcone crossing. The time associated with each bin is the maximum time for which star formation will be accumulated to the bin, with the minimum time corresponding to the value associated with the previous bin (or :math:`t=0` for the first bin). The metallicity bins are arranged logarithmically in metallicity with ``[countMetallicities]`` bins between ``[metallicityMinimum]`` and ``[metallicityMaximum]`` (specified in Solar units). Note that the metallicity associated with each bin is the maximum metallicity for that bin, with the minimum metallicity corresponding to the value associated with the previous bin (or zero metallicity for the first bin). Note that a final bin, extending to infinite metallicity, is always added automatically. If ``[countMetallicities]``\ :math:`=0` is set, then the star formation history is not split by metallicity (i.e. a single metallicity bin encompassing all metallicities from zero to infinity is used). Alternatively, specific metallicity bin boundaries can be set via the ``[metallicityBoundaries]`` parameter---a final boundary corresponding to infinity is always added automatically. **Parameters** * ``[ageMinimum]`` (real; default ``0.01d0``) — The minimum age to use in tabulations of star formation histories [Gyr]. * ``[countAges]`` (integer; default ``10_c_size_t``) — The maximum number of ages to track in any star formation history. * ``[massScaleAbsolute]`` (real; default ``1.0d0``) — The absolute tolerance scale (for the mass in each bin of star formation history) to use during ODE solution. * ``[metallicityBoundaries]`` (real) — The metallicities corresponding to boundaries between metallicity bins to use when tabulating star formation histories. * ``[countMetallicities]`` (integer; default ``10_c_size_t``) — The number of bins in metallicity to use when tabulating star formation histories. * ``[metallicityMinimum]`` (real; default ``1.0d-4``) — The upper limit to the metallicity in the lowest metallicity bin when tabulating star formation histories [Solar units]. * ``[metallicityMaximum]`` (real; default ``1.0d+1``) — The upper limit to the metallicity in the highest metallicity bin when tabulating star formation histories [Solar units]. .. _physics-starFormationHistoryInSitu: ``starFormationHistoryInSitu`` ------------------------------ A star formation histories class which records *in situ* star formation. Another ``starFormationHistory`` object is used to provide the base star formation history. This class tracks a second copy which is identical but excludes any star formation from merging galaxies. .. _physics-starFormationHistoryMetallicitySplit: ``starFormationHistoryMetallicitySplit`` ---------------------------------------- A star formation histories class which records star formation split by metallicity. The star formation history is tabulated on a grid of time and metallicity. The binning in time is chosen such that bins are at most of size ``[timeStep]`` between the time at which each galaxy formed and the final output time, and at most of size ``[timeStepFine]`` in the period ``[timeFine]`` prior to each output time (all times specified in Gyr). The allows fine binning of recent star formation just prior to each output. The time associated with each bin is the maximum time for which star formation will be accumulated to the bin, with the minimum time corresponding to the value associated with the previous bin (or :math:`t=0` for the first bin). The metallicity binning is arranged logarithmically in metallicity with ``[countMetallicities]`` bins between ``[metallicityMinimum]`` and ``[metallicityMaximum]`` (specified in Solar units). The metallicity bins are arranged logarithmically in metallicity with ``[countMetallicities]`` bins between ``[metallicityMinimum]`` and ``[metallicityMaximum]`` (specified in Solar units). Note that the metallicity associated with each bin is the maximum metallicity for that bin, with the minimum metallicity corresponding to the value associated with the previous bin (or zero metallicity for the first bin). Note that a final bin, extending to infinite metallicity, is always added automatically. If ``[countMetallicities]``\ :math:`=0` is set, then the star formation history is not split by metallicity (i.e. a single metallicity bin encompassing all metallicities from zero to infinity is used). Alternatively, specific metallicity bin boundaries can be set via the ``[metallicityBoundaries]`` parameter---a final boundary corresponding to infinity is always added automatically. **Methods** * ``make`` — Make the star formation history. **Parameters** * ``[timeStep]`` (real; default ``0.1d0``) — The time step to use in tabulations of star formation histories [Gyr]. * ``[timeStepFine]`` (real; default ``0.01d0``) — The fine time step to use in tabulations of star formation histories [Gyr]. * ``[timeFine]`` (real; default ``0.1d0``) — The period prior to each output for which the fine time step is used in tabulations of star formation histories [Gyr]. * ``[massScaleAbsolute]`` (real; default ``1.0d0``) — The absolute tolerance scale (for the mass in each bin of star formation history) to use during ODE solution. * ``[metallicityBoundaries]`` (real) — The metallicities corresponding to boundaries between metallicity bins to use when tabulating star formation histories. * ``[countMetallicities]`` (integer; default ``10``) — The number of bins in metallicity to use when tabulating star formation histories. * ``[metallicityMinimum]`` (real; default ``1.0d-4``) — The upper limit to the metallicity in the lowest metallicity bin when tabulating star formation histories [Solar units]. * ``[metallicityMaximum]`` (real; default ``1.0d+1``) — The upper limit to the metallicity in the highest metallicity bin when tabulating star formation histories [Solar units]. .. _physics-starFormationHistoryNull: ``starFormationHistoryNull`` ---------------------------- A null star formation histories class that performs no recording or tracking of star formation history, used when detailed star formation history information is not required in the simulation. **(Default implementation)**