vice.yields.agb.settings
========================

The VICE dataframe: global yield settings for AGB stars

For each chemical element, this object stores the current asymptotic giant
branch (AGB) star nucleosynthetic yield setting. See `Notes`_ below for
mathematical details.

.. versionadded:: 1.2.0
	In earlier versions, functions and classes within VICE accepted keyword
	arguments or attributes which encoded which model table of yields to
	adopt. This same functionality can be achieved by assigning a string as
	the yield setting for specific elements.

.. note:: Modifying yield settings through this dataframe is equivalent
	to going through the ``vice.elements`` module.

Indexing
--------
- ``str`` [case-insensitive] : elemental symbols
	This dataframe must be indexed by the symbol of an element recognized
	by VICE as it appears on the periodic table.

Item Assignment
---------------
For each chemical element, the AGB star yield can be assigned either:

	- ``str`` [case-insensitive] : Adopt values published by a given study
		Keywords correspond to yields calculated on a table of progenitor
		masses and metallicities which can be adopted directly.

		- "cristallo11" : Cristallo et al. (2011, 2015) [1]_ [2]_
		- "karakas10" : Karakas (2010) [3]_
		- "ventura13" : Ventura et al. (2013) [4]_
		- "karakas16" : Karakas & Lugaro (2016) [5]_ ; Karakas et al. (2018)
			[6]_

		.. versionadded:: 1.3.0
			The "ventura13" and "karakas16" yields models were introduced
			in version 1.3.0.

	- <function> : Mathematical function describing the yield
		Must accept progenitor zero age main sequence mass in
		:math:`M_\odot` as the first parameter and the metallicity by
		mass :math:`Z` as the second.

Functions
---------
- keys
- todict
- restore_defaults
- factory_settings
- save_defaults

Notes
-----
VICE defines the yield from AGB stars as the fraction of a star's initial
mass which is processed into some element. As with all other yields in
VICE, these are *net* rather than *gross* yields in that they quantify only
the mass of a given element which is newly produced. For a star
of mass :math:`M_\star`, the mass of the element ejected to the ISM, not
counting previously produced nucleosynthetic material, is given by:

.. math:: M = y_\text{AGB}(M_\star, Z_\star) M_\star

where :math:`y_\text{AGB}` is the yield and :math:`Z_\star` is the initial
metallicity of the star.

This definition is retained in one- and multi-zone
chemical evolution models as well. For further details, see VICE's science
documentation: https://vice-astro.readthedocs.io/en/latest/science_documentation/index.html.

Example Code
------------
>>> import vice
>>> vice.yields.agb.settings["n"] = "cristallo11"
>>> vice.yields.agb.settings["N"]
	"cristallo11"
>>> vice.yields.agb.settings["N"] = "karakas10"
>>> vice.yields.agb.settings["n"]
	"karakas10"
>>> def f(m, z):
	return 0.001 * m * (z / 0.014)
>>> vice.yields.agb.settings["n"] = f
>>> vice.yields.agb.settings["N"]
	<function __main__.f(z)>

.. [1] Cristallo et al. (2011), ApJS, 197, 17
.. [2] Cristallo et al. (2015), ApJS, 219, 40
.. [3] Karakas (2010), MNRAS, 403, 1413
.. [4] Ventura et al. (2013), MNRAS, 431, 3642
.. [5] Kakaras & Lugaro (2016), ApJ, 825, 26
.. [6] Karakas et al. (2018), MNRAS, 477, 421




.. toctree::
	:titlesonly:
	:maxdepth: 5

	vice.yields.agb.settings.keys
	vice.yields.agb.settings.todict
	vice.yields.agb.settings.restore_defaults
	vice.yields.agb.settings.factory_settings
	vice.yields.agb.settings.save_defaults