ucon 0.5.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

ucon/core.py

@@ -28,6 +28,20 @@ from typing import Dict, Tuple, Union
 from ucon.algebra import Exponent, Vector
 
 
+# --------------------------------------------------------------------------------------
+# Exceptions
+# --------------------------------------------------------------------------------------
+
+class DimensionNotCovered(Exception):
+    """Raised when a UnitSystem doesn't cover a requested dimension."""
+    pass
+
+
+class NonInvertibleTransform(Exception):
+    """Raised when a BasisTransform is not invertible (non-square or singular)."""
+    pass
+
+
 # --------------------------------------------------------------------------------------
 # Dimension
 # --------------------------------------------------------------------------------------
@@ -465,6 +479,399 @@ class Unit:
         return Number(quantity=quantity, unit=UnitProduct.from_unit(self), uncertainty=uncertainty)
 
 
+# --------------------------------------------------------------------------------------
+# UnitSystem
+# --------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class UnitSystem:
+    """
+    A named mapping from dimensions to base units.
+
+    Represents a coherent unit system like SI or Imperial, where each
+    covered dimension has exactly one base unit. Partial systems are
+    allowed (Imperial doesn't need mole).
+
+    Parameters
+    ----------
+    name : str
+        The name of the unit system (e.g., "SI", "Imperial").
+    bases : dict[Dimension, Unit]
+        Mapping from dimensions to their base units.
+
+    Raises
+    ------
+    ValueError
+        If name is empty, bases is empty, or a unit's dimension doesn't
+        match its declared dimension key.
+
+    Examples
+    --------
+    >>> si = UnitSystem(
+    ...     name="SI",
+    ...     bases={
+    ...         Dimension.length: meter,
+    ...         Dimension.mass: kilogram,
+    ...         Dimension.time: second,
+    ...     }
+    ... )
+    >>> si.base_for(Dimension.length)
+    <Unit m>
+    """
+    name: str
+    bases: Dict[Dimension, 'Unit']
+
+    def __post_init__(self):
+        if not self.name:
+            raise ValueError("UnitSystem must have a name")
+        if not self.bases:
+            raise ValueError("UnitSystem must have at least one base unit")
+
+        for dim, unit in self.bases.items():
+            if unit.dimension != dim:
+                raise ValueError(
+                    f"Base unit {unit.name} has dimension {unit.dimension.name}, "
+                    f"but was declared as base for {dim.name}"
+                )
+
+    def base_for(self, dim: Dimension) -> 'Unit':
+        """Return the base unit for a dimension.
+
+        Raises
+        ------
+        DimensionNotCovered
+            If this system has no base unit for the dimension.
+        """
+        if dim not in self.bases:
+            raise DimensionNotCovered(
+                f"{self.name} has no base unit for {dim.name}"
+            )
+        return self.bases[dim]
+
+    def covers(self, dim: Dimension) -> bool:
+        """Return True if this system has a base unit for the dimension."""
+        return dim in self.bases
+
+    @property
+    def dimensions(self) -> set:
+        """Return the set of dimensions covered by this system."""
+        return set(self.bases.keys())
+
+    def __hash__(self):
+        # Frozen dataclass with dict field needs custom hash
+        return hash((self.name, tuple(sorted(self.bases.items(), key=lambda x: x[0].name))))
+
+
+# --------------------------------------------------------------------------------------
+# BasisTransform
+# --------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class BasisTransform:
+    """
+    A surjective map between dimensional exponent spaces.
+
+    Transforms exponent vectors from one system's basis to another's using
+    matrix multiplication. Columns correspond to source dimensions, rows
+    correspond to destination dimensions.
+
+    Parameters
+    ----------
+    src : UnitSystem
+        The source unit system.
+    dst : UnitSystem
+        The destination unit system.
+    src_dimensions : tuple[Dimension, ...]
+        Ordered source dimensions (matrix columns).
+    dst_dimensions : tuple[Dimension, ...]
+        Ordered destination dimensions (matrix rows).
+    matrix : tuple[tuple[Fraction, ...], ...]
+        Transformation matrix with exact Fraction arithmetic.
+
+    Raises
+    ------
+    ValueError
+        If matrix dimensions don't match the declared dimension counts.
+
+    Examples
+    --------
+    >>> # 1:1 dimension relabeling (esu_charge -> charge)
+    >>> esu_to_si = BasisTransform(
+    ...     src=cgs_esu,
+    ...     dst=si,
+    ...     src_dimensions=(Dimension.esu_charge,),
+    ...     dst_dimensions=(Dimension.charge,),
+    ...     matrix=((1,),),
+    ... )
+    """
+    src: 'UnitSystem'
+    dst: 'UnitSystem'
+    src_dimensions: Tuple[Dimension, ...]
+    dst_dimensions: Tuple[Dimension, ...]
+    matrix: Tuple[Tuple, ...]
+
+    def __post_init__(self):
+        from fractions import Fraction
+
+        # Convert matrix entries to Fraction for exact arithmetic
+        converted = tuple(
+            tuple(Fraction(x) for x in row)
+            for row in self.matrix
+        )
+        object.__setattr__(self, 'matrix', converted)
+
+        # Validate matrix dimensions
+        rows = len(self.matrix)
+        cols = len(self.matrix[0]) if self.matrix else 0
+
+        if rows != len(self.dst_dimensions):
+            raise ValueError(
+                f"Matrix has {rows} rows but {len(self.dst_dimensions)} "
+                f"dst dimensions declared"
+            )
+        if cols != len(self.src_dimensions):
+            raise ValueError(
+                f"Matrix has {cols} columns but {len(self.src_dimensions)} "
+                f"src dimensions declared"
+            )
+
+    def transform(self, src_vector: Vector) -> Vector:
+        """Map exponent vector from src basis to dst basis."""
+        from fractions import Fraction
+
+        # Extract components corresponding to src_dimensions
+        src_components = []
+        for dim in self.src_dimensions:
+            src_components.append(self._get_component(src_vector, dim))
+
+        # Matrix multiply
+        result = {}
+        for i, dst_dim in enumerate(self.dst_dimensions):
+            val = sum(
+                self.matrix[i][j] * src_components[j]
+                for j in range(len(self.src_dimensions))
+            )
+            result[dst_dim] = val
+
+        return self._build_vector(result)
+
+    def _get_component(self, vector: Vector, dim: Dimension) -> 'Fraction':
+        """Extract the component of a vector corresponding to a dimension."""
+        from fractions import Fraction
+
+        dim_vector = dim.value
+        if isinstance(dim_vector, tuple):
+            dim_vector = dim_vector[0]
+
+        # Find which component is non-zero in the dimension's vector
+        for attr, val in [('T', dim_vector.T), ('L', dim_vector.L),
+                          ('M', dim_vector.M), ('I', dim_vector.I),
+                          ('Θ', dim_vector.Θ), ('J', dim_vector.J),
+                          ('N', dim_vector.N), ('B', dim_vector.B)]:
+            if val == Fraction(1):
+                return getattr(vector, attr)
+
+        # For compound dimensions, return the dot product
+        return Fraction(0)
+
+    def _build_vector(self, dim_values: dict) -> Vector:
+        """Build a Vector from dimension -> value mapping."""
+        from fractions import Fraction
+
+        kwargs = {'T': Fraction(0), 'L': Fraction(0), 'M': Fraction(0),
+                  'I': Fraction(0), 'Θ': Fraction(0), 'J': Fraction(0),
+                  'N': Fraction(0), 'B': Fraction(0)}
+
+        for dim, val in dim_values.items():
+            dim_vector = dim.value
+            if isinstance(dim_vector, tuple):
+                dim_vector = dim_vector[0]
+
+            # Apply the value to the appropriate component
+            for attr, basis_val in [('T', dim_vector.T), ('L', dim_vector.L),
+                                    ('M', dim_vector.M), ('I', dim_vector.I),
+                                    ('Θ', dim_vector.Θ), ('J', dim_vector.J),
+                                    ('N', dim_vector.N), ('B', dim_vector.B)]:
+                if basis_val != Fraction(0):
+                    kwargs[attr] = kwargs[attr] + val * basis_val
+
+        return Vector(**kwargs)
+
+    def validate_edge(self, src_unit: 'Unit', dst_unit: 'Unit') -> bool:
+        """Check if src transforms to dst's dimension."""
+        src_dim_vector = src_unit.dimension.value
+        if isinstance(src_dim_vector, tuple):
+            src_dim_vector = src_dim_vector[0]
+
+        transformed = self.transform(src_dim_vector)
+
+        dst_dim_vector = dst_unit.dimension.value
+        if isinstance(dst_dim_vector, tuple):
+            dst_dim_vector = dst_dim_vector[0]
+
+        return transformed == dst_dim_vector
+
+    @property
+    def is_square(self) -> bool:
+        """Return True if the matrix is square."""
+        return len(self.src_dimensions) == len(self.dst_dimensions)
+
+    @property
+    def is_invertible(self) -> bool:
+        """Return True if the matrix is invertible."""
+        from fractions import Fraction
+        if not self.is_square:
+            return False
+        return self._determinant() != Fraction(0)
+
+    def inverse(self) -> 'BasisTransform':
+        """Return the inverse transform.
+
+        Raises
+        ------
+        NonInvertibleTransform
+            If the transform is not invertible (non-square or singular).
+        """
+        if not self.is_invertible:
+            raise NonInvertibleTransform(
+                f"Transform {self.src.name} -> {self.dst.name} "
+                f"({len(self.dst_dimensions)}x{len(self.src_dimensions)}) "
+                f"is not invertible"
+            )
+        inv_matrix = self._invert_matrix()
+        return BasisTransform(
+            src=self.dst,
+            dst=self.src,
+            src_dimensions=self.dst_dimensions,
+            dst_dimensions=self.src_dimensions,
+            matrix=inv_matrix,
+        )
+
+    def _determinant(self) -> 'Fraction':
+        """Compute determinant for square matrices."""
+        from fractions import Fraction
+        n = len(self.matrix)
+        if n == 1:
+            return self.matrix[0][0]
+        if n == 2:
+            return (self.matrix[0][0] * self.matrix[1][1] -
+                    self.matrix[0][1] * self.matrix[1][0])
+        # General case: cofactor expansion
+        det = Fraction(0)
+        for j in range(n):
+            minor = tuple(
+                tuple(self.matrix[i][k] for k in range(n) if k != j)
+                for i in range(1, n)
+            )
+            sign = Fraction((-1) ** j)
+            sub_det = BasisTransform._static_determinant(minor)
+            det += sign * self.matrix[0][j] * sub_det
+        return det
+
+    @staticmethod
+    def _static_determinant(matrix: tuple) -> 'Fraction':
+        """Recursive determinant for submatrices."""
+        from fractions import Fraction
+        n = len(matrix)
+        if n == 1:
+            return matrix[0][0]
+        if n == 2:
+            return matrix[0][0] * matrix[1][1] - matrix[0][1] * matrix[1][0]
+        det = Fraction(0)
+        for j in range(n):
+            minor = tuple(
+                tuple(matrix[i][k] for k in range(n) if k != j)
+                for i in range(1, n)
+            )
+            det += Fraction((-1) ** j) * matrix[0][j] * BasisTransform._static_determinant(minor)
+        return det
+
+    def _invert_matrix(self) -> Tuple[Tuple, ...]:
+        """Gauss-Jordan elimination with exact Fraction arithmetic."""
+        from fractions import Fraction
+        n = len(self.matrix)
+
+        # Augment with identity
+        aug = [
+            [Fraction(self.matrix[i][j]) for j in range(n)] +
+            [Fraction(1) if i == j else Fraction(0) for j in range(n)]
+            for i in range(n)
+        ]
+
+        # Forward elimination with partial pivoting
+        for col in range(n):
+            pivot_row = None
+            for row in range(col, n):
+                if aug[row][col] != 0:
+                    pivot_row = row
+                    break
+            if pivot_row is None:
+                raise NonInvertibleTransform("Singular matrix")
+
+            aug[col], aug[pivot_row] = aug[pivot_row], aug[col]
+
+            pivot = aug[col][col]
+            aug[col] = [x / pivot for x in aug[col]]
+
+            for row in range(n):
+                if row != col:
+                    factor = aug[row][col]
+                    aug[row] = [a - factor * b for a, b in zip(aug[row], aug[col])]
+
+        return tuple(
+            tuple(aug[i][n + j] for j in range(n))
+            for i in range(n)
+        )
+
+
+# --------------------------------------------------------------------------------------
+# RebasedUnit
+# --------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RebasedUnit:
+    """
+    A unit whose dimension was transformed by a BasisTransform.
+
+    Lives in the destination partition but preserves provenance to the
+    original unit and the transform that created it.
+
+    Parameters
+    ----------
+    original : Unit
+        The original unit before transformation.
+    rebased_dimension : Dimension
+        The dimension in the destination system.
+    basis_transform : BasisTransform
+        The transform that rebased this unit.
+
+    Examples
+    --------
+    >>> rebased = RebasedUnit(
+    ...     original=statcoulomb,
+    ...     rebased_dimension=Dimension.charge,
+    ...     basis_transform=esu_to_si,
+    ... )
+    >>> rebased.dimension
+    <Dimension.charge>
+    >>> rebased.name
+    'statcoulomb'
+    """
+    original: 'Unit'
+    rebased_dimension: Dimension
+    basis_transform: 'BasisTransform'
+
+    @property
+    def dimension(self) -> Dimension:
+        """Return the rebased dimension (in the destination system)."""
+        return self.rebased_dimension
+
+    @property
+    def name(self) -> str:
+        """Return the name of the original unit."""
+        return self.original.name
+
+
 @dataclass(frozen=True)
 class UnitFactor:
     """

ucon/graph.py

@@ -28,7 +28,15 @@ from contextvars import ContextVar
 from dataclasses import dataclass, field
 from typing import Union
 
-from ucon.core import Dimension, Unit, UnitFactor, UnitProduct, Scale
+from ucon.core import (
+    BasisTransform,
+    Dimension,
+    RebasedUnit,
+    Unit,
+    UnitFactor,
+    UnitProduct,
+    Scale,
+)
 from ucon.maps import Map, LinearMap, AffineMap
 
 
@@ -66,6 +74,9 @@ class ConversionGraph:
     # Edges between UnitProducts (keyed by frozen factor representation)
     _product_edges: dict[tuple, dict[tuple, Map]] = field(default_factory=dict)
 
+    # Rebased units: original unit → RebasedUnit (for cross-basis edges)
+    _rebased: dict[Unit, RebasedUnit] = field(default_factory=dict)
+
     # ------------- Edge Management -------------------------------------------
 
     def add_edge(
@@ -74,6 +85,7 @@ class ConversionGraph:
         src: Union[Unit, UnitProduct],
         dst: Union[Unit, UnitProduct],
         map: Map,
+        basis_transform: BasisTransform | None = None,
     ) -> None:
         """Register a conversion edge. Also registers the inverse.
 
@@ -85,15 +97,31 @@ class ConversionGraph:
             Destination unit expression.
         map : Map
             The conversion morphism (src → dst).
+        basis_transform : BasisTransform, optional
+            If provided, creates a cross-basis edge. The src unit is rebased
+            to the dst's dimension and the edge connects the rebased unit
+            to dst.
 
         Raises
         ------
         DimensionMismatch
-            If src and dst have different dimensions.
+            If src and dst have different dimensions (and no basis_transform).
         CyclicInconsistency
             If the reverse edge exists and round-trip is not identity.
         """
-        # Handle Unit vs UnitProduct dispatch
+        # Cross-basis edge with BasisTransform
+        if basis_transform is not None:
+            if isinstance(src, Unit) and not isinstance(src, UnitProduct):
+                if isinstance(dst, Unit) and not isinstance(dst, UnitProduct):
+                    self._add_cross_basis_edge(
+                        src=src,
+                        dst=dst,
+                        map=map,
+                        basis_transform=basis_transform,
+                    )
+                    return
+
+        # Handle Unit vs UnitProduct dispatch (normal case)
         if isinstance(src, Unit) and not isinstance(src, UnitProduct):
             if isinstance(dst, Unit) and not isinstance(dst, UnitProduct):
                 self._add_unit_edge(src=src, dst=dst, map=map)
@@ -142,6 +170,114 @@ class ConversionGraph:
         self._product_edges.setdefault(src_key, {})[dst_key] = map
         self._product_edges.setdefault(dst_key, {})[src_key] = map.inverse()
 
+    def _add_cross_basis_edge(
+        self,
+        *,
+        src: Unit,
+        dst: Unit,
+        map: Map,
+        basis_transform: BasisTransform,
+    ) -> None:
+        """Add cross-basis edge between Units via BasisTransform.
+
+        Creates a RebasedUnit for src in the destination's dimension partition,
+        then stores the edge from the rebased unit to dst.
+        """
+        # Validate that the transform maps src to dst's dimension
+        if not basis_transform.validate_edge(src, dst):
+            raise DimensionMismatch(
+                f"Transform {basis_transform.src.name} -> {basis_transform.dst.name} "
+                f"does not map {src.name} to {dst.name}'s dimension"
+            )
+
+        # Create RebasedUnit in destination's dimension partition
+        rebased = RebasedUnit(
+            original=src,
+            rebased_dimension=dst.dimension,
+            basis_transform=basis_transform,
+        )
+        self._rebased[src] = rebased
+
+        # Store edge from rebased to dst (same dimension now)
+        dim = dst.dimension
+        self._ensure_dimension(dim)
+        self._unit_edges[dim].setdefault(rebased, {})[dst] = map
+        self._unit_edges[dim].setdefault(dst, {})[rebased] = map.inverse()
+
+    def connect_systems(
+        self,
+        *,
+        basis_transform: BasisTransform,
+        edges: dict[tuple[Unit, Unit], Map],
+    ) -> None:
+        """Bulk-add edges between systems.
+
+        Parameters
+        ----------
+        basis_transform : BasisTransform
+            The transform bridging the two systems.
+        edges : dict
+            Mapping from (src_unit, dst_unit) to Map.
+        """
+        for (src, dst), edge_map in edges.items():
+            self.add_edge(
+                src=src,
+                dst=dst,
+                map=edge_map,
+                basis_transform=basis_transform,
+            )
+
+    def list_rebased_units(self) -> dict[Unit, RebasedUnit]:
+        """Return all rebased units in the graph.
+
+        Returns
+        -------
+        dict[Unit, RebasedUnit]
+            Mapping from original unit to its RebasedUnit.
+        """
+        return dict(self._rebased)
+
+    def list_transforms(self) -> list[BasisTransform]:
+        """Return all BasisTransforms active in the graph.
+
+        Returns
+        -------
+        list[BasisTransform]
+            Unique transforms used by rebased units.
+        """
+        seen = set()
+        result = []
+        for rebased in self._rebased.values():
+            bt = rebased.basis_transform
+            if id(bt) not in seen:
+                seen.add(id(bt))
+                result.append(bt)
+        return result
+
+    def edges_for_transform(self, transform: BasisTransform) -> list[tuple[Unit, Unit]]:
+        """Return all edges that use a specific BasisTransform.
+
+        Parameters
+        ----------
+        transform : BasisTransform
+            The transform to filter by.
+
+        Returns
+        -------
+        list[tuple[Unit, Unit]]
+            List of (original_unit, destination_unit) pairs.
+        """
+        result = []
+        for original, rebased in self._rebased.items():
+            if rebased.basis_transform == transform:
+                # Find the destination unit (the one the rebased unit connects to)
+                dim = rebased.dimension
+                if dim in self._unit_edges and rebased in self._unit_edges[dim]:
+                    for dst in self._unit_edges[dim][rebased]:
+                        if not isinstance(dst, RebasedUnit):
+                            result.append((original, dst))
+        return result
+
     def _ensure_dimension(self, dim: Dimension) -> None:
         if dim not in self._unit_edges:
             self._unit_edges[dim] = {}
@@ -206,10 +342,28 @@ class ConversionGraph:
         return self._convert_products(src=src_prod, dst=dst_prod)
 
     def _convert_units(self, *, src: Unit, dst: Unit) -> Map:
-        """Convert between plain Units via BFS."""
+        """Convert between plain Units via BFS.
+
+        Handles cross-basis conversions via rebased units.
+        """
         if src == dst:
             return LinearMap.identity()
 
+        # Check if src has a rebased version that can reach dst
+        if src in self._rebased:
+            rebased = self._rebased[src]
+            if rebased.dimension == dst.dimension:
+                # Convert via the rebased unit
+                return self._bfs_convert(start=rebased, target=dst, dim=dst.dimension)
+
+        # Check if dst has a rebased version (inverse conversion)
+        if dst in self._rebased:
+            rebased_dst = self._rebased[dst]
+            if rebased_dst.dimension == src.dimension:
+                # Convert from src to the rebased dst
+                return self._bfs_convert(start=src, target=rebased_dst, dim=src.dimension)
+
+        # Check for dimension mismatch
         if src.dimension != dst.dimension:
             raise DimensionMismatch(f"{src.dimension} != {dst.dimension}")
 
@@ -217,13 +371,16 @@ class ConversionGraph:
         if self._has_direct_unit_edge(src=src, dst=dst):
             return self._get_direct_unit_edge(src=src, dst=dst)
 
-        # BFS
-        dim = src.dimension
+        # BFS in same dimension
+        return self._bfs_convert(start=src, target=dst, dim=src.dimension)
+
+    def _bfs_convert(self, *, start, target, dim: Dimension) -> Map:
+        """BFS to find conversion path within a dimension."""
         if dim not in self._unit_edges:
             raise ConversionNotFound(f"No edges for dimension {dim}")
 
-        visited: dict[Unit, Map] = {src: LinearMap.identity()}
-        queue = deque([src])
+        visited: dict = {start: LinearMap.identity()}
+        queue = deque([start])
 
         while queue:
             current = queue.popleft()
@@ -239,12 +396,12 @@ class ConversionGraph:
                 composed = edge_map @ current_map
                 visited[neighbor] = composed
 
-                if neighbor == dst:
+                if neighbor == target:
                     return composed
 
                 queue.append(neighbor)
 
-        raise ConversionNotFound(f"No path from {src} to {dst}")
+        raise ConversionNotFound(f"No path from {start} to {target}")
 
     def _convert_products(self, *, src: UnitProduct, dst: UnitProduct) -> Map:
         """Convert between UnitProducts.