.. _astropy-units:
**************************************
Units and Quantities (`astropy.units`)
**************************************
.. |quantity| replace:: :class:`~astropy.units.Quantity`
.. currentmodule:: astropy.units
Introduction
============
`astropy.units` handles defining, converting between, and performing
arithmetic with physical quantities, such as meters, seconds, Hz,
etc. It also handles logarithmic units such as magnitude and decibel.
`astropy.units` does not know spherical geometry or sexagesimal
(hours, min, sec): if you want to deal with celestial coordinates,
see the `astropy.coordinates` package.
Getting Started
===============
Most users of the `astropy.units` package will :ref:`work with "quantities"
`: the combination of a value and a unit. The easiest way to create
a |quantity| is to simply multiply or divide a value by one of the built-in
units. It works with scalars, sequences and Numpy arrays::
>>> from astropy import units as u
>>> 42.0 * u.meter # doctest: +FLOAT_CMP
>>> [1., 2., 3.] * u.m # doctest: +FLOAT_CMP
>>> import numpy as np
>>> np.array([1., 2., 3.]) * u.m # doctest: +FLOAT_CMP
You can get the unit and value from a |quantity| using the unit and
value members::
>>> q = 42.0 * u.meter
>>> q.value
42.0
>>> q.unit
Unit("m")
From this simple building block, it's easy to start combining
quantities with different units::
>>> 15.1 * u.meter / (32.0 * u.second) # doctest: +FLOAT_CMP
>>> 3.0 * u.kilometer / (130.51 * u.meter / u.second) # doctest: +FLOAT_CMP
>>> (3.0 * u.kilometer / (130.51 * u.meter / u.second)).decompose() # doctest: +FLOAT_CMP
Unit conversion is done using the
:meth:`~astropy.units.quantity.Quantity.to` method, which returns a new
|quantity| in the given unit::
>>> x = 1.0 * u.parsec
>>> x.to(u.km) # doctest: +FLOAT_CMP
It is also possible to work directly with units at a lower level, for
example, to create custom units::
>>> from astropy.units import imperial
>>> cms = u.cm / u.s
>>> # ...and then use some imperial units
>>> mph = imperial.mile / u.hour
>>> # And do some conversions
>>> q = 42.0 * cms
>>> q.to(mph) # doctest: +FLOAT_CMP
Units that "cancel out" become a special unit called the
"dimensionless unit":
>>> u.m / u.m
Unit(dimensionless)
To create a simple :ref:`dimensionless quantity `,
multiply a value by the unscaled dimensionless unit::
>>> q = 1.0 * u.dimensionless_unscaled
>>> q.unit
Unit(dimensionless)
`astropy.units` is able to match compound units against the units it already
knows about::
>>> (u.s ** -1).compose() # doctest: +SKIP
[Unit("Bq"), Unit("Hz"), Unit("3.7e+10 Ci")]
And it can convert between unit systems, such as SI or CGS:
.. doctest-skip::
>>> (1.0 * u.Pa).cgs
The units ``mag``, ``dex`` and ``dB`` are special, being :ref:`logarithmic
units `, for which a value is the logarithm of a physical
quantity in a given unit. These can be used with a physical unit in
parentheses to create a corresponding logarithmic quantity::
>>> -2.5 * u.mag(u.ct / u.s)
>>> from astropy import constants as c
>>> u.Dex((c.G * u.M_sun / u.R_sun**2).cgs) # doctest: +FLOAT_CMP
`astropy.units` also handles :ref:`equivalencies `, such as
that between wavelength and frequency. To use that feature, equivalence objects
are passed to the :meth:`~astropy.units.quantity.Quantity.to` conversion
method. For instance, a conversion from wavelength to frequency doesn't
normally work:
>>> (1000 * u.nm).to(u.Hz) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
UnitConversionError: 'nm' (length) and 'Hz' (frequency) are not convertible
but by passing an equivalency list, in this case ``spectral()``, it does:
>>> (1000 * u.nm).to(u.Hz, equivalencies=u.spectral()) # doctest: +FLOAT_CMP
Quantities and units can be :ref:`printed nicely to strings
` using the `Format String Syntax
`_, the
preferred string formatting syntax in recent versions of python. Format
specifiers (like ``0.03f``) in new-style format strings will used to format the
quantity value::
>>> q = 15.1 * u.meter / (32.0 * u.second)
>>> q # doctest: +FLOAT_CMP
>>> "{0:0.03f}".format(q)
'0.472 m / s'
The value and unit can also be formatted separately. Format specifiers
used on units can be used to choose the unit formatter::
>>> q = 15.1 * u.meter / (32.0 * u.second)
>>> q # doctest: +FLOAT_CMP
>>> "{0.value:0.03f} {0.unit:FITS}".format(q)
'0.472 m s-1'
Using `astropy.units`
=====================
.. toctree::
:maxdepth: 2
quantity
standard_units
combining_and_defining
decomposing_and_composing
logarithmic_units
format
equivalencies
conversion
See Also
========
- `FITS Standard `_ for
units in FITS.
- The `Units in the VO 1.0 Standard
`_ for representing units in
the VO.
- OGIP Units: A standard for storing units in `OGIP FITS files
`_.
- `Standards for astronomical catalogues units
`_.
- `IAU Style Manual
`_.
- `A table of astronomical unit equivalencies
`_
.. note that if this section gets too long, it should be moved to a separate
doc page - see the top of performance.inc.rst for the instructions on how to do
that
.. include:: performance.inc.rst
Reference/API
=============
.. automodapi:: astropy.units.quantity
.. automodapi:: astropy.units
.. automodapi:: astropy.units.format
.. automodapi:: astropy.units.si
.. automodapi:: astropy.units.cgs
.. automodapi:: astropy.units.astrophys
.. automodapi:: astropy.units.function.units
.. automodapi:: astropy.units.photometric
.. automodapi:: astropy.units.imperial
.. automodapi:: astropy.units.cds
.. automodapi:: astropy.units.equivalencies
.. automodapi:: astropy.units.function
.. automodapi:: astropy.units.function.logarithmic
:include-all-objects:
.. automodapi:: astropy.units.deprecated
.. automodapi:: astropy.units.required_by_vounit
Acknowledgments
===============
This code is adapted from the `pynbody
`__ units module written by Andrew
Pontzen, who has granted the Astropy Project permission to use the code
under a BSD license.