vice.mlr.powerlaw
=================

Compute either the lifetime or the mass of a dying star according to a
single power-law relationship between the two.

**Signature**: vice.mlr.powerlaw(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. Interpretation 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 in Gyr
	according to the single power law.
	If ``which == "age"``, the mass of a star in :math:`M_\odot` with
	the specified lifetime in Gyr.

Notes
-----
This power-law is of the following form:

.. math:: \tau = (1 + p_\text{MS}) \tau_\odot
	\left(\frac{M}{M_\odot}\right)^{-\gamma}

where :math:`\tau_\odot` is the main sequence lifetime of the sun
(taken to be 10 Gyr), :math:`p_\text{MS}` is the parameter
``postMS``, and :math:`\gamma` is the power-law index, taken to be 3.5.

This form of the mass-lifetime relation can be derived from the scaling
relation:

.. math:: \frac{\tau}{\tau_\odot} \sim \frac{M/M_\odot}{L/L_\odot}

where :math:`L` is the luminosity of a star assuming
:math:`L \sim M^{4.5}`, a popular exercise in undergraduate astronomy
courses.

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.

Example Code
------------
>>> import vice
>>> vice.mlr.powerlaw(1) # the lifetime of the sun
11.0
>>> vice.mlr.powerlaw(1, postMS = 0) # main sequence lifetime only
10.0
>>> vice.mlr.powerlaw(1, which = "age") # what mass lives 1 Gyr?
1.9839958856298403
>>> vice.mlr.powerlaw(2, which = "age") # 2 Gyr?
1.627541971155844
>>> vice.mlr.powerlaw(3, which = "age") # 3 Gyr?
1.449507306037525
>>> vice.mlr.powerlaw(3, postMS = 0, which = "age") # MS turnoff mass
1.4105676750826
>>> vice.mlr.powerlaw(3, postMS = 0)
0.21383343303319474