Units API¶

Reference for bilt.units, bilt.units.dimensions and unit-related exceptions in bilt.errors. For model declarations and a guided example, see Units in models.

Imports and declarations¶

from typing import Annotated

from bilt import Quantity, Tensor, tensor
from bilt.units import Metadata, Prefix, Unit, kilometer, meter
from bilt.units.dimensions import ABSOLUTE, LENGTH, TEMPERATURE

Length = Annotated[Quantity, LENGTH]
LengthSeries = Annotated[Tensor, LENGTH]
AbsoluteTemperature = Annotated[Quantity, TEMPERATURE, ABSOLUTE]

Declare dimensions, not units, on model ports. A bare Quantity is refused; a bare Tensor declares no physical dimension. A declared quantity port can accept a compatible unit-carrying tensor; a declared tensor port requires a tensor. Plain ports, such as float, stand outside the unit system.

Built-in units¶

All names below are exported from bilt.units. Names use the spelling shown (meter, liter, and siemen). Prefix variants are available only where listed; use Unit.new_named() to define others.

Compose other units with *, /, integer powers, and reciprocals: meter / second, kilogram / meter**3, meter**2, 1 / second.

Conventions:

• percent represents 0.01 * UNITLESS; radian is dimensionless and a degree is π/180 radians.
• year is 365.25 days. absolute_year exists as a unit, but model evaluation currently has no coherent absolute-second counterpart and rejects absolute time inputs.
• Use celsius for a temperature difference and absolute_celsius for a reading. Absolute and relative units cannot be interconverted.
• Currency conversions use fixed, bundled annual exchange and inflation data, relative to USD in 2025. They do not fetch live rates. Index a currency before using it as a unit; an unsupported year raises AttributeError.

from bilt.units import GBP, USD, UNITLESS, percent

assert (50.0 * percent).convert_to(UNITLESS).value == 0.5
cost_in_gbp = (100.0 * USD[2024]).convert_to(GBP[2024])

Quantities¶

Quantity is available from both bilt and bilt.units. Methods return a new quantity without changing the original.

distance = 5.0 * kilometer
assert distance.convert_to(meter).value == 5000.0

Outside models, convert operands to the same unit before addition, subtraction, ordering or equality checks. These operations do not automatically convert representations; distinct but equivalent unit objects may require cast_to() for addition. Equality compares the numerical values and unit equivalence.

Absolute + relative and absolute − relative produce absolute quantities; absolute − absolute produces a relative quantity. For direct Python arithmetic, align the absolute units and the relative step scales first. Absolute + absolute and relative − absolute are refused.

During model evaluation, Bilt converts inputs to coherent units and returns calculated outputs in coherent units. For ordinary physical dimensions these are SI units; currency uses USD2025 and metadata tags are retained.

Inside transforms, extract numbers with q.convert_to(unit).value and construct quantities with Quantity(value, unit) or a float multiplied by a unit. Bare quantity .value, representation-dependent .unit access, and cast_to() are refused. Transform checks do not prove dimensional correctness of arbitrary Python.

Defining and inspecting units¶

Define shared custom units in a project module and import them where needed:

from bilt.units import Unit, hour, meter

nautical_mile = Unit.new_named("nautical_mile", relation=1852.0 * meter)
knot = Unit.new_named("knot", relation=nautical_mile / hour)

assert (2.0 * nautical_mile).convert_to(meter).value == 3704.0

Names are cached process-wide. Repeating the same definition returns the cached unit; a different relation under an existing name raises BiltUnitError. Only one absolute counterpart may be registered for a given relative scale. Use dimensions, such as LENGTH / TIME, in port declarations for these units too.

Prefixes¶

Prefix is an integer enum whose values are powers of ten:

from bilt.units import Prefix, Unit, second

microsecond = Unit.new_named("microsecond", relation=second, prefix=Prefix.MICRO)

The name must start with the prefix's lowercase name. Use an unprefixed reference unit as above; do not also multiply the relation by the prefix factor.

Dimensions and metadata¶

Import dimension constants and ABSOLUTE from bilt.units.dimensions.

from bilt.units import Metadata, kilogram
from bilt.units.dimensions import MASS

fuel = Metadata("fuel")
FuelMass = Annotated[Quantity, MASS * fuel]
fuel_mass = 2.0 * kilogram * fuel
assert fuel_mass.strip_metadata().unit == kilogram

Tags are part of dimensional compatibility: tagged and untagged masses cannot be converted directly. Use strip_metadata() deliberately, or cast_to() when the units are equivalent after removing tags. Put tags into the dimension in annotations; Annotated[Quantity, MASS, fuel] is refused. Equations express tag changes through tagged unit factors; transforms support strip_metadata() and multiplication by a tag.

Unit-carrying tensors¶

Import tensor and Tensor from bilt.

Unit multiplication labels values; convert_to() rescales them. Concrete tensor arithmetic is otherwise dispatched through Bilt models. Tensors do not expose the quantity helpers cast_to() or strip_metadata().

Errors and messages¶

Import exceptions from bilt.errors. Catch classes rather than matching full message strings; messages include the offending ports, quantities and units.

Common message excerpts (… stands for context-dependent details):

BiltPortDeclarationError, BiltDefinitionError and BiltUnresolvedAnnotationError are definition failures; catching BiltUnitsError alone does not catch them. See the units guide for model examples.