unitflow.expr

Symbolic expressions, equations, inequalities, and constraints.

Symbolic expression and constraint layer.

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

Bases: Expr

Parameters:
left: Expr
right: Expr
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

exception unitflow.expr.BooleanCoercionError[source]

Bases: ExprError

Raised when a constraint is coerced to boolean.

exception unitflow.expr.CompilationError[source]

Bases: ExprError

Raised when numeric compilation of an expression fails.

class unitflow.expr.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.expr.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.expr.ConversionExpr(expr: 'Expr', target_unit: 'Unit')[source]

Bases: Expr

Parameters:
expr: Expr
target_unit: Unit
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

exception unitflow.expr.DimensionMismatchExprError[source]

Bases: ExprError

Raised when expressions have mismatched dimensions in operations.

class unitflow.expr.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.expr.DivExpr(left: 'Expr', right: 'Expr')[source]

Bases: Expr

Parameters:
left: Expr
right: Expr
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

class unitflow.expr.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

exception unitflow.expr.EvaluationError[source]

Bases: ExprError

Raised when expression evaluation fails (e.g. unbound symbol).

class unitflow.expr.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.expr.ExprError[source]

Bases: UnitflowError

Raised for general expression and symbolic errors.

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

Bases: Expr

Parameters:
left: Expr
right: Expr
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

class unitflow.expr.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.expr.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.expr.PowExpr(base: 'Expr', power: 'int')[source]

Bases: Expr

Parameters:

  • base (Expr)

  • power (int)

base: Expr
power: int
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

class unitflow.expr.QuantityExpr(value: 'Quantity')[source]

Bases: Expr

Parameters:

value (Quantity)

value: Quantity
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

class unitflow.expr.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.expr.SubExpr(left: 'Expr', right: 'Expr')[source]

Bases: Expr

Parameters:
left: Expr
right: Expr
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

class unitflow.expr.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

unitflow.expr.compile_numeric(expr, symbols, reference_units)[source]

Compile an expression into a fast float function.

The returned callable takes one positional float argument per symbol (in the order given by symbols) and returns a float.

All unit conversions and constant quantities are baked into the generated function at compile time so the inner loop is pure arithmetic.

Args:

expr: The expression to compile. symbols: Ordered list of symbols that become positional arguments. reference_units: The unit each symbol’s float value is expressed in.

Raises:
CompilationError: If a symbol in the expression is not in symbols,

or if dimensional validation fails.

Parameters:
Return type:

Callable[[…], float]

unitflow.expr.compile_residual(equation, symbols, reference_units)[source]

Compile an Equation into a residual function (lhs - rhs).

The returned callable takes one positional float argument per symbol and returns lhs - rhs as a float. This is the standard form for scipy.optimize.root and similar solvers.

Args:

equation: The equation to compile as a residual. symbols: Ordered list of symbols that become positional arguments. reference_units: The unit each symbol’s float value is expressed in.

Raises:
CompilationError: If a symbol in the equation is not in symbols,

or if dimensional validation fails.

Parameters:
Return type:

Callable[[…], float]

unitflow.expr.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