text: Units and Quantities (
  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 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 <Quantity 42. m> >>> [1., 2., 3.] * u.m <Quantity [1., 2., 3.] m> >>> import numpy as np >>> np.array([1., 2., 3.]) * u.m <Quantity [1., 2., 3.] m>
  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) <Quantity 0.471875 m / s> >>> 3.0 * u.kilometer / (130.51 * u.meter / u.second) <Quantity 0.022986744310780783 km s / m> >>> (3.0 * u.kilometer / (130.51 * u.meter / u.second)).decompose() <Quantity 22.986744310780782 s>
  Unit conversion is done using the
  to() method, which returns a new
  Quantity in the given unit:
  >>> x = 1.0 * u.parsec >>> x.to(u.km) <Quantity 30856775814671.914 km>
  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) <Quantity 0.939513242662849 mi / h>
  Units that “cancel out” become a special unit called the “dimensionless unit”:
  >>> u.m / u.m Unit(dimensionless)
  astropy.units is able to match compound units against the units it already
  knows about:
  >>> (u.s ** -1).compose() [Unit("Bq"), Unit("Hz"), Unit("3.7e+10 Ci")]
  And it can convert between unit systems, such as SI or CGS:
  >>> (1.0 * u.Pa).cgs <Quantity 10.0 Ba>
  The units
  mag,
  dex and
  dB are special, being 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) <Magnitude -2.5 mag(ct / s)> >>> from astropy import constants as c >>> u.Dex((c.G * u.M_sun / u.R_sun**2).cgs) <Dex 4.438067627303133 dex(cm / s2)>
  astropy.units also handles equivalencies, such as
  that between wavelength and frequency. To use that feature, equivalence objects
  are passed to the
  to() conversion
  method. For instance, a conversion from wavelength to frequency doesn’t
  normally work:
  >>> (1000 * u.nm).to(u.Hz) 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()) <Quantity 2.99792458e+14 Hz>
  Quantities and units can be 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 <Quantity 0.471875 m / s> >>> "{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 <Quantity 0.471875 m / s> >>> "{0.value:0.03f} {0.unit:FITS}".format(q) '0.472 m s-1'
  Using
  astropy.units¶
  - Quantity
  - Creating Quantity instances
  - Converting to different units
  - Comparing quantities
  - Plotting quantities
  - Arithmetic
  - Numpy functions
  - Dimensionless quantities
  - Converting to plain Python scalars
  - Functions that accept Quantities
  - Representing vectors with units
  - Creating and converting quantities without copies
  - Known issues with conversion to numpy arrays
  - Subclassing Quantity
  - Standard units
  - Combining and defining units
  - Decomposing and composing units
  - Magnitudes and other Logarithmic Units
  - String representations of units
  - Equivalencies
  - Low-level unit 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.
  -.
  Reference/API¶
  astropy.units.quantity Module¶
  This module defines the
  Quantity object, which represents a number with some
  associated units.
  Quantity objects support operations like ordinary numbers,
  but will deal with unit conversions internally.
  astropy.units Package¶
  This subpackage contains classes and functions for defining and converting between different physical units.
  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.
  astropy.units.format Package¶
  A collection of different unit formats.
  astropy.units.si Module¶
  This package defines the SI units. They are also available in the
  astropy.units namespace.
  astropy.units.cgs Module¶
  This package defines the CGS units. They are also available in the
  top-level
  astropy.units namespace.
  astropy.units.astrophys Module¶
  This package defines the astrophysics-specific units. They are also
  available in the
  astropy.units namespace.
  astropy.units.function.units Module¶
  This package defines units that can also be used as functions of other units.
  If called, their arguments are used to initialize the corresponding function
  unit (e.g.,
  u.mag(u.ct/u.s)). Note that the prefixed versions cannot be
  called, as it would be unclear what, e.g.,
  u.mmag(u.ct/u.s) would mean.
  astropy.units.photometric Module¶
  This module defines magnitude zero points and related photometric quantities.
  The corresponding magnitudes are given in the description of each unit
  (the actual definitions are in
  logarithmic).
  astropy.units.imperial Module¶
  This package defines colloquially used Imperial units. They are
  available in the
  astropy.units.imperial namespace, but not in the
  top-level
  astropy.units namespace, e.g.:
  >>> import astropy.units as u >>> mph = u.imperial.mile / u.hour >>> mph Unit("mi / h")
  To include them in
  compose and the results of
  find_equivalent_units, do:
  >>> import astropy.units as u >>> u.imperial.enable()
  astropy.units.cds Module¶
  This package defines units used in the CDS format, both the units defined in Centre de Données astronomiques de Strasbourg Standards for Astronomical Catalogues 2.0 format and the complete set of supported units. This format is used by VOTable up to version 1.2.
  These units are not available in the top-level
  astropy.units
  namespace. To use these units, you must import the
  astropy.units.cds
  module:
  >>> from astropy.units import cds >>> q = 10. * cds.lyr
  To include them in
  compose and the results of
  find_equivalent_units, do:
  >>> from astropy.units import cds >>> cds.enable()
  astropy.units.function Package¶
  This subpackage contains classes and functions for defining and converting between different function units and quantities, i.e., using units which are some function of a physical unit, such as magnitudes and decibels.
  astropy.units.deprecated Module¶
  This package defines deprecated units.
  These units are not available in the top-level
  astropy.units
  namespace. To use these units, you must import the
  astropy.units.deprecated
  module:
  >>> from astropy.units import deprecated >>> q = 10. * deprecated.emu
  To include them in
  compose and the results of
  find_equivalent_units, do:
  >>> from astropy.units import deprecated >>> deprecated.enable()
  astropy.units.required_by_vounit Module¶
  This package defines SI prefixed units that are required by the VOUnit standard
  but that are rarely used in practice and liable to lead to confusion (such as
  msolMass for milli-solar mass). They are in a separate module from
  astropy.units.deprecated because they need to be enabled by default for
  astropy.units to parse compliant VOUnit strings. As a result, e.g.,
  Unit('msolMass') will just work, but to access the unit directly, use
  astropy.units.required_by_vounit.msolMass instead of the more typical idiom
  possible for the non-prefixed unit,
  astropy.units.solMass.