unitx

Write physical formulas with units and constants in Python. unitx provides unit conversion, dimensional checks, exact unit algebra, and type hints for scalar calculations, with optional NumPy integration.

Install

Python 3.12 or later, with no mandatory runtime dependencies:

pip install unitx

If NumPy 2.1 or later is already installed, the same package works with arrays. To install NumPy alongside unitx, use:

pip install 'unitx[numpy]'

Calculate with units

Import ready-to-use units from si and physical constants from SI:

>>> from unitx.si import SI, si
>>> distance = 3 * si.m
>>> duration = 2 * si.s
>>> speed = distance / duration
>>> print(speed)
1.5 m/s
>>> print(speed.to(si.cm / si.s))
150.0 cm/s
>>> print(SI.c)
299792458 m/s
>>> rest_energy = (SI.me * SI.c**2).to(si.MeV)
>>> round(float(rest_energy.value), 6)
0.510999

Addition aligns compatible units; multiplication, division and powers combine them. Incompatible conversions and arithmetic raise DimensionError. Use strings when units come from data or configuration:

>>> from unitx import Quantity, Unit
>>> length = Quantity(1, 'm') + Quantity(50, 'cm')
>>> print(length)
3/2 m
>>> length.value_in('cm')
Fraction(150, 1)
>>> Quantity(1, 'm') == Quantity(100, 'cm')
True
>>> Unit('m') == Unit('cm')
False

.value is the stored magnitude in .unit; .to(unit) returns a new quantity, and .value_in(unit) returns only the converted magnitude. Unit scales and rational exponents retain exact structure. Numerical results follow the magnitude's domain: Fraction supports rational arithmetic, Decimal follows its context, and float calculations can round. Use .isclose() for approximate comparisons.

Temperatures and logarithmic readings

Use @ for an absolute coordinate reading and * for a linear difference:

>>> room = 20 @ si.degC
>>> print(room.to(si.degF))
68 °F
>>> print(room + 5 * si.K)
25 °C
>>> (30 @ si.degC) - room == 10 * si.K
True
>>> (30 @ si.dBm).to_quantity(si.W) == 1 * si.W
True

Points are AffineQuantity objects; differences are Quantity objects. Use .to_quantity() to turn a point into an ordinary physical quantity for further arithmetic. Read the point and difference guide for temperature, dBm/dBW/dBV, and logarithmic ratio rules.

Mathematical functions and time

>>> from unitx import math, pi, time
>>> math.sqrt(9 * si.m**2)
Quantity(3.0, Unit('m'))
>>> math.sin(90 * si.deg).value
1.0
>>> math.sin(pi / 2).value
1.0
>>> start = time.perf_counter()
>>> elapsed = time.perf_counter() - start
>>> isinstance(elapsed.value, int) and elapsed.unit == si.ns
True

unitx.math checks units for roots, trigonometry, exponentials, logarithms, hypot, and atan2. unitx.time returns integer nanosecond clock readings and adapts durations to sleep and datetime.timedelta. See standard-library enhancements for the supported functions, numerical backends, and clock semantics.

Work with NumPy

One Quantity wraps a whole array with one unit:

import numpy as np

from unitx import Quantity
from unitx.si import si

positions = Quantity(np.array([1.0, 2.0, 3.0]), si.m)
velocity = positions / (2 * si.s)
mean_velocity = np.mean(velocity)
assert mean_velocity == 1 * si.m / si.s
np.testing.assert_allclose(velocity.value_in(si.cm / si.s), [50, 100, 150])

NumPy handles broadcasting and numerical kernels; unitx checks and combines units. Comparisons return boolean masks. Supported reductions, integration, gradients, and output buffers follow the NumPy support matrix. Array assignment and augmented arithmetic preserve the destination unit and dtype.

Use .value or .value_in(unit) at plotting and external-library boundaries. np.asarray(quantity) and np.array(quantity) raise TypeError to prevent implicit unit removal. NumPy's type stubs do not describe every wrapped operation; see the typing guide.

The physics notebooks cover blackbody radiation, damped motion, wave-packet spreading, attenuation, and measurement uncertainty. For example, Planck spectra combine physical constants, broadcasting, and spectral-density conversion:

Read more

Start at the documentation index, or go directly to a topic:

This README describes the current source tree. Public APIs may change during the 0.x series; consult a release's matching tag for its documentation. Development and release checks are described in the contributing guide.

Licensed under the MIT License.