ucon.dimension¶
Dimension algebra and enumeration. All physical dimensions are represented as exponent vectors over the SI basis.
ucon.dimension¶
Defines physical dimensions using basis-aware exponent vectors.
The Dimension class represents physical dimensions as immutable dataclasses backed by Vector exponents. This replaces the previous Enum-based approach with a more flexible system that supports:
- Algebraic operations (multiplication, division, exponentiation)
- Named dimensions via attribute access (Dimension.length, Dimension.mass)
- Module constants (LENGTH, MASS, etc.) for static imports
- Derived dimensions created dynamically from algebraic expressions
- Pseudo-dimensions (ANGLE, RATIO, COUNT) that are semantically isolated
- Basis-aware transformations for cross-system dimensional analysis
Example¶
from ucon import Dimension Dimension.length / Dimension.time == Dimension.velocity True Dimension.length ** 2 Dimension(area)
Module constants also available:¶
from ucon.dimension import LENGTH, TIME LENGTH / TIME Dimension(velocity)
Dimension
dataclass
¶
A physical dimension represented by an exponent vector over a basis.
Parameters¶
vector : Vector The dimensional exponent vector. name : str | None Optional human-readable name (e.g., "length", "velocity"). symbol : str | None Optional short symbol (e.g., "L", "T"). tag : str | None Tag for pseudo-dimensions. Pseudo-dimensions share the zero vector but are semantically isolated (e.g., "angle", "ratio", "count").
Examples¶
from ucon.dimension import LENGTH, TIME velocity = LENGTH / TIME velocity == VELOCITY True
basis
property
¶
The basis this dimension is expressed in.
value
property
¶
Backward compatibility: the dimensional vector.
This is equivalent to .vector but matches the old Enum API.
is_pseudo
property
¶
True if this is a pseudo-dimension (tagged, dimensionless vector).
is_dimensionless
property
¶
True if the underlying vector is dimensionless.
from_components(basis=None, *, name=None, symbol=None, **components)
classmethod
¶
Create a dimension from named component exponents.
Parameters¶
basis : Basis The basis to use. Defaults to SI. name : str | None Optional name for the dimension. symbol : str | None Optional symbol for the dimension. **components Named exponents (e.g., L=1, T=-1 for velocity).
Returns¶
Dimension A new dimension with the specified components.
Examples¶
velocity = Dimension.from_components(L=1, T=-1, name="velocity") velocity == LENGTH / TIME True
pseudo(tag, *, name=None, symbol=None, basis=None)
classmethod
¶
Create a pseudo-dimension with a semantic tag.
Pseudo-dimensions share the zero vector (dimensionless) but are semantically isolated from each other and from NONE.
Parameters¶
tag : str Semantic tag for isolation (e.g., "angle", "ratio", "count"). name : str | None Optional name. Defaults to tag. symbol : str | None Optional symbol. basis : Basis The basis to use. Defaults to SI.
Returns¶
Dimension A pseudo-dimension with the specified tag.
Examples¶
ANGLE = Dimension.pseudo("angle", name="angle") ANGLE.is_pseudo True ANGLE == NONE False
in_basis(transform)
¶
is_base()
¶
True if this is a base dimension (single component with exponent 1).
base_expansion()
¶
__mul__(other)
¶
Multiply dimensions (add exponent vectors).
NONE acts as identity: NONE * X = X and X * NONE = X. Pseudo-dimensions behave like NONE in algebraic combinations: - MASS * COUNT = MASS (count adds zero to the vector) - ANGLE * LENGTH = LENGTH But pseudo-dimensions preserve themselves when alone: - ANGLE * NONE = ANGLE
__truediv__(other)
¶
Divide dimensions (subtract exponent vectors).
NONE acts as identity: X / NONE = X. Pseudo-dimensions behave like NONE in algebraic combinations: - MASS / COUNT = MASS (count subtracts zero from the vector) - LENGTH / ANGLE = LENGTH But self-division returns NONE: - ANGLE / ANGLE = NONE (not ANGLE, since exponent becomes 0)
__pow__(power)
¶
Raise dimension to a power (multiply exponent vector by scalar).
Pseudo-dimensions behave like dimensionless for exponentiation: - ANGLE ** 2 = ANGLE (angle^2 is still angle semantically) - COUNT ** -1 = COUNT (per-count is still count semantically)
__eq__(other)
¶
Compare dimensions for equality.
Pseudo-dimensions compare by tag, not just vector. Regular dimensions compare by vector.
__hash__()
¶
Hash based on vector and tag for pseudo-dimensions.
__bool__()
¶
False for NONE (dimensionless with no tag), True otherwise.
resolve(vector)
¶
Resolve a vector to a named dimension, or create a derived dimension.
Parameters¶
vector : Vector The dimensional exponent vector to resolve.
Returns¶
Dimension A registered dimension if one matches, otherwise a new derived dimension.
Examples¶
from ucon.dimension import SI, resolve from ucon.basis import Vector from fractions import Fraction v = Vector(SI, (Fraction(-1), Fraction(1), Fraction(0), Fraction(0), ... Fraction(0), Fraction(0), Fraction(0), Fraction(0))) resolve(v) Dimension(velocity)
basis()
¶
Return the 8 SI base dimensions in canonical order.
all_dimensions()
¶
Return all standard dimensions (base, derived, and pseudo).
This is useful for iteration when you need to list all known dimensions.