<commit_before>.. |quantity| replace:: :class:`~astropy.units.Quantity`

.. _unit_equivalencies:

Equivalencies
*************

The unit module has machinery for supporting equivalences between
different units in certain contexts, namely when equations can
uniquely relate a value in one unit to a different unit. A good
example is the equivalence between wavelength, frequency and energy
for specifying a wavelength of radiation. Normally these units are not
convertible, but when understood as representing light, they are
convertible in certain contexts.  Here we describe how to use the
equivalencies included in `astropy.units` and how to
define new equivalencies.

Equivalencies are used by passing a list of equivalency pairs to the
``equivalencies`` keyword argument of :meth:`Quantity.to
<astropy.units.quantity.Quantity.to>` or :meth:`Unit.to
<astropy.units.core.UnitBase.to>` methods.  Alternatively, if a larger
piece of code needs the same equivalencies, one can set them for a
:ref:`given context <equivalency-context>`.

Built-in equivalencies
======================

Parallax Units
--------------

:func:`~astropy.units.equivalencies.parallax` is a function that returns an
equivalency list to handle conversions between angles and length.

Length and angles are not normally convertible, so
:meth:`~astropy.units.core.UnitBase.to` raises an exception::

  >>> from astropy import units as u
  >>> (8.0 * u.arcsec).to(u.parsec)  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
    ...
  UnitConversionError: 'arcsec' (angle) and 'pc' (length) are not convertible

However, when passing the result of
:func:`~astropy.units.equivalencies.parallax` as the third argument to the
:meth:`~astropy.units.core.UnitBase.to` method, angles can be converted
into units of length (and vice versa).

    >>> (8.0 * u.arcsec).to(u.parsec, equivalencies=u.parallax())
    <Quantity 0.125 pc>
    >>> u.AU.to(u.arcminute, equivalencies=u.parallax())
    3437.7467707580054

Angles as Dimensionless Units
-----------------------------

Angles are treated as a physically distinct type, which usually helps
to avoid mistakes.  However, this is not very handy when working with
units related to rotational energy or the small angle approximation.
(Indeed, this double-sidedness underlies why radian went from
`supplementary to derived unit <http://www.bipm.org/en/CGPM/db/20/8/>`__.)
The function :func:`~astropy.units.equivalencies.dimensionless_angles`
provides the required equivalency list that helps convert between
angles and dimensionless units.  It is somewhat
different from all others in that it allows an arbitrary change in the
number of powers to which radian is raised (i.e., including zero and thus
dimensionless).  For instance, normally the following raise exceptions::

  >>> from astropy import units as u
  >>> u.degree.to('')  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
    ...
  UnitConversionError: 'deg' (angle) and '' (dimensionless) are not convertible
  >>> (u.kg * u.m**2 * (u.cycle / u.s)**2).to(u.J)  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
    ...
  UnitConversionError: 'cycle2 kg m2 / s2' and 'J' (energy) are not convertible<commit_msg>updated with more informative title and example text<commit_after>.. |quantity| replace:: :class:`~astropy.units.Quantity`

.. _unit_equivalencies:

Equivalencies
*************

The unit module has machinery for supporting equivalences between
different units in certain contexts, namely when equations can
uniquely relate a value in one unit to a different unit. A good
example is the equivalence between wavelength, frequency and energy
for specifying a wavelength of radiation. Normally these units are not
convertible, but when understood as representing light, they are
convertible in certain contexts.  Here we describe how to use the
equivalencies included in `astropy.units` and how to
define new equivalencies.

Equivalencies are used by passing a list of equivalency pairs to the
``equivalencies`` keyword argument of :meth:`Quantity.to
<astropy.units.quantity.Quantity.to>` or :meth:`Unit.to
<astropy.units.core.UnitBase.to>` methods.  Alternatively, if a larger
piece of code needs the same equivalencies, one can set them for a
:ref:`given context <equivalency-context>`.

Built-in equivalencies
======================

How to Convert Parallax to Distance
-----------------------------------

The length unit *parsec* is defined such that a star one parsec away
will exhibit a 1-arcsecond parallax. (Think of it as a contraction
between *parallax* and *arcsecond*.)

The :func:`~astropy.units.equivalencies.parallax` function handles
conversions between parallax angles and length.

In general, you should not be able to change units of length into
angles or vice versa, so :meth:`~astropy.units.core.UnitBase.to`
raises an exception::

  >>> from astropy import units as u
  >>> (0.8 * u.arcsec).to(u.parsec)  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
    ...
  UnitConversionError: 'arcsec' (angle) and 'pc' (length) are not convertible

To trigger the conversion between parallax angle and distance, provide
:func:`~astropy.units.equivalencies.parallax` as the optional keyword
argument (``equivalencies=``) to the
:meth:`~astropy.units.core.UnitBase.to` method.

    >>> (0.8 * u.arcsec).to(u.parsec, equivalencies=u.parallax())
    <Quantity 1.25 pc>

Angles as Dimensionless Units
-----------------------------

Angles are treated as a physically distinct type, which usually helps
to avoid mistakes.  However, this is not very handy when working with
units related to rotational energy or the small angle approximation.
(Indeed, this double-sidedness underlies why radian went from
`supplementary to derived unit <http://www.bipm.org/en/CGPM/db/20/8/>`__.)
The function :func:`~astropy.units.equivalencies.dimensionless_angles`
provides the required equivalency list that helps convert between
angles and dimensionless units.  It is somewhat
different from all others in that it allows an arbitrary change in the
number of powers to which radian is raised (i.e., including zero and thus
dimensionless).  For instance, normally the following raise exceptions::

  >>> from astropy import units as u
  >>> u.degree.to('')  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
    ...
  UnitConversionError: 'deg' (angle) and '' (dimensionless) are not convertible
  >>> (u.kg * u.m**2 * (u.cycle / u.s)**2).to(u.J)  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
    ...
  UnitConversionError: 'cycle2 kg m2 / s2' and 'J' (energy) are not convertible
{'fraction_non_alphanumeric': 0.11300194058814748, 'fraction_numerical': 0.0073145245559038665, 'mean_word_length': 4.355715427657874, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 52, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, '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': '2617519', 'n_tokens_mistral': 1995, 'n_tokens_neox': 1867, 'n_words': 768}