prophys.units

Physical units and dimensional checking.

Frame and UncertainAttribute have always carried a units string, but nothing read it: a metre frame combined with a kilometre field produced a silently wrong answer, and an attribute declared in “kW” could be calibrated against observations in “MW” without complaint. This module turns those labels into checkable quantities.

A Unit is a symbol, a Dimension (the seven SI base exponents), and a scale factor to the SI base — so km is (length=1, scale=1000), kW is (mass=1, length=2, time=-3, scale=1000), and m/s is a compound of the two. parse() builds one from a string, accepting SI prefixes and the usual *, / and ^ composition.

Two rules follow:

  • Compatible units share a dimension and can be converted between (convert()).

  • Incompatible units cannot be combined at all, and the attempt raises UnitError at model-build time rather than producing a number.

Checking is at Python model-build time, never inside the JAX trace, so it costs nothing at run time — the same discipline Frame compatibility already follows.

Units the SI does not define — currency, counts, arbitrary index scales — are supported as dimensionless tagged units: two different tags never convert into each other, so EUR and USD stay distinct while both remain dimensionless.

Module Attributes

BASE_DIMENSIONS

Order of the SI base dimensions in a Dimension exponent tuple.

DIMENSIONLESS

The dimension of a pure number.

Functions

check_compatible(a, b[, context])

Raise UnitError unless a and b are compatible.

compatible(a, b)

Whether two units share a dimension and a tag, and so convert into each other.

conversion_factor(from_, to)

Multiplier taking a value from from_ into to.

convert(value, from_, to)

Convert value from one unit to another.

describe(text)

A one-line description of a unit: its symbol, dimension and SI scale.

parse(text)

Parse a unit expression such as "m", "km/h", "kg*m/s^2".

register_unit(unit, *[, aliases])

Add a unit to the registry under its symbol and any aliases.

same_unit(units)

The single unit shared by a collection, or raise.

Classes

Dimension([length, mass, time, current, ...])

Exponents of the seven SI base dimensions.

Unit(symbol[, dimension, scale, offset, tag])

A unit of measurement: a symbol, a dimension, and a scale to SI.

Exceptions

UnitError

Raised when two quantities' units are incompatible, or a unit string cannot be parsed.