vice.toolkit.J21_sf_law
=======================

The default star formation law of the ``milkyway`` object. This is a
callable object, accepting simulation time and either star formation rate
or gas supply as second arguments. By default, it implements the star
formation law adopted in Johnson et al. (2021) [1]_.

**Signature**: vice.toolkit.J21_sf_law(area, \*\*kwargs)

.. versionadded:: 1.2.0

.. warning:: In a ``milkyway`` object, every zone has an instance of this
	class as its ``tau_star`` attribute. Any modifications to the attributes
	of this class should be made for **every zone**; if this is not
	ensured, the star formation law will not be consistent across all
	zones.

Parameters
----------
area : real number
	The value of the attribute ``area``. See below.
\*\*kwargs : varying types
	Other attributes can have their values set via keyword. See below.

Attributes
----------
area : real number
	The surface area in :math:`kpc^2` of the corresponding annulus in a
	``milkyway`` model.
present_day_molecular : real number [default : 2.0]
	The depletion time of molecular gas at the present day in Gyr. Positive
	definite.
molecular_index : real number [default : 0.5]
	The power-law index on the time-dependence.
Sigma_g1 : real number [default : 5.0e+06]
	The smaller of the two surface densities of gas at which there is a
	break in the Kennicutt-Schmidt relation. Assumes units of
	:math:`M_\odot kpc^{-2}`.
Sigma_g2 : real number [default : 2.0e+07]
	The larger of the two surface densities of gas at which there is a
	break in the Kennicutt-Schmidt relation. Assumes units of
	:math:`M_\odot kpc^{-2}`.
index1 : real number [default : 1.7]
	The index of the power-law at gas surface densities below ``Sigma_g1``.
index2 : real number [default : 3.6]
	The index of the power-law at gas surface densities between ``Sigma_g1``
	and ``Sigma_g2``, above which it is assumed to be linear.
mode : str ["sfr", "ifr", or "gas"] [default : "ifr"]
	The mode of the ``milkyway`` object.

Calling
-------
Calling this object will calculate the star formation efficiency timescale
:math:`\tau_\star` according to the parameters of the star formation law
entered as attributes of this object. As in the ``singlezone`` object, this
timescale is the gas supply per unit star formation in Gyr.

Parameters:

		- time : real number
			Simulation time in Gyr. Postive definite.
		- arg2 : real number
			Either the gas supply in :math:`M_\odot` or the star formation
			rate in :math:`M_\odot Gyr^{-1}`. Will be called by VICE
			directly. With the attribute ``area``, the surface density of
			the corresponding quantity is known. Positive definite.

Returns:

		- tau_star : real number
			The star formation efficiency timescale given that simulation
			time and star formation rate/gas supply, in Gyr (as necessary).

.. seealso:: vice.milkyway

Notes
-----
This object encodes the parameters of the desired Kennicutt-Schmidt relation
into the ``milkyway`` object. This is the relationship relating the surface
densities of star formation :math:`\dot{\Sigma}_\star` and gas
:math:`\Sigma_\text{gas}`.

This object implements a star formation law in the ``milkyway`` object
defined according to:

.. math:: \dot{\Sigma}_\star \sim \Sigma_\text{gas}^N

The value of the power-law index :math:`N` has two breaks, at
:math:`\Sigma_{\text{gas},1}` and :math:`\Sigma_{\text{gas},2}`.

.. math::

	N = 1.0\ (\Sigma_\text{gas} \geq \Sigma_{\text{gas},2})
	\\
	N = \gamma_2\ (\Sigma_{\text{gas},1} \leq \Sigma_\text{gas} \leq
		\Sigma_{\text{gas},2})
	\\
	N = \gamma_1\ (\Sigma_\text{gas} \leq \Sigma_{\text{gas},1})

The values :math:`\gamma_1` and :math:`\gamma_2` correspond to the
attributes ``index1`` and ``index2``, respectively. As their names would
suggest, :math:`\Sigma_{\text{gas},1}` and :math:`\Sigma_{\text{gas},2}`
correspond to ``Sigma_g1`` and ``Sigma_g2``.

The depletion time of molecular gas due to star formation
:math:`\tau_\text{mol}` is defined according to the following
scaling:

.. math:: \tau_\text{mol} = \tau_{\text{mol},0} \left(t/t_0\right)^\beta

where :math:`t_0` is the age of the universe today, :math:`t` is the age of
the universe at some simulation time, and :math:`\tau_{\text{mol},0}` is
:math:`\tau_\text{mol}` at the present day. Because the ``milkyway`` model
only supports lookback times up to 13.2 Gyr, the relation between age of
the universe and simulation time is a simple linear translation:

.. math:: t = t_\text{sim} + 0.5\ \text{Gyr}

with the assumption that :math:`t_0` = 13.7 Gyr is the age of the universe
at the present day.

.. [1] Johnson et al. (2021), MNRAS, 508, 4484




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

	vice.toolkit.J21_sf_law.area
	vice.toolkit.J21_sf_law.molecular
	vice.toolkit.J21_sf_law.present_day_molecular
	vice.toolkit.J21_sf_law.molecular_index
	vice.toolkit.J21_sf_law.Sigma_g1
	vice.toolkit.J21_sf_law.Sigma_g2
	vice.toolkit.J21_sf_law.index1
	vice.toolkit.J21_sf_law.index2