ucon.formulas

Named relationships between input kinds and an output kind. A FormulaRegistry indexes KindFormula instances by name and by input-kind tuple, with commutative two-input formulas mirrored automatically.

See API › Formulas for usage and the Kind-of-Quantity Problem for the conceptual framing.

Kind formulas: declared relationships between :class:~ucon.kinds.types.Kind nodes.

A formula is the edge of the kind graph: it documents the relationship between operand kinds and a result kind, and (in later versions) drives kind assignment for multiplication and named computation. Addition dispatch is governed by the kind lattice, not by formulas.

Formulas do kind work only: aspect propagation is the aspect stratum's carry rule (ucon.aspects), not a formula concern — formulas do not produce aspects. generalizes and commutative gained semantics in v1.9.2.

AmbiguousFormula

Bases: FormulaError

Two or more formulas match at the same specificity level.

Raised during ancestor-walk when multiple formulas match at the same L1 distance. Callers must disambiguate by using more specific kinds or by naming the formula explicitly.

DuplicateFormula

Bases: FormulaError

A formula with the given name is already registered.

The registry's primary key is the formula name. Re-registering a formula with the same name is refused.

FormulaError

Bases: Exception

Base class for formula registry errors.

FormulaNotFound

Bases: FormulaError

No formula matches the supplied lookup key.

name_or_kinds carries the lookup argument for the diagnostic.

FormulaRegistry

Indexes formulas by name and by input-kind tuple.

Parameters

formulas Initial formulas to register.

Notes

Equality semantics on :class:~ucon.formulas.types.KindFormula key off name. Registering two formulas with the same name raises :class:~ucon.formulas.exceptions.DuplicateFormula.

Input-kind indexing keys by ordered tuple of input kinds. When a formula declares commutative=True, the registry indexes both the original ordering and a canonical sorted key — so voltage × current and current × voltage both resolve to the same formula at any arity via :meth:resolve.

register(formula)

Add a formula to the registry. Refuses duplicate names.

names()

All registered formula names.

get(name)

Resolve a formula by name.

Raises

FormulaNotFound If no formula matches.

lookup(*input_kinds)

Resolve a formula by exact input-kind tuple.

Performs EXACT tier lookup only (including the arity-2 commutative mirror in _by_inputs). Callers wanting the richer tiered resolution should use :meth:resolve.

Raises

FormulaNotFound If no formula matches the supplied input kinds.

resolve(*input_kinds, lattice=None, dimension_fallback=False)

Resolve a formula through successive match tiers.

Tiers are checked in strict priority order; the first to produce a match wins:

1. EXACT — exact input-kind tuple match.
2. COMMUTATIVE — canonical sorted-key match (any arity).
3. GENERALIZED — ancestor-walk via lattice at increasing L1 distance (requires lattice; only formulas with generalizes=True).
4. DIMENSIONAL — dimension-tuple match ignoring kind identity (requires dimension_fallback=True).

Parameters

*input_kinds Kinds to match, in caller-supplied order. lattice When provided, enables GENERALIZED matching via ancestor walk. dimension_fallback When True, enables DIMENSIONAL matching as a last resort.

Returns

LookupResult The matched formula and the tier that resolved it.

Raises

FormulaNotFound No formula matched at any enabled tier. AmbiguousFormula Multiple formulas matched at the same GENERALIZED distance.

apply(inputs, *, lattice=None, dimension_fallback=False)

Resolve a formula for the supplied input kinds.

The caller supplies one kind per binding; resolution consults the declared input kinds (in the order of inputs) and returns the formula, its output kind, and the match tier.

Parameters

inputs Mapping from binding name to the operand's kind. lattice Passed through to :meth:resolve for generalized matching. dimension_fallback Passed through to :meth:resolve.

Returns

tuple (formula, output_kind, match_kind).

Raises

FormulaNotFound Propagated from :meth:resolve when no formula matches the supplied input kinds at any enabled tier. AmbiguousFormula Propagated from :meth:resolve.

KindFormula dataclass

A declared relationship between kinds.

Parameters

name Unique formula identifier. Used as the lookup key for named computation. expression Free-text expression for documentation and rendering, e.g. "D * w_R". ucon does not evaluate expressions. input_kinds Operands of the formula keyed by binding name. The binding names appear in expression. output_kind The kind of the result. generalizes Opt-in: when True, formula lookup may match this formula against subkinds of the declared inputs. Default False. Inert in v1.9.0; lookup semantics activate in v1.9.2. commutative Operand order policy under multiplication lookup. Default True (matching ×). Set to False for division and other order-sensitive formulas. Inert in v1.9.0. notes Free-text documentation. Useful for capturing context that the formula declaration alone does not convey (e.g., "w_R depends on radiation type per ICRP 103; caller selects appropriate value").

Notes

Equality and hashing key off name only, matching :class:Kind.

input_kind_tuple()

Input kinds in the binding order declared on the formula.

The order is the iteration order of :attr:input_kinds (insertion order, per dict semantics). Used by :class:~ucon.formulas.registry.FormulaRegistry to key positional lookups.

LookupResult dataclass

Result of :meth:~ucon.formulas.registry.FormulaRegistry.resolve.

Wraps the matched :class:KindFormula together with the :class:MatchKind tier that resolved the query and, for GENERALIZED matches, the L1 distance (number of parent-climbs).

Parameters

formula The matched formula. match_kind The tier that produced the match. distance L1 distance for GENERALIZED matches (sum of parent-climbs across all input positions). Zero for all other tiers.

MatchKind

Bases: Enum

Discriminator indicating which resolution tier matched a formula.

Used by :class:LookupResult to report how a formula was found. Tiers are checked in priority order: EXACT → COMMUTATIVE → GENERALIZED → DIMENSIONAL. The first tier to produce a match wins.