ucon 0.3.2rc6__py3-none-any.whl

ucon/core.py

@@ -0,0 +1,353 @@
+"""
+ucon.core
+==========
+
+Implements the **quantitative core** of the *ucon* system — the machinery that
+manages numeric quantities, scaling prefixes, and dimensional relationships.
+
+Classes
+-------
+- :class:`Exponent` — Represents an exponential base/power pair (e.g., 10³).
+- :class:`Scale` — Enumerates SI and binary magnitude prefixes (kilo, milli, etc.).
+- :class:`Number` — Couples a numeric value with a unit and scale.
+- :class:`Ratio` — Represents a ratio between two :class:`Number` objects.
+
+Together, these classes allow full arithmetic, conversion, and introspection
+of physical quantities with explicit dimensional semantics.
+"""
+from enum import Enum
+from functools import lru_cache, reduce, total_ordering
+from math import log2
+from math import log10
+from typing import Dict, Tuple, Union
+
+from ucon import units
+from ucon.unit import Unit
+
+
+# TODO -- consider using a dataclass
+@total_ordering
+class Exponent:
+    """
+    Represents a **base–exponent pair** (e.g., 10³ or 2¹⁰).
+
+    Provides comparison and division semantics used internally to represent
+    magnitude prefixes (e.g., kilo, mega, micro).
+    """
+    bases = {2: log2, 10: log10}
+
+    __slots__ = ("base", "power")
+
+    def __init__(self, base: int, power: Union[int, float]):
+        if base not in self.bases.keys():
+            raise ValueError(f'Only the following bases are supported: {reduce(lambda a,b: f"{a}, {b}", self.bases.keys())}')
+        self.base = base
+        self.power = power
+
+    @property
+    def evaluated(self) -> float:
+        """Return the numeric value of base ** power."""
+        return self.base ** self.power
+
+    def parts(self) -> Tuple[int, Union[int, float]]:
+        """Return (base, power) tuple, used for Scale lookups."""
+        return self.base, self.power
+
+    def __eq__(self, other: 'Exponent'):
+        if not isinstance(other, Exponent):
+            raise TypeError(f'Cannot compare Exponent to non-Exponent type: {type(other)}')
+        return self.evaluated == other.evaluated
+
+    def __lt__(self, other: 'Exponent'):
+        if not isinstance(other, Exponent):
+            return NotImplemented
+        return self.evaluated < other.evaluated
+
+    def __hash__(self):
+        # Hash by rounded numeric equivalence to maintain cross-base consistency
+        return hash(round(self.evaluated, 15))
+
+    # ---------- Arithmetic Semantics ----------
+
+    def __truediv__(self, other: 'Exponent'):
+        """
+        Divide two Exponents.
+        - If bases match, returns a relative Exponent.
+        - If bases differ, returns a numeric ratio (float).
+        """
+        if not isinstance(other, Exponent):
+            return NotImplemented
+        if self.base == other.base:
+            return Exponent(self.base, self.power - other.power)
+        return self.evaluated / other.evaluated
+
+    def __mul__(self, other: 'Exponent'):
+        if not isinstance(other, Exponent):
+            return NotImplemented
+        if self.base == other.base:
+            return Exponent(self.base, self.power + other.power)
+        return float(self.evaluated * other.evaluated)
+
+    # ---------- Conversion Utilities ----------
+
+    def to_base(self, new_base: int) -> "Exponent":
+        """
+        Convert this Exponent to another base representation.
+
+        Example:
+            Exponent(2, 10).to_base(10)
+            # → Exponent(base=10, power=3.010299956639812)
+        """
+        if new_base not in self.bases:
+            supported = ", ".join(map(str, self.bases))
+            raise ValueError(f"Unsupported base {new_base!r}. Supported bases: {supported}")
+        new_power = self.bases[new_base](self.evaluated)
+        return Exponent(new_base, new_power)
+
+    # ---------- Numeric Interop ----------
+
+    def __float__(self) -> float:
+        return float(self.evaluated)
+
+    def __int__(self) -> int:
+        return int(self.evaluated)
+
+    # ---------- Representation ----------
+
+    def __repr__(self) -> str:
+        return f"Exponent(base={self.base}, power={self.power})"
+
+    def __str__(self) -> str:
+        return f"{self.base}^{self.power}"
+
+
+class Scale(Enum):
+    """
+    Enumerates common **magnitude prefixes** for units and quantities.
+
+    Examples include:
+    - Binary prefixes (kibi, mebi)
+    - Decimal prefixes (milli, kilo, mega)
+
+    Each entry stores its numeric scaling factor (e.g., `kilo = 10³`).
+    """
+    gibi  = Exponent(2, 30)
+    mebi  = Exponent(2, 20)
+    kibi  = Exponent(2, 10)
+    giga  = Exponent(10, 9)
+    mega  = Exponent(10, 6)
+    kilo  = Exponent(10, 3)
+    hecto = Exponent(10, 2)
+    deca  = Exponent(10, 1)
+    one   = Exponent(10, 0)
+    deci  = Exponent(10,-1)
+    centi = Exponent(10,-2)
+    milli = Exponent(10,-3)
+    micro = Exponent(10,-6)
+    nano = Exponent(10,-9)
+    _kibi = Exponent(2,-10)   # "kibi" inverse
+    _mebi = Exponent(2,-20)   # "mebi" inverse
+    _gibi = Exponent(2,-30)   # "gibi" inverse
+
+    @staticmethod
+    @lru_cache(maxsize=1)
+    def all() -> Dict[Tuple[int, int], str]:
+        """Return a map from (base, power) → Scale name."""
+        return {(s.value.base, s.value.power): s.name for s in Scale}
+
+    @staticmethod
+    @lru_cache(maxsize=1)
+    def by_value() -> Dict[float, str]:
+        """
+        Return a map from evaluated numeric value → Scale name.
+        Cached after first access.
+        """
+        return {round(s.value.evaluated, 15): s.name for s in Scale}
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def _decimal_scales(cls):
+        """Return decimal (base-10) scales only."""
+        return list(s for s in cls if s.value.base == 10)
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def _binary_scales(cls):
+        """Return binary (base-2) scales only."""
+        return list(s for s in cls if s.value.base == 2)
+
+    @classmethod
+    def nearest(cls, value: float, include_binary: bool = False, undershoot_bias: float = 0.75) -> "Scale":
+        """
+        Return the Scale that best normalizes `value` toward 1 in log-space.
+        Optionally restricts to base-10 prefixes unless `include_binary=True`.
+        """
+        if value == 0:
+            return Scale.one
+
+        abs_val = abs(value)
+        candidates = cls._decimal_scales() if not include_binary else list(cls)
+
+        def distance(scale: "Scale") -> float:
+            ratio = abs_val / scale.value.evaluated
+            diff = log10(ratio)
+            # Bias overshoots slightly more than undershoots
+            if ratio < 1:
+                diff /= undershoot_bias
+            return abs(diff)
+
+        return min(candidates, key=distance)
+
+    def __truediv__(self, other: 'Scale'):
+        """
+        Divide one Scale by another.
+
+        Always returns a `Scale`, representing the resulting order of magnitude.
+        If no exact prefix match exists, returns the nearest known Scale.
+        """
+        if not isinstance(other, Scale):
+            return NotImplemented
+
+        if self == other:
+            return Scale.one
+
+        if other is Scale.one:
+            return self
+
+        should_consider_binary = (self.value.base == 2) or (other.value.base == 2)
+
+        if self is Scale.one:
+            result = Exponent(other.value.base, -other.value.power)
+            name = Scale.all().get((result.base, result.power))
+            if name:
+                return Scale[name]
+            return Scale.nearest(float(result), include_binary=should_consider_binary)
+
+        result: Union[Exponent, float] = self.value / other.value
+        if isinstance(result, Exponent):
+            match = Scale.all().get(result.parts())
+            if match:
+                return Scale[match]
+        else:
+            return Scale.nearest(float(result), include_binary=should_consider_binary)
+
+    def __lt__(self, other: 'Scale'):
+        return self.value < other.value
+
+    def __gt__(self, other: 'Scale'):
+        return self.value > other.value
+
+    def __eq__(self, other: 'Scale'):
+        return self.value == other.value
+
+
+# TODO -- consider using a 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 import core, units
+        >>> length = core.Number(unit=units.meter, quantity=5)
+        >>> time = core.Number(unit=units.second, quantity=2)
+        >>> speed = length / time
+        >>> speed
+        <2.5 (m/s)>
+    """
+    def __init__(self, unit: Unit = units.none, scale: Scale = Scale.one, quantity = 1):
+        self.unit = unit
+        self.scale = scale
+        self.quantity = quantity
+        self.value = round(self.quantity * self.scale.value.evaluated, 15)
+
+    def simplify(self):
+        return Number(unit=self.unit, quantity=self.value)
+
+    def to(self, new_scale: Scale):
+        new_quantity = self.quantity / new_scale.value.evaluated
+        return Number(unit=self.unit, scale=new_scale, quantity=new_quantity)
+
+    def as_ratio(self):
+        return Ratio(self)
+
+    def __mul__(self, another_number: 'Number') -> 'Number':
+        return Number(
+            unit=self.unit * another_number.unit,
+            scale=self.scale,
+            quantity=self.quantity * another_number.quantity,
+        )
+
+    def __truediv__(self, another_number: 'Number') -> 'Number':
+        unit = self.unit / another_number.unit
+        scale = self.scale / another_number.scale
+        quantity = self.quantity / another_number.quantity
+        return Number(unit, scale, quantity)
+
+    def __eq__(self, another_number):
+        if isinstance(another_number, Number):
+            return (self.unit == another_number.unit) and \
+                   (self.quantity == another_number.quantity) and \
+                   (self.value == another_number.value)
+        elif isinstance(another_number, Ratio):
+            return self == another_number.evaluate()
+        else:
+            raise ValueError(f'"{another_number}" is not a Number or Ratio. Comparison not possible.')
+
+    def __repr__(self):
+        return f'<{self.quantity} {"" if self.scale.name == "one" else self.scale.name}{self.unit.name}>'
+
+
+# TODO -- consider using a dataclass
+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 = Number(), denominator: Number = Number()):
+        self.numerator = numerator
+        self.denominator = denominator
+
+    def reciprocal(self) -> 'Ratio':
+        return Ratio(numerator=self.denominator, denominator=self.numerator)
+
+    def evaluate(self) -> Number:
+        return self.numerator / self.denominator
+
+    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):
+        # TODO -- resolve int/float inconsistency
+        return f'{self.evaluate()}' if self.numerator == self.denominator else f'{self.numerator} / {self.denominator}'

ucon/dimension.py

@@ -0,0 +1,172 @@
+"""
+ucon.dimension
+===============
+
+Defines the algebra of **physical dimensions**--the foundation of all unit
+relationships and dimensional analysis in *ucon*.
+
+Each :class:`Dimension` represents a physical quantity (time, mass, length, etc.)
+expressed as a 7-element exponent vector following the SI base system:
+
+    (T, L, M, I, Θ, J, N) :: (s * m * kg * A * K * cd * mol)
+     time, length, mass, current, temperature, luminous intensity, substance
+
+Derived dimensions are expressed as algebraic sums or differences of these base
+vectors (e.g., `velocity = length / time`, `force = mass * acceleration`).
+
+Classes
+-------
+- :class:`Vector` — Represents the exponent vector of a physical quantity.
+- :class:`Dimension` — Enum of known physical quantities, each with a `Vector`
+  value and operator overloads for dimensional algebra.
+"""
+from dataclasses import dataclass
+from enum import Enum
+from functools import partial, reduce
+from operator import __sub__ as subtraction
+from typing import Callable, Iterable, Iterator
+
+
+diff: Callable[[Iterable], int] = partial(reduce, subtraction)
+
+@dataclass
+class Vector:
+    """
+    Represents the **exponent vector** of a physical quantity.
+
+    Each component corresponds to the power of a base dimension in the SI system:
+    time (T), length (L), mass (M), current (I), temperature (Θ),
+    luminous intensity (J), and amount of substance (N).
+
+    Arithmetic operations correspond to dimensional composition:
+    - Addition (`+`) → multiplication of quantities
+    - Subtraction (`-`) → division of quantities
+
+    e.g.
+    Vector(T=1, L=0, M=0, I=0, Θ=0, J=0, N=0)   => "time"
+    Vector(T=0, L=2, M=0, I=0, Θ=0, J=0, N=0)   => "area"
+    Vector(T=-2, L=1, M=1, I=0, Θ=0, J=0, N=0)  => "force"
+    """
+    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
+
+    def __iter__(self) -> Iterator[int]:
+        yield self.T
+        yield self.L
+        yield self.M
+        yield self.I
+        yield self.Θ
+        yield self.J
+        yield self.N
+
+    def __len__(self) -> int:
+        return sum(tuple(1 for x in self))
+
+    def __add__(self, vector: 'Vector') -> 'Vector':
+        """
+        Addition, here, comes from the multiplication of base quantities
+
+        e.g. F = m * a
+        F =
+            (s^-2 * m^1 * kg   * A * K * cd * mol) +
+            (s    * m   * kg^1 * A * K * cd * mol)
+        """
+        values = tuple(sum(pair) for pair in zip(tuple(self), tuple(vector)))
+        return Vector(*values)
+
+    def __sub__(self, vector: 'Vector') -> 'Vector':
+        """
+        Subtraction, here, comes from the division of base quantities
+        """
+        values = tuple(diff(pair) for pair in zip(tuple(self), tuple(vector)))
+        return Vector(*values)
+
+    def __eq__(self, vector: 'Vector') -> bool:
+        assert isinstance(vector, Vector), "Can only compare Vector to another Vector"
+        return tuple(self) == tuple(vector)
+
+    def __hash__(self) -> int:
+        # Hash based on the string because tuples have been shown to collide
+        # Not the most performant, but effective
+        return hash(str(tuple(self)))
+
+
+class Dimension(Enum):
+    """
+    Represents a **physical dimension** defined by a :class:`Vector`.
+
+    Each dimension corresponds to a distinct combination of base exponents.
+    Dimensions are algebraically composable via multiplication and division:
+
+        >>> Dimension.length / Dimension.time
+        <Dimension.velocity: Vector(T=-1, L=1, M=0, I=0, Θ=0, J=0, N=0)>
+
+    This algebra forms the foundation for unit compatibility and conversion.
+    """
+    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)
+    # ------------------------------------------------
+
+    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)
+
+    def __truediv__(self, dimension: 'Dimension') -> 'Dimension':
+        if not isinstance(dimension, Dimension):
+            raise TypeError(f"Cannot divide Dimension by non-Dimension type: {type(dimension)}")
+        return Dimension(self.value - dimension.value)
+
+    def __mul__(self, dimension: 'Dimension') -> 'Dimension':
+        if not isinstance(dimension, Dimension):
+            raise TypeError(f"Cannot multiply Dimension by non-Dimension type: {type(dimension)}")
+        return Dimension(self.value + dimension.value)
+
+    def __eq__(self, dimension) -> bool:
+        if not isinstance(dimension, Dimension):
+            raise TypeError(f"Cannot compare Dimension with non-Dimension type: {type(dimension)}")
+        return self.value == dimension.value
+
+    def __hash__(self) -> int:
+        return hash(self.value)

ucon/unit.py

@@ -0,0 +1,92 @@
+"""
+ucon.unit
+==========
+
+Defines the **Unit** abstraction — the symbolic and algebraic representation of
+a measurable quantity associated with a :class:`ucon.dimension.Dimension`.
+
+A :class:`Unit` pairs a human-readable name and aliases with its underlying
+dimension.
+
+Units are composable:
+
+    >>> from ucon import units
+    >>> units.meter / units.second
+    <velocity | (m/s)>
+
+They can be multiplied or divided to form compound units, and their dimensional
+relationships are preserved algebraically.
+"""
+from ucon.dimension import Dimension
+
+
+class Unit:
+    """
+    Represents a **unit of measure** associated with a :class:`Dimension`.
+
+    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.
+
+    Notes
+    -----
+    Units participate in algebraic operations that produce new compound units:
+
+        >>> density = units.gram / units.liter
+        >>> density.dimension
+        <Dimension.density: Vector(T=0, L=-3, M=1, I=0, Θ=0, J=0, N=0)>
+
+    The combination rules follow the same algebra as :class:`Dimension`.
+    """
+    def __init__(self, *aliases: str, name: str = '', dimension: Dimension = Dimension.none):
+        self.dimension = dimension
+        self.name = name
+        self.aliases = aliases
+        self.shorthand = aliases[0] if aliases else self.name
+
+    def __repr__(self):
+        addendum = f' | {self.name}' if self.name else ''
+        return f'<{self.dimension.name}{addendum}>'
+
+    # TODO -- limit `operator` param choices
+    def generate_name(self, unit: 'Unit', operator: str):
+        if (self.dimension is Dimension.none) and not (unit.dimension is Dimension.none):
+            return unit.name
+        if not (self.dimension is Dimension.none) and (unit.dimension is Dimension.none):
+            return self.name
+
+        if not self.shorthand and not unit.shorthand:
+            name = ''
+        elif self.shorthand and not unit.shorthand:
+            name = f'({self.shorthand}{operator}?)'
+        elif not self.shorthand and unit.shorthand:
+            name = f'(?{operator}{unit.shorthand})'
+        else:
+            name = f'({self.shorthand}{operator}{unit.shorthand})'
+        return name
+
+    def __truediv__(self, unit: 'Unit') -> 'Unit':
+        # TODO -- define __eq__ for simplification, here
+        if (self.name == unit.name) and (self.dimension == unit.dimension):
+            return Unit()
+
+        if (unit.dimension is Dimension.none):
+            return self
+        
+        return Unit(name=self.generate_name(unit, '/'), dimension=self.dimension / unit.dimension)
+
+    def __mul__(self, unit: 'Unit') -> 'Unit':
+        return Unit(name=self.generate_name(unit, '*'), dimension=self.dimension * unit.dimension)
+
+    def __eq__(self, unit: 'Unit') -> bool:
+        if not isinstance(unit, Unit):
+            raise TypeError(f'Cannot compare Unit to non-Unit type: {type(unit)}')
+        return (self.name == unit.name) and (self.dimension == unit.dimension)
+
+    def __hash__(self) -> int:
+        return hash(tuple([self.name, self.dimension,]))