ucon Pronounced: yoo · cahn

A lightweight, unit-aware computation library for Python — built on first-principles.

Overview

ucon helps Python understand the physical meaning of your numbers. It combines units, scales, and dimensions into a composable algebra that supports:

• Dimensional analysis through Number and Ratio
• Scale-aware arithmetic via UnitFactor and UnitProduct
• Metric and binary prefixes (kilo, kibi, micro, mebi, etc.)
• Pseudo-dimensions for angles, solid angles, and ratios with semantic isolation
• Uncertainty propagation through arithmetic and conversions
• A clean foundation for physics, chemistry, data modeling, and beyond

Think of it as decimal.Decimal for the physical world — precise, predictable, and type-safe.

Introduction

The crux of this tiny library is to provide abstractions that simplify the answering of questions like:

"If given two milliliters of bromine (liquid Br₂), how many grams of bromine does one have?"

To best answer this question, we turn to an age-old technique (dimensional analysis) which essentially allows for the solution to be written as a product of ratios. ucon comes equipped with some useful primitives:

Under the Hood

ucon models unit math through a hierarchy where each layer builds on the last:

Why ucon?

Python already has mature libraries for handling units and physical quantities — Pint, SymPy, and Unum — each solving part of the same problem from different angles:

Together, these tools can use units, but none can explicitly represent and verify the relationships between units and dimensions.

That's the gap ucon fills.

It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them. This allows you to:

• Represent dimensional meaning explicitly (Dimension, Vector);
• Compose and compute with type-safe, introspectable quantities (Unit, Number);
• Extend the system with custom unit registries and conversion families.

Where Pint, Unum, and SymPy focus on how to compute with units, ucon focuses on why those computations make sense. Every operation checks the dimensional structure, not just the unit labels. This means ucon doesn't just track names: it enforces physics:

from ucon import Number, units

length = Number(quantity=5, unit=units.meter)
time = Number(quantity=2, unit=units.second)

speed = length / time     # ✅ valid: L / T = velocity
invalid = length + time   # ❌ raises: incompatible dimensions

Setup

Simple:

pip install ucon

Usage

This sort of dimensional analysis:

 2 mL bromine | 3.119 g bromine
--------------x-----------------  #=> 6.238 g bromine
      1       |  1 mL bromine

becomes straightforward when you define a measurement:

from ucon import Number, Scale, units
from ucon.quantity import Ratio

# Two milliliters of bromine
mL = Scale.milli * units.liter
two_mL_bromine = Number(quantity=2, unit=mL)

# Density of bromine: 3.119 g/mL
bromine_density = Ratio(
    numerator=Number(unit=units.gram, quantity=3.119),
    denominator=Number(unit=mL),
)

# Multiply to find mass
grams_bromine = bromine_density.evaluate() * two_mL_bromine
print(grams_bromine)  # <6.238 g>

Scale prefixes compose naturally:

km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram

print(km.shorthand)  # 'km'
print(mg.shorthand)  # 'mg'

# Scale arithmetic
print(km.fold_scale())  # 1000.0
print(mg.fold_scale())  # 0.001

Units are callable for ergonomic quantity construction:

from ucon import units, Scale

# Callable syntax: unit(quantity) → Number
height = units.meter(1.8)
speed = (units.mile / units.hour)(60)

# Convert between units
height_ft = height.to(units.foot)
print(height_ft)  # <5.905... ft>

# Scaled units work too
km = Scale.kilo * units.meter
distance = km(5)
distance_mi = distance.to(units.mile)
print(distance_mi)  # <3.107... mi>

Dimensionless units have semantic isolation — angles, solid angles, and ratios are distinct:

import math
from ucon import units

# Angle conversions
angle = units.radian(math.pi)
print(angle.to(units.degree))  # <180.0 deg>

# Ratio conversions
ratio = units.percent(50)
print(ratio.to(units.ppm))  # <500000.0 ppm>

# Cross-family conversions are prevented
units.radian(1).to(units.percent)  # raises ConversionNotFound

Uncertainty propagates through arithmetic and conversions:

from ucon import units

# Measurements with uncertainty
length = units.meter(1.234, uncertainty=0.005)
width = units.meter(0.567, uncertainty=0.003)

print(length)  # <1.234 ± 0.005 m>

# Uncertainty propagates through arithmetic (quadrature)
area = length * width
print(area)  # <0.699678 ± 0.00424... m²>

# Uncertainty propagates through conversion
length_ft = length.to(units.foot)
print(length_ft)  # <4.048... ± 0.0164... ft>

Unit systems and basis transforms enable conversions between incompatible dimensional structures. This goes beyond simple unit conversion (meter → foot) into structural transformation:

from fractions import Fraction
from ucon import BasisTransform, Dimension, Unit, UnitSystem, units
from ucon.graph import ConversionGraph
from ucon.maps import LinearMap

# The realm of Valdris has three fundamental dimensions:
#   - Aether (A): magical energy substrate
#   - Resonance (R): vibrational frequency of magic
#   - Substance (S): physical matter
#
# These combine into SI dimensions via a transformation matrix:
#
#   | L |   | 2  0  0 |   | A |
#   | M | = | 1  0  1 | × | R |
#   | T |   |-2 -1  0 |   | S |
#
# Reading the columns:
#   - 1 aether contributes: L², M, T⁻²  (energy-like)
#   - 1 resonance contributes: T⁻¹      (frequency-like)
#   - 1 substance contributes: M         (mass-like)

# Fantasy base units
mote = Unit(name='mote', dimension=Dimension.energy, aliases=('mt',))
chime = Unit(name='chime', dimension=Dimension.frequency, aliases=('ch',))
ite = Unit(name='ite', dimension=Dimension.mass, aliases=('it',))

valdris = UnitSystem(
    name="Valdris",
    bases={
        Dimension.energy: mote,
        Dimension.frequency: chime,
        Dimension.mass: ite,
    }
)

# The basis transform encodes how Valdris dimensions compose into SI
valdris_to_si = BasisTransform(
    src=valdris,
    dst=units.si,
    src_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
    dst_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
    matrix=(
        (2, 0, 0),    # energy: 2 × aether
        (1, 0, 1),    # frequency: aether + substance
        (-2, -1, 0),  # mass: -2×aether - resonance
    ),
)

# Physical calibration: how many SI units per fantasy unit
graph = ConversionGraph()
graph.connect_systems(
    basis_transform=valdris_to_si,
    edges={
        (mote, units.joule): LinearMap(42),           # 1 mote = 42 J
        (chime, units.hertz): LinearMap(7),           # 1 chime = 7 Hz
        (ite, units.kilogram): LinearMap(Fraction(1, 2)),  # 1 ite = 0.5 kg
    }
)

# Game engine converts between physics systems
energy_map = graph.convert(src=mote, dst=units.joule)
energy_map(10)  # 420 joules from 10 motes

# Inverse: display real-world values in game units
joule_to_mote = graph.convert(src=units.joule, dst=mote)
joule_to_mote(420)  # 10 motes

# The transform is invertible with exact Fraction arithmetic
valdris_to_si.is_invertible  # True

This enables fantasy game physics, or any field where the dimensional structure differs from SI.

Roadmap Highlights

See full roadmap: ROADMAP.md

Contributing

Contributions, issues, and pull requests are welcome! Ensure nox is installed.

pip install -r requirements.txt

Then run the full test suite (against all supported python versions) before committing:

nox -s test

"If it can be measured, it can be represented. If it can be represented, it can be validated. If it can be validated, it can be trusted."