vice.mlr.ka1997
===============

Compute either the lifetime or the mass of a dying star according to
the mass-lifetime relation of Kodama & Arimoto (1997) [1]_.

**Signature**: vice.mlr.ka1997(qty, Z = 0.014, which = "mass")

.. versionadded:: 1.3.0

Parameters
----------
qty : float
	Either the mass of a star in :math:`M_\odot` or the age of a
	stellar population in Gyr. Interpretion set by the keyword
	argument ``which``.
Z : float [default : 0.014]
	The metallicity by mass of the stellar population.
which : str [case-insensitive] [default : "mass"]
	The interpretation of ``qty``: either ``"mass"`` or ``"age"``
	(case-insensitive). If ``which == "mass"``, then ``qty`` represents
	a stellar mass in :math:`M_\odot` and this function will compute a
	lifetime in Gyr. Otherwise, ``qty`` represents the age of a stellar
	population and the mass of a star with the specified lifetime will
	be calculated.

Returns
-------
x : float
	If ``which == "mass"``, the lifetime of a star of that mass and
	metallicity in Gyr according to Kodama & Arimoto (1997).
	If ``which == "age"``, the mass of a star in :math:`M_\odot` with
	the specified lifetime in Gyr.

Notes
-----
Kodama & Arimoto (1997) quantified their mass-lifetime relation using
stellar evolution tracks computed with the code presented in Iwamoto &
Saio (1999) [2]_. They report lifetimes on a table of stellar mass and
metallicity, which VICE stores as internal data. To compute lifetimes
at any mass and metallicity, it runs a 2-dimensional linear
interpolation function between the appropriate elements of the
mass-metallicity grid, linearly extrapolating to higher or lower masses
or metallicities as needed.

This form of the mass-lifetime relation quantifies the
*total* lifetimes of stars (i.e. the post main sequence lifetimes are
included a priori, and calculating main sequence lifetimes only is
not available).

Because an interpolation scheme is used to compute lifetimes, inverting
the relationship to compute masses from ages must be done numerically.
For this, VICE makes use of the bisection root-finding algorithm
described in chapter 9 of Press, Teukolsky, Vetterling & Flannery
(2007) [3]_.

Example Code
------------
>>> import vice
>>> vice.mlr.ka1997(1) # the lifetime of the sun
11.225750000000001
>>> vice.mlr.ka1997(1, Z = 0.007) # at half solar metallicity
9.674165
>>> vice.mlr.ka1997(1, which = "age") # what mass lives 1 Gyr?
2.2440397491455073
>>> vice.mlr.ka1997(2, which = "age") # 2 Gyr?
1.6146153297424315
>>> vice.mlr.ka1997(2, Z = 0.007, which = "age")
1.5497655410766602
>>> vice.mlr.ka1997(3)
0.44375200000000004
>>> vice.mlr.ka1997(3, Z = 0.007)
0.40909550000000006
>>> vice.mlr.ka1997(3, Z = 0.007, which = "age")
1.3685676021575928

.. [1] Kodama & Arimoto (1997), A&A, 320, 41
.. [2] Iwamoto & Saio (1999), ApJ, 521, 297
.. [3] Press, Teukolsky, Vetterling & Flannery (2007), Numerical
	Recipes, Cambridge University Press