ucon 0.3.5rc1__py3-none-any.whl → 0.4.0__py3-none-any.whl

ucon/core.py

@@ -22,7 +22,7 @@ from __future__ import annotations
 import math
 from enum import Enum
 from functools import lru_cache, reduce, total_ordering
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Dict, Tuple, Union
 
 from ucon.algebra import Exponent, Vector
@@ -40,47 +40,48 @@ class Dimension(Enum):
     none = Vector()
 
     # -- BASIS ---------------------------------------
-    time                = Vector(1, 0, 0, 0, 0, 0, 0)
-    length              = Vector(0, 1, 0, 0, 0, 0, 0)
-    mass                = Vector(0, 0, 1, 0, 0, 0, 0)
-    current             = Vector(0, 0, 0, 1, 0, 0, 0)
-    temperature         = Vector(0, 0, 0, 0, 1, 0, 0)
-    luminous_intensity  = Vector(0, 0, 0, 0, 0, 1, 0)
-    amount_of_substance = Vector(0, 0, 0, 0, 0, 0, 1)
+    time                = Vector(1, 0, 0, 0, 0, 0, 0, 0)
+    length              = Vector(0, 1, 0, 0, 0, 0, 0, 0)
+    mass                = Vector(0, 0, 1, 0, 0, 0, 0, 0)
+    current             = Vector(0, 0, 0, 1, 0, 0, 0, 0)
+    temperature         = Vector(0, 0, 0, 0, 1, 0, 0, 0)
+    luminous_intensity  = Vector(0, 0, 0, 0, 0, 1, 0, 0)
+    amount_of_substance = Vector(0, 0, 0, 0, 0, 0, 1, 0)
+    information         = Vector(0, 0, 0, 0, 0, 0, 0, 1)
     # ------------------------------------------------
 
-    acceleration = Vector(-2, 1, 0, 0, 0, 0, 0)
-    angular_momentum = Vector(-1, 2, 1, 0, 0, 0, 0)
-    area = Vector(0, 2, 0, 0, 0, 0, 0)
-    capacitance = Vector(4, -2, -1, 2, 0, 0, 0)
-    charge = Vector(1, 0, 0, 1, 0, 0, 0)
-    conductance = Vector(3, -2, -1, 2, 0, 0, 0)
-    conductivity = Vector(3, -3, -1, 2, 0, 0, 0)
-    density = Vector(0, -3, 1, 0, 0, 0, 0)
-    electric_field_strength = Vector(-3, 1, 1, -1, 0, 0, 0)
-    energy = Vector(-2, 2, 1, 0, 0, 0, 0)
-    entropy = Vector(-2, 2, 1, 0, -1, 0, 0)
-    force = Vector(-2, 1, 1, 0, 0, 0, 0)
-    frequency = Vector(-1, 0, 0, 0, 0, 0, 0)
-    gravitation = Vector(-2, 3, -1, 0, 0, 0, 0)
-    illuminance = Vector(0, -2, 0, 0, 0, 1, 0)
-    inductance = Vector(-2, 2, 1, -2, 0, 0, 0)
-    magnetic_flux = Vector(-2, 2, 1, -1, 0, 0, 0)
-    magnetic_flux_density = Vector(-2, 0, 1, -1, 0, 0, 0)
-    magnetic_permeability = Vector(-2, 1, 1, -2, 0, 0, 0)
-    molar_mass = Vector(0, 0, 1, 0, 0, 0, -1)
-    molar_volume = Vector(0, 3, 0, 0, 0, 0, -1)
-    momentum = Vector(-1, 1, 1, 0, 0, 0, 0)
-    permittivity = Vector(4, -3, -1, 2, 0, 0, 0)
-    power = Vector(-3, 2, 1, 0, 0, 0, 0)
-    pressure = Vector(-2, -1, 1, 0, 0, 0, 0)
-    resistance = Vector(-3, 2, 1, -2, 0, 0, 0)
-    resistivity = Vector(-3, 3, 1, -2, 0, 0, 0)
-    specific_heat_capacity = Vector(-2, 2, 0, 0, -1, 0, 0)
-    thermal_conductivity = Vector(-3, 1, 1, 0, -1, 0, 0)
-    velocity = Vector(-1, 1, 0, 0, 0, 0, 0)
-    voltage = Vector(-3, 2, 1, -1, 0, 0, 0)
-    volume = Vector(0, 3, 0, 0, 0, 0, 0)
+    acceleration = Vector(-2, 1, 0, 0, 0, 0, 0, 0)
+    angular_momentum = Vector(-1, 2, 1, 0, 0, 0, 0, 0)
+    area = Vector(0, 2, 0, 0, 0, 0, 0, 0)
+    capacitance = Vector(4, -2, -1, 2, 0, 0, 0, 0)
+    charge = Vector(1, 0, 0, 1, 0, 0, 0, 0)
+    conductance = Vector(3, -2, -1, 2, 0, 0, 0, 0)
+    conductivity = Vector(3, -3, -1, 2, 0, 0, 0, 0)
+    density = Vector(0, -3, 1, 0, 0, 0, 0, 0)
+    electric_field_strength = Vector(-3, 1, 1, -1, 0, 0, 0, 0)
+    energy = Vector(-2, 2, 1, 0, 0, 0, 0, 0)
+    entropy = Vector(-2, 2, 1, 0, -1, 0, 0, 0)
+    force = Vector(-2, 1, 1, 0, 0, 0, 0, 0)
+    frequency = Vector(-1, 0, 0, 0, 0, 0, 0, 0)
+    gravitation = Vector(-2, 3, -1, 0, 0, 0, 0, 0)
+    illuminance = Vector(0, -2, 0, 0, 0, 1, 0, 0)
+    inductance = Vector(-2, 2, 1, -2, 0, 0, 0, 0)
+    magnetic_flux = Vector(-2, 2, 1, -1, 0, 0, 0, 0)
+    magnetic_flux_density = Vector(-2, 0, 1, -1, 0, 0, 0, 0)
+    magnetic_permeability = Vector(-2, 1, 1, -2, 0, 0, 0, 0)
+    molar_mass = Vector(0, 0, 1, 0, 0, 0, -1, 0)
+    molar_volume = Vector(0, 3, 0, 0, 0, 0, -1, 0)
+    momentum = Vector(-1, 1, 1, 0, 0, 0, 0, 0)
+    permittivity = Vector(4, -3, -1, 2, 0, 0, 0, 0)
+    power = Vector(-3, 2, 1, 0, 0, 0, 0, 0)
+    pressure = Vector(-2, -1, 1, 0, 0, 0, 0, 0)
+    resistance = Vector(-3, 2, 1, -2, 0, 0, 0, 0)
+    resistivity = Vector(-3, 3, 1, -2, 0, 0, 0, 0)
+    specific_heat_capacity = Vector(-2, 2, 0, 0, -1, 0, 0, 0)
+    thermal_conductivity = Vector(-3, 1, 1, 0, -1, 0, 0, 0)
+    velocity = Vector(-1, 1, 0, 0, 0, 0, 0, 0)
+    voltage = Vector(-3, 2, 1, -1, 0, 0, 0, 0)
+    volume = Vector(0, 3, 0, 0, 0, 0, 0, 0)
 
     @classmethod
     def _resolve(cls, vector: 'Vector') -> 'Dimension':
@@ -240,8 +241,7 @@ class Scale(Enum):
 
     def __mul__(self, other):
         # --- Case 1: applying Scale to simple Unit --------------------
-        if isinstance(other, Unit) and not isinstance(other, UnitProduct):
-            # Unit no longer has scale attribute - always safe to apply
+        if isinstance(other, Unit):
             return UnitProduct({UnitFactor(unit=other, scale=self): 1})
 
         # --- Case 2: other cases are NOT handled here -----------------
@@ -291,6 +291,7 @@ class Scale(Enum):
         return Scale.nearest(float(result), include_binary=include_binary)
 
 
+@dataclass(frozen=True)
 class Unit:
     """
     Represents a **unit of measure** associated with a :class:`Dimension`.
@@ -300,26 +301,21 @@ class Unit:
 
     Parameters
     ----------
-    *aliases : str
-        Optional shorthand symbols (e.g., "m", "sec").
     name : str
         Canonical name of the unit (e.g., "meter").
     dimension : Dimension
         The physical dimension this unit represents.
+    aliases : tuple[str, ...]
+        Optional shorthand symbols (e.g., ("m", "M")).
     """
-    def __init__(
-        self,
-        *aliases: str,
-        name: str = "",
-        dimension: Dimension = Dimension.none,
-    ):
-        self.aliases = aliases
-        self.name = name
-        self.dimension = dimension
+    name: str = ""
+    dimension: Dimension = field(default=Dimension.none)
+    aliases: tuple[str, ...] = ()
 
     # ----------------- symbolic helpers -----------------
 
-    def _norm(self, aliases: tuple[str, ...]) -> tuple[str, ...]:
+    @staticmethod
+    def _norm(aliases: tuple[str, ...]) -> tuple[str, ...]:
         """Normalize alias bag: drop empty/whitespace-only aliases."""
         return tuple(a for a in aliases if a.strip())
 
@@ -343,8 +339,6 @@ class Unit:
         Unit * Unit -> UnitProduct
         Unit * UnitProduct -> UnitProduct
         """
-        from ucon.core import UnitProduct  # local import to avoid circulars
-
         if isinstance(other, UnitProduct):
             # let UnitProduct handle merging
             return other.__rmul__(self)
@@ -356,12 +350,13 @@ class Unit:
 
     def __truediv__(self, other):
         """
-        Unit / Unit:
-          - If same unit => dimensionless Unit()
-          - If denominator is dimensionless => self
-          - Else => UnitProduct
+        Unit / Unit or Unit / UnitProduct => UnitProduct
         """
-        from ucon.core import UnitProduct  # local import
+        if isinstance(other, UnitProduct):
+            combined = {self: 1.0}
+            for u, exp in other.factors.items():
+                combined[u] = combined.get(u, 0.0) - exp
+            return UnitProduct(combined)
 
         if not isinstance(other, Unit):
             return NotImplemented
@@ -385,13 +380,13 @@ class Unit:
         """
         Unit ** n => UnitProduct with that exponent.
         """
-        from ucon.core import UnitProduct  # local import
-
         return UnitProduct({self: power})
 
     # ----------------- equality & hashing -----------------
 
     def __eq__(self, other):
+        if isinstance(other, UnitProduct):
+            return other.__eq__(self)
         if not isinstance(other, Unit):
             return NotImplemented
         return (
@@ -421,6 +416,18 @@ class Unit:
             return "<Unit>"
         return f"<Unit | {self.dimension.name}>"
 
+    # ----------------- callable (creates Number) -----------------
+
+    def __call__(self, quantity: Union[int, float]) -> "Number":
+        """Create a Number with this unit.
+
+        Example
+        -------
+        >>> meter(5)
+        <5 m>
+        """
+        return Number(quantity=quantity, unit=UnitProduct.from_unit(self))
+
 
 @dataclass(frozen=True)
 class UnitFactor:
@@ -498,7 +505,7 @@ class UnitFactor:
         return NotImplemented
 
 
-class UnitProduct(Unit):
+class UnitProduct:
     """
     Represents a product or quotient of Units.
 
@@ -527,8 +534,7 @@ class UnitProduct(Unit):
         encountered UnitFactor (keeps user-intent scale).
         """
 
-        # UnitProduct always starts dimensionless
-        super().__init__(name="", dimension=Dimension.none)
+        self.name = ""
         self.aliases = ()
 
         merged: dict[UnitFactor, float] = {}
@@ -706,6 +712,35 @@ class UnitProduct(Unit):
             result *= factor.scale.value.evaluated ** power
         return result
 
+    # ------------- Helpers ---------------------------------------------------
+
+    @classmethod
+    def from_unit(cls, unit: Unit) -> 'UnitProduct':
+        """Wrap a plain Unit as a UnitProduct with Scale.one."""
+        return cls({UnitFactor(unit, Scale.one): 1})
+
+    def factors_by_dimension(self) -> dict[Dimension, tuple[UnitFactor, float]]:
+        """Group factors by dimension.
+
+        Returns a dict mapping each Dimension to (UnitFactor, exponent).
+        Raises ValueError if multiple factors share the same Dimension.
+        """
+        result: dict[Dimension, tuple[UnitFactor, float]] = {}
+        for factor, exp in self.factors.items():
+            dim = factor.unit.dimension
+            if dim in result:
+                raise ValueError(f"Multiple factors for dimension {dim}")
+            result[dim] = (factor, exp)
+        return result
+
+    def _norm(self, aliases: tuple[str, ...]) -> tuple[str, ...]:
+        """Normalize alias bag: drop empty/whitespace-only aliases."""
+        return tuple(a for a in aliases if a.strip())
+
+    def __pow__(self, power):
+        """UnitProduct ** n => new UnitProduct with scaled exponents."""
+        return UnitProduct({u: exp * power for u, exp in self.factors.items()})
+
     # ------------- Algebra ---------------------------------------------------
 
     def __mul__(self, other):
@@ -799,7 +834,7 @@ class UnitProduct(Unit):
         return f"<{self.__class__.__name__} {self.shorthand}>"
 
     def __eq__(self, other):
-        if isinstance(other, Unit) and not isinstance(other, UnitProduct):
+        if isinstance(other, Unit):
             # Only equal to a plain Unit if we have exactly that unit^1
             # Here, the tuple comparison will invoke UnitFactor.__eq__(Unit)
             # on the key when factors are keyed by UnitFactor.
@@ -808,4 +843,289 @@ class UnitProduct(Unit):
 
     def __hash__(self):
         # Sort by name; UnitFactor exposes .name, so this is stable.
-        return hash(tuple(sorted(self.factors.items(), key=lambda x: x[0].name)))
+        return hash(tuple(sorted(self.factors.items(), key=lambda x: x[0].name)))
+
+    def __call__(self, quantity: Union[int, float]) -> "Number":
+        """Create a Number with this unit product.
+
+        Example
+        -------
+        >>> (meter / second)(10)
+        <10 m/s>
+        """
+        return Number(quantity=quantity, unit=self)
+
+
+# --------------------------------------------------------------------------------------
+# Number & Ratio (Value Layer)
+# --------------------------------------------------------------------------------------
+
+# Dimensionless unit for use as default in Number
+_none = Unit()
+
+
+Quantifiable = Union['Number', 'Ratio']
+
+
+@dataclass
+class Number:
+    """
+    Represents a **numeric quantity** with an associated :class:`Unit` and :class:`Scale`.
+
+    Combines magnitude, unit, and scale into a single, composable object that
+    supports dimensional arithmetic and conversion:
+
+        >>> from ucon.units import meter, second
+        >>> length = meter(5)
+        >>> time = second(2)
+        >>> speed = length / time
+        >>> speed
+        <2.5 m/s>
+    """
+    quantity: Union[float, int] = 1.0
+    unit: Union[Unit, UnitProduct] = None
+
+    def __post_init__(self):
+        if self.unit is None:
+            object.__setattr__(self, 'unit', _none)
+
+    @property
+    def value(self) -> float:
+        """Return the numeric magnitude as-expressed (no scale folding).
+
+        Scale lives in the unit expression (e.g. kJ, mL) and is NOT
+        folded into the returned value.  Use ``unit.fold_scale()`` on a
+        UnitProduct when you need the base-unit-equivalent magnitude.
+        """
+        return round(self.quantity, 15)
+
+    @property
+    def _canonical_magnitude(self) -> float:
+        """Quantity folded to base-unit scale (internal use for eq/div)."""
+        if isinstance(self.unit, UnitProduct):
+            return self.quantity * self.unit.fold_scale()
+        return self.quantity
+
+    def simplify(self) -> 'Number':
+        """Return a new Number expressed in base scale (Scale.one).
+
+        This normalizes the unit expression by removing all scale prefixes
+        and adjusting the quantity accordingly. No conversion graph is needed
+        since this is purely a scale transformation.
+
+        Examples
+        --------
+        >>> from ucon import Scale, units
+        >>> km = Scale.kilo * units.meter
+        >>> km(5).simplify()
+        <5000 m>
+        >>> mg = Scale.milli * units.gram
+        >>> mg(500).simplify()
+        <0.5 g>
+        """
+        if not isinstance(self.unit, UnitProduct):
+            # Plain Unit already has no scale
+            return Number(quantity=self.quantity, unit=self.unit)
+
+        # Compute the combined scale factor
+        scale_factor = self.unit.fold_scale()
+
+        # Create new unit with all factors at Scale.one
+        base_factors: dict[UnitFactor, float] = {}
+        for factor, exp in self.unit.factors.items():
+            base_factor = UnitFactor(unit=factor.unit, scale=Scale.one)
+            base_factors[base_factor] = exp
+
+        base_unit = UnitProduct(base_factors)
+
+        # Adjust quantity by the scale factor
+        return Number(quantity=self.quantity * scale_factor, unit=base_unit)
+
+    def to(self, target, graph=None):
+        """Convert this Number to a different unit expression.
+
+        Parameters
+        ----------
+        target : Unit or UnitProduct
+            The target unit to convert to.
+        graph : ConversionGraph, optional
+            The conversion graph to use. If not provided, uses the default graph.
+
+        Returns
+        -------
+        Number
+            A new Number with the converted quantity and target unit.
+
+        Examples
+        --------
+        >>> from ucon.units import meter, foot
+        >>> length = meter(100)
+        >>> length.to(foot)
+        <328.084 ft>
+        """
+        from ucon.graph import get_default_graph
+
+        # Wrap plain Units as UnitProducts for uniform handling
+        src = self.unit if isinstance(self.unit, UnitProduct) else UnitProduct.from_unit(self.unit)
+        dst = target if isinstance(target, UnitProduct) else UnitProduct.from_unit(target)
+
+        # 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)
+
+        # Graph-based conversion (use default graph if none provided)
+        if graph is None:
+            graph = get_default_graph()
+
+        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)
+
+    def _is_scale_only_conversion(self, src: UnitProduct, dst: UnitProduct) -> bool:
+        """Check if conversion is just a scale change (same base units)."""
+        if len(src.factors) != len(dst.factors):
+            return False
+
+        src_by_dim = {}
+        dst_by_dim = {}
+        for f, exp in src.factors.items():
+            src_by_dim[f.unit.dimension] = (f.unit, exp)
+        for f, exp in dst.factors.items():
+            dst_by_dim[f.unit.dimension] = (f.unit, exp)
+
+        if src_by_dim.keys() != dst_by_dim.keys():
+            return False
+
+        for dim in src_by_dim:
+            src_unit, src_exp = src_by_dim[dim]
+            dst_unit, dst_exp = dst_by_dim[dim]
+            if src_unit != dst_unit or abs(src_exp - dst_exp) > 1e-12:
+                return False
+
+        return True
+
+    def as_ratio(self):
+        return Ratio(self)
+
+    def __mul__(self, other: Quantifiable) -> 'Number':
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
+        if not isinstance(other, Number):
+            return NotImplemented
+
+        return Number(
+            quantity=self.quantity * other.quantity,
+            unit=self.unit * other.unit,
+        )
+
+    def __truediv__(self, other: Quantifiable) -> "Number":
+        # Allow dividing by a Ratio (interpret as its evaluated Number)
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
+        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
+
+        # --- 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)
+
+        # --- 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)
+
+    def __eq__(self, other: Quantifiable) -> bool:
+        if not isinstance(other, (Number, Ratio)):
+            raise TypeError(
+                f"Cannot compare Number to non-Number/Ratio type: {type(other)}"
+            )
+
+        # If comparing with a Ratio, evaluate it to a Number
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
+        # Dimensions must match
+        if self.unit.dimension != other.unit.dimension:
+            return False
+
+        # Compare magnitudes, scale-adjusted
+        if abs(self._canonical_magnitude - other._canonical_magnitude) >= 1e-12:
+            return False
+
+        return True
+
+    def __repr__(self):
+        if not self.unit.dimension:
+            return f"<{self.quantity}>"
+        return f"<{self.quantity} {self.unit.shorthand}>"
+
+
+class Ratio:
+    """
+    Represents a **ratio of two Numbers**, preserving their unit semantics.
+
+    Useful for expressing physical relationships like efficiency, density,
+    or dimensionless comparisons:
+
+        >>> ratio = Ratio(length, time)
+        >>> ratio.evaluate()
+        <2.5 m/s>
+    """
+    def __init__(self, numerator: Number = None, denominator: Number = None):
+        self.numerator = numerator if numerator is not None else Number()
+        self.denominator = denominator if denominator is not None else Number()
+
+    def reciprocal(self) -> 'Ratio':
+        return Ratio(numerator=self.denominator, denominator=self.numerator)
+
+    def evaluate(self) -> "Number":
+        # Pure arithmetic, no scale normalization.
+        numeric = self.numerator.quantity / self.denominator.quantity
+
+        # Pure unit division, with UnitFactor preservation.
+        unit = self.numerator.unit / self.denominator.unit
+
+        # DO NOT normalize, DO NOT fold scale.
+        return Number(quantity=numeric, unit=unit)
+
+    def __mul__(self, another_ratio: 'Ratio') -> 'Ratio':
+        if self.numerator.unit == another_ratio.denominator.unit:
+            factor = self.numerator / another_ratio.denominator
+            numerator, denominator = factor * another_ratio.numerator, self.denominator
+        elif self.denominator.unit == another_ratio.numerator.unit:
+            factor = another_ratio.numerator / self.denominator
+            numerator, denominator = factor * self.numerator, another_ratio.denominator
+        else:
+            factor = Number()
+            another_number = another_ratio.evaluate()
+            numerator, denominator = self.numerator * another_number, self.denominator
+        return Ratio(numerator=numerator, denominator=denominator)
+
+    def __truediv__(self, another_ratio: 'Ratio') -> 'Ratio':
+        return Ratio(
+            numerator=self.numerator * another_ratio.denominator,
+            denominator=self.denominator * another_ratio.numerator,
+        )
+
+    def __eq__(self, another_ratio: 'Ratio') -> bool:
+        if isinstance(another_ratio, Ratio):
+            return self.evaluate() == another_ratio.evaluate()
+        elif isinstance(another_ratio, Number):
+            return self.evaluate() == another_ratio
+        else:
+            raise ValueError(f'"{another_ratio}" is not a Ratio or Number. Comparison not possible.')
+
+    def __repr__(self):
+        return f'{self.evaluate()}' if self.numerator == self.denominator else f'{self.numerator} / {self.denominator}'