.. highlight:: rest
.. _sec-parameters:
The SLUG Input Deck
====================
SLUG command-line simulations are controlled by an input deck, and input decks can
also be used to control SLUG when it is run as a Python module. The input deck is a
`TOML `_ file which contains human-readable key-value pairs
that control various aspects of the simulation. The input deck is read by SLUG at
runtime when SLUG is run in command-line mode, and the :ref:`sec-slugpy` Python module
provides a class to read input decks which can then be used to control the simulation
in Python -- see :ref:`sec-running` for details.
The input deck contains some top-level key-value pairs that control basic operations
of the simulation, followed by a series of sections that control either some aspect
of simulation physics or some part of the simulation operation. Some of these keywords
and sections are required, while others are optional and have default values. Some
example input decks can be found in the ``examples`` directory of the repository
(see :ref:`sec-examples`).
Below is a full section-by-section listing of the input deck keywords and their meanings,
organized by section.
Numerical Values vs. Distributions vs. Files
---------------------------------------------
Many of the keywords below (the IMF, CMF, CLF, [Fe/H], star formation rate, and
V-band extinction) describe a quantity that SLUG treats as a probability
distribution function (PDF) rather than a fixed value -- see :ref:`sec-pdfs` for
the full set of distributions SLUG understands and how to describe them in a file
of their own. For all such keywords, the corresponding input deck value may be
given in either of two forms:
* A bare number, which is interpreted as a delta function at that value (i.e., the
quantity is fixed, not stochastic).
* A string naming a PDF descriptor file, which is parsed to construct the
corresponding distribution.
Unless noted otherwise, a file name given for one of these keywords (or for
``stars.tracks``, ``spectra.model``, ``phot.filters``, ``extinct.model``, and the
various ``*_registry``/``registry`` overrides below) is resolved by first checking
for a file of that name in the current working directory. If none is found and the
name is not an absolute path, SLUG then searches the following directories, in order,
using the first match it finds:
#. The directory named by the ``SLUG_DIR`` environment variable, if it is set.
#. Each directory listed in the ``SLUG_DATA_PATH`` environment variable, if it is
set, in order. ``SLUG_DATA_PATH`` is a list of directories separated by colons, in
the same format as ``PATH``. When slugpy is imported, or SLUG is run through the
``slug`` command installed by ``pip`` (see :ref:`sec-getting`), it automatically
adds two directories to the start of this list: the per-user directory into which
``python -m slugpy.download_data`` downloads data files by default, and the
directory inside the installed slugpy package that holds the small data files
bundled with it. This is how a PyPI or container installation finds its data files
without ``SLUG_DIR`` being set.
#. The top-level directory of the source repository SLUG was compiled from, if it was
compiled in place from a source checkout (see :ref:`sec-compiling`). This last
step does not apply to installations made with ``pip``.
Most of these keywords resolve directly under each of these search directories, but a
few (``stars.IMF``, and the internal defaults for track/spectral/filter/extinction
registries) are resolved under a fixed subdirectory of ``data/`` instead -- this is
noted individually below where it applies.
.. _ssec-parameters-toplevel:
Top-level Keywords
------------------
These keywords must appear at the top level of the input deck, outside of any section.
They control basic aspects of the simulation, such as the type of simulation to run
and the number of trials to perform.
* ``sim_type`` (required): The type of simulation to run. Must be either ``"cluster"``
(a single simple stellar population, formed all at once) or ``"galaxy"`` (a composite
population, built up over time from a star formation history) -- see
:ref:`sec-running` for the distinction.
* ``n_trial`` (optional, default=1): The number of independent Monte Carlo trials to run.
* ``verbosity`` (optional, default=0): The level of diagnostic output SLUG prints while running.
Setting to 1 will cause SLUG to print when it starts, restarts, or ends, and to list any
keys in the input deck that were valid but not used for this simulation (see
:ref:`ssec-parameters-unused`); setting to 2 or more will cause slug to print at the
start of every trial.
* ``strict_input`` (optional, default=false): If true, any key in the input deck that SLUG
never uses is an error and stops SLUG before it starts, instead of just a warning -- see
:ref:`ssec-parameters-unused`.
* ``rng_seed`` (optional): An integer seed for SLUG's random number generator. If not
given, SLUG seeds itself from the operating system's own entropy source, so
repeated runs of the same input deck will not produce identical results unless a
fixed seed is given.
.. _ssec-parameters-unused:
Unused Keywords
---------------
Any key in the input deck that SLUG never reads is reported when the deck is read. This
almost always means a mistake: a misspelled keyword, or a keyword given in the wrong
section, either of which would otherwise be silently ignored, leaving the default in
place. For example, ``n_trial`` is a top-level keyword, so giving it in the ``[output]``
section has no effect, and produces
::
slug: warning: input deck key 'output.n_trial' (line 18) was never used; did you mean 'n_trial'?
The message gives the full name of the key (the section, then the key), its line in the
input deck, and, when SLUG can tell, the key it was probably meant to be: either the same
name in a different section, or a close misspelling of a keyword that SLUG looked for and
did not find. The run then continues, so check the output of any run whose deck produces
this warning. If ``strict_input`` is true (see :ref:`ssec-parameters-toplevel`), SLUG
instead stops with an error that lists every unused key.
Some keys are valid but have no effect for a particular simulation, for example
``nebular.log_U`` when ``nebular.compute_neb`` is false, ``clusters.CLF`` and the
``[galaxy]`` section in a cluster simulation, or the ``[spectra]`` and ``[extinct]``
settings when no spectral synthesis or extinction was requested. These are not mistakes,
so they do not produce a warning. If ``verbosity`` is 1 or higher, SLUG instead prints a
note for each one, giving the reason it was not used:
::
slug: note: input deck key 'clusters.CLF' (line 12) was ignored: sim_type is "cluster"; this key is only used by galaxy simulations
When SLUG is used from Python, the same information is available as the ``unusedKeys`` and
``ignoredKeys`` properties of a ``SimControls`` object, and ``strictInput`` gives the value
of ``strict_input``.
.. _ssec-parameters-output:
Output Control Keywords
-----------------------
These keywords, in the ``[output]`` section, control what outputs are produced by
the simulation, how they are formatted, and where they are written.
* ``model_name`` (optional, default="slug_sim"): The base name used for this
model's output file(s).
* ``output_times``: Specifies the simulation time(s), in yr, at which output should
be written. This may be given either as a number/PDF (see above) -- in which case
every trial draws its own single output time from it -- or as an explicit array of
times, in which case every trial produces output at each of the listed times.
Exactly one of ``output_times`` or the ``start_time`` / ``end_time`` / ``ntime`` trio
below must be given.
* ``start_time``, ``end_time``, ``ntime``: An alternative to ``output_times``, these
three keywords (which must all be given together) specify a grid of ``ntime``
output times running from ``start_time`` to ``end_time`` (in yr), shared by every
trial. ``start_time`` and ``end_time`` may only be equal if ``ntime`` = 1, and vice versa.
* ``log_time`` (optional, default=false): If true, the ``start_time`` / ``end_time`` / ``ntime``
grid above is spaced logarithmically rather than linearly; requires ``start_time`` > 0.
* ``write_cluster`` (optional, default=true): Whether to write basic properties for
each individual star cluster.
* ``write_cluster_spec`` (optional, default=true): Whether to write the spectrum of
each individual star cluster; only meaningful if spectral synthesis has been requested
(see ``spectra.model`` below).
* ``write_cluster_phot`` (optional, default=true): Whether to write the photometry
of each individual star cluster; only meaningful if photometry has been requested
(see ``phot.filters`` below).
* ``write_galaxy`` (optional, default=true; galaxy simulations only): Whether to
write basic properties for the galaxy as a whole.
* ``write_galaxy_spec`` (optional, default=true; galaxy simulations only): Whether
to write the integrated spectrum of the whole galaxy.
* ``write_galaxy_phot`` (optional, default=true; galaxy simulations only): Whether
to write the integrated photometry of the whole galaxy.
* ``write_cluster_yields`` (optional, default=true): Whether to write the nucleosynthetic
yields of each individual star cluster; only meaningful if yield channels have been
requested (see ``yields.channelN`` below).
* ``write_galaxy_yields`` (optional, default=true; galaxy simulations only): Whether
to write the nucleosynthetic yields of the whole galaxy; only meaningful if yield
channels have been requested (see ``yields.channelN`` below).
* ``write_cluster_feedback`` (optional, default=true): Whether to write the feedback
of each individual star cluster, i.e., its cumulative number of supernovae and the
instantaneous mass, momentum, and energy fluxes of its stellar winds (see
:ref:`sec-feedback` and ``[feedback]`` below).
* ``write_galaxy_feedback`` (optional, default=true; galaxy simulations only): Whether
to write the feedback of the whole galaxy, i.e., the same quantities as
``write_cluster_feedback``, summed over all clusters, field stars, and the
non-stochastic part of the population.
* ``output_mode`` (optional, default="h5"): The output file format. Must be one of
``h5`` / ``hdf5`` (a single, consolidated HDF5 file), ``h5divided`` / ``hdf5divided``
(HDF5 output, but skipping consolidation when SLUG is built with OpenMP, leaving
one file per thread), or ``ascii`` / ``txt`` (plain-text output).
* ``out_dir`` (optional, default=""): The directory into which output should be
written. An empty string (the default) writes into the current working directory.
* ``checkpoint_interval`` (optional, default=0): The number of trials between
checkpoints; 0 disables checkpointing. Only supported when ``output_mode`` is
``h5`` or ``h5divided`` -- a non-zero value combined with ``ascii`` output is an error.
At least one of the ``write_*`` keywords relevant to the simulation's own
``sim_type`` must be left true, and if ``phot.filters`` was given, at least one of
``write_cluster_phot`` / ``write_galaxy_phot`` must be true -- otherwise SLUG raises
an error at startup, since the corresponding output(s) would otherwise never be written.
The same holds for yields: if any ``yields.channelN`` was given, ``write_cluster_yields``
must be true for a cluster simulation, and at least one of ``write_cluster_yields`` /
``write_galaxy_yields`` must be true for a galaxy simulation.
.. _ssec-parameters-integrator:
Integrator Control Keywords
----------------------------
These optional keywords, in the ``[integrator]`` section, control the numerical
tolerances SLUG's adaptive PDF integrator uses wherever it must integrate over a
continuous (non-stochastic) population. The defaults are chosen to be reasonable
for typical SLUG simulations and rarely need to be changed.
* ``rel_tol`` (optional, default=1e-2): The integrator's relative error tolerance.
* ``abs_tol`` (optional, default=1e-3): The integrator's absolute error tolerance.
* ``max_iter`` (optional, default=524288, i.e. 2^19): The maximum number of
integrand evaluations the integrator is allowed before giving up; 0 means unlimited.
.. _ssec-parameters-stars:
Stellar Population Keywords
-----------------------------
These keywords, in the ``[stars]`` section, describe the stellar population itself
-- the initial mass function, the stellar evolutionary tracks, and related
composition/rotation settings.
* ``IMF`` (required): The stellar initial mass function, as a number or PDF (see
above). A file name is resolved under ``data/imfs`` within each of the search
directories described above, after first checking the current working directory.
The following IMF
models are included in the SLUG repo: ``chabrier.toml`` (a Chabrier 2005 IMF),
``chabrier03.toml`` (a Chabrier 2003 IMF), ``kroupa.toml`` (a Kroupa 2002 IMF),
``salpeter.toml`` (a Salpeter IMF), and ``weidner_kroupa06.toml`` (one version
of the Weidner & Kroupa 2006 IGIMF model).
* ``tracks`` (required): The name of the stellar evolutionary track set to use
(e.g. ``"MIST"``), as listed in the track registry (see ``track_registry`` below).
* ``track_registry`` (optional, default="data/tracks/tracks.toml"): Overrides the
default registry file used to look up ``tracks``.
* ``FeH`` (required): The stellar metallicity, [Fe/H], as a number or PDF (see above).
* ``v_vcrit`` (optional, default=0.0): The stellar rotation rate, as a fraction of
the critical (breakup) velocity; shared by the tracks and, if used, the nebular
emission grid.
* ``alphaFe`` (optional, default=0.0): The stellar [alpha/Fe] abundance ratio;
shared by the tracks and the spectral synthesis model.
* ``CFe`` (optional, default=0.0): The stellar [C/Fe] abundance ratio; used only by
the spectral synthesis model (the tracks have no corresponding axis).
* ``min_stoch_mass`` (optional, default=0.0): The minimum stellar mass treated
fully stochastically; stars below this mass are instead drawn from the
continuous part of the IMF.
.. _ssec-parameters-cluster:
Cluster Keywords
-------------------
These keywords, in the ``[clusters]`` section, describe the population of star
clusters formed by the simulation.
* ``CMF`` (required): The cluster mass function, as a number or PDF (see above).
* ``CLF`` (required for galaxy simulations; unused for cluster simulations): The
cluster lifetime function, as a number or PDF (see above). When clusters form
in a galaxy simulation, their lifetimes are drawn from the CLF, and clusters
that exceed their lifetime are considered disrupted and are no longer output in
the list of clusters in the galaxy (though the light produced by their stars
still contributes to the integrated galaxy light).
* ``f_cluster`` (optional, default=1.0; galaxy simulations only): The fraction of a
galaxy simulation's stellar mass formed in individually-tracked, stochastic
clusters; the remainder is treated as "field" stars whose formation times are
continuously-distributed.
.. _ssec-parameters-galaxy:
Galaxy Keywords
-------------------
These keywords, in the ``[galaxy]`` section, describe the star formation history of
a galaxy simulation, and are only used (and only permitted) when ``sim_type`` =
``"galaxy"``. Exactly one of ``sfr`` / ``sfr_dist`` must be given.
* ``sfr``: The star formation rate as a function of time. A bare number gives a
constant rate, in Msun/yr, shared by every trial; a string names a PDF descriptor
file giving the (possibly time-varying) rate directly -- unlike every other
file-valued keyword described above, this file name is resolved relative to the
current working directory only, not via the search directories described above.
* ``sfr_dist``: A distribution (number or PDF, as above) from which each trial
independently draws its own single, constant star formation rate, in Msun/yr.
Unlike ``sfr``, a bare number here is treated as an ordinary delta function, as
for every other PDF-valued keyword.
.. _ssec-parameters-specsyn:
Spectral Synthesis Keywords
------------------------------
These keywords, in the ``[spectra]`` section, control spectral synthesis. The
entire section is optional: if ``model`` is not given, no spectra (and, since
photometry and extinction both require a spectral synthesizer, no photometry or
extinction) are computed for this simulation.
* ``model`` (required to enable spectral synthesis): The spectral synthesis
model(s) to use. May be ``"blackbody"`` (approximate every star as a blackbody,
needing no stellar atmosphere library), ``"default"`` (a standard, physically
comprehensive chain of atmosphere libraries covering the whole HR diagram, from
Wolf-Rayet winds through white dwarf atmospheres), the name of a single atmosphere
library from the spectral registry (see ``registry`` below), or an array of such
library names, in which case the libraries are chained together, each covering
whichever stars fall outside the coverage of the ones before it.
* ``registry`` (optional, default="data/spectra/spectra.toml"): Overrides the
default registry file used to look up ``model``.
* ``wl_min``, ``wl_max``, ``nwl`` (optional; must be given together): Override the
default output wavelength grid (roughly 91 to 1e5 Angstrom at 2048 points) with a
grid of ``nwl`` points spanning ``wl_min`` to ``wl_max`` Angstrom.
* ``z`` (optional, default=0.0): A redshift applied to every computed spectrum.
.. _ssec-parameters-phot:
Photometry Keywords
-----------------------
These keywords, in the ``[phot]`` section, control the computation of photometry
from the synthesized spectra. The entire section is optional: if ``filters`` is not
given (or names no filters), no photometry is computed. Using this section requires
spectral synthesis to also be enabled (see ``spectra.model`` above).
* ``filters`` (required to enable photometry): The filter(s) to compute photometry
in, as a string (for a single filter) or array of strings. Most filter names take
the form ``facility.instrument.filter`` (or ``facility.filter`` where a facility
has only one instrument), as listed in the filter registry (see ``registry``
below); idealized filters (e.g. ionizing photon rates) are also available, named
``Q(...)``. The special name ``"Lbol"`` requests the bolometric luminosity, which
is computed directly from the spectrum rather than through the ordinary filter
machinery.
* ``system`` (optional, default="Flambda"): The photometric system to report
magnitudes/fluxes in. Must be one of ``Flambda``, ``Fnu``, ``ST``, ``AB``, or ``Vega``.
* ``registry`` (optional, default="data/filters/filters.toml"): Overrides the
default registry file used to look up ``filters``.
* ``vega`` (optional): Overrides the default reference Vega spectrum file used by
the ``Vega`` photometric system.
.. _ssec-parameters-extinct:
Extinction Keywords
-----------------------
These keywords, in the ``[extinct]`` section, control dust extinction applied to
the synthesized spectra and photometry. The entire section is optional: if neither
``AV`` nor ``AV_field`` is given, no extinction is applied. Using this section
requires spectral synthesis to also be enabled (see ``spectra.model`` above).
* ``AV`` (optional): The V-band extinction, in mag, applied to stars in
individually-tracked clusters, as a number or PDF (see above).
* ``AV_field`` (optional; galaxy simulations only): The V-band extinction applied
to the continuous ("field") stellar population, as a number or PDF. If ``AV`` is
given but ``AV_field`` is not (or vice versa), the missing one defaults to a
fixed extinction of zero, rather than being left unset.
* ``neb_factor`` (optional, default=1.0): A multiplicative factor applied to the
extinction of nebular emission relative to the extinction of stellar light; this
can be a number or a PDF (see above). The default value of 1.0 means that nebular
emission is extincted by the same amount as stellar light, while a value of
2.1 means the nebular emission is 2.1 times more extincted than the stellar light,
the ratio inferred by
`Calzetti et al. 1994 `_.
* ``model`` (required if ``AV`` or ``AV_field`` is given): The name of the
extinction curve to apply, as listed in the extinction registry (see ``registry`` below).
* ``registry`` (optional, default="data/extinct/extinct.toml"): Overrides the
default registry file used to look up ``model``.
.. _ssec-parameters-nebular:
Nebular Emission Keywords
-----------------------------
These keywords, in the ``[nebular]`` section, control the contribution of nebular
(ionized gas) emission to the computed spectra and photometry. Unlike most of the
sections above, every keyword here is independently optional and simply falls back
to its own default if omitted.
* ``compute_neb`` (optional, default=true if spectral synthesis is enabled, false
otherwise): Whether nebular emission is computed at all. Nebular emission is added to
the synthesized spectra, so it requires spectral synthesis to be enabled (see
``spectra.model`` above): explicitly setting ``compute_neb`` to true without it is
an error. If false, every other keyword in this section is ignored.
* ``log_U`` (optional, default=-2.5): The base-10 logarithm of the ionization parameter.
* ``cov_fac`` (optional, default=0.5): The nebular covering factor (the fraction of
ionizing photons that actually ionize gas within the covering material, as
opposed to escaping).
* ``line_width`` (optional, default=20.0): The assumed width of nebular emission
lines, in km/s.
* ``table`` (optional, default=``data/nebular/nebular.h5``): Overrides the default
nebular emission grid used to compute nebular contributions for this simulation's
own track set.
.. _ssec-parameters-yields:
Yields Control Keywords
-----------------------
These keywords, in the ``[yields]`` section, control the calculation of the
nucleosynthetic yields of the stellar population, i.e., the mass of each isotope that
the population has returned to the interstellar medium. The entire section is
optional: if no ``channelN`` table is given, no yields are computed and no yield output
is written. Unlike spectra, photometry, and extinction, yields do not require spectral
synthesis to be enabled. See :ref:`sec-yields` for the physics of how yields are
computed.
* ``channelN`` (at least ``channel1`` required to enable yields): Each yield
channel is described by its own subtable, ``[yields.channel1]``,
``[yields.channel2]``, etc. Channels must be numbered consecutively starting at 1;
SLUG stops reading at the first number that is missing, so a ``channel3`` given
without a ``channel2`` is ignored (and reported as an unused key -- see
:ref:`ssec-parameters-unused`). Depending on ``channel_decomposed`` (see below),
the yields from different channels are reported separately or summed together.
Each subtable has the following keywords:
* ``channel`` (required): The type of nucleosynthetic source this channel
represents. See :ref:`sec-yields` for the list of available channels; SLUG
raises an error at startup if the value is not one of them.
* ``model`` (required): The name of the yield table to use for this channel, as
listed in the yield registry (see ``registry`` below). See :ref:`sec-yields` for
the list of models included in the default data set. Each model has a specified
range in [Fe/H], and the range of [Fe/H] in ``stars.FeH`` must lie within the
range covered by the model, or SLUG raises an error at startup. The registry
lists the models available for each channel separately, so it is also an error
to name a model that the registry does not list for the ``channel`` you have
chosen; for example, ``kobayashi06_11`` is available for ``ccsn`` but not for
``massive_star_winds``.
* ``m_min`` (optional, default=the lowest mass tabulated by the model): The
minimum initial stellar mass, in Msun, that contributes to this channel. If
not specified, the minimum stellar mass contributing to the channel is the
minimum tabulated mass provided in the selected ``model``; the same applies
to ``m_max``.
* ``m_max`` (optional, default=the highest mass tabulated by the model): The
maximum initial stellar mass, in Msun, that contributes to this channel. Stars
with masses outside the range ``m_min`` to ``m_max`` contribute nothing to this
channel. If this range extends beyond the masses tabulated by the model, the
yields are extrapolated by scaling the yields of the nearest tabulated mass in
proportion to the stellar mass. Together, ``m_min`` and ``m_max`` allow the mass
range of one channel to be split between several different models, by giving
several channels of the same type with different mass ranges. Both ``m_min`` and
``m_max`` must be positive, and ``m_min`` must be strictly less than ``m_max``
once the defaults have been applied, or SLUG raises an error at startup. In
particular, since an omitted ``m_max`` defaults to the highest mass tabulated by
the model, an ``m_min`` above that mass is an error unless a larger ``m_max`` is
given as well.
* ``registry`` (optional, default="data/yields/yields.toml"): Overrides the
default registry file used to look up the ``model`` of each channel.
* ``isotopes`` (optional): An array of strings selecting which isotopes are included
in the yield calculation and output. Each entry is an element symbol followed
immediately by a mass number, e.g. ``["H1", "He4", "Fe56"]``; symbols are not case
sensitive. SLUG automatically adds every isotope that is connected to the ones you
list by radioactive decay, so that the yield of each listed isotope is complete and
the decay calculation stays consistent: (i) every isotope that decays, directly or
through intermediates, into a listed isotope, and (ii) every decay product of any
isotope that is included. For example, with ``min_isotope_lifetime = 0`` (see below),
listing ``Fe56`` also includes ``Ni56`` and ``Co56``, which decay into it, and listing
``Ni56`` also includes ``Co56`` and ``Fe56``. Isotopes shorter-lived than
``min_isotope_lifetime`` are never included, even if listed; decay links are
followed through them, so their long-lived parents and descendants are still
included. Only isotopes that the requested models tabulate, or that are decay
products of isotopes they tabulate, can be added this way. The emission of a proton or
alpha particle (``H1`` or ``He4``) is not counted as a decay link when searching for
the parents of a listed isotope, so listing ``H1`` or ``He4`` does not add every
proton or alpha emitter; an included alpha emitter does, however, bring its ``He4``
decay product with it. If ``isotopes`` is not given, every isotope tabulated by at
least one of the requested models is included, plus any radioactive decay products of
those isotopes. An entry that is a valid isotope but that none of the requested models
tabulates is ignored, but SLUG raises an error if no entry matches anything. Entries
that are not well formed are always errors, whether or not other entries are valid:
an entry with no mass number (e.g. ``"H"``), an unrecognized element symbol (e.g.
``"Xx12"``), or a mass number for which SLUG's isotope table has no such isotope (e.g.
``"Fe999"``), as is giving ``isotopes`` as anything other than an array of strings. An
isotope that some requested models tabulate and others do not has zero yield from the
models that do not.
* ``channel_decomposed`` (optional, default=true): If true, yields are reported
separately for each channel, so the output has one value per (channel, isotope) pair.
If false, the yields from all channels are summed, so the output has only one value
per isotope. See :ref:`sec-output` for details on how the outputs are formatted.
`Warning:` some yield models contain large numbers of isotopes, and using
``channel_decomposed`` output with such tables plus multiple channels can produce
voluminous outputs.
* ``no_decay`` (optional, default=false): If false, the reported yield of each isotope
is the mass actually present at the output time, i.e., accounting for radioactive
decay of the isotope since it was produced, and for the accumulation of the daughter
products of other isotopes' decays. If true, radioactive decay is ignored, and
the reported yield is the total mass of each isotope produced, whether or not it
has since decayed.
* ``min_isotope_lifetime`` (optional, default=1e4): Minimum lifetime, in yr, of the
radioactive isotopes that SLUG tracks explicitly. Any unstable isotope with a shorter
lifetime is treated as decaying the instant it is produced: it is removed from the
isotope list, and it does not appear in the output. Its own yield is added to those of
its first descendants whose lifetimes are at least ``min_isotope_lifetime`` (or that
are stable), and decays of other isotopes that would produce it produce those
descendants directly. This approximation is accurate for yields at times long
compared to ``min_isotope_lifetime``, and it can make the calculation of decayed
yields much faster. Larger values (up to ~1e5) are faster still, and are
appropriate if yields are only needed at times of several Myr or more; values much
larger than this begin to approximate isotopes that have not yet decayed by the ages of
interest, and so should be avoided. Set ``min_isotope_lifetime = 0`` to track every
isotope explicitly, though this can be very slow and, because it forces the time
integrals to resolve extremely short lifetimes, may also be less accurate at a given
integration tolerance. This applies whether or not ``no_decay`` is set, so with ``no_decay =
true`` the reported yields are those that would be present if every isotope shorter
lived than ``min_isotope_lifetime`` had decayed, and no others. Must be non-negative,
or SLUG raises an error at startup.
For example, the following requests yields from both core-collapse supernovae and
winds, using the same model for both, for only a few isotopes:
.. code-block:: toml
[yields]
isotopes = ["H1", "He4", "C12", "O16", "Fe56"]
[yields.channel1]
channel = "ccsn"
model = "sukhbold16"
[yields.channel2]
channel = "massive_star_winds"
model = "sukhbold16"
Since the two channels are reported separately by default, this gives ten columns of
yield data in all. ``Ni56`` and ``Co56``, which decay into ``Fe56``, are not reported,
because their lifetimes are shorter than the default ``min_isotope_lifetime``; their
yields are included in that of ``Fe56``. Adding ``min_isotope_lifetime = 0`` would
instead report seven isotopes per channel, since listing ``Fe56`` would then also
include ``Ni56`` and ``Co56`` (see ``isotopes`` above), for fourteen columns in all. See :ref:`ssec-troubleshooting-yields` for the
errors SLUG reports for problems with the ``[yields]`` section.
.. _ssec-parameters-feedback:
Feedback Control Keywords
-------------------------
These keywords, in the ``[feedback]`` section, control the calculation of feedback
from the stellar population: the number of core-collapse supernovae and the mass,
momentum, and energy fluxes of stellar winds. The entire section is optional, and
every keyword in it has a default. See :ref:`sec-feedback` for the physics of how
feedback is computed and a full description of each wind model.
* ``sn_mass_range`` (optional, default=none): An array of initial stellar masses, in
Msun, specifying the mass range or ranges in which stars end their lives as
core-collapse supernovae. The array is read as consecutive (lower, upper) pairs,
each giving one mass interval (including its endpoints); giving more than one pair
specifies disjoint intervals, which can be used to describe mass gaps due to failed
supernovae. For example, ``sn_mass_range = [8.0, 20.0, 25.0, 120.0]`` means that
stars with initial masses from 8 to 20 Msun and from 25 to 120 Msun explode as
supernovae, and no others do. The array must have an even number of elements, all
of which must be finite, positive, and strictly increasing, or SLUG raises an error
at startup. If ``sn_mass_range`` is given and non-empty, it overrides any supernova
mass range implied by the yield model. If it is omitted or empty, the range of masses
that produce supernovae is taken from the ``ccsn`` yield channel (see
``yields.channelN`` above); if there is no such channel either, no supernovae are
counted.
* ``wr_winds`` (optional, default="nugis_lamers_00"): The wind velocity model for
Wolf-Rayet stars. Must be one of ``nugis_lamers_00``, ``l_over_c``, or ``none``.
* ``ob_winds`` (optional, default="vink_sander_21"): The wind velocity model for O and
B stars. Must be one of ``vink_sander_21``, ``vink_01``, or ``none``.
* ``agb_winds`` (optional, default="slug2"): The wind velocity model for RGB and AGB
stars. Must be one of ``slug2`` or ``none``.
* ``other_winds`` (optional, default="vesc"): The wind velocity model for all stars not
in one of the above three categories. Must be one of ``vesc`` or ``none``.
An unrecognized name for any of the four wind models causes SLUG to raise an error at
startup. Setting a wind model to ``none`` sets the wind velocity, and thus the wind
momentum and energy fluxes, of stars in that category to zero; it does not change their
wind mass fluxes, which come from the stellar tracks. For example, the following uses a
fixed supernova mass range of 8 to 40 Msun and turns off winds from Wolf-Rayet stars,
while leaving the other wind models at their defaults:
.. code-block:: toml
[feedback]
sn_mass_range = [8.0, 40.0]
wr_winds = "none"