Skip to main content
`Ctrl`+`K`

# Cosmological Units and Equivalencies

This package defines and collects cosmological units and equivalencies. We suggest importing this units package as

    >>> import astropy.cosmology.units as cu

To enable the main `astropy.units` to access these units when searching for unit conversions and equivalencies, use `add_enabled_units()`.

    >>> import astropy.units as u
    >>> u.add_enabled_units(cu)

## About the Units

hide:

    >>> import astropy.units as u

### Cosmological Redshift and Dimensionless Equivalency

There are numerous measures of distance in cosmology – luminosities, CMB temperature, the universe’s age, etc. – but redshift is the principal measure from which others are defined. In cosmology, distance measures are commonly exasperating to follow in a derivation, because they are used interchangeably. `astropy` provides the `redshift` unit and associated equivalencies to assist in these derivations and unify the distance measures.

#### Examples

To convert to or from dimensionless to “redshift” units:

    >>> import astropy.units as u
    >>> import astropy.cosmology.units as cu
    >>> z = 1100 * cu.redshift
    >>> z.to(u.dimensionless_unscaled, equivalencies=cu.dimensionless_redshift())
    <Quantity 1100.>

The equivalency works as part of a quantity with composite units

    >>> q = (2.7 * u.K) * z
    >>> q.to(u.K, equivalencies=cu.dimensionless_redshift())
    <Quantity 2970. K>

Since the redshift is not a true unit and is used so frequently, the redshift / dimensionless equivalency is actually enabled by default.

    >>> z == 1100 * u.dimensionless_unscaled
    np.True_

    >>> q.to(u.K)
    <Quantity 2970. K>

To temporarily remove the equivalency and enforce unit strictness, use `astropy.units.set_enabled_equivalencies()` as a context.

    >>> with u.set_enabled_equivalencies([]):
    ...     try:
    ...         z.to(u.dimensionless_unscaled)
    ...     except u.UnitConversionError:
    ...         print("equivalency disabled")
    equivalency disabled

The other redshift equivalency is `with_redshift`, enabling redshift to be converted to other units, like CMB temperature:

    >>> from astropy.cosmology import WMAP9
    >>> z = 1100 * cu.redshift
    >>> z.to(u.K, cu.with_redshift(WMAP9))
    <Quantity 3000.225 K>

or the Hubble parameter:

    >>> z.to(u.km / u.s / u.Mpc, cu.with_redshift(WMAP9))
    <Quantity 1565637.40154275 km / (Mpc s)>

    >>> z.to(cu.littleh, cu.with_redshift(WMAP9))
    <Quantity 15656.37401543 littleh>

or a physical distance (comoving, lookback, or luminosity):

    >>> z.to(u.Mpc, cu.with_redshift(WMAP9, distance="luminosity"))
    <Quantity 15418438.76317008 Mpc>

These conversions are cosmology dependent, so if the cosmology changes, so too will the conversions.

    >>> excosmo = WMAP9.clone(Tcmb0=3.0)
    >>> z.to(u.K, cu.with_redshift(excosmo))
    <Quantity 3303. K>

If no argument is given (or the argument is `None`), this equivalency assumes the current default |Cosmology|:

    >>> z.to(u.K, cu.with_redshift())
    <Quantity 3000.7755 K>

To use this equivalency in a larger block of code:

    >>> with u.add_enabled_equivalencies(cu.with_redshift()):
    ...     # long derivation here
    ...     z.to(u.K)
    <Quantity 3000.7755 K>

### Reduced Hubble Constant and “little-h” Equivalency

The dimensionless version of the Hubble constant — often known as “little h” — is a frequently used quantity in extragalactic astrophysics. It is also widely known as the bane of beginners’ existence in such fields (See e.g., the title of this paper, which also provides valuable advice on the use of little h). `astropy` provides the `with_H0()` equivalency that helps keep this straight in at least some of these cases, by providing a way to convert to/from physical to “little h” units.

#### Examples

To convert to or from physical to “little h” units:

    >>> import astropy.units as u
    >>> import astropy.cosmology.units as cu
    >>> H0_70 = 70 * u.km/u.s/u.Mpc
    >>> distance = 70 * (u.Mpc/cu.littleh)
    >>> distance.to(u.Mpc, cu.with_H0(H0_70))
    <Quantity 100.0 Mpc>
    >>> luminosity = 0.49 * u.Lsun * cu.littleh**-2
    >>> luminosity.to(u.Lsun, cu.with_H0(H0_70))
    <Quantity 1.0 solLum>

Note the unit name `littleh`: while this unit is usually expressed in the literature as just `h`, here it is `littleh` to avoid confusion with “hours.”

If no argument is given (or the argument is `None`), this equivalency assumes the `H0` from the current default |Cosmology|:

    >>> distance = 100 * (u.Mpc/cu.littleh)
    >>> distance.to(u.Mpc, cu.with_H0())
    <Quantity 147.79781259 Mpc>

This equivalency also allows a common magnitude formulation of little h scaling:

    >>> mag_quantity = 12 * (u.mag - u.MagUnit(cu.littleh**2))
    >>> mag_quantity
    <Magnitude 12. mag(1 / littleh2)>
    >>> mag_quantity.to(u.mag, cu.with_H0(H0_70))
    <Quantity 11.2254902 mag>

## Reference/API

### astropy.cosmology.units Module

Cosmological units and equivalencies.

Available Units
Unit | Description | Represents | Aliases | SI Prefixes
--- | --- | --- | --- | ---
`littleh` | Reduced/”dimensionless” Hubble constant |  |  | No
`redshift` | Cosmological redshift. |  |  | No

#### Functions

`dimensionless_redshift`() | Allow redshift to be 1-to-1 equivalent to dimensionless.
`redshift_distance`([cosmology, kind]) | Convert quantities between redshift and distance.
`redshift_hubble`([cosmology]) | Convert quantities between redshift and Hubble parameter and little-h.
`redshift_temperature`([cosmology]) | Convert quantities between redshift and CMB temperature.
`with_H0`([H0]) | Convert between quantities with little-h and the equivalent physical units.
`with_redshift`([cosmology, distance, hubble, ...]) | Convert quantities between measures of cosmological distance.