Navigation

Units (astropy.units)

Introduction

astropy.units handles defining and converting between physical units, and performing arithmetic with physical quantities (numbers with associated units).

Getting Started

>>> from astropy import units as u
>>> # Convert from parsec to meter
>>> u.pc.to(u.m)
3.0856776e+16
>>> cms = u.cm / u.s
>>> mph = u.mile / u.hour
>>> cms.to(mph, 1)
0.02236936292054402
>>> cms.to(mph, [1., 1000., 5000.])
array([  2.23693629e-02,   2.23693629e+01,   1.11846815e+02])

Units that “cancel out” become a special unit called the “dimensionless unit”:

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

astropy is able to match compound units against the units it already knows about:

>>> (u.s ** -1).compose()
[Unit("Hz"), ...]

And it can convert between unit systems:

>>> u.Pa.to_system(u.cgs)
[Unit("1.000000e+01 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:

>>> u.nm.to(u.Hz, [1000, 2000])
UnitsException: 'nm' (length) and 'Hz' (frequency) are not convertible

but by passing an equivalency list, in this case spectral(), it does:

>>> u.nm.to(u.Hz, [1000, 2000], equivalencies=u.spectral())
array([  2.99792458e+14,   1.49896229e+14])
>>> u.nm.to(u.eV, [1000, 2000], equivs=u.spectral())
array([ 1.23984201,  0.61992101])

Also included in the astropy.units package is the Quantity object, which represents a numerical value with an associated unit. These objects support arithmetic with other numbers and Quantity objects and preserve their 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.0229867443108 km s / (m)>
>>> (3.0 * u.kilometer / (130.51 * u.meter / u.second)).decompose()
<Quantity 22.9867443108 s>

See Also

Reference/API

astropy.units.core Module

Core units classes and functions

Functions

def_unit(s[, represents, register, doc, ...]) Factory function for defining new units.

Classes

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

Class Inheritance Diagram

Inheritance diagram of astropy.units.core.UnitsException, astropy.units.core.UnitsWarning, astropy.units.core.UnitBase, astropy.units.core.NamedUnit, astropy.units.core.IrreducibleUnit, astropy.units.core.Unit, astropy.units.core.CompositeUnit, astropy.units.core.PrefixUnit, astropy.units.core.UnrecognizedUnit

astropy.units.format Module

A collection of different unit formats.

Functions

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

Classes

Generic() A “generic” format.
CDS() Support the Centre de Données astronomiques de Strasbourg Standards for Astronomical Catalogues 2.0 format.
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.
Unicode() Output-only format for 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

Inheritance diagram of astropy.units.format.generic.Generic, astropy.units.format.cds.CDS, astropy.units.format.console.Console, astropy.units.format.fits.Fits, astropy.units.format.latex.Latex, astropy.units.format.unicode_format.Unicode, astropy.units.format.generic.Unscaled, astropy.units.format.vounit.VOUnit

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{3.6525 \times 10^{2}\ d} annum N
Angstrom ångström: 10 ** -10 m \mathrm{10^{-1}\ nm} AA, angstrom N
arcmin arc minute: angular measurement \mathrm{1.6667 \times 10^{-2}\ {}^{\circ}} arcminute N
arcsec arc second: angular measurement \mathrm{2.7778 \times 10^{-4}\ {}^{\circ}} arcsecond 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.7027 \times 10^{-11}\ Bq} curie N
d day (d) \mathrm{2.4 \times 10^{1}\ h} day N
deg degree: angular measurement 1/360 of full rotation \mathrm{1.7453 \times 10^{-2}\ rad} degree N
eV Electron Volt \mathrm{1.6022 \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{10^{-3}\ kg} gram N
H Henry: inductance \mathrm{\frac{Wb}{A}} Henry, henry N
h hour (h) \mathrm{3.6 \times 10^{3}\ s} hour, hr N
hourangle hour angle: angular measurement with 24 in a full circle \mathrm{1.5 \times 10^{1}\ {}^{\circ}}   N
Hz Frequency \mathrm{\frac{1}{s}} Hertz, hertz N
J Joule: energy \mathrm{m\ N} 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{10^{3}\ cm^{3.0}} L, liter N
lm lumen: luminous flux \mathrm{sr\ cd} 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{10^{-3}\ {}^{\prime\prime}}   N
micron micron: alias for micrometer (um) \mathrm{\mu m}   N
min minute (min) \mathrm{6 \times 10^{1}\ 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 N
Pa Pascal: pressure \mathrm{\frac{J}{m^{3}}} Pascal, pascal 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{8.6164 \times 10^{4}\ s}   N
sr steradian: unit of solid angle in SI \mathrm{rad^{2}} steradian N
t Metric tonne \mathrm{10^{3}\ kg} tonne N
T Tesla: magnetic flux density \mathrm{\frac{Wb}{m^{2}}} Tesla, tesla N
uas arc second: angular measurement \mathrm{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{s\ V} Weber, weber N
wk week (wk) \mathrm{7\ d} week N
yr year (yr) \mathrm{3.6525 \times 10^{2}\ 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{s\ Bi} 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{g^{1/2}\ cm^{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.3333 \times 10^{-30}\ m\ C} Debye, debye N
dyn dyne: CGS unit of force \mathrm{\frac{g\ cm}{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{10^{-4}\ T} Gauss, gauss N
g gram (g) \mathrm{10^{-3}\ 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}{s\ cm}} 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.496 \times 10^{11}\ m} au N
barn barn: unit of area used in HEP \mathrm{10^{-28}\ m^{2}}   N
beam beam     N
bin bin     N
bit bit     Y
byte byte     Y
chan chan     N
ct count (ct)   count N
Jy Jansky: spectral flux density \mathrm{10^{-26}\ \frac{W}{Hz\ m^{2}}} Jansky, jansky N
lyr Light year \mathrm{9.4607 \times 10^{15}\ m} lightyear N
M_e Electron mass \mathrm{9.1094 \times 10^{-31}\ kg}   N
M_p Proton mass \mathrm{1.6726 \times 10^{-27}\ kg}   N
mag Stellar magnitude.     Y
pc parsec: approximately 3.26 light-years. \mathrm{3.0857 \times 10^{16}\ m} parsec N
ph photon (ph)   photon Y
pix pixel (pix)   pixel N
R Rayleigh: photon flux \mathrm{7.9577 \times 10^{8}\ \frac{ph}{sr\ s\ m^{2}}} Rayleigh, rayleigh N
Ry Rydberg: Energy of a photon whose wavenumber is the Rydberg constant \mathrm{1.3606 \times 10^{1}\ eV} rydberg N
solLum Solar luminance \mathrm{3.846 \times 10^{26}\ W} L_sun N
solMass Solar mass \mathrm{1.9891 \times 10^{30}\ kg} M_sun N
solRad Solar radius \mathrm{6.9551 \times 10^{8}\ m} R_sun N
Sun Sun     N
u Unified atomic mass unit \mathrm{1.6605 \times 10^{-27}\ kg} Da, Dalton N
vox voxel (vox)   voxel N

astropy.units.imperial Module

This package defines colloquially used Imperial units. They are also available in the astropy.units namespace.

Available Units
Unit Description Represents Aliases SI Prefixes
ac International acre \mathrm{4.356 \times 10^{4}\ ft^{2}} acre N
BTU British thermal unit \mathrm{1.0551\ kJ} btu N
cal Thermochemical calorie: pre-SI metric unit of energy \mathrm{4.184\ J} calorie N
cup U.S. \mathrm{5 \times 10^{-1}\ pint}   N
foz U.S. \mathrm{1.25 \times 10^{-1}\ cup} fluid_oz, fluid_ounce N
ft International foot \mathrm{1.2 \times 10^{1}\ inch} foot N
gallon U.S. \mathrm{3.7854\ l}   N
hp Electrical horsepower \mathrm{7.457 \times 10^{2}\ W} horsepower N
inch International inch \mathrm{2.54\ cm}   N
kcal Calorie: colloquial definition of Calorie \mathrm{10^{3}\ 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{1.6 \times 10^{1}\ oz} pound N
mi International mile \mathrm{5.28 \times 10^{3}\ ft} mile N
nmi Nautical mile \mathrm{1.852 \times 10^{3}\ m} nauticalmile, NM N
oz International avoirdupois ounce \mathrm{2.835 \times 10^{1}\ g} ounce N
pint U.S. \mathrm{5 \times 10^{-1}\ quart}   N
quart U.S. \mathrm{2.5 \times 10^{-1}\ gallon}   N
tbsp U.S. \mathrm{5 \times 10^{-1}\ foz} tablespoon N
ton International avoirdupois ton \mathrm{2 \times 10^{3}\ lb}   N
tsp U.S. \mathrm{3.3333 \times 10^{-1}\ tbsp} teaspoon N
yd International yard \mathrm{3\ ft} yard N

astropy.units.equivalencies Module

A set of standard astronomical equivalencies.

Functions

spectral() Returns a list of equivalence pairs that handle spectral wavelength, frequency, and energy equivalences.
spectral_density(sunit, sfactor) Returns a list of equivalence pairs that handle spectral density with regard to wavelength and frequency.

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(value, unit) A Quantity represents a number with some associated unit.

Class Inheritance Diagram

Inheritance diagram of astropy.units.quantity.Quantity

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.

Page Contents