vice.yields.agb.grid
====================

Obtain the stellar mass-metallicity grid of fractional net yields from
asymptotic giant branch stars published in a nucleosynthesis study.

**Signature**: vice.yields.agb.grid(element, study = "cristallo11")

Parameters
----------
element : ``str`` [case-insensitive]
	The symbol of the element to obtain the yield grid for.
study : ``str`` [case-insensitive] [default : "cristallo11"]
	A keyword denoting which study to pull the yield table from.

	Recognized Keywords:

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

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

Returns
-------
grid : ``tuple`` (2-D)
	A tuple of tuples containing the yield grid. The first axis is the
	stellar mass, and second is the metallicity
masses : ``tuple``
	The masses in units of :math:`M_\odot` that the yield grid is sampled
	on.
z : ``tuple``
	The metallicities by mass :math:`Z` that the yield grid is sample on.

Raises
------
* ValueError
	- 	The study or the element are not built into VICE
* LookupError
	- 	``study == "karakas10"`` and the atomic number of the element is
		:math:`\geq` 29. The Karakas (2010) study did not report yields
		for elements heavier the nickel.
	- 	The Ventura et al. (2013) tables include yields only for the
		following elements: he, c, n, o, ne, na, mg, al, si. A request for
		a table for any other element with raise an exception.
* IOError [Occur's only if VICE's file structure has been modified]
	- 	The parameters passed to this function are allowed but the data
		file is not found.

Notes
-----
The AGB star yields stored by VICE are reported *as published* by each
corresponding study. With the exception of converting the values to
*fractional* yields (i.e. by dividing by progenitor initial mass), they
were not modified in any way.

Example Code
------------
>>> y, m, z = vice.agb_yield_grid("sr")
>>> m
    (1.3, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 6.0)
>>> z
    (0.0001, 0.0003, 0.001, 0.002, 0.003, 0.006, 0.008, 0.01, 0.014, 0.02)
>>> # the fractional yield from 1.3 Msun stars at Z = 0.001
>>> y[0][2]
    2.32254e-09

.. [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