Installation

pip install pyqn

PyQn needs Python 3.10 or later.

Quick start

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

Unit syntax

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 k M G T P E Z Y. Deca and hecto (da, h) and the prefixes added in 2022 (ronna, quetta, ronto and quecto) are not supported.

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

Every combination of prefix and unit symbol reads in only one way. To make that possible, a few units have unusual symbols:

• inch, not in, because min would be both minutes and milli-inches;

• yard, not yd (the yoctoday);

• dy for the day, because d is the prefix deci;

• asec for the arcsecond, because as is the attosecond.

Note also that b is the barn, so mb is the millibarn: the millibar is mbar.

Conventions

Units.conversion(other, force=...) can convert between units of different dimensions using one of three conventions:

force="spec"

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

force="mol"

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

force="kBT"

Energy and temperature are interconverted with 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

Only one convention can be used in each conversion.

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

Quantities

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.

Limitations

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

Units

These are the units that PyQn recognises; each can take any SI prefix.

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

Silly units

Miscellaneous units

Development

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.

Licence

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