PyQn

PyQn is a lightweight Python package for parsing, validating, manipulating and converting physical units and quantities.

Units are written as plain strings in a compact syntax, such as kJ.mol-1, cm-1 or Pa-1/2. PyQn works out their dimensions, so conversions and arithmetic between them are checked. A few conventions allow conversions between units of different dimensions where that is usual practice, such as between wavenumbers and energies in spectroscopy.

PyQn is pure Python with no dependencies. It aims to be convenient within particular fields of science rather than to cover every unit in use.

The documentation, with worked examples for spectroscopy, atmospheric chemistry, physical chemistry and the validation of data, is at https://pyqn.readthedocs.io.

pip install pyqn

PyQn needs Python 3.10 or later.

>>> from pyqn import Units, Quantity
>>> Units("km.hr-1").conversion("m.s-1")
0.2777777777777778
>>> Units("J/mol.K")
J.mol-1.K-1
>>> str(Units("kJ.mol-1").dims)
'L2.M.T-2.Q-1'
>>> Units("J") == Units("kg.m2.s-2")
True
>>> Units("m.s-1") * Units("s")
m

Converting between units of different dimensions is an error, unless a convention is asked for (see Conventions):

>>> Units("J").conversion("K")
Traceback (most recent call last):
    ...
UnitsError: Failure in units conversion: units J (L2.M.T-2) and K (Theta) have different dimensions

A unit string is a sequence of atoms joined by . (multiply) or / (divide). Each atom is a unit symbol, perhaps with an SI prefix, followed by an optional exponent:

• The exponent follows the unit directly, as an integer or a ratio of integers: not m^2 or m**2.
• Each / divides by everything after it up to the next /: J/mol.K is J mol⁻¹ K⁻¹, and kg/m2/s is kg m⁻² s⁻¹.
• Spaces are not allowed: kg m-2 is an error, not kg m⁻².
• 1 is the unit of a dimensionless quantity, as in 1/s.
• The SI prefixes are y z a f p n μ m c d h k M G T P E Z Y, but each unit takes only some of them: see the Prefixes column in the table of Units. Hecto (h) goes only with Pa, L, l, m and g, as in hPa. Deca (da) and the prefixes added in 2022 (ronna, quetta, ronto and quecto) are not supported.
• pyqn 2.0 allowed every prefix but hecto on every unit. Prefixes that a unit no longer takes, as in kmin or μÅ, still work in pyqn 2.1 but give a DeprecationWarning; pyqn 3.0 will reject them.
• μ may be typed as the Greek letter mu or as the micro sign µ; the ohm and angstrom signs are likewise read as Ω and Å. A plain u is the atomic mass unit, not micro.
• Symbols are case-sensitive: K is the kelvin and k the kayser.
• undef stands for undefined units. Products, ratios and powers involving undef are undef too; undef units cannot be converted, and quantities with them cannot be added or subtracted.

Every string reads in only one way. Because each unit takes only some prefixes, the standard symbols in (inch), yd (yard) and d (day) are safe to use: min is still the minute and cd the candela. pyqn prints these units with the symbols it used before version 2.1, inch, yard and dy, which every version reads (see Domains). The arcsecond is asec, because as is the attosecond.

Note also that b is the barn, so mb is the millibarn: the millibar is mbar. And ppt is always parts per trillion, never parts per thousand.

A domain is a named set of units, used when parsing unit strings, so that strings that make no sense in a field are rejected. The default domain, domains.everything, has every unit.

>>> from pyqn import domains
>>> Units("km.h-1", domain=domains.si)
km.h-1
>>> Units("ft", domain=domains.si)
Traceback (most recent call last):
    ...
UnitsError: Unrecognised unit in the si domain: ft (the tonne, t, does not take the prefix f)

domains.si has the SI units and the non-SI units accepted for use with them: the minute, hour, day, astronomical unit, degree, arcminute, arcsecond, hectare, litre, tonne, dalton and electronvolt.

Each unit has a canonical symbol, which means the same in every domain and is what pyqn prints, so what pyqn prints can be read back in any domain that has the unit. A domain can also accept other spellings of a unit, and its format() writes units with them:

>>> u = Units("km.d-1", domain=domains.si)
>>> u
km.dy-1
>>> domains.si.format(u)
'km.d-1'

Once parsed, units are the same whatever domain they came from: arithmetic, comparisons and conversions work in the same way, and a string in them, as in u.conversion("m.s-1"), is read in the default domain. Quantity and Quantity.parse() also take a domain.

You can make domains of your own. When a domain is made, pyqn checks that every string it accepts reads in only one way:

>>> from pyqn import Domain
>>> lab = Domain("lab", units=[*domains.si.units, domains.everything.stems["Torr"]])
>>> Units("mTorr", domain=lab)
mTorr

pyqn has domains for several fields. Each has the units of si and those that the field uses with them, and some read a symbol in the field's own way. In geology, D is the darcy, so mD is the millidarcy, which pyqn prints with the darcy's canonical symbol; in radiation physics, rad is the unit of absorbed dose, and there is no radian.

>>> Units("mD", domain=domains.geology)
mdarcy
>>> domains.geology.format(Units("mD", domain=domains.geology))
'mD'
>>> Units("mD", domain=domains.spectroscopy)
mD

Gaussian (cgs) units belong to a system with three base dimensions, so pyqn defines them by the SI units they correspond to. They convert to those units, but the gauss and the oersted, for example, cannot be converted into each other, because the tesla and the ampere per metre have different dimensions:

>>> Units("G", domain=domains.gaussian_electromagnetism).conversion("T")
0.0001

Units.conversion(other, force=...) can convert between units of different dimensions using conventions, each of which treats some physical constants as 1:

force="spec"

Spectroscopy, with h and c: energy, wavenumber and frequency are interconverted with E = hν = hcν̃.

force="mol"

Molar quantities, with the Avogadro constant: the amount dimension is added or removed, as between kJ.mol-1 and J (per molecule).

force="kBT"

Energy and temperature, with the Boltzmann constant: E = k_BT.

>>> Units("J").conversion("cm-1", force="spec")
5.0341165675427096e+22
>>> Units("eV").conversion("kJ.mol-1", force="mol")
96.48533212331002
>>> Units("K").conversion("J", force="kBT")
1.380649e-23

Conventions can be combined:

>>> Units("kJ.mol-1").conversion("cm-1", force=("mol", "spec"))
83.59347229111778
>>> Units("K").conversion("cm-1", force=("kBT", "spec"))
0.6950348004861274

pyqn finds the powers of the constants by which the dimensions of the two units differ. The constants have independent dimensions, so there is at most one way to use them, and a conversion that needs any other change of dimensions is an error. The units can have any dimensions, so pressure broadening coefficients, for example, convert too:

>>> Units("cm-1.atm-1").conversion("MHz.Torr-1", force="spec")
39.44637605263158

Two consequences: because spec treats c as 1, it also converts lengths to light-travel times (cm to s); and mol only adds or removes the amount dimension entirely, so mol cannot be converted to mol2. Wavelengths are not covered, because a wavelength is inversely proportional to frequency rather than a multiple of it.

Conversion factors use the exact values of the SI defining constants and the CODATA 2022 values of the others (such as the electron mass and the hartree).

A molecule, molec, is a unit of amount: exactly 1/N_A mol. So HITRAN's line intensities, in cm^-1/(molecule cm^-2), convert to molar units directly, and to units per molecule with force="mol":

>>> s = Units("cm-1/molec.cm-2")
>>> s
cm.molec-1
>>> s.conversion("cm.mol-1")
6.02214076e+23
>>> s.conversion("cm", force="mol")
1.0

Mass, volume and amount fractions all have dimension 1 in the SI, but cannot be converted into each other without molar masses or densities. So the units for a particular kind of fraction have a pseudo-dimension, which cancels only against itself:

>>> Units("wt%").conversion("ppmw")
10000.0
>>> Units("ppmv").conversion("ppmw")
Traceback (most recent call last):
    ...
UnitsError: Failure in units conversion: units ppmv ([volume fraction]) and ppmw ([mass fraction]) have different dimensions

The plain ppm, ppb, ppt and % have dimension 1, and can stand for any kind of fraction. A convention named after a pseudo-dimension treats it as dimensionless:

>>> Units("ppmv").conversion("μmol/mol", force="volume fraction")
1.0

A Quantity has a value, units, and optionally a name and a standard uncertainty, sd. Arithmetic on quantities checks their units and propagates their uncertainties, assuming they are uncorrelated. An sd of 0 means the value is exact; an sd of None means its uncertainty is unknown, and so is the uncertainty of anything calculated from it.

>>> q = Quantity.parse("x = 1.5(2)e-3 m.s-1")
>>> q.value, q.sd
(0.0015, 0.0002)
>>> q.as_str()
'x = 0.00150(20) m.s-1'
>>> t = Quantity(name="t", value=10.0, units="s", sd=0.5)
>>> (q * t).as_str()
'0.0150(21) m'
>>> q.convert_units_to("km.hr-1").as_str()
'0.00540(72) km.hr-1'

Quantities can be added or subtracted only if their units are equal: J and kg.m2.s-2 can be added, but J and kJ cannot.

• Temperatures are absolute: there are no units with an offset, such as °C or °F.
• Angles are dimensionless, so, for example, Hz and rad.s-1 are the same units.
• There are no logarithmic units, such as the decibel.

These are the units in the default domain, with their canonical symbols and the SI prefixes that each takes ("all except h" is every SI prefix except hecto). The default domain also reads in, yd and d as the inch, yard and day.

Unity

SI unit stems

Derived SI units

Non-SI pressure units

cgs units

Angular units

Non-SI energy units

Non-SI mass units

Non-SI units of length, area and volume

Non-SI time units

Astronomical units

Imperial, customary and US units

Maritime units

Amounts, concentrations and fractions

Geological and petroleum units

Gaussian electromagnetic units

Radiation units

Silly units

Miscellaneous units

Install the package in editable mode with its development tools (this needs pip 25.1 or later):

python -m pip install -e . --group dev

Then run the tests, which include the examples in this README, and check the formatting and the code:

pytest
ruff format --check .
ruff check .

python -m pyqn.list_base_units rst prints the table of units above, and a test checks that the README has the current version.

The documentation, in docs/, includes this README as its user guide. To build it:

python -m pip install -e . --group docs
sphinx-build -W -b html docs docs/_build/html

PyQn is free software, released under the GNU General Public License, version 3 or later (see LICENSE).