Units and Quantities (astropy.units) — Astropy v6.0.1 (2024)

Introduction#

astropy.units handles defining, converting between, and performingarithmetic 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 Quantity objects: the combination of a value and a unit. The most convenient way tocreate a Quantity is to multiply or divide a value by one of the built-inunits. 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>

>>> q = 42.0 * u.meter>>> q.value42.0>>> q.unitUnit("m")

>>> 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>

>>> x = 1.0 * u.parsec>>> x.to(u.km) <Quantity 30856775814671.914 km>

>>> 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>

>>> u.m / u.mUnit(dimensionless)

>>> q = 1.0 * u.dimensionless_unscaled>>> q.unitUnit(dimensionless)

>>> (u.s ** -1).compose() [Unit("Bq"), Unit("Hz"), Unit("2.7027e-11 Ci")]

>>> (1.0 * u.Pa).cgs<Quantity 10. P / s>

>>> -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)>

>>> (1000 * u.nm).to(u.Hz) Traceback (most recent call last): ...UnitConversionError: 'nm' (length) and 'Hz' (frequency) are not convertible

>>> (1000 * u.nm).to(u.Hz, equivalencies=u.spectral()) <Quantity 2.99792458e+14 Hz>

>>> q = 15.1 * u.meter / (32.0 * u.second)>>> q <Quantity 0.471875 m / s>>>> f"{q:0.03f}"'0.472 m / s'

>>> q = 15.1 * u.meter / (32.0 * u.second)>>> q <Quantity 0.471875 m / s>>>> f"{q.value:0.03f} {q.unit:FITS}"'0.472 m s-1'

Using astropy.units#

Acknowledgments#

This code was originally based on the pynbody units module written by AndrewPontzen, who has granted the Astropy Project permission to use the codeunder a BSD license.

See Also#

• FITS Standard forunits in FITS.

• The Units in the VO 1.0 Standard for representing units inthe 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.

Performance Tips#

If you are attaching units to arrays to make Quantity objects, multiplyingarrays by units will result in the array being copied in memory, which will slowthings down. Furthermore, if you are multiplying an array by a composite unit,the array will be copied for each individual multiplication. Thus, in thefollowing case, the array is copied four successive times:

In [1]: import numpy as npIn [2]: from astropy import units as uIn [3]: rng = np.random.default_rng()In [4]: array = rng.random(10000000)In [5]: %timeit array * u.m / u.s / u.kg / u.sr92.5 ms ± 2.52 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)

There are several ways to speed this up. First, when you are using compositeunits, ensure that the entire unit gets evaluated first, then attached to thearray. You can do this by using parentheses as for any other operation:

In [6]: %timeit array * (u.m / u.s / u.kg / u.sr)21.5 ms ± 886 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)

In this case, this has sped things up by a factor of 4. If you use a compositeunit several times in your code then you can define a variable for it:

In [7]: UNIT_MSKGSR = u.m / u.s / u.kg / u.srIn [8]: %timeit array * UNIT_MSKGSR22.2 ms ± 551 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)

In this case and the case with brackets, the array is still copied once whencreating the Quantity. If you want to avoid any copies altogether, you canmake use of the << operator to attach the unit to the array:

In [9]: %timeit array << u.m / u.s / u.kg / u.sr47.1 µs ± 5.77 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each)

Note that these are now microseconds, so this is 2000x faster than theoriginal case with no brackets. Note that brackets are not needed when using<< since * and / have a higher precedence, so the unit will beevaluated first. When using <<, be aware that because the data is not beingcopied, changing the original array will also change the Quantity object.

Note that for composite units, you will definitely see animpact if you can pre-compute the composite unit:

In [10]: %timeit array << UNIT_MSKGSR6.51 µs ± 112 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)

Which is over 10000x faster than the original example. SeeCreating and Converting Quantities without Copies for more details about the <<operator.

Reference/API#