.. _astropy-cosmology-units-and-equivalencies: ************************************ Cosmological Units and Equivalencies ************************************ .. currentmodule:: astropy.cosmology.units 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 :mod:`astropy.units` to access these units when searching for unit conversions and equivalencies, use :func:`~astropy.units.add_enabled_units`. >>> import astropy.units as u >>> u.add_enabled_units(cu) # doctest: +SKIP About the Units =============== .. doctest:: :hide: >>> import astropy.units as u .. _cosmological-redshift: 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 ^^^^^^^^ .. EXAMPLE START: Using redshift-dimensionless equivalency 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()) 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()) 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 True >>> q.to(u.K) To temporarily remove the equivalency and enforce unit strictness, use :func:`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 .. EXAMPLE END .. EXAMPLE START: Using `with_redshift` equivalency The other redshift equivalency is `~astropy.cosmology.units.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)) or the Hubble parameter: >>> z.to(u.km / u.s / u.Mpc, cu.with_redshift(WMAP9)) # doctest: +FLOAT_CMP >>> z.to(cu.littleh, cu.with_redshift(WMAP9)) # doctest: +FLOAT_CMP or a physical distance (comoving, lookback, or luminosity): .. doctest-requires:: scipy >>> z.to(u.Mpc, cu.with_redshift(WMAP9, distance="luminosity")) # doctest: +FLOAT_CMP 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)) If no argument is given (or the argument is `None`), this equivalency assumes the current default |Cosmology|: >>> z.to(u.K, cu.with_redshift()) 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) .. EXAMPLE END .. _littleh-and-H0-equivalency: 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 :func:`~astropy.cosmology.units.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 ^^^^^^^^ .. EXAMPLE START: Using the "little h" Equivalency To convert to or from physical to "little h" units: .. code-block:: python >>> 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)) # doctest: +FLOAT_CMP >>> luminosity = 0.49 * u.Lsun * cu.littleh**-2 >>> luminosity.to(u.Lsun, cu.with_H0(H0_70)) # doctest: +FLOAT_CMP 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|: .. code-block:: python >>> distance = 100 * (u.Mpc/cu.littleh) >>> distance.to(u.Mpc, cu.with_H0()) # doctest: +FLOAT_CMP This equivalency also allows a common magnitude formulation of little h scaling: .. code-block:: python >>> mag_quantity = 12 * (u.mag - u.MagUnit(cu.littleh**2)) >>> mag_quantity # doctest: +FLOAT_CMP >>> mag_quantity.to(u.mag, cu.with_H0(H0_70)) # doctest: +FLOAT_CMP .. EXAMPLE END Reference/API ============= .. automodapi:: astropy.cosmology.units :inherited-members: