vice.mlr.mm1989
===============

Compute either the lifetime or the mass of a dying star according to
the mass-lifetime relation of Maeder & Meynet (1989) [1]_.

**Signature**: vice.mlr.mm1989(qty, postMS = 0.1, 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``.
postMS : float [default : 0.1]
	The ratio of a star's post main sequence lifetime to its main
	sequence lifetime. Zero to compute the main sequence lifetime
	alone, or the main sequence turnoff mass when ``which == "age"``.
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 Maeder & Meynet (1989).
	If ``which == "age"``, the mass of a star in :math:`M_\odot` with
	the specified lifetime in Gyr.

Notes
-----
The mass-lifetime relation of Maeder & Meynet (1989) is given by:

.. math:: \log_{10}\tau = \alpha \log_{10}(M/M_\odot) + \beta

for stellar masses below 60 :math:`M_\odot`. Above this mass, the
lifetime is given by:

.. math:: \tau = 1.2\left(\frac{M}{M_\odot}\right)^{-1.85} + 0.003

and in both cases, :math:`\tau` is in Gyr.

Though this form was originally published in Maeder & Meynet (1989),
in detail the form here is taken from Romano et al. (2005) [2]_.

The timescale :math:`\tau` quantifies only the main sequence lifetime
of stars; the parameter ``postMS`` specifies the length of the post
main sequence lifetime. This parameterization neglects the metallicity
dependence of the mass-lifetime relation.

The values of the coefficients :math:`\alpha` and :math:`\beta` vary
with stellar mass according to (:math:`m = M/M_\odot`):

+------------------------------+------------------+------------------+
| Mass Range                   | :math:`\alpha`   | :math:`\beta`    |
+------------------------------+------------------+------------------+
| :math:`m \leq 1.3`           | -0.6545          | 1                |
+------------------------------+------------------+------------------+
| :math:`1.3 < m \leq 3`       | -3.7             | 1.35             |
+------------------------------+------------------+------------------+
| :math:`3 < m \leq 7`         | -2.51            | 0.77             |
+------------------------------+------------------+------------------+
| :math:`7 < m \leq 15`        | -1.78            | 0.17             |
+------------------------------+------------------+------------------+
| :math:`15 < m \leq 60`       | -0.86            | -0.94            |
+------------------------------+------------------+------------------+

In calculating stellar masses from ages (i.e. when ``which == "age"``),
the equation must be solved 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.mm1989(1) # the lifetime of the sun
11.0
>>> vice.mlr.mm1989(1, postMS = 0) # main sequence lifetime only
10.0
>>> vice.mlr.mm1989(1, which = "age") # what mass lives 1 Gyr?
2.3775540199279783
>>> vice.mlr.mm1989(2, which = "age") # 2 Gyr?
1.9712891674041746
>>> vice.mlr.mm1989(2, postMS = 0, which = "age") # MS turnoff mass
1.9207444791793824
>>> vice.mlr.mm1989(3)
0.42271148013148074
>>> vice.mlr.mm1989(3, postMS = 0)
0.38428316375589155
>>> vice.mlr.mm1989(3, which = "age")
1.721426746368408

.. [1] Maeder & Meynet (1989), A&A, 210, 155
.. [2] Romano et al. (2005), A&A, 430, 491
.. [3] Press, Teukolsky, Vetterling & Flannery (2007), Numerical
	Recipes, Cambridge University Press