vice.mlr
========

The Mass-Lifetime Relationship (MLR) for Stars: VICE provides several
functional forms available for individual calculations as well as for use
in chemical evolution models.

**Signature**: vice.mlr

.. versionadded:: 1.3.0

Contents
--------
setting : ``str``
	A string denoting which of the following functional forms is to
	describe the MLR in all chemical evolution models.
recognized : ``tuple``
	A tuple of strings denoting the allowed values of the parameter
	``setting``. Each string corresponds directly to the name of the
	function to adopt.

		- "powerlaw"
		- "vincenzo2016"
		- "hpt2000"
		- "ka1997"
		- "pm1993"
		- "mm1989"
		- "larson1974"

powerlaw : <function>
	The MLR parameterized by a single power-law, a popular exercise in
	undergraduate astronomy courses.
vincenzo2016 : <function>
	The MLR as characterized by Vincenzo et al. (2016) [1]_.
hpt2000 : <function>
	The MLR as described in Hurley, Pols & Tout (2000) [2]_.
ka1997 : <function>
	The MLR as tabulated in Kodama & Arimoto (1997) [3]_.
pm1993 : <function>
	The MLR as formulated by Padovani & Matteucci (1993) [4]_.
mm1989 : <function>
	The MLR as characterized by Maeder & Meynet (1989) [5]_.
larson1974 : <function>
	The MLR as parameterized by Larson (1974) [6]_.
test : <function>
	Run unit-tests on VICE's MLR capabilities.

The following forms of the mass-lifetime relation take into account the
metallicity dependence:

	- "vincenzo2016" : Vincenzo et al. (2016)
	- "hpt2000" : Hurley, Pols & Tout (2000)
	- "ka1997" : Kodama & Arimoto (1997)

The following require numerical solutions to the inverse function (i.e.
stellar mass as a function of lifetime), and consequently can increase the
required integration times in chemical evolution models, particularly for
fine timestepping:

	- "hpt2000" : Hurley, Pols & Tout (2000)
	- "ka1997" : Koama & Arimoto (1997)
	- "mm1989" : Maeder & Meynet (1989)

The following quantify the total lifetimes *a priori*, and any prescription
for the post main sequence lifetimes will consequently be neglected in
chemical evolution models:

	- "vincenzo2016": Vincenzo et al. (2016)
	- "ka1997" : Kodama & Arimoto (1997)

Except where measurements of the total lifetimes are available, VICE always
implements the simplest assumption of allowing the user to specify the
parameter ``postMS`` describing the ratio of post main sequence to main
sequence lifetimes, and the total lifetime then follows trivially via:

.. math:: \tau_\text{total} = (1 + p_\text{MS}) \tau_\text{MS}

where :math:`p_\text{MS}` denotes this ratio.

.. note:: For reasons relating to the implementation, this set of functions
	is not a module but an object. Consequently, importing them with
	``from vice import mlr`` will work fine, but for example
	``from vice.mlr import vincenzo2016`` will produce a
	``ModuleNotFoundError``. If necessary, new variables can always be
	assigned to map to these functions (e.g.
	``vincenzo2016 = vice.mlr.vincenzo2016``).

.. [1] Vincenzo et al. (2016), MNRAS, 460, 2238
.. [2] Hurley, Pols & Tout (2000), MNRAS, 315, 543
.. [3] Kodama & Arimoto (1997), A&A, 320, 41
.. [4] Padovani & Matteucci (1993), ApJ, 416, 26
.. [5] Maeder & Meynet (1989), A&A, 210, 155
.. [6] Larson (1974), MNRAS, 166, 585




.. toctree::
	:titlesonly:
	:maxdepth: 5

	vice.mlr.setting
	vice.mlr.recognized
	vice.mlr.powerlaw
	vice.mlr.vincenzo2016
	vice.mlr.hpt2000
	vice.mlr.ka1997
	vice.mlr.pm1993
	vice.mlr.mm1989
	vice.mlr.larson1974