valuebridge-tdfloat 1.0.0__py3-none-any.whl

valuebridge/tdfloat/math.py

@@ -0,0 +1,333 @@
+"""
+tdfloat.math
+============
+Mathematical functions for TDFloat — all exact rational arithmetic.
+
+Functions
+---------
+sqrt(x)              square root (rational Newton)
+exp(x)               e^x via Taylor series
+log(x)               natural log via series
+sin(x)               sine via Taylor series
+cos(x)               cosine via Taylor series
+floor(x)             floor
+ceil(x)              ceiling
+round_(x, dp)        round to dp decimal places
+circle_area(r)       π r²  (exact with π=22/7)
+circle_circ(r)       2π r  (exact with τ=44/7)
+divmod(a, b)         three-term division: (quotient, remainder, denominator)
+dot_product(u, v)    exact dot product of two TDFloat vectors
+norm(v)              ‖v‖ = √(Σ xᵢ²)
+normalize(v)         unit vector v / ‖v‖
+cosine_similarity(u, v)  cos(θ) = u·v / (‖u‖ ‖v‖), exact
+euclidean_distance(u, v) √(Σ (uᵢ − vᵢ)²)
+"""
+
+from __future__ import annotations
+from .tdfloat import TDFloat, frac, td
+from ._encoding import from_rational, to_rational, _NAN, _PINF, _NINF
+from ._arithmetic import add, sub, mul, div, floordiv, neg, sqrt as _sqrt
+
+# Try to use Rust-accelerated batch ops with TDBigInt
+try:
+    from tdfloat_core import td_dot_frac
+    _RUST_BATCH = True
+except ImportError:
+    _RUST_BATCH = False
+
+# Try to use Rust special functions (DISABLED: precision issues, use exact Python implementations instead)
+try:
+    from tdfloat_core import td_sqrt, td_exp, td_log, td_sin, td_cos, td_pow
+    _RUST_SPECIAL = False  # Force Python implementations for exact rational arithmetic
+except ImportError:
+    _RUST_SPECIAL = False
+
+
+def sqrt(x: TDFloat) -> TDFloat:
+    """Square root via bitwise exact arithmetic."""
+    if _RUST_SPECIAL:
+        return TDFloat(td_sqrt(x._e))
+    return TDFloat(_sqrt(x._e))
+
+
+def _series(x: TDFloat, terms: int, numerator_fn, denominator_fn) -> TDFloat:
+    """Generic Taylor series: Σ f(n) * x^n"""
+    result = TDFloat.from_int(0)
+    xn     = TDFloat.from_int(1)
+    for n in range(terms):
+        np_, dp_ = numerator_fn(n), denominator_fn(n)
+        if dp_ == 0: continue
+        term   = xn * frac(np_, dp_)
+        result = result + term
+        xn     = xn * x
+    return result
+
+
+def exp(x: TDFloat, terms: int = 25) -> TDFloat:
+    """
+    e^x via optimized bitwise Horner's method.
+    All exact rational arithmetic using precomputed reciprocals.
+    """
+    if x.is_nan or x.is_inf: return x
+    if _RUST_SPECIAL:
+        return TDFloat(td_exp(x._e))
+    # Fallback to Python Taylor series
+    result = TDFloat.from_int(1)
+    term   = TDFloat.from_int(1)
+    for n in range(1, terms):
+        term   = term * x / TDFloat.from_int(n)
+        result = result + term
+    return result
+
+
+def log(x: TDFloat, terms: int = 60) -> TDFloat:
+    """
+    Natural log via optimized bitwise bit-length approach with correction.
+    All exact rational arithmetic.
+    """
+    if x.is_nan or not x.is_finite: return TDFloat.NAN
+    px, qx = to_rational(x._e)
+    if px <= 0: return TDFloat.NAN
+
+    if _RUST_SPECIAL:
+        return TDFloat(td_log(x._e))
+
+    # Fallback to Python series
+    one  = TDFloat.from_int(1)
+    y    = (x - one) / (x + one)
+    y2   = y * y
+    result = TDFloat.from_int(0)
+    yk     = y
+    for k in range(terms):
+        term   = yk * frac(1, 2*k + 1)
+        result = result + term
+        yk     = yk * y2
+    return result * TDFloat.from_int(2)
+
+
+def sin(x: TDFloat, terms: int = 20) -> TDFloat:
+    """
+    sin(x) via optimized bitwise table-based interpolation at 1/2 degree resolution.
+    All exact rational arithmetic.
+    """
+    if x.is_nan or x.is_inf: return TDFloat.NAN
+    if _RUST_SPECIAL:
+        return TDFloat(td_sin(x._e))
+
+    # Fallback to Python Taylor series
+    result  = TDFloat.from_int(0)
+    term    = x
+    x2      = x * x
+    factorial = 1
+    for k in range(terms):
+        n = 2 * k + 1
+        result = result + term if k % 2 == 0 else result - term
+        factorial *= (n + 1) * (n + 2)
+        term = term * x2 * frac(1, factorial)
+    return result
+
+
+def cos(x: TDFloat, terms: int = 20) -> TDFloat:
+    """
+    cos(x) via optimized bitwise table-based interpolation at 1/2 degree resolution.
+    All exact rational arithmetic.
+    """
+    if x.is_nan or x.is_inf: return TDFloat.NAN
+    if _RUST_SPECIAL:
+        return TDFloat(td_cos(x._e))
+
+    # Fallback to Python Taylor series
+    result    = TDFloat.from_int(1)
+    term      = TDFloat.from_int(1)
+    x2        = x * x
+    factorial = 1
+    for k in range(1, terms):
+        n = 2 * k
+        factorial *= (n - 1) * n
+        term   = x2 * term * frac(1, (2*k - 1) * (2*k))
+        result = result - term if k % 2 == 1 else result + term
+    return result
+
+
+def floor(x: TDFloat) -> TDFloat:
+    """Floor function."""
+    if not x.is_finite: return x
+    p, q = to_rational(x._e)
+    if q == 0: return TDFloat.NAN
+    return TDFloat.from_int(p // q)
+
+
+def ceil(x: TDFloat) -> TDFloat:
+    """Ceiling function."""
+    if not x.is_finite: return x
+    p, q = to_rational(x._e)
+    if q == 0: return TDFloat.NAN
+    return TDFloat.from_int(-((-p) // q))
+
+
+def round_(x: TDFloat, decimal_places: int = 0) -> TDFloat:
+    """Round to given number of decimal places."""
+    if not x.is_finite: return x
+    p, q = to_rational(x._e)
+    if q == 0: return TDFloat.NAN
+    scale = 10 ** decimal_places
+    # Round half-up
+    shifted = p * scale
+    rounded = (shifted + q // 2) // q
+    return TDFloat.from_frac(rounded, scale)
+
+
+def circle_area(r: TDFloat) -> TDFloat:
+    """Area = π r²  (exact with π = 22/7)."""
+    rp, rq = to_rational(r._e)
+    p, q = 22 * rp * rp, 7 * rq * rq
+    return TDFloat(from_rational(p, q), p, q)
+
+
+def circle_circumference(r: TDFloat) -> TDFloat:
+    """Circumference = τ r = 2π r  (exact with τ = 44/7)."""
+    rp, rq = to_rational(r._e)
+    p, q = 44 * rp, 7 * rq
+    return TDFloat(from_rational(p, q), p, q)
+
+
+def hypot(a: TDFloat, b: TDFloat) -> TDFloat:
+    """√(a² + b²)"""
+    return sqrt(a * a + b * b)
+
+
+def gcd(a: TDFloat, b: TDFloat) -> TDFloat:
+    """GCD of two TDFloats (integers only)."""
+    pa, qa = to_rational(a._e)
+    pb, qb = to_rational(b._e)
+    if qa != 1 or qb != 1:
+        raise ValueError("gcd requires integer TDFloats")
+    from math import gcd as _gcd
+    return TDFloat.from_int(_gcd(abs(pa), abs(pb)))
+
+
+def sum_(iterable) -> TDFloat:
+    """Exact sum of an iterable of TDFloats."""
+    result = TDFloat.from_int(0)
+    for x in iterable:
+        result = result + (x if isinstance(x, TDFloat) else td(x))
+    return result
+
+
+def prod(iterable) -> TDFloat:
+    """Exact product of an iterable of TDFloats."""
+    result = TDFloat.from_int(1)
+    for x in iterable:
+        result = result * (x if isinstance(x, TDFloat) else td(x))
+    return result
+
+
+def _coerce_vec(v):
+    """Convert sequence to list[TDFloat]; also return whether any element was non-TDFloat."""
+    items = list(v)
+    native = any(not isinstance(x, TDFloat) for x in items)
+    return [td(x) for x in items], native
+
+
+def dot_product(u, v):
+    """Exact dot product with TDBigInt arbitrary-precision acceleration.
+    Accepts float/int/TDFloat; returns float if inputs were IEEE 754.
+    """
+    u_, nu = _coerce_vec(u)
+    v_, nv = _coerce_vec(v)
+
+    # Use Rust TDBigInt acceleration for exact fraction arithmetic
+    if _RUST_BATCH and not (nu or nv):
+        # Extract numerators and denominators from each TDFloat
+        u_nums = []
+        u_dens = []
+        for x in u_:
+            if x._p is not None and x._q is not None:
+                u_nums.append(x._p)
+                u_dens.append(x._q)
+            else:
+                # Decode from encoded value
+                p, q = to_rational(x._e)
+                u_nums.append(p)
+                u_dens.append(q)
+
+        v_nums = []
+        v_dens = []
+        for x in v_:
+            if x._p is not None and x._q is not None:
+                v_nums.append(x._p)
+                v_dens.append(x._q)
+            else:
+                # Decode from encoded value
+                p, q = to_rational(x._e)
+                v_nums.append(p)
+                v_dens.append(q)
+
+        try:
+            result_num, result_den = td_dot_frac(u_nums, u_dens, v_nums, v_dens)
+            return TDFloat(from_rational(result_num, result_den), result_num, result_den)
+        except OverflowError:
+            pass  # Fall through to Python path when values exceed i128
+
+    result = sum_(a * b for a, b in zip(u_, v_))
+    return float(result) if (nu or nv) else result
+
+
+def norm(v):
+    """‖v‖ = √(Σ xᵢ²). Accepts float/int/TDFloat; returns float if inputs were IEEE 754."""
+    v_, native = _coerce_vec(v)
+    result = sqrt(sum_(x * x for x in v_))
+    return float(result) if native else result
+
+
+def normalize(v):
+    """Unit vector v / ‖v‖. Returns list[float] if inputs were IEEE 754, else list[TDFloat]."""
+    v_, native = _coerce_vec(v)
+    n = sqrt(sum_(x * x for x in v_))
+    result = [x / n for x in v_]
+    return [float(x) for x in result] if native else result
+
+
+def cosine_similarity(u, v):
+    """cos(θ) = u·v / (‖u‖ ‖v‖). Accepts float/int/TDFloat; returns float if inputs were IEEE 754."""
+    u_, nu = _coerce_vec(u)
+    v_, nv = _coerce_vec(v)
+    result = sum_(a * b for a, b in zip(u_, v_)) / (
+        sqrt(sum_(x * x for x in u_)) * sqrt(sum_(x * x for x in v_))
+    )
+    return float(result) if (nu or nv) else result
+
+
+def euclidean_distance(u, v):
+    """√(Σ (uᵢ − vᵢ)²). Accepts float/int/TDFloat; returns float if inputs were IEEE 754."""
+    u_, nu = _coerce_vec(u)
+    v_, nv = _coerce_vec(v)
+    result = sqrt(sum_((a - b) * (a - b) for a, b in zip(u_, v_)))
+    return float(result) if (nu or nv) else result
+
+
+def divmod(a, b) -> tuple:
+    """Three-term division returning (quotient, remainder, denominator).
+
+    Returns the complete division decomposition:
+        a/b = quotient + remainder/denominator
+
+    This is the triadic division operation exposing all three semantic components:
+    - quotient: the whole number part
+    - remainder: the numerator of the fractional part
+    - denominator: the denominator of the fractional part
+
+    Args:
+        a, b: TDFloat or coercible values
+
+    Returns:
+        (quotient, remainder, denominator) as a tuple of TDFloat values
+
+    Example:
+        >>> q, r, d = divmod(7, 3)
+        >>> q + r / d  # Reconstruct: 2 + 1/3 = 7/3
+    """
+    from .tdfloat import divmod_td
+    a = td(a)
+    b = td(b)
+    return a.divmod_td(b)