<commit_before>.. _astropy-cosmology:

***********************************************
Cosmological Calculations (`astropy.cosmology`)
***********************************************

Introduction
============

The `astropy.cosmology` subpackage contains classes for representing
cosmologies, and utility functions for calculating commonly used
quantities that depend on a cosmological model. This includes
distances, ages and lookback times corresponding to a measured
redshift or the transverse separation corresponding to a measured
angular separation.


Getting Started
===============

There are many functions available to calculate cosmological
quantities as a function of redshift. For example, the two cases below
calculate the Hubble constant at z=0 (i.e., ``H0``), and the number of
transverse proper kpc corresponding to an arcminute at z=3:

  >>> from astropy import cosmology
  >>> cosmology.core.set_current(cosmology.WMAP9)
  <astropy.utils.state._Context object at ...>
  >>> cosmology.H(0)
  <Quantity 69.3... km / (Mpc s)>

.. doctest-requires:: scipy

  >>> cosmology.kpc_proper_per_arcmin(3)
  <Quantity 472.977... kpc / arcmin>

All the functions available are listed in the `Reference/API`_
section. These will use the "current" cosmology to calculate the
values (see `The Current Cosmology`_ section below for more
details). If you haven't set this explicitly, they will use the 9-year
WMAP cosmological parameters and print a warning message.

Also note that the cosmology subpackage makes use of `~astropy.units`, so
in many cases returns values with units attached -- consult the documentation
for that subpackage for more details, but, briefly, to access the floating
point (or array) values:

  >>> from astropy import cosmology
  >>> H0 = cosmology.H(0)
  >>> H0.value, H0.unit
  (69.3..., Unit("km / (Mpc s)"))

There are also several standard cosmologies already defined, as
described in `Built-in Cosmologies`_ below. These are objects
with methods and attributes that calculate cosmological
values. For example, the comoving distance in Mpc to redshift 4 using
the 5-year WMAP parameters:

.. doctest-requires:: scipy

  >>> from astropy.cosmology import WMAP5
  >>> WMAP5.comoving_distance(4)
  <Quantity 7329.328... Mpc>

An important point is that the cosmological parameters of each
instance are immutable -- that is, if you want to change, say,
``Om``, you need to make a new instance of the class.  Also note that
the built in cosmologies are instances of classes as described below,
not functions.

Using `cosmology`
=================

Most of the functionality is enabled by the
`~astropy.cosmology.FLRW` object. This represents a homogeneous
and isotropic cosmology (a cosmology characterized by the
Friedmann-Lemaitre-Robertson-Walker metric, named after the people who
solved Einstein's field equation for this special case).  However, you
can't work with this class directly, as you must specify a dark energy
model by using one of its subclasses instead, such as
`~astropy.cosmology.FlatLambdaCDM`.

You can create a new `~astropy.cosmology.FlatLambdaCDM` object with
arguments giving the Hubble parameter and omega matter (both at z=0):

  >>> from astropy.cosmology import FlatLambdaCDM
  >>> cosmo = FlatLambdaCDM(H0=70, Om0=0.3)
  >>> cosmo
  FlatLambdaCDM(H0=70 km / (Mpc s), Om0=0.3, Tcmb0=2.725 K,
                Neff=3.04, m_nu=[ 0.  0.  0.] eV)

This can also be done more explicitly using units, which is recommended:

  >>> from astropy.cosmology import FlatLambdaCDM
  >>> import astropy.units as u
  >>> cosmo = FlatLambdaCDM(H0=70 * u.km / u.s / u.Mpc, Om0=0.3)

However, most of the parameters that accept units (``H0``, ``Tcmb0``)
have default units, so unit quantities do not have to be used.
The exception are neutrino masses, where you must supply a
units if you want massive neutrinos.

The pre-defined cosmologies described in the `Getting Started`_
section are instances of `~astropy.cosmology.FlatLambdaCDM`, and have
the same methods. So we can find the luminosity distance to
redshift 4 by:

.. doctest-requires:: scipy

  >>> cosmo.luminosity_distance(4)
  <Quantity 35842.353... Mpc>

or the age of the universe at z = 0:

.. doctest-requires:: scipy

  >>> cosmo.age(0)
  <Quantity 13.461... Gyr>

They also accept arrays of redshifts:

.. doctest-requires:: scipy

  >>> cosmo.age([0.5, 1, 1.5]).value
  array([ 8.421...,  5.746...,  4.196...])

See the `~astropy.cosmology.FLRW` and
`~astropy.cosmology.FlatLambdaCDM` object docstring for all the
methods and attributes available. In addition to flat Universes,
non-flat varieties are supported such as
`~astropy.cosmology.LambdaCDM`.  There are also a variety of
standard cosmologies with the parameters already defined
(see `Built-in Cosmologies`_):

  >>> from astropy.cosmology import WMAP7   # WMAP 7-year cosmology
  >>> WMAP7.critical_density(0)       # critical density at z = 0
  <Quantity 9.310...e-30 g / cm3>

You can see how the density parameters evolve with redshift as well

  >>> from astropy.cosmology import WMAP7   # WMAP 7-year cosmology
  >>> WMAP7.Om([0, 1.0, 2.0]), WMAP7.Ode([0., 1.0, 2.0])
  (array([ 0.272      ,  0.748985...,  0.909052...]),
   array([ 0.727915...,  0.250550...,  0.090102...]))

Note that these don't quite add up to one even though WMAP7 assumes a
flat Universe because photons and neutrinos are included, and that
they are not `~astropy.units.Quantity` objects because they are dimensionless.

Cosmological instances have an optional ``name`` attribute which can be
descriptive:

  >>> from astropy.cosmology import FlatwCDM
  >>> cosmo = FlatwCDM(name='SNLS3+WMAP7', H0=71.58, Om0=0.262, w0=-1.016)
  >>> cosmo
  FlatwCDM(name="SNLS3+WMAP7", H0=71.6 km / (Mpc s), Om0=0.262,
           w0=-1.02, Tcmb0=2.725 K, Neff=3.04, m_nu=[ 0.  0.  0.] eV)

This is also an example of a model with a different model for dark
energy, a flat Universe with a constant dark energy equation of state,
but not necessarily a cosmological constant.  A variety of additional
dark energy models are also supported -- see `Specifying a dark energy model`_.

In addition to the `~astropy.cosmology.LambdaCDM` object, there
are convenience functions that calculate some of these quantities
without needing to explicitly give a cosmology - but there are more
methods available if you work directly with the cosmology object.

.. doctest-requires:: scipy

  >>> from astropy import cosmology
  >>> cosmology.kpc_proper_per_arcmin(3)
  <Quantity 472.977... kpc / arcmin>
  >>> cosmology.arcsec_per_kpc_proper(3)
  <Quantity 0.1268... arcsec / kpc>

These functions will perform calculations using the "current"
cosmology. This is a specific cosmology that is currently active in
``astropy`` and it's described further in the following section. They
can also be explicitly given a cosmology using the ``cosmo`` keyword
argument. A full list of convenience functions is included below, in
the `Reference/API`_ section.

Finally, if you know a cosmological quantity and you want to know the
redshift which it corresponds to, you can use ``z_at_value``:

.. doctest-requires:: scipy

  >>> import astropy.units as u
  >>> from astropy.cosmology import Planck13, z_at_value
  >>> z_at_value(Planck13.age, 2 * u.Gyr)
  3.1981...

For some quantities there can be more than one redshift that satisfies
a value. In this case you can use the ``zmin`` and ``zmax`` keywords to
restrict the search range.


The Current Cosmology
---------------------

Sometimes it's useful for Astropy functions to assume a default
cosmology so that the desired cosmology doesn't have to be specified
every time the function is called -- the convenience functions
described in the previous section are one example. For these cases
it's possible to specify a "current" cosmology.

You can set the current cosmology to a pre-defined value by using the
"default_cosmology" option in the ``[cosmology.core]`` section of the
configuration file (see :ref:`astropy_config`). Alternatively, you can
use the `~astropy.cosmology.set_current` function to set a<commit_msg>update docs to avoid functional cosmology use<commit_after>.. _astropy-cosmology:

***********************************************
Cosmological Calculations (`astropy.cosmology`)
***********************************************

Introduction
============

The `astropy.cosmology` subpackage contains classes for representing
cosmologies, and utility functions for calculating commonly used
quantities that depend on a cosmological model. This includes
distances, ages and lookback times corresponding to a measured
redshift or the transverse separation corresponding to a measured
angular separation.


Getting Started
===============

There are many functions available to calculate cosmological
quantities as a function of redshift. For example, the two cases below
calculate the Hubble constant at z=0 (i.e., ``H0``), and the number of
transverse proper kpc corresponding to an arcminute at z=3:

  >>> from astropy import cosmology
  >>> cosmology.core.set_current(cosmology.WMAP9)
  <astropy.utils.state._Context object at ...>
  >>> cosmology.get_current().H(0)
  <Quantity 69.3... km / (Mpc s)>

.. doctest-requires:: scipy

  >>> cosmology.get_current().kpc_proper_per_arcmin(3)
  <Quantity 472.977... kpc / arcmin>

All the functions available are listed in the `Reference/API`_
section. These will use the "current" cosmology to calculate the
values (see `The Current Cosmology`_ section below for more
details). If you haven't set this explicitly, they will use the 9-year
WMAP cosmological parameters and print a warning message.

Also note that the cosmology subpackage makes use of `~astropy.units`, so
in many cases returns values with units attached -- consult the documentation
for that subpackage for more details, but, briefly, to access the floating
point (or array) values:

  >>> from astropy import cosmology
  >>> H0 = cosmology.get_current().H(0)
  >>> H0.value, H0.unit
  (69.3..., Unit("km / (Mpc s)"))

There are also several standard cosmologies already defined, as
described in `Built-in Cosmologies`_ below. These are objects
with methods and attributes that calculate cosmological
values. For example, the comoving distance in Mpc to redshift 4 using
the 5-year WMAP parameters:

.. doctest-requires:: scipy

  >>> from astropy.cosmology import WMAP5
  >>> WMAP5.comoving_distance(4)
  <Quantity 7329.328... Mpc>

An important point is that the cosmological parameters of each
instance are immutable -- that is, if you want to change, say,
``Om``, you need to make a new instance of the class.  Also note that
the built in cosmologies are instances of classes as described below,
not functions.

Using `cosmology`
=================

Most of the functionality is enabled by the
`~astropy.cosmology.FLRW` object. This represents a homogeneous
and isotropic cosmology (a cosmology characterized by the
Friedmann-Lemaitre-Robertson-Walker metric, named after the people who
solved Einstein's field equation for this special case).  However, you
can't work with this class directly, as you must specify a dark energy
model by using one of its subclasses instead, such as
`~astropy.cosmology.FlatLambdaCDM`.

You can create a new `~astropy.cosmology.FlatLambdaCDM` object with
arguments giving the Hubble parameter and omega matter (both at z=0):

  >>> from astropy.cosmology import FlatLambdaCDM
  >>> cosmo = FlatLambdaCDM(H0=70, Om0=0.3)
  >>> cosmo
  FlatLambdaCDM(H0=70 km / (Mpc s), Om0=0.3, Tcmb0=2.725 K,
                Neff=3.04, m_nu=[ 0.  0.  0.] eV)

This can also be done more explicitly using units, which is recommended:

  >>> from astropy.cosmology import FlatLambdaCDM
  >>> import astropy.units as u
  >>> cosmo = FlatLambdaCDM(H0=70 * u.km / u.s / u.Mpc, Om0=0.3)

However, most of the parameters that accept units (``H0``, ``Tcmb0``)
have default units, so unit quantities do not have to be used.
The exception are neutrino masses, where you must supply a
units if you want massive neutrinos.

The pre-defined cosmologies described in the `Getting Started`_
section are instances of `~astropy.cosmology.FlatLambdaCDM`, and have
the same methods. So we can find the luminosity distance to
redshift 4 by:

.. doctest-requires:: scipy

  >>> cosmo.luminosity_distance(4)
  <Quantity 35842.353... Mpc>

or the age of the universe at z = 0:

.. doctest-requires:: scipy

  >>> cosmo.age(0)
  <Quantity 13.461... Gyr>

They also accept arrays of redshifts:

.. doctest-requires:: scipy

  >>> cosmo.age([0.5, 1, 1.5]).value
  array([ 8.421...,  5.746...,  4.196...])

See the `~astropy.cosmology.FLRW` and
`~astropy.cosmology.FlatLambdaCDM` object docstring for all the
methods and attributes available. In addition to flat Universes,
non-flat varieties are supported such as
`~astropy.cosmology.LambdaCDM`.  There are also a variety of
standard cosmologies with the parameters already defined
(see `Built-in Cosmologies`_):

  >>> from astropy.cosmology import WMAP7   # WMAP 7-year cosmology
  >>> WMAP7.critical_density(0)       # critical density at z = 0
  <Quantity 9.310...e-30 g / cm3>

You can see how the density parameters evolve with redshift as well

  >>> from astropy.cosmology import WMAP7   # WMAP 7-year cosmology
  >>> WMAP7.Om([0, 1.0, 2.0]), WMAP7.Ode([0., 1.0, 2.0])
  (array([ 0.272      ,  0.748985...,  0.909052...]),
   array([ 0.727915...,  0.250550...,  0.090102...]))

Note that these don't quite add up to one even though WMAP7 assumes a
flat Universe because photons and neutrinos are included, and that
they are not `~astropy.units.Quantity` objects because they are dimensionless.

Cosmological instances have an optional ``name`` attribute which can be
descriptive:

  >>> from astropy.cosmology import FlatwCDM
  >>> cosmo = FlatwCDM(name='SNLS3+WMAP7', H0=71.58, Om0=0.262, w0=-1.016)
  >>> cosmo
  FlatwCDM(name="SNLS3+WMAP7", H0=71.6 km / (Mpc s), Om0=0.262,
           w0=-1.02, Tcmb0=2.725 K, Neff=3.04, m_nu=[ 0.  0.  0.] eV)

This is also an example of a model with a different model for dark
energy, a flat Universe with a constant dark energy equation of state,
but not necessarily a cosmological constant.  A variety of additional
dark energy models are also supported -- see `Specifying a dark energy model`_.

Getting Redshifts from Cosmological Quantities
----------------------------------------------

If you know a cosmological quantity and you want to know the
redshift which it corresponds to, you can use ``z_at_value``:

.. doctest-requires:: scipy

  >>> import astropy.units as u
  >>> from astropy.cosmology import Planck13, z_at_value
  >>> z_at_value(Planck13.age, 2 * u.Gyr)
  3.1981...

For some quantities there can be more than one redshift that satisfies
a value. In this case you can use the ``zmin`` and ``zmax`` keywords to
restrict the search range.


The Current Cosmology
---------------------

Sometimes it's useful for Astropy functions to assume a default
cosmology so that the desired cosmology doesn't have to be specified
every time the function is called -- the convenience functions
described in the previous section are one example. For these cases
it's possible to specify a "current" cosmology.

You can set the current cosmology to a pre-defined value by using the
"default_cosmology" option in the ``[cosmology.core]`` section of the
configuration file (see :ref:`astropy_config`). Alternatively, you can
use the `~astropy.cosmology.set_current` function to set a
{'fraction_non_alphanumeric': 0.11264783816971499, 'fraction_numerical': 0.029276804756672915, 'mean_word_length': 4.100197758734344, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 196, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4477849', 'n_tokens_mistral': 4941, 'n_tokens_neox': 4439, 'n_words': 1928}