vice.mlr.vincenzo2016
=====================

Compute either the lifetime or the mass of a dying star according to
the mass-lifetime relation of Vincenzo et al. (2016) [1]_.

**Signature**: vice.mlr.vincenzo2016(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 the Vincenzo et al. (2016)
	relation.
	If ``which == "age"``, the mass of a star in :math:`M_\odot` with
	the specified lifetime in Gyr.

Notes
-----
This relation is of the following functional form:

.. math:: \tau = A \exp(B m^{-C})

where :math:`A`, :math:`B`, and :math:`C` are functions of metallicity.
Vincenzo et al. (2016) computed the values of these coefficients
using the PARSEC stellar evolution code (Bressan et al. 2012 [2]_;
Tang et al. 2014 [3]_; Chen et al. 2015 [4]_) which were then used in
combination with a one-zone chemical evolution model to reproduce the
color-magnitude diagram of the Sculptor dwarf galaxy.

VICE stores a table of values of :math:`A`, :math:`B`, and :math:`C` as
internal data, interpolating linearly between them in metallicity
:math:`Z`. 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).

Example Code
------------
>>> import vice
>>> vice.mlr.vincenzo2016(1) # the lifetime of the sun
11.146605845086224
>>> vice.mlr.vincenzo2016(1, Z = 0.007) # at half solar metallicity
8.873217338534232
>>> vice.mlr.vincenzo2016(1, which = "age") # what mass lives 1 Gyr?
2.2090823821884733
>>> vice.mlr.vincenzo2016(2, which = "age") # 2 Gyr?
1.7081324509721378
>>> vice.mlr.vincenzo2016(2, Z = 0.007, which = "age")
1.6033524375573776
>>> vice.mlr.vincenzo2016(3)
0.48203178060452745
>>> vice.mlr.vincenzo2016(3, Z = 0.001)
0.33000930985434906
>>> vice.mlr.vincenzo2016(3, which = "age")
1.4878361243926437

.. [1] Vincenzo et al. (2016), MNRAS, 460, 2238
.. [2] Bressan et al. (2012), MNRAS, 427, 127
.. [3] Tang et al. (2014), MNRAS, 445, 4287
.. [4] Chen et al. (2015), MNARS, 452, 1068