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

ucon/__init__.py

@@ -38,20 +38,41 @@ Design Philosophy
 """
 from ucon import units
 from ucon.algebra import Exponent
-from ucon.core import Dimension, Scale, Unit, UnitFactor, UnitProduct, Number, Ratio
+from ucon.core import (
+    BasisTransform,
+    Dimension,
+    DimensionNotCovered,
+    NonInvertibleTransform,
+    RebasedUnit,
+    Scale,
+    Unit,
+    UnitFactor,
+    UnitProduct,
+    UnitSystem,
+    Number,
+    Ratio,
+)
 from ucon.graph import get_default_graph, using_graph
+from ucon.units import UnknownUnitError, get_unit_by_name
 
 
 __all__ = [
-    'Exponent',
+    'BasisTransform',
     'Dimension',
+    'DimensionNotCovered',
+    'Exponent',
+    'NonInvertibleTransform',
     'Number',
     'Ratio',
+    'RebasedUnit',
     'Scale',
     'Unit',
     'UnitFactor',
     'UnitProduct',
+    'UnitSystem',
+    'UnknownUnitError',
     'get_default_graph',
-    'using_graph',
+    'get_unit_by_name',
     'units',
+    'using_graph',
 ]

ucon/algebra.py

@@ -20,13 +20,14 @@ Classes
 - :class:`Exponent` — Base/power pair supporting prefix arithmetic.
 """
 import math
-from dataclasses import dataclass
+from dataclasses import dataclass, fields
+from fractions import Fraction
 from functools import partial, reduce, total_ordering
 from operator import __sub__ as subtraction
 from typing import Callable, Iterable, Iterator, Tuple, Union
 
 
-diff: Callable[[Iterable], int] = partial(reduce, subtraction)
+diff: Callable[[Iterable], Fraction] = partial(reduce, subtraction)
 
 
 @dataclass
@@ -43,22 +44,34 @@ class Vector:
     - Addition (`+`) → multiplication of quantities
     - Subtraction (`-`) → division of quantities
 
+    Components are stored as `Fraction` for exact arithmetic, enabling
+    fractional exponents (e.g., CGS-ESU charge: M^(1/2) · L^(3/2) · T^(-1)).
+    Integer and float inputs are automatically converted to Fraction.
+
     e.g.
     Vector(T=1, L=0, M=0, I=0, Θ=0, J=0, N=0, B=0)   => "time"
     Vector(T=0, L=2, M=0, I=0, Θ=0, J=0, N=0, B=0)   => "area"
     Vector(T=-2, L=1, M=1, I=0, Θ=0, J=0, N=0, B=0)  => "force"
     Vector(T=0, L=0, M=0, I=0, Θ=0, J=0, N=0, B=1)   => "information"
+    Vector(L=Fraction(3,2), M=Fraction(1,2), T=-1)   => "esu_charge"
     """
-    T: int = 0  # time
-    L: int = 0  # length
-    M: int = 0  # mass
-    I: int = 0  # current
-    Θ: int = 0  # temperature
-    J: int = 0  # luminous intensity
-    N: int = 0  # amount of substance
-    B: int = 0  # information (bits)
-
-    def __iter__(self) -> Iterator[int]:
+    T: Union[int, float, Fraction] = 0  # time
+    L: Union[int, float, Fraction] = 0  # length
+    M: Union[int, float, Fraction] = 0  # mass
+    I: Union[int, float, Fraction] = 0  # current
+    Θ: Union[int, float, Fraction] = 0  # temperature
+    J: Union[int, float, Fraction] = 0  # luminous intensity
+    N: Union[int, float, Fraction] = 0  # amount of substance
+    B: Union[int, float, Fraction] = 0  # information (bits)
+
+    def __post_init__(self):
+        """Convert all components to Fraction for exact arithmetic."""
+        for field in fields(self):
+            val = getattr(self, field.name)
+            if not isinstance(val, Fraction):
+                object.__setattr__(self, field.name, Fraction(val))
+
+    def __iter__(self) -> Iterator[Fraction]:
         yield self.T
         yield self.L
         yield self.M
@@ -90,7 +103,7 @@ class Vector:
         values = tuple(diff(pair) for pair in zip(tuple(self), tuple(vector)))
         return Vector(*values)
 
-    def __mul__(self, scalar: Union[int, float]) -> 'Vector':
+    def __mul__(self, scalar: Union[int, float, Fraction]) -> 'Vector':
         """
         Scalar multiplication of the exponent vector.
 
@@ -99,9 +112,18 @@ class Vector:
             >>> Dimension.length ** 2   # area
             >>> Dimension.time ** -1    # frequency
         """
-        values = tuple(component * scalar for component in tuple(self))
+        n = Fraction(scalar) if not isinstance(scalar, Fraction) else scalar
+        values = tuple(component * n for component in tuple(self))
         return Vector(*values)
 
+    def __rmul__(self, scalar: Union[int, float, Fraction]) -> 'Vector':
+        """Right multiplication: scalar * vector."""
+        return self.__mul__(scalar)
+
+    def __neg__(self) -> 'Vector':
+        """Negate the vector: -v."""
+        return Vector(*(-component for component in tuple(self)))
+
     def __eq__(self, other) -> bool:
         if not isinstance(other, Vector):
             return NotImplemented

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:
     """
@@ -701,16 +1108,21 @@ class UnitProduct:
         part = getattr(unit, "shorthand", "") or getattr(unit, "name", "") or ""
         if not part:
             return
+
+        def fmt_exp(p: float) -> str:
+            """Format exponent, using int when possible to avoid '2.0' → '²·⁰'."""
+            return str(int(p) if p == int(p) else p).translate(cls._SUPERSCRIPTS)
+
         if power > 0:
             if power == 1:
                 num.append(part)
             else:
-                num.append(part + str(power).translate(cls._SUPERSCRIPTS))
+                num.append(part + fmt_exp(power))
         elif power < 0:
             if power == -1:
                 den.append(part)
             else:
-                den.append(part + str(-power).translate(cls._SUPERSCRIPTS))
+                den.append(part + fmt_exp(-power))
 
     @property
     def shorthand(self) -> str: