ucon.basis.graph

BasisGraph registry and ContextVar-based scoping for basis selection.

BasisGraph registry and standard-graph factory.

This module owns two cohesive concerns:

1. :class:BasisGraph — the graph type and path-finding/composition logic.
2. :func:_build_standard_basis_graph — factory that constructs the default graph populated with the standard SI/CGS/CGS-ESU/CGS-EMU/natural/planck/atomic transforms.

The basis subpackage is a clean DAG (types ← vector ← transforms ← graph ← ops); transforms does not depend on graph, so all imports here sit at module top.

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.