vice.mlr.hpt2000
================

Compute either the lifetime or the mass of a dying star according to
the mass-lifetime relation of Hurley, Pols & Tout (2000) [1]_.

**Signature**: vice.mlr.hpt2000(qty, postMS = 0.1, 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``.
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"``.
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 the Hurley, Pols & Tout (2000)
	relation.
	If ``which == "age"``, the mass of a star in :math:`M_\odot` with
	the specified lifetime in Gyr.

Notes
-----
The Hurley, Pols & Tout (2000) relation quantifies the main sequence
lifetime according to (see their section 5.1):

.. math:: t_\text{MS} = \text{max}(\mu, x) t_\text{BGB}

where :math:`t_\text{BGB}` is the time required for the star to reach
the base of the giant branch (BGB), given by:

.. math:: t_\text{BGB} = \frac{
		a_1 + a_2 M^4 + a_3 M^{5.5} + M^7
	}{
		a_4 M^2 + a_5 M^7
	}

where :math:`M` is the mass of the star in solar masses and the
coefficients :math:`a_n` depend on metallicity in a manner described in
their Appendix A. The quantities :math:`\mu` and :math:`x` are given by

.. math:: \mu = \text{max}\left(0.5, 1.0 - 0.01\text{max}\left(
	\frac{a_6}{M^{a_7}}, a_8 + \frac{a_9}{M^{a_{10}}}\right)\right)

and

.. math:: x = \text{max}(0.95, \text{min}(0.95 - 0.03(\zeta + 0.30103),
	0.99))

where :math:`\zeta` is calculated from the metallicity by mass
:math:`Z` according to :math:`\zeta = \log_{10}(Z / 0.02)`.

VICE stores the necessary data with which to compute the coefficients
:math:`a_n` as internal data. Although this form takes into account the
metallicity dependence of stellar lifetimes, this formalism quantifies
*only* the main sequence lifetimes, with the parameter ``postMS``
quantifying the length of the post main sequence lifetime.

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) [2]_.

Example Code
------------
>>> import vice
>>> vice.mlr.hpt2000(1) # the lifetime of the sun
10.949827652466094
>>> vice.mlr.hpt2000(1, postMS = 0) # main sequence lifetime only
9.954388774969177
>>> vice.mlr.hpt2000(1, Z = 0.007) # at half solar metallicity
9.160722377683282
>>> vice.mlr.hpt2000(1, postMS = 0, Z = 0.007)
8.32792943425753
>>> vice.mlr.hpt2000(1, which = "age") # what mass lives 1 Gyr?
2.1353209857940674
>>> vice.mlr.hpt2000(2, which = "age") # 2 Gyr
1.6775577716827392
>>> vice.mlr.hpt2000(2, postMS = 0, which = "age") # MS turnoff mass
1.6241520633697508
>>> vice.mlr.hpt2000(3)
0.39829399679015326
>>> vice.mlr.hpt2000(3, which = "age")
1.4629812650680543
>>> vice.mlr.hpt2000(3, postMS = 0, which = "age")
1.4181586170196532

.. [1] Hurley, Pols & Tout (2000), MNRAS, 315, 543
.. [2] Press, Teukolsky, Vetterling & Flannery (2007), Numerical
	Recipes, Cambridge University Press