astropy.units handles defining and converting between physical units, and performing arithmetic with physical quantities (numbers with associated units).
>>> 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>
Core units classes and functions
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. |
A collection of different unit formats.
get_format([format]) | Get a formatter by name. |
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. |
This package defines the SI units. They are also available in the astropy.units namespace.
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 |
This package defines the CGS units. They are also available in the top-level astropy.units namespace.
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 |
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.
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 |
This package defines colloquially used Imperial units. They are also available in the astropy.units namespace.
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 |
A set of standard astronomical equivalencies.
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. |