Units and Quantities (`astropy.units`)¶

Introduction¶

astropy.units handles defining, converting between, and performing arithmetic with physical quantities. Examples of physical quantities are meters, seconds, Hz, etc.

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.0 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.47187... m / s>
>>> 3.0 * u.kilometer / (130.51 * u.meter / u.second)
<Quantity 0.0229867443... km s / m>
>>> (3.0 * u.kilometer / (130.51 * u.meter / u.second)).decompose()
<Quantity 22.9867443... 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.9... 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.93951324266284... 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>

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):
  ...
UnitsError: 'nm' (length) and 'Hz' (frequency) are not convertible
Traceback (most recent call last):
  ...
UnitsError: '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 299792457999999.94 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.47187... 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.47187... m / s>
>>> "{0.value:0.03f} {0.unit:FITS}".format(q)
'0.472 m s-1'

Using `astropy.units`¶

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.

Classes¶

Quantity A Quantity represents a number with some associated unit.

Class Inheritance Diagram¶

digraph inheritancec2fd2636e1 { rankdir=LR; size="8.0, 12.0"; "Quantity" [style="setlinewidth(0.5)",URL="../api/astropy.units.quantity.Quantity.html#astropy.units.quantity.Quantity",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A `Quantity` represents a number with some associated unit.",height=0.25,shape=box,fontsize=10]; "ndarray" -> "Quantity" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ndarray" [style="setlinewidth(0.5)",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="ndarray(shape, dtype=float, buffer=None, offset=0,",height=0.25,shape=box,fontsize=10]; }

astropy.units Module¶

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.

Functions¶

`add_enabled_equivalencies`(equivalencies)	Adds to the equivalencies enabled in the unit registry.
`add_enabled_units`(units)	Adds to the set of units enabled in the unit registry.
`brightness_temperature`(beam_area, disp)	Defines the conversion between Jy/beam and “brightness temperature”, $T_B$ , in Kelvins.
`def_physical_type`(unit, name)	Adds a new physical unit mapping.
`def_unit`(s[, represents, register, doc, ...])	Factory function for defining new units.
`dimensionless_angles`()	Allow angles to be equivalent to dimensionless (with 1 rad = 1 m/m = 1).
`doppler_optical`(rest)	Return the equivalency pairs for the optical convention for velocity.
`doppler_radio`(rest)	Return the equivalency pairs for the radio convention for velocity.
`doppler_relativistic`(rest)	Return the equivalency pairs for the relativistic convention for velocity.
`get_current_unit_registry`()
`get_physical_type`(unit)	Given a unit, returns the name of the physical quantity it represents.
`logarithmic`()	Allow logarithmic units to be converted to dimensionless fractions
`mass_energy`()	Returns a list of equivalence pairs that handle the conversion between mass and energy.
`parallax`()	Returns a list of equivalence pairs that handle the conversion between parallax angle and distance.
`set_enabled_equivalencies`(equivalencies)	Sets the equivalencies enabled in the unit registry.
`set_enabled_units`(units)	Sets the units enabled in the unit registry.
`spectral`()	Returns a list of equivalence pairs that handle spectral wavelength, wave number, frequency, and energy equivalences.
`spectral_density`(wav[, factor])	Returns a list of equivalence pairs that handle spectral density with regard to wavelength and frequency.
`temperature`()	Convert between Kelvin, Celsius, and Fahrenheit here because Unit and CompositeUnit cannot do addition or subtraction properly.
`temperature_energy`()	Convert between Kelvin and keV(eV) to an equivalent amount.

Classes¶

`CompositeUnit`(scale, bases, powers[, ...])	Create a composite unit using expressions of previously defined units.
`IrreducibleUnit`(st[, register, doc, format, ...])	Irreducible units are the units that all other units are defined in terms of.
`NamedUnit`(st[, register, doc, format, namespace])	The base class of units that have a name.
`PrefixUnit`(st[, represents, register, doc, ...])	A unit that is simply a SI-prefixed version of another unit.
`Quantity`	A `Quantity` represents a number with some associated unit.
`Unit`(st[, represents, register, doc, ...])	The main unit class.
`UnitBase`	Abstract base class for units.
`UnitsError`	The base class for unit-specific exceptions.
`UnitsWarning`	The base class for unit-specific exceptions.
`UnrecognizedUnit`(st[, register, doc, ...])	A unit that did not parse correctly.

Class Inheritance Diagram¶

digraph inheritance3ceb671924 { rankdir=LR; size="8.0, 12.0"; "AstropyWarning" [style="setlinewidth(0.5)",URL="../api/astropy.utils.exceptions.AstropyWarning.html#astropy.utils.exceptions.AstropyWarning",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The base warning class from which all Astropy warnings should inherit.",height=0.25,shape=box,fontsize=10]; "CompositeUnit" [style="setlinewidth(0.5)",URL="../api/astropy.units.CompositeUnit.html#astropy.units.CompositeUnit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Create a composite unit using expressions of previously defined",height=0.25,shape=box,fontsize=10]; "UnitBase" -> "CompositeUnit" [arrowsize=0.5,style="setlinewidth(0.5)"]; "IrreducibleUnit" [style="setlinewidth(0.5)",URL="../api/astropy.units.IrreducibleUnit.html#astropy.units.IrreducibleUnit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Irreducible units are the units that all other units are defined",height=0.25,shape=box,fontsize=10]; "NamedUnit" -> "IrreducibleUnit" [arrowsize=0.5,style="setlinewidth(0.5)"]; "NamedUnit" [style="setlinewidth(0.5)",URL="../api/astropy.units.NamedUnit.html#astropy.units.NamedUnit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The base class of units that have a name.",height=0.25,shape=box,fontsize=10]; "UnitBase" -> "NamedUnit" [arrowsize=0.5,style="setlinewidth(0.5)"]; "PrefixUnit" [style="setlinewidth(0.5)",URL="../api/astropy.units.PrefixUnit.html#astropy.units.PrefixUnit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A unit that is simply a SI-prefixed version of another unit.",height=0.25,shape=box,fontsize=10]; "Unit" -> "PrefixUnit" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Quantity" [style="setlinewidth(0.5)",URL="../api/astropy.units.quantity.Quantity.html#astropy.units.quantity.Quantity",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A `Quantity` represents a number with some associated unit.",height=0.25,shape=box,fontsize=10]; "ndarray" -> "Quantity" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Unit" [style="setlinewidth(0.5)",URL="../api/astropy.units.Unit.html#astropy.units.Unit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The main unit class.",height=0.25,shape=box,fontsize=10]; "NamedUnit" -> "Unit" [arrowsize=0.5,style="setlinewidth(0.5)"]; "UnitBase" [style="setlinewidth(0.5)",URL="../api/astropy.units.UnitBase.html#astropy.units.UnitBase",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Abstract base class for units.",height=0.25,shape=box,fontsize=10]; "UnitsError" [style="setlinewidth(0.5)",URL="../api/astropy.units.UnitsError.html#astropy.units.UnitsError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The base class for unit-specific exceptions.",height=0.25,shape=box,fontsize=10]; "UnitsWarning" [style="setlinewidth(0.5)",URL="../api/astropy.units.UnitsWarning.html#astropy.units.UnitsWarning",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The base class for unit-specific exceptions.",height=0.25,shape=box,fontsize=10]; "AstropyWarning" -> "UnitsWarning" [arrowsize=0.5,style="setlinewidth(0.5)"]; "UnrecognizedUnit" [style="setlinewidth(0.5)",URL="../api/astropy.units.UnrecognizedUnit.html#astropy.units.UnrecognizedUnit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A unit that did not parse correctly. This allows for",height=0.25,shape=box,fontsize=10]; "IrreducibleUnit" -> "UnrecognizedUnit" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ndarray" [style="setlinewidth(0.5)",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="ndarray(shape, dtype=float, buffer=None, offset=0,",height=0.25,shape=box,fontsize=10]; }

astropy.units.format Module¶

A collection of different unit formats.

Functions¶

get_format([format]) Get a formatter by name.

Classes¶

`Base`	The abstract base class of all unit formats.
`Generic`()	A “generic” format.
`CDS`()	Support the Centre de Données astronomiques de Strasbourg Standards for Astronomical Catalogues 2.0 format, and the complete set of supported units.
`Console`()	Output-only format for to display pretty formatting at the console.
`Fits`()	The FITS standard unit format.
`Latex`()	Output LaTeX to display the unit based on IAU style guidelines.
`OGIP`()	Support the units in Office of Guest Investigator Programs (OGIP) FITS files.
`Unicode`()	Output-only format to display pretty formatting at the console using Unicode characters.
`Unscaled`()	A format that doesn’t display the scale part of the unit, other than that, it is identical to the `Generic` format.
`VOUnit`()	The proposed IVOA standard for units used by the VO.

Class Inheritance Diagram¶

digraph inheritance4e9cbd1ff0 { rankdir=LR; size="8.0, 12.0"; "Base" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Base.html#astropy.units.format.Base",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The abstract base class of all unit formats.",height=0.25,shape=box,fontsize=10]; "CDS" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.CDS.html#astropy.units.format.CDS",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Support the `Centre de Données astronomiques de Strasbourg",height=0.25,shape=box,fontsize=10]; "Base" -> "CDS" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Console" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Console.html#astropy.units.format.Console",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Output-only format for to display pretty formatting at the",height=0.25,shape=box,fontsize=10]; "Base" -> "Console" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Fits" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Fits.html#astropy.units.format.Fits",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The FITS standard unit format.",height=0.25,shape=box,fontsize=10]; "Generic" -> "Fits" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Generic" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Generic.html#astropy.units.format.Generic",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A \"generic\" format.",height=0.25,shape=box,fontsize=10]; "Base" -> "Generic" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Latex" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Latex.html#astropy.units.format.Latex",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Output LaTeX to display the unit based on IAU style guidelines.",height=0.25,shape=box,fontsize=10]; "Base" -> "Latex" [arrowsize=0.5,style="setlinewidth(0.5)"]; "OGIP" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.OGIP.html#astropy.units.format.OGIP",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Support the units in `Office of Guest Investigator Programs (OGIP)",height=0.25,shape=box,fontsize=10]; "Generic" -> "OGIP" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Unicode" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Unicode.html#astropy.units.format.Unicode",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Output-only format to display pretty formatting at the console",height=0.25,shape=box,fontsize=10]; "Console" -> "Unicode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Unscaled" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.Unscaled.html#astropy.units.format.Unscaled",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A format that doesn't display the scale part of the unit, other",height=0.25,shape=box,fontsize=10]; "Generic" -> "Unscaled" [arrowsize=0.5,style="setlinewidth(0.5)"]; "VOUnit" [style="setlinewidth(0.5)",URL="../api/astropy.units.format.VOUnit.html#astropy.units.format.VOUnit",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="The proposed IVOA standard for units used by the VO.",height=0.25,shape=box,fontsize=10]; "Generic" -> "VOUnit" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

astropy.units.si Module¶

This package defines the SI units. They are also available in the astropy.units namespace.

Available Units
Unit	Description	Represents	Aliases	SI Prefixes
`A`	ampere: base unit of electric current in SI		`ampere`, `amp`	Y
`a`	annum (a)	$\mathrm{365.25\,d}$	`annum`	N
`Angstrom`	ångström: 10 ** -10 m	$\mathrm{0.1\,nm}$	`AA`, `angstrom`	N
`arcmin`	arc minute: angular measurement	$\mathrm{0.016666667\,{}^{\circ}}$	`arcminute`	N
`arcsec`	arc second: angular measurement	$\mathrm{0.00027777778\,{}^{\circ}}$	`arcsecond`	N
`bar`	bar: pressure	$\mathrm{100000\,Pa}$		N
`Bq`	becquerel: unit of radioactivity	$\mathrm{Hz}$	`becquerel`	N
`C`	coulomb: electric charge	$\mathrm{A\,s}$	`coulomb`	N
`cd`	candela: base unit of luminous intensity in SI		`candela`	Y
`Ci`	curie: unit of radioactivity	$\mathrm{2.7027027 \times 10^{-11}\,Bq}$	`curie`	N
`d`	day (d)	$\mathrm{24\,h}$	`day`	N
`deg`	degree: angular measurement 1/360 of full rotation	$\mathrm{0.017453293\,rad}$	`degree`	N
`deg_C`	Degrees Celsius		`Celsius`	N
`eV`	Electron Volt	$\mathrm{1.6021766 \times 10^{-19}\,J}$	`electronvolt`	N
`F`	Farad: electrical capacitance	$\mathrm{\frac{C}{V}}$	`Farad`, `farad`	N
`fortnight`	fortnight	$\mathrm{2\,wk}$		N
`g`	gram (g)	$\mathrm{0.001\,kg}$	`gram`	N
`H`	Henry: inductance	$\mathrm{\frac{Wb}{A}}$	`Henry`, `henry`	N
`h`	hour (h)	$\mathrm{3600\,s}$	`hour`, `hr`	N
`hourangle`	hour angle: angular measurement with 24 in a full circle	$\mathrm{15\,{}^{\circ}}$		N
`Hz`	Frequency	$\mathrm{\frac{1}{s}}$	`Hertz`, `hertz`	N
`J`	Joule: energy	$\mathrm{N\,m}$	`Joule`, `joule`	N
`K`	Kelvin: temperature with a null point at absolute zero.		`Kelvin`	Y
`kg`	kilogram: base unit of mass in SI.		`kilogram`	Y
`l`	liter: metric unit of volume	$\mathrm{1000\,cm^{3}}$	`L`, `liter`	N
`lm`	lumen: luminous flux	$\mathrm{cd\,sr}$	`lumen`	N
`lx`	lux: luminous emittence	$\mathrm{\frac{lm}{m^{2}}}$	`lux`	N
`m`	meter: base unit of length in SI		`meter`	Y
`mas`	arc second: angular measurement	$\mathrm{0.001\,{}^{\prime\prime}}$		N
`micron`	micron: alias for micrometer (um)	$\mathrm{\mu m}$		N
`min`	minute (min)	$\mathrm{60\,s}$	`minute`	N
`mol`	mole: amount of a chemical substance in SI.		`mole`	Y
`N`	Newton: force	$\mathrm{\frac{kg\,m}{s^{2}}}$	`Newton`, `newton`	N
`Ohm`	Ohm: electrical resistance	$\mathrm{\frac{V}{A}}$	`ohm`, `Ohm`	N
`Pa`	Pascal: pressure	$\mathrm{\frac{J}{m^{3}}}$	`Pascal`, `pascal`	N
`%`	percent: one hundredth of unity, factor 0.01	$\mathrm{0.01\,}$	`pct`	N
`rad`	radian: angular measurement of the ratio between the length on an arc and its radius		`radian`	Y
`S`	Siemens: electrical conductance	$\mathrm{\frac{A}{V}}$	`Siemens`, `siemens`	N
`s`	second: base unit of time in SI.		`second`	Y
`sday`	Sidereal day (sday) is the time of one rotation of the Earth.	$\mathrm{86164.091\,s}$		N
`sr`	steradian: unit of solid angle in SI	$\mathrm{rad^{2}}$	`steradian`	N
`t`	Metric tonne	$\mathrm{1000\,kg}$	`tonne`	N
`T`	Tesla: magnetic flux density	$\mathrm{\frac{Wb}{m^{2}}}$	`Tesla`, `tesla`	N
`uas`	arc second: angular measurement	$\mathrm{1 \times 10^{-6}\,{}^{\prime\prime}}$		N
`V`	Volt: electric potential or electromotive force	$\mathrm{\frac{J}{C}}$	`Volt`, `volt`	N
`W`	Watt: power	$\mathrm{\frac{J}{s}}$	`Watt`, `watt`	N
`Wb`	Weber: magnetic flux	$\mathrm{V\,s}$	`Weber`, `weber`	N
`wk`	week (wk)	$\mathrm{7\,d}$	`week`	N
`yr`	year (yr)	$\mathrm{365.25\,d}$	`year`	N

astropy.units.cgs Module¶

This package defines the CGS units. They are also available in the top-level astropy.units namespace.

Available Units
Unit	Description	Represents	Aliases	SI Prefixes
`abC`	abcoulomb: CGS (EMU) of charge	$\mathrm{Bi\,s}$	`abcoulomb`	N
`Ba`	Barye: CGS unit of pressure	$\mathrm{\frac{g}{cm\,s^{2}}}$	`Barye`, `barye`	N
`Bi`	Biot: CGS (EMU) unit of current	$\mathrm{\frac{cm^{1/2}\,g^{1/2}}{s}}$	`Biot`, `abA`, `abampere`, `emu`	N
`C`	coulomb: electric charge	$\mathrm{A\,s}$	`coulomb`	N
`cd`	candela: base unit of luminous intensity in SI		`candela`	N
`cm`	centimeter (cm)	$\mathrm{cm}$	`centimeter`	N
`D`	Debye: CGS unit of electric dipole moment	$\mathrm{3.3333333 \times 10^{-30}\,C\,m}$	`Debye`, `debye`	N
`deg_C`	Degrees Celsius		`Celsius`	N
`dyn`	dyne: CGS unit of force	$\mathrm{\frac{cm\,g}{s^{2}}}$	`dyne`	N
`erg`	erg: CGS unit of energy	$\mathrm{\frac{cm^{2}\,g}{s^{2}}}$		N
`Fr`	Franklin: CGS (ESU) unit of charge	$\mathrm{\frac{cm^{3/2}\,g^{1/2}}{s}}$	`Franklin`, `statcoulomb`, `statC`, `esu`	N
`G`	Gauss: CGS unit for magnetic field	$\mathrm{0.0001\,T}$	`Gauss`, `gauss`	N
`g`	gram (g)	$\mathrm{0.001\,kg}$	`gram`	N
`Gal`	Gal: CGS unit of acceleration	$\mathrm{\frac{cm}{s^{2}}}$	`gal`	N
`K`	Kelvin: temperature with a null point at absolute zero.		`Kelvin`	N
`k`	kayser: CGS unit of wavenumber	$\mathrm{\frac{1}{cm}}$	`Kayser`, `kayser`	N
`mol`	mole: amount of a chemical substance in SI.		`mole`	N
`P`	poise: CGS unit of dynamic viscosity	$\mathrm{\frac{g}{cm\,s}}$	`poise`	N
`rad`	radian: angular measurement of the ratio between the length on an arc and its radius		`radian`	N
`s`	second: base unit of time in SI.		`second`	N
`sr`	steradian: unit of solid angle in SI	$\mathrm{rad^{2}}$	`steradian`	N
`St`	stokes: CGS unit of kinematic viscosity	$\mathrm{\frac{cm^{2}}{s}}$	`stokes`	N
`statA`	statampere: CGS (ESU) unit of current	$\mathrm{\frac{Fr}{s}}$	`statampere`	N

astropy.units.astrophys Module¶

This package defines the astrophysics-specific units. They are also available in the astropy.units namespace.

The mag unit is provided for compatibility with the FITS unit string standard. However, it is not very useful as-is since it is “orphaned” and can not be converted to any other unit. A future astropy magnitudes library is planned to address this shortcoming.

Available Units
Unit	Description	Represents	Aliases	SI Prefixes
`adu`	adu			N
`AU`	astronomical unit: approximately the mean Earth–Sun distance.	$\mathrm{1.4959787 \times 10^{11}\,m}$	`au`	N
`barn`	barn: unit of area used in HEP	$\mathrm{1 \times 10^{-28}\,m^{2}}$		N
`beam`	beam			N
`bin`	bin			N
`bit`	b (bit)		`b`, `bit`	Y
`byte`	B (byte)		`B`, `byte`	Y
`chan`	chan			N
`ct`	count (ct)		`count`	N
`cycle`	cycle: angular measurement, a full turn or rotation	$\mathrm{6.2831853\,rad}$	`cy`	N
`dB`	Decibel: ten per base 10 logarithmic unit	$\mathrm{0.1\,dex}$	`decibel`	N
`dex`	Dex: Base 10 logarithmic unit			Y
`electron`	Number of electrons			N
`Jy`	Jansky: spectral flux density	$\mathrm{1 \times 10^{-26}\,\frac{W}{Hz\,m^{2}}}$	`Jansky`, `jansky`	N
`lyr`	Light year	$\mathrm{9.4607305 \times 10^{15}\,m}$	`lightyear`	N
`M_e`	Electron mass	$\mathrm{9.1093829 \times 10^{-31}\,kg}$		N
`M_p`	Proton mass	$\mathrm{1.6726218 \times 10^{-27}\,kg}$		N
`mag`	Astronomical magnitude: -2.5 per base 10 logarithmic unit	$\mathrm{-0.4\,dex}$		N
`pc`	parsec: approximately 3.26 light-years.	$\mathrm{3.0856776 \times 10^{16}\,m}$	`parsec`	N
`ph`	photon (ph)		`photon`	Y
`pix`	pixel (pix)		`pixel`	N
`R`	Rayleigh: photon flux	$\mathrm{7.9577472 \times 10^{8}\,\frac{ph}{s\,sr\,m^{2}}}$	`Rayleigh`, `rayleigh`	N
`Ry`	Rydberg: Energy of a photon whose wavenumber is the Rydberg constant	$\mathrm{13.605692\,eV}$	`rydberg`	N
`solLum`	Solar luminance	$\mathrm{3.846 \times 10^{26}\,W}$	`L_sun`, `Lsun`	N
`solMass`	Solar mass	$\mathrm{1.9891 \times 10^{30}\,kg}$	`M_sun`, `Msun`	N
`solRad`	Solar radius	$\mathrm{6.95508 \times 10^{8}\,m}$	`R_sun`, `Rsun`	N
`Sun`	Sun			N
`u`	Unified atomic mass unit	$\mathrm{1.6605387 \times 10^{-27}\,kg}$	`Da`, `Dalton`	N
`vox`	voxel (vox)		`voxel`	N

astropy.units.imperial Module¶

This package defines colloquially used Imperial units. By default, they are not enabled. To enable them, do:

>>> from astropy.units import imperial
>>> imperial.enable()  

Available Units
Unit	Description	Represents	Aliases	SI Prefixes
`ac`	International acre	$\mathrm{43560\,ft^{2}}$	`acre`	N
`BTU`	British thermal unit	$\mathrm{1.0550559\,kJ}$	`btu`	N
`cal`	Thermochemical calorie: pre-SI metric unit of energy	$\mathrm{4.184\,J}$	`calorie`	N
`cup`	U.S.	$\mathrm{0.5\,pint}$		N
`deg_F`	Degrees Fahrenheit		`Fahrenheit`	N
`foz`	U.S.	$\mathrm{0.125\,cup}$	`fluid_oz`, `fluid_ounce`	N
`ft`	International foot	$\mathrm{12\,inch}$	`foot`	N
`gallon`	U.S.	$\mathrm{3.7854118\,\mathcal{l}}$		N
`hp`	Electrical horsepower	$\mathrm{745.69987\,W}$	`horsepower`	N
`inch`	International inch	$\mathrm{2.54\,cm}$		N
`kcal`	Calorie: colloquial definition of Calorie	$\mathrm{1000\,cal}$	`Cal`, `Calorie`, `kilocal`, `kilocalorie`	N
`kn`	nautical unit of speed: 1 nmi per hour	$\mathrm{\frac{nmi}{h}}$	`kt`, `knot`, `NMPH`	N
`lb`	International avoirdupois pound	$\mathrm{16\,oz}$	`pound`	N
`mi`	International mile	$\mathrm{5280\,ft}$	`mile`	N
`nmi`	Nautical mile	$\mathrm{1852\,m}$	`nauticalmile`, `NM`	N
`oz`	International avoirdupois ounce	$\mathrm{28.349523\,g}$	`ounce`	N
`pint`	U.S.	$\mathrm{0.5\,quart}$		N
`quart`	U.S.	$\mathrm{0.25\,gallon}$		N
`tbsp`	U.S.	$\mathrm{0.5\,foz}$	`tablespoon`	N
`ton`	International avoirdupois ton	$\mathrm{2000\,lb}$		N
`tsp`	U.S.	$\mathrm{0.33333333\,tbsp}$	`teaspoon`	N
`yd`	International yard	$\mathrm{3\,ft}$	`yard`	N

Functions¶

enable() Enable Imperial units so they appear in results of find_equivalent_units and compose.

astropy.units.cds Module¶

This package defines units used in the CDS format.

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

To include them in compose and the results of find_equivalent_units, do:

>>> from astropy.units import cds
>>> cds.enable()  

Available Units
Unit	Description	Represents	Aliases	SI Prefixes
`%`	percent	$\mathrm{\%}$		N
`---`	dimensionless and unscaled	$\mathrm{}$		N
`\h`	Planck constant	$\mathrm{6.6260696 \times 10^{-34}\,J\,s}$		N
`A`	Ampere	$\mathrm{A}$		Y
`a`	year	$\mathrm{a}$		N
`a0`	Bohr radius	$\mathrm{5.2917721 \times 10^{-11}\,m}$		N
`AA`	Angstrom	$\mathrm{\overset{\circ}{A}}$	`Å`, `Angstrom`, `Angstroem`	N
`al`	Light year	$\mathrm{lyr}$		N
`alpha`	Fine structure constant	$\mathrm{0.0072973526\,}$		N
`arcm`	minute of arc	$\mathrm{{}^{\prime}}$	`arcmin`	N
`arcs`	second of arc	$\mathrm{{}^{\prime\prime}}$	`arcsec`	N
`atm`	atmosphere	$\mathrm{101325\,Pa}$		N
`AU`	astronomical unit	$\mathrm{AU}$	`au`	N
`bar`	bar	$\mathrm{bar}$		N
`barn`	barn	$\mathrm{barn}$		N
`bit`	bit	$\mathrm{bit}$		Y
`byte`	byte	$\mathrm{byte}$		Y
`C`	Coulomb	$\mathrm{C}$		N
`c`	speed of light	$\mathrm{2.9979246 \times 10^{8}\,\frac{m}{s}}$		N
`cal`	calorie	$\mathrm{4.1854\,J}$		N
`cd`	candela	$\mathrm{cd}$		Y
`Crab`	Crab (X-ray) flux			Y
`ct`	count	$\mathrm{ct}$		Y
`D`	Debye (dipole)	$\mathrm{D}$		N
`d`	Julian day	$\mathrm{d}$		N
`deg`	degree	$\mathrm{{}^{\circ}}$	`°`, `degree`	N
`dyn`	dyne	$\mathrm{dyn}$		N
`e`	electron charge	$\mathrm{1.6021766 \times 10^{-19}\,C}$		N
`eps0`	electric constant	$\mathrm{8.8541878 \times 10^{-12}\,\frac{F}{m}}$		N
`erg`	erg	$\mathrm{erg}$		N
`eV`	electron volt	$\mathrm{eV}$		N
`F`	Farad	$\mathrm{F}$		N
`G`	Gravitation constant	$\mathrm{6.67384 \times 10^{-11}\,\frac{m^{3}}{kg\,s^{2}}}$		N
`g`	gram	$\mathrm{g}$		N
`gauss`	Gauss	$\mathrm{G}$		N
`geoMass`	Earth mass	$\mathrm{5.9742 \times 10^{24}\,kg}$	`Mgeo`	N
`H`	Henry	$\mathrm{H}$		N
`h`	hour	$\mathrm{h}$		N
`hr`	hour	$\mathrm{h}$		N
`Hz`	Hertz	$\mathrm{Hz}$		N
`inch`	inch	$\mathrm{0.0254\,m}$		N
`J`	Joule	$\mathrm{J}$		N
`JD`	Julian day	$\mathrm{d}$		N
`jovMass`	Jupiter mass	$\mathrm{1.8987 \times 10^{27}\,kg}$	`Mjup`	N
`Jy`	Jansky	$\mathrm{Jy}$		N
`k`	Boltzmann	$\mathrm{1.3806488 \times 10^{-23}\,\frac{J}{K}}$		N
`K`	Kelvin	$\mathrm{K}$		Y
`l`	litre	$\mathrm{\mathcal{l}}$		N
`lm`	lumen	$\mathrm{lm}$		N
`Lsun`	solar luminosity	$\mathrm{L_{\odot}}$	`solLum`	N
`lx`	lux	$\mathrm{lx}$		N
`lyr`	Light year	$\mathrm{lyr}$		N
`m`	meter	$\mathrm{m}$		Y
`mag`	magnitude	$\mathrm{mag}$		N
`mas`	millisecond of arc	$\mathrm{marcsec}$		N
`me`	electron mass	$\mathrm{9.1093829 \times 10^{-31}\,kg}$		N
`min`	minute	$\mathrm{min}$		N
`MJD`	Julian day	$\mathrm{d}$		N
`mmHg`	millimeter of mercury	$\mathrm{133.32239\,Pa}$		N
`mol`	mole	$\mathrm{mol}$		Y
`mp`	proton mass	$\mathrm{1.6726218 \times 10^{-27}\,kg}$		N
`Msun`	solar mass	$\mathrm{M_{\odot}}$	`solMass`	N
`mu0`	magnetic constant	$\mathrm{1.2566371 \times 10^{-6}\,\frac{N}{A^{2}}}$	`µ0`	N
`muB`	Bohr magneton	$\mathrm{9.2740097 \times 10^{-24}\,\frac{J}{T}}$		N
`N`	Newton	$\mathrm{N}$		N
`Ohm`	Ohm	$\mathrm{\Omega}$		N
`Pa`	Pascal	$\mathrm{Pa}$		N
`pc`	parsec	$\mathrm{pc}$		N
`ph`	photon	$\mathrm{ph}$		Y
`pi`	π	$\mathrm{3.1415927\,}$		N
`pix`	pixel	$\mathrm{pix}$		Y
`ppm`	parts per million	$\mathrm{1 \times 10^{-6}\,}$		N
`R`	gas constant	$\mathrm{8.3144621\,\frac{J}{K\,mol}}$		N
`rad`	radian	$\mathrm{rad}$		Y
`Rgeo`	Earth equatorial radius	$\mathrm{6378136\,m}$		N
`Rjup`	Jupiter equatorial radius	$\mathrm{71492000\,m}$		N
`Rsun`	solar radius	$\mathrm{R_{\odot}}$	`solRad`	N
`Ry`	Rydberg	$\mathrm{R_{\infty}}$		N
`s`	second	$\mathrm{s}$	`sec`	Y
`S`	Siemens	$\mathrm{S}$		N
`sr`	steradian	$\mathrm{sr}$		N
`Sun`	solar unit	$\mathrm{Sun}$		Y
`T`	Tesla	$\mathrm{T}$		N
`t`	metric tonne	$\mathrm{1000\,kg}$		N
`u`	atomic mass	$\mathrm{1.6605389 \times 10^{-27}\,kg}$		N
`V`	Volt	$\mathrm{V}$		N
`W`	Watt	$\mathrm{W}$		N
`Wb`	Weber	$\mathrm{Wb}$		N
`yr`	year	$\mathrm{a}$		N
`µas`	microsecond of arc	$\mathrm{\mu arcsec}$		N

Functions¶

enable() Enable CDS units so they appear in results of find_equivalent_units and compose.

astropy.units.equivalencies Module¶

A set of standard astronomical equivalencies.

Functions¶

`parallax`()	Returns a list of equivalence pairs that handle the conversion between parallax angle and distance.
`spectral`()	Returns a list of equivalence pairs that handle spectral wavelength, wave number, frequency, and energy equivalences.
`spectral_density`(wav[, factor])	Returns a list of equivalence pairs that handle spectral density with regard to wavelength and frequency.
`doppler_radio`(rest)	Return the equivalency pairs for the radio convention for velocity.
`doppler_optical`(rest)	Return the equivalency pairs for the optical convention for velocity.
`doppler_relativistic`(rest)	Return the equivalency pairs for the relativistic convention for velocity.
`mass_energy`()	Returns a list of equivalence pairs that handle the conversion between mass and energy.
`brightness_temperature`(beam_area, disp)	Defines the conversion between Jy/beam and “brightness temperature”, $T_B$ , in Kelvins.
`dimensionless_angles`()	Allow angles to be equivalent to dimensionless (with 1 rad = 1 m/m = 1).
`logarithmic`()	Allow logarithmic units to be converted to dimensionless fractions
`temperature`()	Convert between Kelvin, Celsius, and Fahrenheit here because Unit and CompositeUnit cannot do addition or subtraction properly.
`temperature_energy`()	Convert between Kelvin and keV(eV) to an equivalent amount.

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.

Units and Quantities (`astropy.units`)¶

Introduction¶

Getting Started¶

Using `astropy.units`¶

See Also¶

Reference/API¶

astropy.units.quantity Module¶

Classes¶

Class Inheritance Diagram¶

astropy.units Module¶

Functions¶

Classes¶

Class Inheritance Diagram¶

astropy.units.format Module¶

Functions¶

Classes¶

Class Inheritance Diagram¶

astropy.units.si Module¶

astropy.units.cgs Module¶

astropy.units.astrophys Module¶

astropy.units.imperial Module¶

Functions¶

astropy.units.cds Module¶

Functions¶

astropy.units.equivalencies Module¶

Functions¶

Acknowledgments¶

Page Contents

Navigation

Units and Quantities (astropy.units)¶

Introduction¶

Getting Started¶

Using astropy.units¶

See Also¶

Reference/API¶

astropy.units.quantity Module¶

Classes¶

Class Inheritance Diagram¶

astropy.units Module¶

Functions¶

Classes¶

Class Inheritance Diagram¶

astropy.units.format Module¶

Functions¶

Classes¶

Class Inheritance Diagram¶

astropy.units.si Module¶

astropy.units.cgs Module¶

astropy.units.astrophys Module¶

astropy.units.imperial Module¶

Functions¶

astropy.units.cds Module¶

Functions¶

astropy.units.equivalencies Module¶

Functions¶

Acknowledgments¶

Page Contents

Units and Quantities (`astropy.units`)¶

Using `astropy.units`¶