.. _astropy-units: ************************************** Units and Quantities (`astropy.units`) ************************************** .. 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 work with :ref:`Quantity objects `: the combination of a value and a unit. The most convenient way to create a |Quantity| is to multiply or divide a value by one of the built-in units. It works with scalars, sequences, and ``numpy`` arrays. Examples -------- .. EXAMPLE START: Creating and Combining Quantities with Units To create a |Quantity| object:: >>> 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 basic building block, it is possible 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 .. EXAMPLE END .. EXAMPLE START: Creating Custom Units for Quantity Objects 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 basic :ref:`dimensionless quantity `, multiply a value by the unscaled dimensionless unit:: >>> q = 1.0 * u.dimensionless_unscaled >>> q.unit Unit(dimensionless) .. EXAMPLE END .. EXAMPLE START: Matching and Converting Between Units `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("2.7027e-11 Ci")] And it can convert between unit systems, such as `SI `_ or `CGS `_:: >>> (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 does not 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 :func:`~astropy.units.equivalencies.spectral`, it does: >>> (1000 * u.nm).to(u.Hz, equivalencies=u.spectral()) # doctest: +FLOAT_CMP .. EXAMPLE END .. EXAMPLE START: Printing Quantities and Units to Strings Quantities and units can be :ref:`printed nicely to strings ` using the `Format String Syntax `_. Format specifiers (like ``0.03f``) in strings will be used to format the quantity value:: >>> q = 15.1 * u.meter / (32.0 * u.second) >>> q # doctest: +FLOAT_CMP >>> f"{q:0.03f}" '0.472 m / s' The value and unit can also be formatted separately. Format specifiers for units can be used to choose the unit formatter:: >>> q = 15.1 * u.meter / (32.0 * u.second) >>> q # doctest: +FLOAT_CMP >>> f"{q.value:0.03f} {q.unit:FITS}" '0.472 m s-1' .. EXAMPLE END Using `astropy.units` ===================== .. toctree:: :maxdepth: 2 quantity type_hints standard_units combining_and_defining decomposing_and_composing logarithmic_units structured_units format equivalencies physical_types constants_versions conversion Acknowledgments =============== This code was originally based on the `pynbody `__ units module written by Andrew Pontzen, who has granted the Astropy Project permission to use the code under a BSD license. 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.misc .. automodapi:: astropy.units.function.units .. automodapi:: astropy.units.photometric .. automodapi:: astropy.units.imperial .. automodapi:: astropy.units.cds .. automodapi:: astropy.units.physical .. automodapi:: astropy.units.equivalencies .. automodapi:: astropy.units.function.core .. automodapi:: astropy.units.function.logarithmic :include-all-objects: .. automodapi:: astropy.units.deprecated .. automodapi:: astropy.units.required_by_vounit