Navigation

Units (astropy.units)

Introduction

astropy.units is a Python package to handle 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.units also handles equivalencies, such as that between wavelength and frequency. To use that feature, equivalence objects are passed to the to conversion method:

# 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 unit (spectral()), it does...
>>> u.nm.to(u.Hz, [1000, 2000], equivs=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 units:

>>> from astropy import units as u
>>> 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)).simplify_units()
<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.1557 \times 10^{7}\ s} annum N
adu adu     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
beam beam     N
bin bin     N
bit bit     Y
byte byte     Y
C coulomb: electric charge \mathrm{A\ s} coulomb N
cd candela: base unit of luminous intensity in SI   candela Y
chan chan     N
ct count (ct)   count 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 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{10^{3}\ cm^{3.0}} 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 milliarc second: angular measurement \mathrm{2.7778 \times 10^{-7}\ {}^{\circ}}   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
ph photon (ph)   photon N
pix pixel (pix)   pixel N
rad radian: angular measurement of the ratio between the length on an arc and its radius   radian Y
s second: base unit of time in SI.   second Y
S Siemens: electrical conductance \mathrm{\frac{A}{V}} Siemens, siemens N
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
V Volt: electric potential or electromotive force \mathrm{\frac{J}{C}} Volt, volt N
vox voxel (vox)   voxel 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{3.1557 \times 10^{7}\ s} 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
Ba Barye: CGS unit of pressure \mathrm{\frac{g}{cm\ s^{2}}} Barye, barye N
D Debye: CGS unit of electric dipole moment \mathrm{3.3333 \times 10^{-30}\ C\ m} 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 (Fr) \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
Gal Gal: CGS unit of acceleration \mathrm{\frac{cm}{s^{2}}} gal N
k kayser: CGS unit of wavenumber \mathrm{\frac{1}{cm}} Kayser, kayser N
P poise: CGS unit of dynamic viscosity \mathrm{\frac{g}{s\ cm}} poise N
St stokes: CGS unit of kinematic viscosity \mathrm{\frac{cm^{2}}{s}} stokes 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
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
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
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

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

[edit this page on github]

Page Contents




Brought to you by Read the Docs