unitflow

Top-level package: re-exports quantities, units, symbols, constraints, serialization helpers, and common catalog symbols.

Public package surface for the current semantic core.

exception unitflow.BooleanCoercionError[source]

Bases: ExprError

Raised when a constraint is coerced to boolean.

class unitflow.Conjunction(left: 'Constraint', right: 'Constraint')[source]

Bases: Constraint

Parameters:
left: Constraint
right: Constraint
property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

class unitflow.Constraint[source]

Bases: object

Base class for all symbolic constraints.

property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

is_same(other)[source]

Check if this constraint is structurally identical to another.

Parameters:

other (Any)

Return type:

bool

class unitflow.Dimension(exponents)[source]

Bases: object

Immutable exponent vector over the fixed base-dimension basis.

Parameters:

exponents (tuple[int, ...])

exponents: tuple[int, ...]
classmethod zero()[source]

Return the dimensionless exponent vector.

Return type:

Dimension

classmethod base(name)[source]

Return a single base dimension by its canonical name.

Parameters:

name (str)

Return type:

Dimension

classmethod from_mapping(exponents_by_name)[source]

Construct a dimension vector from a sparse base-dimension mapping.

Parameters:

exponents_by_name (dict[str, int])

Return type:

Dimension

property is_dimensionless: bool

Whether all exponents are zero.

to_mapping()[source]

Return a sparse mapping of non-zero exponents by base-dimension name.

Return type:

dict[str, int]

exception unitflow.DimensionError[source]

Bases: SemanticCoreError

Raised when dimension construction or algebra is invalid.

exception unitflow.DimensionMismatchError[source]

Bases: QuantityError

Raised when quantity arithmetic requires compatible dimensions and they do not match.

exception unitflow.DimensionMismatchExprError[source]

Bases: ExprError

Raised when expressions have mismatched dimensions in operations.

class unitflow.Disjunction(left: 'Constraint', right: 'Constraint')[source]

Bases: Constraint

Parameters:
left: Constraint
right: Constraint
property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

class unitflow.Equation(left: 'Expr', right: 'Expr')[source]

Bases: Constraint

Parameters:
left: Expr
right: Expr
property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

class unitflow.Expr[source]

Bases: object

Base class for all symbolic expressions.

property dimension: Dimension
property free_symbols: frozenset[Symbol]
evaluate(context)[source]

Evaluate this expression against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the expression. Array-backed quantities are not supported in v0.

Parameters:

context (dict[Symbol, Quantity])

Return type:

Quantity

to(target_unit)[source]
Parameters:

target_unit (Unit)

Return type:

Expr

is_same(other)[source]

Check if this expression is structurally identical to another.

Parameters:

other (Any)

Return type:

bool

exception unitflow.ExprError[source]

Bases: UnitflowError

Raised for general expression and symbolic errors.

exception unitflow.IncompatibleUnitError[source]

Bases: UnitError

Raised when unit compatibility is required but not satisfied.

class unitflow.Negation(constraint: 'Constraint')[source]

Bases: Constraint

Parameters:

constraint (Constraint)

constraint: Constraint
property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

class unitflow.NonStrictInequality(left: 'Expr', right: 'Expr', operator: 'str')[source]

Bases: Constraint

Parameters:

  • left (Expr)

  • right (Expr)

  • operator (str)

left: Expr
right: Expr
operator: str
property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

class unitflow.Quantity(magnitude, unit)[source]

Bases: object

Concrete magnitude plus semantic unit.

Parameters:

  • magnitude (Any)

  • unit (Unit)

magnitude: Any
unit: Unit
to(target_unit)[source]
Parameters:

target_unit (Unit)

Return type:

Quantity

is_close(other, *, rel_tol=1e-09, abs_tol=0.0)[source]
Parameters:

  • other (object)

  • rel_tol (float)

  • abs_tol (float)

Return type:

bool

exception unitflow.QuantityError[source]

Bases: SemanticCoreError

Raised when quantity construction or quantity arithmetic is invalid.

class unitflow.Scale(coefficient, pi_power=0)[source]

Bases: object

Exact scale represented as a rational coefficient times an integer power of pi.

Parameters:

  • coefficient (Fraction)

  • pi_power (int)

coefficient: Fraction
pi_power: int
classmethod one()[source]
Return type:

Scale

classmethod zero()[source]
Return type:

Scale

classmethod from_int(value)[source]
Parameters:

value (int)

Return type:

Scale

classmethod from_ratio(numerator, denominator=1, *, pi_power=0)[source]
Parameters:

  • numerator (int)

  • denominator (int)

  • pi_power (int)

Return type:

Scale

classmethod pi()[source]
Return type:

Scale

property is_zero: bool
as_float()[source]

Lossy float conversion for debugging and later backend integration.

Return type:

float

exception unitflow.ScaleError[source]

Bases: SemanticCoreError

Raised when exact scale construction or algebra is invalid.

exception unitflow.SemanticCoreError[source]

Bases: UnitflowError

Raised for invalid operations in the semantic core.

exception unitflow.SerializationError[source]

Bases: UnitflowError

Raised when serialization or deserialization fails.

class unitflow.StrictInequality(left: 'Expr', right: 'Expr', operator: 'str')[source]

Bases: Constraint

Parameters:

  • left (Expr)

  • right (Expr)

  • operator (str)

left: Expr
right: Expr
operator: str
property free_symbols: frozenset[Symbol]
evaluate(context, *, rel_tol=1e-09, abs_tol=0.0)[source]

Evaluate this constraint against a context of realized scalar values.

Context keys must be the same Symbol instances used to build the constraint. Array-backed quantities are not supported in v0. Tolerance parameters are explicit per call, never global state.

Parameters:
Return type:

bool

class unitflow.Symbol(name, _dimension, unit=None, quantity_kind=None)[source]

Bases: Expr

A symbolic variable with dimension and optional unit bindings.

Parameters:

  • name (str)

  • _dimension (Dimension)

  • unit (Unit | None)

  • quantity_kind (str | None)

name: str
unit: Unit | None
quantity_kind: str | None
property dimension: Dimension
property free_symbols: frozenset[Symbol]
evaluate(context)[source]

Look up this symbol’s value in the context.

Context keys must be the same Symbol instances used to build the expression (identity-based lookup). Constructing a new Symbol with the same name/unit and using it as a key will fail because Expr.__eq__ returns an Equation, not a bool.

Parameters:

context (dict[Symbol, Quantity])

Return type:

Quantity

is_same(other)[source]

Check if this expression is structurally identical to another.

Parameters:

other (object)

Return type:

bool

class unitflow.Unit(dimension, scale, name=None, symbol=None, aliases=(), family=None, quantity_kind=None)[source]

Bases: object

Immutable semantic unit definition.

Parameters:

  • dimension (Dimension)

  • scale (Scale)

  • name (str | None)

  • symbol (str | None)

  • aliases (tuple[str, ...])

  • family (UnitFamily | None)

  • quantity_kind (str | None)

dimension: Dimension
scale: Scale
name: str | None
symbol: str | None
aliases: tuple[str, ...]
family: UnitFamily | None
quantity_kind: str | None
classmethod dimensionless(*, name=None, symbol=None, aliases=(), family=None, quantity_kind=None)[source]
Parameters:

  • name (str | None)

  • symbol (str | None)

  • aliases (tuple[str, ...])

  • family (UnitFamily | None)

  • quantity_kind (str | None)

Return type:

Unit

is_compatible_with(other)[source]
Parameters:

other (Unit)

Return type:

bool

conversion_factor_to(other)[source]
Parameters:

other (Unit)

Return type:

Scale

with_metadata(*, name=<object object>, symbol=<object object>, aliases=<object object>, family=<object object>, quantity_kind=<object object>)[source]
Parameters:

  • name (str | None | object)

  • symbol (str | None | object)

  • aliases (tuple[str, ...] | None | object)

  • family (UnitFamily | None | object)

  • quantity_kind (str | None | object)

Return type:

Unit

exception unitflow.UnitError[source]

Bases: SemanticCoreError

Raised when unit construction or unit algebra is invalid.

class unitflow.UnitFamily(name, description)[source]

Bases: object

Semantic metadata for units that share a meaningful family.

Parameters:

  • name (str)

  • description (str)

name: str
description: str
exception unitflow.UnitFamilyError[source]

Bases: SemanticCoreError

Raised when unit-family metadata is invalid.

class unitflow.UnitNamespace(name)[source]

Bases: object

A simple named namespace for unit lookup by symbol, name, or alias.

Parameters:

name (str)

register(unit)[source]
Parameters:

unit (Unit)

Return type:

Unit

define_unit(*, name, symbol, expr, aliases=(), family=None, quantity_kind=None)[source]
Parameters:

  • name (str)

  • symbol (str)

  • expr (Unit | Quantity)

  • aliases (tuple[str, ...])

  • family (UnitFamily | None)

  • quantity_kind (str | None)

Return type:

Unit

resolve(identifier)[source]
Parameters:

identifier (str)

Return type:

Unit

identifiers()[source]
Return type:

tuple[str, …]

class unitflow.UnitRegistry(name='registry')[source]

Bases: object

A lightweight registry that resolves identifiers across namespaces.

Parameters:

name (str)

add_namespace(namespace)[source]
Parameters:

namespace (UnitNamespace)

Return type:

UnitNamespace

resolve(identifier)[source]
Parameters:

identifier (str)

Return type:

Unit

namespaces()[source]
Return type:

tuple[str, …]

exception unitflow.UnitflowError[source]

Bases: Exception

Base exception for all unitflow-specific errors.

unitflow.define_unit(*, name, symbol, expr, aliases=(), family=None, quantity_kind=None)[source]

Define a new semantic unit from an existing unit or exact quantity expression.

Parameters:

  • name (str)

  • symbol (str)

  • expr (Unit | Quantity)

  • aliases (tuple[str, ...])

  • family (UnitFamily | None)

  • quantity_kind (str | None)

Return type:

Unit

unitflow.deserialize_constraint(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Constraint

unitflow.deserialize_dimension(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Dimension

unitflow.deserialize_expr(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Expr

unitflow.deserialize_quantity(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Quantity

unitflow.deserialize_scale(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Scale

unitflow.deserialize_unit(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Unit

unitflow.deserialize_unit_family(data)[source]
Parameters:

data (dict[str, Any])

Return type:

UnitFamily

unitflow.generate_prefixes(namespace, base_unit, *, prefixes=None, include=None, exclude=None, resolver=None)[source]

Generate prefixed variants of a base unit and register them in a namespace.

Returns a dict mapping prefix names to the created units.

Parameters:

  • namespace (UnitNamespace)

  • base_unit (Unit)

  • prefixes (dict[str, tuple[str, Fraction]] | None)

  • include (set[str] | None)

  • exclude (set[str] | None)

  • resolver (DisplayResolver | None)

Return type:

dict[str, Unit]

unitflow.serialize_constraint(constraint)[source]
Parameters:

constraint (Constraint)

Return type:

dict[str, Any]

unitflow.serialize_dimension(dimension)[source]
Parameters:

dimension (Dimension)

Return type:

dict[str, Any]

unitflow.serialize_expr(expr)[source]
Parameters:

expr (Expr)

Return type:

dict[str, Any]

unitflow.serialize_quantity(quantity)[source]
Parameters:

quantity (Quantity)

Return type:

dict[str, Any]

unitflow.serialize_scale(scale)[source]
Parameters:

scale (Scale)

Return type:

dict[str, Any]

unitflow.serialize_unit(unit)[source]
Parameters:

unit (Unit)

Return type:

dict[str, Any]

unitflow.serialize_unit_family(family)[source]
Parameters:

family (UnitFamily)

Return type:

dict[str, Any]

unitflow.symbol(name, *, dimension=None, unit=None, quantity_kind=None)[source]

Create a new symbol with either a unit or dimension.

Parameters:

  • name (str)

  • dimension (Dimension | None)

  • unit (Unit | None)

  • quantity_kind (str | None)

Return type:

Symbol