tools-only Units and Quantities (astropy.units)
The astropy.units module handles defining, converting between, and performing arithmetic with physical quantities.
Creating Quantities
Multiply or divide numeric values by built-in units to create Quantity objects:
from astropy import units as u
import numpy as np
# Scalar quantities
distance = 42.0 * u.meter
velocity = 100 * u.km / u.s
# Array quantities
distances = np.array([1., 2., 3.]) * u.m
wavelengths = [500, 600, 700] * u.nm
Access components via .value and .unit attributes:
distance.value # 42.0
distance.unit # Unit("m")
Unit Conversions
Use .to() method for conversions:
distance = 1.0 * u.parsec
distance.to(u.km) # <Quantity 30856775814671.914 km>
wavelength = 500 * u.nm
wavelength.to(u.angstrom) # <Quantity 5000. Angstrom>
Arithmetic Operations
Quantities support standard arithmetic with automatic unit management:
# Basic operations
speed = 15.1 * u.meter / (32.0 * u.second) # <Quantity 0.471875 m / s>
area = (5 * u.m) * (3 * u.m) # <Quantity 15. m2>
# Units cancel when appropriate
ratio = (10 * u.m) / (5 * u.m) # <Quantity 2. (dimensionless)>
# Decompose complex units
time = (3.0 * u.kilometer / (130.51 * u.meter / u.second))
time.decompose() # <Quantity 22.986744310780782 s>
Unit Systems
Convert between major unit systems:
# SI to CGS
pressure = 1.0 * u.Pa
pressure.cgs # <Quantity 10. Ba>
# Find equivalent representations
(u.s ** -1).compose() # [Unit("Bq"), Unit("Hz"), ...]
Equivalencies
Domain-specific conversions require equivalencies:
# Spectral equivalency (wavelength ↔ frequency)
wavelength = 1000 * u.nm
wavelength.to(u.Hz, equivalencies=u.spectral())
# <Quantity 2.99792458e+14 Hz>
# Doppler equivalencies
velocity = 1000 * u.km / u.s
velocity.to(u.Hz, equivalencies=u.doppler_optical(500*u.nm))
# Other equivalencies
u.brightness_temperature(500*u.GHz)
u.doppler_radio(1.4*u.GHz)
u.mass_energy()
u.parallax()
Logarithmic Units
Special units for magnitudes, decibels, and dex:
# Magnitudes
flux = -2.5 * u.mag(u.ct / u.s)
# Decibels
power_ratio = 3 * u.dB(u.W)
# Dex (base-10 logarithm)
abundance = 8.5 * u.dex(u.cm**-3)
Common Units
Length
u.m, u.km, u.cm, u.mm, u.micron, u.angstrom, u.au, u.pc, u.kpc, u.Mpc, u.lyr
Time
u.s, u.min, u.hour, u.day, u.year, u.Myr, u.Gyr
Mass
u.kg, u.g, u.M_sun, u.M_earth, u.M_jup
Temperature
u.K, u.deg_C
Angle
u.deg, u.arcmin, u.arcsec, u.rad, u.hourangle, u.mas
Energy/Power
u.J, u.erg, u.eV, u.keV, u.MeV, u.GeV, u.W, u.L_sun
Frequency
u.Hz, u.kHz, u.MHz, u.GHz
Flux
u.Jy, u.mJy, u.erg / u.s / u.cm**2
Performance Optimization
Pre-compute composite units for array operations:
# Slow (creates intermediate quantities)
result = array * u.m / u.s / u.kg / u.sr
# Fast (pre-computed composite unit)
UNIT_COMPOSITE = u.m / u.s / u.kg / u.sr
result = array * UNIT_COMPOSITE
# Fastest (avoid copying with <<)
result = array << UNIT_COMPOSITE # 10000x faster
String Formatting
Format quantities with standard Python syntax:
velocity = 15.1 * u.meter / (32.0 * u.second)
f"{velocity:0.03f}" # '0.472 m / s'
f"{velocity:.2e}" # '4.72e-01 m / s'
f"{velocity.unit:FITS}" # 'm s-1'
Defining Custom Units
# Create new unit
bakers_fortnight = u.def_unit('bakers_fortnight', 13 * u.day)
# Enable in string parsing
u.add_enabled_units([bakers_fortnight])
Constants
Access physical constants with units:
from astropy.constants import c, G, M_sun, h, k_B
speed_of_light = c.to(u.km/u.s)
gravitational_constant = G.to(u.m**3 / u.kg / u.s**2)