ucon.basis.ops¶
Explicit cross-basis arithmetic for Vector. Pure-function helpers (unify, multiply_via, divide_via) that resolve a common basis through a BasisGraph before composing two vectors. Replaces the implicit cross-basis fallback that lived inside Vector.__mul__ / __truediv__ in v1.7.
Explicit cross-basis arithmetic for :class:ucon.basis.vector.Vector.
Vector arithmetic is strict same-basis (raises
:class:ucon.basis.types.BasisMismatch). When two vectors live in
different bases, the active :class:ucon.basis.graph.BasisGraph is consulted
for a clean (non-lossy) projection between them. Both directions are tried;
the first clean projection wins. A "clean" projection is one that does not
raise :class:ucon.basis.types.LossyProjection — i.e., no non-zero
component of the source vector would be discarded.
Public surface¶
- :func:
unify— re-express two vectors in a common basis. - :func:
multiply_via— multiply two vectors, unifying bases as needed. - :func:
divide_via— divide two vectors, unifying bases as needed.
All three accept an optional graph= kwarg or an optional system=
kwarg (which contributes its basis_graph). When neither is given, the
active :class:UnitSystem's basis_graph is used.
This module sits at the top of the basis subpackage's import DAG: it
imports types, vector, and graph, but nothing imports it from
within ucon.basis.
unify(a, b, *, system=None, graph=None)
¶
Bring two vectors into a common basis.
If a and b already share a basis, they are returned unchanged.
Otherwise a clean (non-lossy) projection is sought in both directions
via the resolved :class:BasisGraph.
Parameters¶
a, b : Vector
Vectors to unify.
system : UnitSystem, optional
If provided (and graph is not), the system's basis_graph is
consulted.
graph : BasisGraph, optional
Explicit graph override. Wins over system.
Returns¶
tuple[Vector, Vector]
(a', b') re-expressed in a single common basis.
Raises¶
BasisMismatch If no clean projection connects the two bases in either direction.
multiply_via(a, b, *, system=None, graph=None)
¶
Multiply two vectors, unifying bases via a :class:BasisGraph.
Same-basis multiplication is identical to a * b. Cross-basis
multiplication consults the resolved graph for a clean projection.
Parameters¶
a, b : Vector
Vectors to multiply.
system : UnitSystem, optional
If provided (and graph is not), the system's basis_graph is
consulted for cross-basis projection.
graph : BasisGraph, optional
Explicit graph override. Wins over system.
Returns¶
Vector The component-wise sum of the two vectors after unification, in the common basis.
Raises¶
BasisMismatch If no clean projection connects the two bases.
divide_via(a, b, *, system=None, graph=None)
¶
Divide two vectors, unifying bases via a :class:BasisGraph.
Same-basis division is identical to a / b. Cross-basis division
consults the resolved graph for a clean projection.
Parameters¶
a, b : Vector
Vectors to divide.
system : UnitSystem, optional
If provided (and graph is not), the system's basis_graph is
consulted for cross-basis projection.
graph : BasisGraph, optional
Explicit graph override. Wins over system.
Returns¶
Vector The component-wise difference of the two vectors after unification.
Raises¶
BasisMismatch If no clean projection connects the two bases.