ucon.basis.graph

BasisGraph registry and ContextVar-based scoping for basis selection.

BasisGraph registry and context scoping for basis transforms.

Provides path-finding and transitive composition of basis transforms, plus ContextVar-based scoping for default basis and basis graph overrides.

BasisGraph

Graph of basis transforms with path-finding and composition.

Nodes are Basis objects (dimensional coordinate systems). Edges are BasisTransform objects. Path-finding composes transforms transitively.

Examples:

>>> graph = BasisGraph()
>>> graph.add_transform(SI_TO_CGS)
>>> graph.add_transform(CGS_TO_CGS_ESU)
>>> # Transitive composition: SI -> CGS -> CGS-ESU
>>> transform = graph.get_transform(SI, CGS_ESU)

add_transform(transform)

Register a transform. Does NOT auto-register inverse.

Parameters:

Name	Type	Description	Default
transform	_Transform	The transform to register.	required

add_transform_pair(forward, reverse)

Register bidirectional transforms (e.g., projection + embedding).

Parameters:

Name	Type	Description	Default
forward	BasisTransform	Transform A -> B.	required
reverse	BasisTransform	Transform B -> A.	required

get_transform(source, target)

Find or compose a transform between bases.

Parameters:

Name	Type	Description	Default
source	Basis	The source basis.	required
target	Basis	The target basis.	required

Returns:

Type	Description
BasisTransform	A BasisTransform from source to target.

Raises:

Type	Description
NoTransformPath	If no path exists between the bases.

are_connected(a, b)

Check if two bases can interoperate.

Parameters:

Name	Type	Description	Default
a	Basis	First basis.	required
b	Basis	Second basis.	required

Returns:

Type	Description
bool	True if a path exists between the bases.

reachable_from(basis)

Return all bases reachable from the given basis.

Parameters:

Name	Type	Description	Default
basis	Basis	The starting basis.	required

Returns:

Type	Description
set[Basis]	Set of all bases reachable via transforms.

with_transform(transform)

Return a new graph with an additional transform (copy-on-extend).

Parameters:

Name	Type	Description	Default
transform	BasisTransform	The transform to add.	required

Returns:

Type	Description
'BasisGraph'	A new BasisGraph with the additional transform.

get_default_basis()

Get the current default basis.

Returns the context-local basis if one has been set via :func:using_basis, otherwise returns SI.

Returns

Basis The active basis for the current context.

get_basis_graph()

Get the current basis graph.

Priority:

1. Context-local graph (from :func:using_basis_graph)
2. Module-level default graph (lazily built with standard transforms)

Returns

BasisGraph The active basis graph for the current context.

set_default_basis_graph(graph)

Replace the module-level default basis graph.

Parameters

graph : BasisGraph The new default basis graph.

reset_default_basis_graph()

Reset to the standard basis graph on next access.

The standard graph (with SI, CGS, CGS-ESU, and NATURAL transforms) is lazily rebuilt when :func:get_basis_graph is next called.

using_basis(basis)

Context manager for scoped basis override.

Within the with block, :func:get_default_basis returns the provided basis instead of SI. Thread-safe via ContextVar.

Parameters

basis : Basis The basis to use within this context.

Yields

Basis The provided basis.

using_basis_graph(graph)

Context manager for scoped basis graph override.

Within the with block, :func:get_basis_graph returns the provided graph. Thread-safe via ContextVar.

Parameters

graph : BasisGraph or None The basis graph to use, or None to fall back to the module default.

Yields

BasisGraph or None The provided graph.