ucon 0.5.0__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
 # --------------------------------------------------------------------------------------
@@ -445,15 +459,417 @@ class Unit:
 
     # ----------------- callable (creates Number) -----------------
 
-    def __call__(self, quantity: Union[int, float]) -> "Number":
+    def __call__(self, quantity: Union[int, float], uncertainty: Union[float, None] = None) -> "Number":
         """Create a Number with this unit.
 
+        Parameters
+        ----------
+        quantity : int or float
+            The numeric value.
+        uncertainty : float, optional
+            The measurement uncertainty.
+
         Example
         -------
         >>> meter(5)
         <5 m>
+        >>> meter(1.234, uncertainty=0.005)
+        <1.234 ± 0.005 m>
         """
-        return Number(quantity=quantity, unit=UnitProduct.from_unit(self))
+        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)
@@ -872,15 +1288,24 @@ class UnitProduct:
         # Sort by name; UnitFactor exposes .name, so this is stable.
         return hash(tuple(sorted(self.factors.items(), key=lambda x: x[0].name)))
 
-    def __call__(self, quantity: Union[int, float]) -> "Number":
+    def __call__(self, quantity: Union[int, float], uncertainty: Union[float, None] = None) -> "Number":
         """Create a Number with this unit product.
 
+        Parameters
+        ----------
+        quantity : int or float
+            The numeric value.
+        uncertainty : float, optional
+            The measurement uncertainty.
+
         Example
         -------
         >>> (meter / second)(10)
         <10 m/s>
+        >>> (meter / second)(10, uncertainty=0.5)
+        <10 ± 0.5 m/s>
         """
-        return Number(quantity=quantity, unit=self)
+        return Number(quantity=quantity, unit=self, uncertainty=uncertainty)
 
 
 # --------------------------------------------------------------------------------------
@@ -908,9 +1333,16 @@ class Number:
         >>> speed = length / time
         >>> speed
         <2.5 m/s>
+
+    Optionally includes measurement uncertainty for error propagation:
+
+        >>> length = meter(1.234, uncertainty=0.005)
+        >>> length
+        <1.234 ± 0.005 m>
     """
     quantity: Union[float, int] = 1.0
     unit: Union[Unit, UnitProduct] = None
+    uncertainty: Union[float, None] = None
 
     def __post_init__(self):
         if self.unit is None:
@@ -952,7 +1384,7 @@ class Number:
         """
         if not isinstance(self.unit, UnitProduct):
             # Plain Unit already has no scale
-            return Number(quantity=self.quantity, unit=self.unit)
+            return Number(quantity=self.quantity, unit=self.unit, uncertainty=self.uncertainty)
 
         # Compute the combined scale factor
         scale_factor = self.unit.fold_scale()
@@ -965,8 +1397,16 @@ class Number:
 
         base_unit = UnitProduct(base_factors)
 
-        # Adjust quantity by the scale factor
-        return Number(quantity=self.quantity * scale_factor, unit=base_unit)
+        # Adjust quantity and uncertainty by the scale factor
+        new_uncertainty = None
+        if self.uncertainty is not None:
+            new_uncertainty = self.uncertainty * abs(scale_factor)
+
+        return Number(
+            quantity=self.quantity * scale_factor,
+            unit=base_unit,
+            uncertainty=new_uncertainty,
+        )
 
     def to(self, target, graph=None):
         """Convert this Number to a different unit expression.
@@ -999,7 +1439,10 @@ class Number:
         # Scale-only conversion (same base unit, different scale)
         if self._is_scale_only_conversion(src, dst):
             factor = src.fold_scale() / dst.fold_scale()
-            return Number(quantity=self.quantity * factor, unit=target)
+            new_uncertainty = None
+            if self.uncertainty is not None:
+                new_uncertainty = self.uncertainty * abs(factor)
+            return Number(quantity=self.quantity * factor, unit=target, uncertainty=new_uncertainty)
 
         # Graph-based conversion (use default graph if none provided)
         if graph is None:
@@ -1008,7 +1451,14 @@ class Number:
         conversion_map = graph.convert(src=src, dst=dst)
         # Use raw quantity - the conversion map handles scale via factorwise decomposition
         converted_quantity = conversion_map(self.quantity)
-        return Number(quantity=converted_quantity, unit=target)
+
+        # Propagate uncertainty through conversion using derivative
+        new_uncertainty = None
+        if self.uncertainty is not None:
+            derivative = abs(conversion_map.derivative(self.quantity))
+            new_uncertainty = derivative * self.uncertainty
+
+        return Number(quantity=converted_quantity, unit=target, uncertainty=new_uncertainty)
 
     def _is_scale_only_conversion(self, src: UnitProduct, dst: UnitProduct) -> bool:
         """Check if conversion is just a scale change (same base units)."""
@@ -1040,12 +1490,82 @@ class Number:
         if isinstance(other, Ratio):
             other = other.evaluate()
 
+        # Scalar multiplication
+        if isinstance(other, (int, float)):
+            new_uncertainty = None
+            if self.uncertainty is not None:
+                new_uncertainty = abs(other) * self.uncertainty
+            return Number(
+                quantity=self.quantity * other,
+                unit=self.unit,
+                uncertainty=new_uncertainty,
+            )
+
         if not isinstance(other, Number):
             return NotImplemented
 
+        # Uncertainty propagation for multiplication
+        # δc = |c| * sqrt((δa/a)² + (δb/b)²)
+        new_uncertainty = None
+        result_quantity = self.quantity * other.quantity
+        if self.uncertainty is not None or other.uncertainty is not None:
+            rel_a = (self.uncertainty / abs(self.quantity)) if (self.uncertainty and self.quantity != 0) else 0
+            rel_b = (other.uncertainty / abs(other.quantity)) if (other.uncertainty and other.quantity != 0) else 0
+            rel_c = math.sqrt(rel_a**2 + rel_b**2)
+            new_uncertainty = abs(result_quantity) * rel_c if rel_c > 0 else None
+
         return Number(
-            quantity=self.quantity * other.quantity,
+            quantity=result_quantity,
             unit=self.unit * other.unit,
+            uncertainty=new_uncertainty,
+        )
+
+    def __add__(self, other: 'Number') -> 'Number':
+        if not isinstance(other, Number):
+            return NotImplemented
+
+        # Dimensions must match for addition
+        if self.unit.dimension != other.unit.dimension:
+            raise TypeError(
+                f"Cannot add Numbers with different dimensions: "
+                f"{self.unit.dimension} vs {other.unit.dimension}"
+            )
+
+        # Uncertainty propagation for addition: δc = sqrt(δa² + δb²)
+        new_uncertainty = None
+        if self.uncertainty is not None or other.uncertainty is not None:
+            ua = self.uncertainty if self.uncertainty is not None else 0
+            ub = other.uncertainty if other.uncertainty is not None else 0
+            new_uncertainty = math.sqrt(ua**2 + ub**2)
+
+        return Number(
+            quantity=self.quantity + other.quantity,
+            unit=self.unit,
+            uncertainty=new_uncertainty,
+        )
+
+    def __sub__(self, other: 'Number') -> 'Number':
+        if not isinstance(other, Number):
+            return NotImplemented
+
+        # Dimensions must match for subtraction
+        if self.unit.dimension != other.unit.dimension:
+            raise TypeError(
+                f"Cannot subtract Numbers with different dimensions: "
+                f"{self.unit.dimension} vs {other.unit.dimension}"
+            )
+
+        # Uncertainty propagation for subtraction: δc = sqrt(δa² + δb²)
+        new_uncertainty = None
+        if self.uncertainty is not None or other.uncertainty is not None:
+            ua = self.uncertainty if self.uncertainty is not None else 0
+            ub = other.uncertainty if other.uncertainty is not None else 0
+            new_uncertainty = math.sqrt(ua**2 + ub**2)
+
+        return Number(
+            quantity=self.quantity - other.quantity,
+            unit=self.unit,
+            uncertainty=new_uncertainty,
         )
 
     def __truediv__(self, other: Quantifiable) -> "Number":
@@ -1053,25 +1573,47 @@ class Number:
         if isinstance(other, Ratio):
             other = other.evaluate()
 
+        # Scalar division
+        if isinstance(other, (int, float)):
+            new_uncertainty = None
+            if self.uncertainty is not None:
+                new_uncertainty = self.uncertainty / abs(other)
+            return Number(
+                quantity=self.quantity / other,
+                unit=self.unit,
+                uncertainty=new_uncertainty,
+            )
+
         if not isinstance(other, Number):
             raise TypeError(f"Cannot divide Number by non-Number/Ratio type: {type(other)}")
 
         # Symbolic quotient in the unit algebra
         unit_quot = self.unit / other.unit
 
+        # Uncertainty propagation for division
+        # δc = |c| * sqrt((δa/a)² + (δb/b)²)
+        def compute_uncertainty(result_quantity):
+            if self.uncertainty is None and other.uncertainty is None:
+                return None
+            rel_a = (self.uncertainty / abs(self.quantity)) if (self.uncertainty and self.quantity != 0) else 0
+            rel_b = (other.uncertainty / abs(other.quantity)) if (other.uncertainty and other.quantity != 0) else 0
+            rel_c = math.sqrt(rel_a**2 + rel_b**2)
+            return abs(result_quantity) * rel_c if rel_c > 0 else None
+
         # --- Case 1: Dimensionless result ----------------------------------
         # If the net dimension is none, we want a pure scalar:
         # fold *all* scale factors into the numeric magnitude.
         if not unit_quot.dimension:
             num = self._canonical_magnitude
             den = other._canonical_magnitude
-            return Number(quantity=num / den, unit=_none)
+            result = num / den
+            return Number(quantity=result, unit=_none, uncertainty=compute_uncertainty(result))
 
         # --- Case 2: Dimensionful result -----------------------------------
         # For "real" physical results like g/mL, m/s², etc., preserve the
         # user's chosen unit scales symbolically. Only divide the raw quantities.
         new_quantity = self.quantity / other.quantity
-        return Number(quantity=new_quantity, unit=unit_quot)
+        return Number(quantity=new_quantity, unit=unit_quot, uncertainty=compute_uncertainty(new_quantity))
 
     def __eq__(self, other: Quantifiable) -> bool:
         if not isinstance(other, (Number, Ratio)):
@@ -1094,6 +1636,10 @@ class Number:
         return True
 
     def __repr__(self):
+        if self.uncertainty is not None:
+            if not self.unit.dimension:
+                return f"<{self.quantity} ± {self.uncertainty}>"
+            return f"<{self.quantity} ± {self.uncertainty} {self.unit.shorthand}>"
         if not self.unit.dimension:
             return f"<{self.quantity}>"
         return f"<{self.quantity} {self.unit.shorthand}>"