ucon.basis

Core basis abstractions: Basis, BasisComponent, Vector, and related exceptions.

Basis abstraction for user-definable dimensional coordinate systems.

This package provides the foundation for representing dimensions in arbitrary bases (SI, CGS, CGS-ESU, natural units, custom domains) without hardcoding to a specific set of components.

Submodules

• builtin: Standard bases (SI, CGS, CGS-ESU, NATURAL)
• transforms: Transform types and standard transform instances
• graph: BasisGraph registry and context scoping

BasisComponent dataclass

An atomic generator of a dimensional basis.

A BasisComponent represents a single independent dimension in a basis, such as "length", "mass", or "time" in SI, or custom dimensions like "mana" or "gold" in a game domain.

Parameters:

Name	Type	Description	Default
name	str	The canonical name of the component (e.g., "length").	required
symbol	str | None	Optional short symbol (e.g., "L"). If None, name is used.	None

Examples:

>>> length = BasisComponent("length", "L")
>>> str(length)
'L'
>>> mass = BasisComponent("mass")
>>> str(mass)
'mass'

Basis

An ordered collection of basis components defining a coordinate system.

A Basis defines the dimensional coordinate system for a set of units. Components are indexed by both name and symbol for flexible lookup.

Parameters:

Name	Type	Description	Default
name	str	A descriptive name for the basis (e.g., "SI", "CGS", "Mechanics").	required
components	Sequence[str | BasisComponent]	Sequence of component names (str) or BasisComponent objects.	required

Raises:

Type	Description
ValueError	If component names or symbols collide.

Examples:

>>> mechanics = Basis("Mechanics", ["length", "mass", "time"])
>>> len(mechanics)
3
>>> "length" in mechanics
True
>>> mechanics.index("length")
0

>>> si = Basis("SI", [
...     BasisComponent("length", "L"),
...     BasisComponent("mass", "M"),
...     BasisComponent("time", "T"),
... ])
>>> "L" in si
True
>>> si.index("L")
0

name property

The descriptive name of this basis.

component_names property

Tuple of component names in order.

index(name)

Return the index of a component by name or symbol.

Parameters:

Name	Type	Description	Default
name	str	Component name or symbol to look up.	required

Returns:

Type	Description
int	The zero-based index of the component.

Raises:

Type	Description
KeyError	If name/symbol is not found in this basis.

zero_vector()

Create a zero vector in this basis.

Returns:

Type	Description
'Vector'	A Vector with all components set to Fraction(0).

Vector dataclass

A dimensional exponent vector tied to a specific basis.

Vector represents a point in dimensional space, where each component is the exponent of the corresponding basis component. For example, velocity (length/time) in SI would be Vector(SI, (1, 0, -1, 0, 0, 0, 0, 0)).

Parameters:

Name	Type	Description	Default
basis	Basis	The Basis this vector belongs to.	required
components	tuple[int | Fraction, ...]	Tuple of Fraction exponents, one per basis component.	required

Raises:

Type	Description
ValueError	If components length doesn't match basis length.

__getitem__(key)

Get a component by name, symbol, or index.

Parameters:

Name	Type	Description	Default
key	str | int	Component name, symbol, or integer index.	required

Returns:

Type	Description
Fraction	The Fraction exponent for that component.

is_dimensionless()

Return True if all exponents are zero.

__mul__(other)

Multiply dimensions (add exponents).

__truediv__(other)

Divide dimensions (subtract exponents).

__pow__(exponent)

Raise dimension to a power (multiply all exponents).

__neg__()

Negate all exponents (reciprocal dimension).

LossyProjection

Bases: Exception

Raised when a basis transform would discard dimensional information.

This occurs when a source component has a non-zero exponent but maps entirely to zeros in the target basis (e.g., SI current -> CGS).

NoTransformPath

Bases: Exception

Raised when no path exists between two bases in a BasisGraph.