unitx 0.1.2__tar.gz → 0.3.0__tar.gz

{unitx-0.1.2 → unitx-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.1.2
+Version: 0.3.0
 Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
 Project-URL: Homepage, https://github.com/DaitTHU/unitx
 Project-URL: Issues, https://github.com/DaitTHU/unitx/issues

{unitx-0.1.2 → unitx-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unitx"
-version = "0.1.2"
+version = "0.3.0"
 description = "A modern, intuitive Python library for units, quantities, and dimensional analysis."
 readme = "README.md"
 requires-python = ">=3.11"

unitx-0.3.0/src/unitx/__init__.py

@@ -0,0 +1,7 @@
+"""Utilities for working with physical units and quantities."""
+
+__all__ = ['Dimension', 'DIMENSIONLESS', 'Unit', 'Quantity']
+
+from .dimension import Dimension, DIMENSIONLESS
+from .unit import Unit
+from .quantity import Quantity

unitx-0.3.0/src/unitx/_data/prefix.py

@@ -0,0 +1,65 @@
+from ..factor import Factor, ONE, TEN
+
+
+class PrefixData:
+    '''
+    Attributes:
+        factor (Factor): 1000 for kilo-
+        names (tuple[str, ...]): kilo
+    '''
+
+    __slots__ = ('factor', 'names')
+
+    def __init__(self, facotr: Factor, *names: str) -> None:
+        self.factor = facotr
+        self.names = names
+
+    @property
+    def name(self) -> str: return self.names[0]
+
+
+__PREFIX_LIB: dict[str | tuple[str, ...], PrefixData] = {
+    # whole unit
+    'Q': PrefixData(TEN ** 30, 'quetta'),
+    'R': PrefixData(TEN ** 27, 'ronna'),
+    'Y': PrefixData(TEN ** 24, 'yotta'),
+    'Z': PrefixData(TEN ** 21, 'zetta'),
+    'E': PrefixData(TEN ** 18, 'exa'),
+    'P': PrefixData(TEN ** 15, 'peta'),
+    'T': PrefixData(TEN ** 12, 'tera'),
+    'G': PrefixData(TEN ** 9, 'giga'),
+    'M': PrefixData(TEN ** 6, 'mega'),
+    ('k', 'K'): PrefixData(TEN ** 3, 'kilo'),
+    'h': PrefixData(TEN ** 2, 'hecto'),
+    'da': PrefixData(TEN ** 1, 'deca'),
+    '': PrefixData(ONE, ''),
+    # sub-unit
+    'd': PrefixData(TEN ** -1, 'deci'),
+    'c': PrefixData(TEN ** -2, 'centi'),
+    'm': PrefixData(TEN ** -3, 'milli'),
+    ('µ', 'μ', 'u'): PrefixData(TEN ** -6, 'micro'),  # chr(0xB5), chr(0x03BC)
+    'n': PrefixData(TEN ** -9, 'nano'),
+    'p': PrefixData(TEN ** -12, 'pico'),
+    'f': PrefixData(TEN ** -15, 'femto'),
+    'a': PrefixData(TEN ** -18, 'atto'),
+    'z': PrefixData(TEN ** -21, 'zepto'),
+    'y': PrefixData(TEN ** -24, 'yocto'),
+    'r': PrefixData(TEN ** -27, 'ronto'),
+    'q': PrefixData(TEN ** -30, 'quecto'),
+}
+
+PREFIX: dict[str, PrefixData] = {
+    prefix[0] if isinstance(prefix, tuple) else prefix: data
+    for prefix, data in __PREFIX_LIB.items()
+}
+'''prefix {symbol: data}'''
+
+PREFIX_NAME: dict[str, str] = {
+    name: prefix for prefix, data in PREFIX.items() for name in data.names if name
+}
+'''prefix {name: symbol}'''
+
+PREFIX_ALIAS: dict[str, str] = {
+    alias: prefix[0] for prefix in __PREFIX_LIB if isinstance(prefix, tuple) for alias in prefix[1:]
+}
+'''prefix {alias: symbol}'''

unitx-0.3.0/src/unitx/_data/unit.py

@@ -0,0 +1,44 @@
+from ..dimension import Dimension
+from ..factor import Factor, ONE, TEN
+
+
+class UnitData:
+    '''
+    Attributes:
+        factor (Factor): 1/1000 for gram
+        names (tuple[str, ...]): liter or litre
+        dimension (Dimension): L³ for liter
+        prefixable (bool): whether the unit can be prefixed
+    '''
+
+    __slots__ = ('factor', 'names', 'dimension', 'prefixable')
+
+    def __init__(self, factor: Factor, *names: str, dimension: Dimension, prefixable=True) -> None:
+        self.factor = factor
+        self.names = names
+        self.dimension = dimension
+        self.prefixable = prefixable
+
+    @property
+    def name(self) -> str: return self.names[0]
+
+
+UNIT: dict[str, UnitData] = {
+    '': UnitData(ONE, '', dimension=Dimension(), prefixable=False),
+    's': UnitData(ONE, 'second', dimension=Dimension(T=1)),
+    'm': UnitData(ONE, 'meter', 'metre', dimension=Dimension(L=1)),
+    'g': UnitData(TEN ** -3, 'gram', dimension=Dimension(M=1)),
+    'A': UnitData(ONE, 'ampere', dimension=Dimension(I=1)),
+    'K': UnitData(ONE, 'kelvin', dimension=Dimension(Theta=1)),
+    'mol': UnitData(ONE, 'mole', dimension=Dimension(N=1)),
+    'cd': UnitData(ONE, 'candela', dimension=Dimension(J=1)),
+}
+'''unit {symbol: data}'''
+
+UNIT_NAME: dict[str, str] = {
+    name: unit for unit, data in UNIT.items() for name in data.names if name
+}
+'''unit {name: symbol}'''
+
+UNIT_ALIAS: dict[str, str] = {}
+'''unit {alias: symbol}'''

unitx-0.3.0/src/unitx/dimension.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from fractions import Fraction
+from typing import Iterable, Literal
+
+from .utils.number import common_fraction, ZERO
+from .utils.special_char import superscript
+
+__all__ = ['Dimension', 'DIMENSIONLESS']
+
+_SYMBOL = ('T', 'L', 'M', 'I', 'Θ', 'N', 'J')
+_SYMBOL_ASCII = ('T', 'L', 'M', 'I', 'Theta', 'N', 'J')
+_LEN = len(_SYMBOL)
+_ALLZERO = (ZERO,) * _LEN
+
+
+class Dimension:
+    '''
+    Implementation of physical dimensions.
+    - `T`: time
+    - `L`: length
+    - `M`: mass
+    - `I`: current
+    - `Θ`: temperature (use ASCII alias `Theta` for code)
+    - `N`: amount
+    - `J`: luminous
+
+    Construct
+    ---
+    >>> dim_velocity = Dimension(L=1, T=-1)
+    >>> dim_force = Dimension(M=1, L=1, T=-2)
+
+    Attributes
+    ---
+    You can access the exponents of each dimension by symbols or full names.
+    >>> dim_force.T
+    -2
+    >>> dim_force.mass
+    1
+
+    Operations
+    ---
+    You can perform multiplication, division, and exponentiation on dimensions.
+    >>> dim_force * dim_velocity
+    Dimension(T=-3, L=2, M=1)
+    >>> dim_velocity / Dimension(T=1)
+    Dimension(T=-2, L=1)
+    >>> dim_force ** 2
+    Dimension(T=-4, L=2, M=2)
+    >>> 1 / dim_force
+    Dimension(T=2, L=-1, M=-1)
+    '''
+
+    __slots__ = ('_exponents',)
+    _exponents: tuple[Fraction, ...]  # Exponents for T, L, M, I, Θ, N, J
+
+    def __new__(cls, T=0, L=0, M=0, I=0, Theta=0, N=0, J=0) -> Dimension:
+        exponents = tuple(map(common_fraction, (T, L, M, I, Theta, N, J)))
+        if not any(exponents):
+            return DIMENSIONLESS
+        obj = object.__new__(cls)
+        object.__setattr__(obj, '_exponents', exponents)
+        return obj
+
+    def __setattr__(self, name: str, value) -> None:
+        raise AttributeError('Dimension is immutable and cannot set attribute.')
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError('Dimension is immutable and cannot delete attribute.')
+
+    @classmethod
+    def _from_iter(cls, iterable: Iterable[Fraction], /) -> Dimension:
+        '''Constructor from an iterable of exponents. Internal use only.'''
+        exponents = tuple(iterable)
+        assert len(exponents) == _LEN, f'Expected {_LEN} exponents, got {len(exponents)}.'
+        assert all(isinstance(v, Fraction) for v in exponents), 'All exponents must be of type Fraction.'
+        if not any(exponents):
+            return DIMENSIONLESS
+        obj = object.__new__(cls)
+        object.__setattr__(obj, '_exponents', exponents)
+        return obj
+
+    def __mul__(self, other: Dimension) -> Dimension:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        return self._from_iter(a + b for a, b in zip(self._exponents, other._exponents))
+
+    def __truediv__(self, other: Dimension) -> Dimension:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        return self._from_iter(a - b for a, b in zip(self._exponents, other._exponents))
+
+    def __pow__(self, power: int | Fraction | float) -> Dimension:
+        power = common_fraction(power, stacklevel=2)
+        if not isinstance(power, (int, Fraction)):
+            return NotImplemented
+        return self._from_iter(a * power for a in self._exponents)
+
+    def __rtruediv__(self, other: Literal[1]) -> Dimension:
+        if other == 1:
+            return self._from_iter(-a for a in self._exponents)
+        return NotImplemented
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        return self._exponents == other._exponents
+
+    def __hash__(self) -> int: return hash(self._exponents)
+
+    def as_tuple(self) -> tuple[Fraction, ...]: return self._exponents
+
+    @staticmethod
+    def __unpack_exponents():
+        def __getter(index: int):
+            return lambda self: self._exponents[index]
+        return (property(__getter(i)) for i in range(_LEN))
+
+    T, L, M, I, Θ, N, J = __unpack_exponents()
+    Theta = Θ  # Alias for Θ
+    time, length, mass, current, temperature, amount, luminous = T, L, M, I, Θ, N, J
+
+    def __repr__(self) -> str:
+        para = ', '.join(f'{s}={v}' for s, v in zip(_SYMBOL_ASCII, self._exponents) if v)
+        return '{}({})'.format(self.__class__.__name__, para)
+
+    def __str__(self) -> str:
+        return ''.join(s + superscript(v) for s, v in zip(_SYMBOL, self._exponents) if v) or '1'
+
+
+DIMENSIONLESS = object.__new__(Dimension)
+object.__setattr__(DIMENSIONLESS, '_exponents', _ALLZERO)

unitx-0.3.0/src/unitx/exceptions.py

@@ -0,0 +1,30 @@
+class UnitxError(Exception):
+    '''Base class for all exceptions raised by unitx.'''
+
+
+class UnitSyntaxError(UnitxError, ValueError):
+    '''Exception raised when a unit expression has invalid syntax.'''
+
+
+class UnitSymbolError(UnitxError, ValueError):
+    '''Exception raised when a unit symbol is invalid.'''
+
+
+class DimensionError(UnitxError, ValueError):
+    '''Exception raised when quantities with incompatible dimensions are combined.'''
+
+
+class UnitxWarning(UserWarning):
+    '''Base class for all warnings raised by unitx.'''
+
+
+class InexactFloatWarning(UnitxWarning):
+    '''Warning issued when a float is converted to an approximate Rational.'''
+
+
+class SymbolExistsWarning(UnitxWarning):
+    '''Warning issued when a created symbol already exists.'''
+
+
+class IncompleteFactorWarning(UnitxWarning):
+    '''Warning issued when the factorization of a number is not completed due to time constraints.'''

unitx-0.3.0/src/unitx/factor.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import math
+import operator
+from decimal import Decimal
+from fractions import Fraction
+from typing import Callable, Literal, Self
+
+from .monomial import Monomial
+from .utils.number import common_fraction, factorint, factorfrac, isprime
+
+
+class SymbolicNumber:
+    '''
+    A symbolic representation of a mathematical constant.
+
+    The constant is identified by a specific symbol and value. Its value is not
+    expressible as a product of prime numbers raised to rational exponents.
+    '''
+    __slots__ = ('_symbol', '_value')
+
+    def __new__(cls, symbol: str, value: float) -> SymbolicNumber:
+        if not isinstance(symbol, str):
+            raise TypeError(f'Symbol must be str, got {type(symbol)!r}.')
+        if not isinstance(value, float):
+            raise TypeError(f'Value must be float, got {type(value)!r}.')
+        if not math.isfinite(value) or value <= 0:
+            raise ValueError('SymbolicNumber value must be positive.')
+        if symbol == '':
+            raise ValueError('SymbolicNumber symbol cannot be empty.')
+        obj = super().__new__(cls)
+        obj._symbol, obj._value = symbol, value
+        return obj
+
+    @property
+    def symbol(self) -> str: return self._symbol
+    @property
+    def value(self) -> float: return self._value
+
+    def __repr__(self) -> str:
+        return f'{type(self).__name__}({self._symbol!r}, {self._value!r})'
+
+    def __str__(self) -> str: return self._symbol
+
+    def __float__(self) -> float: return self._value
+
+    def __hash__(self) -> int: return hash((self._symbol, self._value))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, SymbolicNumber):
+            return self._symbol == other._symbol and self._value == other._value
+        if isinstance(other, (int, float)):
+            return self._value == other
+        return NotImplemented
+
+    @staticmethod
+    def _comparison_op(op) -> Callable[[SymbolicNumber, object], bool]:
+        def comparison(self: SymbolicNumber, other: object) -> bool:
+            if isinstance(other, SymbolicNumber):
+                return op(self._value, other._value)
+            if isinstance(other, (int, float)):
+                return op(self._value, other)
+            return NotImplemented
+        return comparison
+
+    __lt__ = _comparison_op(operator.lt)
+    __le__ = _comparison_op(operator.le)
+    __gt__ = _comparison_op(operator.gt)
+    __ge__ = _comparison_op(operator.ge)
+
+    @staticmethod
+    def _arithmetic_op(op) -> Callable[[SymbolicNumber, object], Factor]:
+        def arithmetic(self: SymbolicNumber, other: object) -> Factor:
+            if isinstance(other, (int, float, Fraction, SymbolicNumber)):
+                return op(Factor(self), Factor(other))
+            return NotImplemented
+        return arithmetic
+
+    __mul__ = __rmul__ = _arithmetic_op(operator.mul)
+    __truediv__ = _arithmetic_op(operator.truediv)
+    __rtruediv__ = _arithmetic_op(lambda self, other: other / self)
+
+    def __pow__(self, other: int | float | Fraction) -> Factor:
+        if not isinstance(other, (int, float, Fraction)):
+            return NotImplemented
+        return Factor._from_monomial(Monomial({self: common_fraction(other, stacklevel=2)}))
+
+
+class Factor:
+    '''
+    An exact representation of scaling factors for unit conversions.
+
+    This class uses `Monomial` to represent factor number absolutely precisely.
+    Instead of using floats which suffer from precision drift during repeated 
+    multiplications and roots, `Factor` decomposes numbers into a mapping of
+    prime bases to their rational exponents.
+
+    Algebraic Mapping:
+    - Base Elements: Prime integers (e.g., 2, 3, 5) or `SymbolicNumber`s (e.g., π).
+    - Exponents: `Fraction` representing powers.
+
+    Examples
+    --------
+    >>> Factor(12)
+    Factor.from_dict({2: 2, 3: 1})
+    >>> Factor(2.54)  # 127 / 50
+    Factor.from_dict({127: 1, 2: -1, 5: -2})
+    >>> str(Factor(3) / 10)
+    '3/10'
+    >>> float(Factor(2.54))
+    2.54
+    '''
+    __slots__ = ('_monomial', '_value')
+    _monomial: Monomial[int | SymbolicNumber]
+    _value: float
+    
+    def __init__(self, value: int | float | Fraction | Decimal | SymbolicNumber, /) -> None:
+        try:
+            if value <= 0:
+                raise ValueError('Factor must be positive.')
+        except TypeError:
+            raise TypeError('Factor must be a number.')
+        if isinstance(value, int):
+            self._monomial = Monomial(factorint(value))
+            self._value = float(value)
+            return
+        elif isinstance(value, SymbolicNumber):
+            self._monomial = Monomial({value: 1})
+            self._value = float(value)
+            return
+        elif isinstance(value, (float, Decimal)):
+            value = common_fraction(value, stacklevel=2)
+        if isinstance(value, Fraction):
+            self._monomial = Monomial(factorfrac(value))  # type: ignore
+            self._value = float(value)
+            return
+        raise TypeError(f'Expected int, float, Fraction, Decimal or SymbolicNumber, got {type(value)!r}.')
+
+    @classmethod
+    def _from_monomial(cls, monomial: Monomial[int | SymbolicNumber], /) -> Self:
+        '''Direct constructor from Monomial without copy. Internal use only.'''
+        obj = object.__new__(cls)
+        obj._monomial = monomial
+        return obj
+
+    @classmethod
+    def from_dict(cls, elements: dict[int | SymbolicNumber, int | Fraction], /) -> Self:
+        '''Construct a Factor from a dictionary of base elements to their exponents.'''
+        monomial = Monomial(elements)
+        if not all(isinstance(base, (int, SymbolicNumber)) for base in monomial.bases()):
+            raise TypeError('All bases must be int or SymbolicNumber.')
+        if not all(isinstance(exp, Fraction) for exp in monomial.exponents()):
+            raise TypeError('All exponents must be Fraction.')
+        if not all(exp > 0 for base, exp in monomial.components() if isinstance(base, int)):
+            raise ValueError('All integer bases must have positive exponents.')
+        if not all(isprime(base) for base in monomial.bases() if isinstance(base, int)):
+            raise ValueError('All integer bases must be prime numbers.')
+        return cls._from_monomial(monomial)
+
+    def decompose(self, *, extract_integer=True, rationalization_denominator=False) -> tuple[Fraction, Factor]:
+        '''
+        Decompose the factor into a rational part and an irrational part.
+        
+        Parameters
+        ----------
+        extract_integer : bool, optional
+            If True, extract integer part from the fraction exponents of integer bases.
+            This is the difference between 2^(3/2) and 2 * 2^(1/2).
+        rationalization_denominator : bool, optional
+            If True, exponents of integer bases in the irrational part are all
+            positive to rationalize the denominator. This is the difference
+            between 2^(-3/2) and 2^(1/2) / 4.
+
+        Returns
+        -------
+        tuple[Fraction, Factor]
+            A tuple containing the rational part and the irrational part.
+        '''
+        rational = Fraction(1)
+        irrational = {}
+        for base, exponent in self._monomial.components():
+            if isinstance(base, SymbolicNumber):
+                irrational[base] = exponent
+                continue
+            if exponent.denominator == 1:
+                rational *= Fraction(base) ** exponent.numerator
+                continue
+            if extract_integer or (rationalization_denominator and exponent > 0):
+                integer_exponent = math.floor(exponent) \
+                    if rationalization_denominator else int(exponent)
+                rational *= Fraction(base) ** integer_exponent
+                irrational[base] = exponent - integer_exponent
+            else:
+                irrational[base] = exponent
+        return rational, Factor._from_monomial(Monomial._from_dict(irrational))
+
+    @property
+    def value(self) -> float:
+        if hasattr(self, '_value_cache'):
+            return self._value
+        rational, irrational = self.decompose()
+        if not irrational._monomial:
+            return float(rational)
+        float_factors = [float(base) ** float(exponent) for base, exponent in irrational._monomial.components()]
+        float_factors.append(float(rational))
+        float_factors.sort()
+        # balance multiplication to minimize floating-point error
+        self._value = 1.0
+        lo, hi = 0, len(float_factors) - 1
+        while lo <= hi:
+            if self._value > 1.0:
+                self._value *= float_factors[hi]
+                hi -= 1
+            else:
+                self._value *= float_factors[lo]
+                lo += 1
+        return self._value
+
+    def __float__(self) -> float: return self.value
+
+    def format(self, mul: Literal['⋅', '*', ' * ', ' '] = '⋅',
+               exp: Literal['sup', '^', '**'] = 'sup', frac: bool = True, 
+               order: Literal['insertion', 'ascending', 'descending'] = 'insertion',
+               compact: bool = True) -> str:
+        '''
+        Format the factor as a string.
+        - `mul`, `exp`, `frac`, and `order` are passed to the `Monomial.format()` method.
+        - `compact=True` indicates that the factor is formatted in a compact form,
+            with the rational part extracted as a single fraction rather than as
+            a product of factors with integer exponents.
+        >>> Factor(12).format()
+        '12'
+        >>> Factor(12).format(compact=False)
+        '2²⋅3'
+        '''
+        if not compact:
+            return self._monomial.format(mul=mul, exp=exp, frac=frac, order=order)
+        rational, irrational = self.decompose(rationalization_denominator=True)
+        display_elements = {}
+        if rational.numerator > 1:
+            display_elements[rational.numerator] = Fraction(1)
+        if rational.denominator > 1:
+            display_elements[rational.denominator] = Fraction(-1)
+        display_elements.update(irrational._monomial.components())
+        return Monomial._from_dict(display_elements).format(mul=mul, exp=exp, frac=frac, order=order)
+
+    def __str__(self) -> str: return self.format()
+
+    def __repr__(self) -> str:
+        kv = ', '.join(f'{base!r}: {exponent!r}' for base, exponent in self._monomial.components())
+        return '%s.from_dict({%s})' % (type(self).__name__, kv)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Factor):
+            return self._monomial == other._monomial
+        if isinstance(other, (int, float, Fraction)):
+            return self.value == float(other)
+        return NotImplemented
+
+    def __mul__(self, other: int | float | Fraction | SymbolicNumber | Factor) -> Factor:
+        if isinstance(other, (int, float, Fraction, SymbolicNumber)):
+            other = Factor(other)
+        if not isinstance(other, Factor):
+            return NotImplemented
+        return Factor._from_monomial(self._monomial * other._monomial)
+
+    __rmul__ = __mul__
+
+    def __truediv__(self, other: int | float | Fraction | SymbolicNumber | Factor) -> Factor:
+        if other == 0:
+            raise ZeroDivisionError('Division by zero.')
+        if isinstance(other, (int, float, Fraction, SymbolicNumber)):
+            other = Factor(other)
+        if not isinstance(other, Factor):
+            return NotImplemented
+        return Factor._from_monomial(self._monomial / other._monomial)
+
+    def __rtruediv__(self, other: int | float | Fraction | SymbolicNumber) -> Factor:
+        if isinstance(other, (int, float, Fraction, SymbolicNumber)):
+            return Factor(other) / self
+        return NotImplemented
+
+    def __pow__(self, other: int | float | Fraction) -> Factor:
+        if other == 0:
+            return Factor(1)
+        other = common_fraction(other, stacklevel=2)
+        return Factor._from_monomial(self._monomial ** other)
+
+    def __call__(self, magnitude):
+        '''Mapping `factor(x) = factor * x`'''
+        return self.value * magnitude
+
+
+ONE = Factor(1)
+TWO = Factor(2)
+TEN = Factor(10)
+PI = SymbolicNumber('π', 3.141592653589793)
+'''The ratio of the circumference of a circle to its diameter.'''