ucon.basis.transforms¶
BasisTransform, ConstantBoundBasisTransform, ConstantBinding, and standard transform instances.
Basis transform types and standard transform instances.
Transform Types¶
- BasisTransform: Linear map between dimensional bases via matrix multiplication
- ConstantBinding: Binds a source dimension to a target expression via a physical constant
- ConstantBoundBasisTransform: Transform with constants that enable inversion of non-square matrices
Standard Transforms¶
- SI_TO_CGS: Projects SI to CGS (drops current, temperature, amount, luminosity, information)
- SI_TO_CGS_ESU: Maps SI to CGS-ESU (current becomes derived dimension)
- CGS_TO_SI: Embedding from CGS back to SI
- SI_TO_NATURAL: Maps SI to natural units via physical constants
- NATURAL_TO_SI: Inverse of SI_TO_NATURAL
SI_TO_CGS = BasisTransform(SI, CGS, ((Fraction(0), Fraction(0), Fraction(1)), (Fraction(1), Fraction(0), Fraction(0)), (Fraction(0), Fraction(1), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0))))
module-attribute
¶
Transform from SI to CGS.
Projects SI dimensions to CGS by preserving length, mass, and time, and dropping current, temperature, luminous_intensity, amount_of_substance, and information.
Warning: This is a lossy projection. Attempting to transform a vector with non-zero current (or other dropped components) will raise LossyProjection unless allow_projection=True.
SI_TO_CGS_ESU = BasisTransform(SI, CGS_ESU, ((Fraction(0), Fraction(0), Fraction(1), Fraction(0)), (Fraction(1), Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(1), Fraction(0), Fraction(0)), (Fraction(3, 2), Fraction(1, 2), Fraction(-2), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0), Fraction(0))))
module-attribute
¶
Transform from SI to CGS-ESU.
Maps SI dimensions to CGS-ESU. Current (I) becomes a derived dimension expressed as L^(3/2) M^(1/2) T^(-2), which is the dimensional formula for charge/time in the ESU system.
Temperature, luminous_intensity, amount_of_substance, and information are not representable in CGS-ESU and will raise LossyProjection if non-zero.
SI_TO_CGS_EMU = BasisTransform(SI, CGS, ((Fraction(0), Fraction(0), Fraction(1)), (Fraction(1), Fraction(0), Fraction(0)), (Fraction(0), Fraction(1), Fraction(0)), (Fraction(1, 2), Fraction(1, 2), Fraction(-1)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0)), (Fraction(0), Fraction(0), Fraction(0))))
module-attribute
¶
Transform from SI to CGS-EMU.
Maps SI dimensions to CGS-EMU. Current (I) becomes a derived dimension expressed as L^(1/2) M^(1/2) T^(-1), which is the dimensional formula for current in the electromagnetic CGS system.
Note: This differs from SI_TO_CGS_ESU where I -> L^(3/2) M^(1/2) T^(-2). The EMU system uses the permeability of free space = 1, while ESU uses the permittivity of free space = 1.
CGS_TO_SI = SI_TO_CGS.embedding()
module-attribute
¶
Embedding from CGS back to SI.
Maps CGS dimensions back to SI with zeros for components that were dropped in the projection (current, temperature, amount, luminosity, angle).
SI_TO_NATURAL = ConstantBoundBasisTransform(source=SI, target=NATURAL, matrix=((Fraction(-1),), (Fraction(-1),), (Fraction(1),), (Fraction(0),), (Fraction(1),), (Fraction(0),), (Fraction(0),), (Fraction(0),)), bindings=_NATURAL_BINDINGS)
module-attribute
¶
Transform from SI to natural units.
Maps SI dimensions to the single energy dimension in natural units: - Time (T) → E⁻¹ (via ℏ) - Length (L) → E⁻¹ (via ℏc) - Mass (M) → E (via c²) - Temperature (Θ) → E (via k_B)
Current (I), luminous_intensity (J), amount_of_substance (N), and information (B) are not representable in natural units and will raise LossyProjection if non-zero (unless allow_projection=True).
Key consequences: - Velocity (L/T) → E⁰ (dimensionless, since c = 1) - Energy (ML²T⁻²) → E (as expected) - Action (ML²T⁻¹) → E⁰ (dimensionless, since ℏ = 1)
NATURAL_TO_SI = SI_TO_NATURAL.inverse()
module-attribute
¶
Transform from natural units back to SI.
This is the inverse of SI_TO_NATURAL, computed using the constant bindings. Allows converting natural unit dimensions back to their SI representation.
Note: Information about which specific combination of L, T, M, Θ a given E dimension originated from is tracked via the constant bindings. However, the numeric conversion factors require the actual constant values from ucon.constants.
BasisTransform
dataclass
¶
Linear map between dimensional bases.
Represents how each component of the source basis expresses in terms of the target basis components via matrix multiplication.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
Basis
|
The source basis. |
required |
target
|
Basis
|
The target basis. |
required |
matrix
|
tuple[tuple[Fraction, ...], ...]
|
Transformation matrix as tuple of tuples. Shape is
(len(source), len(target)). Entry |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If matrix dimensions don't match basis dimensions. |
Examples:
>>> # Identity transform
>>> identity = BasisTransform.identity(some_basis)
>>> identity.is_identity()
True
>>> # SI current in CGS-ESU: I -> L^(3/2) M^(1/2) T^(-2)
>>> transform = BasisTransform(SI, CGS_ESU, matrix)
>>> esu_dim = transform(si_current_vector)
__str__()
¶
Human-readable string with matrix visualization.
__call__(vector, *, allow_projection=False)
¶
Transform a vector from source basis to target basis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vector
|
Vector
|
The vector to transform (must be in source basis). |
required |
allow_projection
|
bool
|
If False (default), raise LossyProjection when a non-zero component would be discarded. If True, silently project (drop) unrepresentable components. |
False
|
Returns:
| Type | Description |
|---|---|
Vector
|
A new Vector in the target basis. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If vector is not in the source basis. |
LossyProjection
|
If allow_projection=False and a non-zero component maps entirely to zeros in the target basis. |
inverse()
¶
Return the inverse transform (target -> source).
Uses Gaussian elimination with partial pivoting over Fraction for exact arithmetic.
Returns:
| Type | Description |
|---|---|
'BasisTransform'
|
A new BasisTransform from target to source. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the matrix is not square or is singular. |
embedding()
¶
Return the canonical embedding (target -> source).
For a projection A -> B, the embedding B -> A maps each B component back to its source A component, with zeros for unmapped A components.
Only valid for clean projections where each target component maps from exactly one source component with coefficient 1.
Returns:
| Type | Description |
|---|---|
'BasisTransform'
|
A new BasisTransform from target to source. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the transform is not a clean projection. |
__matmul__(other)
¶
Compose transforms: (self @ other)(v) = self(other(v)).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
'BasisTransform'
|
Transform to apply first. |
required |
Returns:
| Type | Description |
|---|---|
'BasisTransform'
|
A composed transform from other.source to self.target. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If other.target != self.source. |
identity(basis)
classmethod
¶
Return the identity transform for a basis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
basis
|
Basis
|
The basis for the identity transform. |
required |
Returns:
| Type | Description |
|---|---|
'BasisTransform'
|
An identity transform where source == target == basis. |
is_identity()
¶
Check if this transform is the identity.
Returns:
| Type | Description |
|---|---|
bool
|
True if source == target and matrix is identity matrix. |
ConstantBinding
dataclass
¶
Binds a source dimension to a target expression via a physical constant.
Records that source_component in the source basis becomes
target_expression in the target basis, with the relationship
defined by a physical constant raised to exponent.
Parameters¶
source_component : BasisComponent The fundamental component being transformed. target_expression : Vector How it expresses in the target basis. constant_symbol : str Symbol of the constant defining this relationship (e.g., "c", "ℏ"). We use a string rather than a Constant object to avoid circular imports between ucon.basis and ucon.constants. exponent : Fraction Power of the constant in the relationship (usually ±1/2 or ±1).
Examples¶
In natural units: length = ℏc/E, so L → E⁻¹ via ℏc¶
from fractions import Fraction binding = ConstantBinding( ... source_component=BasisComponent("length", "L"), ... target_expression=Vector(NATURAL, (Fraction(-1),)), ... constant_symbol="ℏc", ... exponent=Fraction(1), ... )
ConstantBoundBasisTransform
dataclass
¶
A basis transform with constants that enable inversion of non-square matrices.
Extends BasisTransform with explicit constant bindings that record which
constants define each non-trivial mapping. This enables inverse() to work
on non-square transforms by providing the information needed to reverse
derived mappings.
Parameters¶
source : Basis Source basis. target : Basis Target basis. matrix : tuple[tuple[Fraction, ...], ...] Dimensional transformation matrix. Shape is (len(source), len(target)). bindings : tuple[ConstantBinding, ...] Constants that define derived relationships.
Examples¶
SI (8 dimensions) → NATURAL (1 dimension) transform¶
SI_TO_NATURAL = ConstantBoundBasisTransform( ... source=SI, ... target=NATURAL, ... matrix=(...), # 8×1 matrix ... bindings=(...), # Bindings for L, T, M, Θ → E ... )
This works because bindings record how to reverse!¶
NATURAL_TO_SI = SI_TO_NATURAL.inverse()
__call__(vector, *, allow_projection=False)
¶
Transform a vector from source basis to target basis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vector
|
Vector
|
The vector to transform (must be in source basis). |
required |
allow_projection
|
bool
|
If False (default), raise LossyProjection when a non-zero component would be discarded. If True, silently project (drop) unrepresentable components. |
False
|
Returns:
| Type | Description |
|---|---|
Vector
|
A new Vector in the target basis. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If vector is not in the source basis. |
LossyProjection
|
If allow_projection=False and a non-zero component maps entirely to zeros in the target basis. |
inverse()
¶
Compute the inverse transform using constant bindings.
For each binding (src_component → target_expression via constant): - The inverse maps target_expression → src_component - The constant exponent is negated (constant^(-exponent))
Returns¶
ConstantBoundBasisTransform The inverse transform from target to source.
Raises¶
ValueError If a source component has no binding and cannot be inverted.
Notes¶
Components that map to zero (truly dropped) cannot be recovered and will map to zero in the inverse. Only components with bindings are invertible for non-square matrices.
as_basis_transform()
¶
Return as plain BasisTransform (loses binding information).
Useful for interoperability with code expecting BasisTransform.