valuebridge-tdfloat 1.0.0__py3-none-any.whl

valuebridge/tdfloat/tdfloat.py

@@ -0,0 +1,532 @@
+"""
+tdfloat.tdfloat
+===============
+The TDFloat class — a floating-point number as a single Python integer.
+
+Encoding (from encoding_any_symbol.v):
+  position  = 2 * rank + info_bit
+  rank      = abs_digits * 78 + dot_pos
+  info_bit  = 1 if dot_pos > 0  (the "." is present)
+
+The "." is the info_bit:
+  info_bit = 0  →  integer axis   (no dot, exact integer)
+  info_bit = 1  →  half-step axis (has dot, fractional)
+
+Every number is stored as one Python int.
+All arithmetic is exact rational arithmetic on integers.
+No Python float is used anywhere in the core.
+"""
+
+from __future__ import annotations
+from ._encoding import (
+    _NAN, _PINF, _NINF, _SPECIALS,
+    pack, unpack, from_rational, to_rational,
+    from_str, to_str, encode_symbol, decode_rank, decode_info,
+    DOT_POSITIONS, MAX_DOT_POS,
+)
+from ._arithmetic import (
+    add, sub, neg, mul, div, floordiv, mod, divmod_td,
+    eq, lt, abs_val, pow_int, sqrt,
+)
+
+# Try to use Rust-accelerated rational ops for fraction fast path
+# NOTE: Disabled due to bugs in from_rational_bw for non-terminating decimals
+# The Python version in _encoding.py works correctly
+try:
+    from tdfloat_core import td_rational_add, td_rational_sub, td_rational_mul, td_rational_div
+    _RUST_RATIONAL = False  # Force use of Python implementation until Rust is fixed
+except ImportError:
+    _RUST_RATIONAL = False
+
+
+class TDFloat:
+    """
+    Triadic Dot Float — a number on the half-step rational line.
+
+    Encoding
+    --------
+    Every TDFloat is a single Python int.
+
+      encoded = 2 * rank + info_bit          (encode_symbol)
+      rank    = abs_digits * 78 + dot_pos
+      info_bit = 1 if '.' present, 0 if integer
+
+    The "." is the info_bit — its presence moves a number from
+    the integer axis (even position) to the half-step axis (odd position).
+
+    Constructors
+    ------------
+    TDFloat(int)            from raw encoded integer
+    TDFloat.from_int(n)     exact integer
+    TDFloat.from_frac(p,q)  exact rational
+    TDFloat.from_str('3.14') decimal string (no Python float)
+    td(x)                   convenience: int, str, or float
+
+    Arithmetic
+    ----------
+    + - * / // % ** abs neg     all exact rational
+    sqrt()                      rational Newton's method
+    All operations are associative and commutative.
+
+    Constants
+    ---------
+    TDFloat.PI    = 22/7
+    TDFloat.TAU   = 44/7
+    TDFloat.E     = 19/7
+    TDFloat.PHI   = 3/2
+    TDFloat.SQRT2 = 7/5
+    TDFloat.HALF  = 1/2
+    ... (see tdfloat.constants for all)
+
+    Phase / axis
+    ------------
+    .is_integer   True if on the integer axis (info_bit=0)
+    .is_fractional True if on the half-step axis (info_bit=1)
+    .dot_pos       number of decimal places after '.'
+    .info_bit      0 or 1
+    .encoded       the raw integer
+
+    Special values
+    --------------
+    TDFloat.NAN   not-a-number
+    TDFloat.INF   positive infinity
+    TDFloat.NINF  negative infinity
+    """
+
+    __slots__ = ('_e', '_p', '_q')
+
+    def __init__(self, encoded: int, p: int = None, q: int = None):
+        self._e = int(encoded)
+        # Store canonical fraction if provided (avoids decimal round-trip loss)
+        if p is not None and q is not None and q != 0:
+            from math import gcd
+            g = gcd(abs(int(p)), abs(int(q)))
+            self._p = int(p) // g
+            self._q = int(q) // g
+            if self._q < 0: self._p, self._q = -self._p, -self._q
+        else:
+            # Auto-extract fraction from encoded value if not provided
+            # This makes the fraction fast path automatic and transparent
+            p_rat, q_rat = to_rational(self._e)
+            if q_rat != 0 and (p_rat != 0 or q_rat == 1):
+                self._p = p_rat
+                self._q = q_rat
+            else:
+                self._p = None
+                self._q = None
+
+    # ── Constructors ──────────────────────────────────────────────────
+
+    @classmethod
+    def from_int(cls, n: int) -> TDFloat:
+        """Exact integer. Always I-phase (integer axis, info_bit=0)."""
+        return cls(from_rational(n, 1), n, 1)
+
+    @classmethod
+    def from_frac(cls, p: int, q: int) -> TDFloat:
+        """
+        Exact rational p/q.
+        I-phase if q is a power of 2 and divides p*10^k for small k.
+        N-phase (half-step axis) otherwise.
+        """
+        return cls(from_rational(p, q), p, q)
+
+    @classmethod
+    def from_str(cls, s: str) -> TDFloat:
+        """
+        Parse decimal string without using Python float.
+        Supports: '3.14', '-0.5', '1e-3', 'inf', '-inf', 'nan'
+        """
+        return cls(from_str(s))
+
+    @classmethod
+    def from_float(cls, x: float) -> TDFloat:
+        """
+        Lift a Python float by extracting its exact binary fraction.
+        This is the only place a Python float is accepted.
+        """
+        import struct
+        if x != x: return cls(_NAN)
+        if x == float('inf'):  return cls(_PINF)
+        if x == float('-inf'): return cls(_NINF)
+        raw  = struct.pack('>d', x)
+        bits = int.from_bytes(raw, 'big')
+        s    = (bits >> 63) & 1
+        e    = (bits >> 52) & 0x7FF
+        m    = bits & ((1 << 52) - 1)
+        if e == 0:   sig, exp = m, 1 - 1023 - 52
+        else:        sig, exp = (1 << 52) | m, e - 1023 - 52
+        if sig == 0: return cls(from_rational(0, 1))
+        # value = sig * 2^exp = sig / 2^(-exp)  if exp < 0
+        if exp >= 0:
+            p, q = sig * (2 ** exp), 1
+        else:
+            p, q = sig, 2 ** (-exp)
+        pp = -p if s else p
+        return cls(from_rational(pp, q), pp, q)
+
+    # ── Arithmetic ────────────────────────────────────────────────────
+
+    def __add__(self, o) -> TDFloat:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        # Use exact fractions if both available
+        if self._p is not None and o._p is not None:
+            if _RUST_RATIONAL:
+                enc, p, q = td_rational_add(self._p, self._q, o._p, o._q)
+                return TDFloat(enc, p, q)
+            from ._arithmetic import _simplify
+            p, q = _simplify(self._p * o._q + o._p * self._q, self._q * o._q)
+            return TDFloat(from_rational(p, q), p, q)
+        return TDFloat(add(self._e, o._e))
+
+    def __radd__(self, o) -> TDFloat:
+        return _coerce(o) + self
+
+    def __sub__(self, o) -> TDFloat:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        if self._p is not None and o._p is not None:
+            if _RUST_RATIONAL:
+                enc, p, q = td_rational_sub(self._p, self._q, o._p, o._q)
+                return TDFloat(enc, p, q)
+            from ._arithmetic import _simplify
+            p, q = _simplify(self._p * o._q - o._p * self._q, self._q * o._q)
+            return TDFloat(from_rational(p, q), p, q)
+        return TDFloat(sub(self._e, o._e))
+
+    def __rsub__(self, o) -> TDFloat:
+        return _coerce(o) - self
+
+    def __mul__(self, o) -> TDFloat:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        if self._p is not None and o._p is not None:
+            if _RUST_RATIONAL:
+                enc, p, q = td_rational_mul(self._p, self._q, o._p, o._q)
+                return TDFloat(enc, p, q)
+            from ._arithmetic import _simplify
+            p, q = _simplify(self._p * o._p, self._q * o._q)
+            return TDFloat(from_rational(p, q), p, q)
+        return TDFloat(mul(self._e, o._e))
+
+    def __rmul__(self, o) -> TDFloat:
+        return _coerce(o) * self
+
+    def __truediv__(self, o) -> TDFloat:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        if self._p is not None and o._p is not None:
+            if o._p == 0:
+                return TDFloat(_NAN) if self._p == 0 else (TDFloat(_NINF) if self._p < 0 else TDFloat(_PINF))
+            if _RUST_RATIONAL:
+                enc, p, q = td_rational_div(self._p, self._q, o._p, o._q)
+                return TDFloat(enc, p, q)
+            from ._arithmetic import _simplify
+            p, q = _simplify(self._p * o._q, self._q * o._p)
+            return TDFloat(from_rational(p, q), p, q)
+        return TDFloat(div(self._e, o._e))
+
+    def __rtruediv__(self, o) -> TDFloat:
+        return _coerce(o) / self
+
+    def __floordiv__(self, o) -> TDFloat:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        return TDFloat(floordiv(self._e, o._e))
+
+    def __mod__(self, o) -> TDFloat:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        return TDFloat(mod(self._e, o._e))
+
+    def divmod_td(self, o) -> tuple:
+        """Three-term division: returns (quotient, remainder, denominator).
+
+        Returns the complete quotient-remainder decomposition:
+            self/o = quotient + remainder/denominator
+
+        Args:
+            o: TDFloat divisor
+
+        Returns:
+            (quotient, remainder, denominator) as a tuple of TDFloat values
+            with _p and _q set for the fast path
+        """
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        from ._arithmetic import divmod_td as divmod_td_encoded
+        quot_e, rem_e, den_e = divmod_td_encoded(self._e, o._e)
+
+        # Decode each result to preserve _p and _q for fast path
+        p_q, q_q = to_rational(quot_e)
+        p_r, q_r = to_rational(rem_e)
+        p_d, q_d = to_rational(den_e)
+
+        return (
+            TDFloat(quot_e, p_q, q_q),
+            TDFloat(rem_e, p_r, q_r),
+            TDFloat(den_e, p_d, q_d)
+        )
+
+    def __pow__(self, n) -> TDFloat:
+        if isinstance(n, TDFloat):
+            # Only integer powers supported natively
+            pn, pd = to_rational(n._e)
+            if pd == 1:
+                n_int = int(pn)
+            else:
+                raise TypeError("Non-integer powers require tdfloat.math")
+        else:
+            n_int = int(n)
+
+        # For fraction fast path: compute directly on numerator and denominator
+        if self._p is not None:
+            p_result = self._p ** n_int
+            q_result = self._q ** n_int
+            return TDFloat(pow_int(self._e, n_int), p_result, q_result)
+        return TDFloat(pow_int(self._e, n_int))
+
+    def __neg__(self) -> TDFloat:
+        if self._p is not None:
+            return TDFloat(neg(self._e), -self._p, self._q)
+        return TDFloat(neg(self._e))
+
+    def __pos__(self) -> TDFloat:
+        return self
+
+    def __abs__(self) -> TDFloat:
+        if self._p is not None:
+            return TDFloat(abs_val(self._e), abs(self._p), self._q)
+        return TDFloat(abs_val(self._e))
+
+    def sqrt(self) -> TDFloat:
+        """Square root via rational Newton's method.
+        Automatically preserves _p and _q through auto-extraction."""
+        return TDFloat(sqrt(self._e))
+
+    # ── Comparison ────────────────────────────────────────────────────
+
+    def __eq__(self, o) -> bool:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        # Use exact fractions if available
+        if self._p is not None and o._p is not None:
+            return self._p * o._q == o._p * self._q
+        return eq(self._e, o._e)
+
+    def __lt__(self, o) -> bool:
+        if not isinstance(o, TDFloat): o = _coerce(o)
+        if self._p is not None and o._p is not None:
+            return self._p * o._q < o._p * self._q
+        return lt(self._e, o._e)
+
+    def __le__(self, o) -> bool: return self == o or self < o
+    def __gt__(self, o) -> bool: return not self <= o
+    def __ge__(self, o) -> bool: return not self < o
+
+    def __bool__(self) -> bool:
+        return self._e != 0 and self._e not in _SPECIALS
+
+    def __hash__(self) -> int:
+        p, q = self.as_fraction()
+        return hash((p, q))
+
+    # ── Encoding / phase inspection ───────────────────────────────────
+
+    @property
+    def encoded(self) -> int:
+        """The single integer that IS this float on the half-step line."""
+        return self._e
+
+    @property
+    def info_bit(self) -> int:
+        """0 = integer axis (no dot), 1 = half-step axis (has dot)."""
+        if self._e in _SPECIALS: return 0
+        return decode_info(abs(self._e))
+
+    @property
+    def is_integer(self) -> bool:
+        """True if this number lives on the integer axis (no dot)."""
+        return self.info_bit == 0 and self._e not in _SPECIALS
+
+    @property
+    def is_fractional(self) -> bool:
+        """True if this number lives on the half-step axis (has dot)."""
+        return self.info_bit == 1
+
+    @property
+    def dot_pos(self) -> int:
+        """Number of decimal places after the dot (0 if integer)."""
+        if self._e in _SPECIALS: return 0
+        rank = decode_rank(abs(self._e))
+        return rank % DOT_POSITIONS
+
+    @property
+    def abs_digits(self) -> int:
+        """The digit string as an integer (no dot, no sign)."""
+        if self._e in _SPECIALS: return 0
+        rank = decode_rank(abs(self._e))
+        return rank // DOT_POSITIONS
+
+    @property
+    def is_nan(self) -> bool:  return self._e == _NAN
+    @property
+    def is_inf(self) -> bool:  return self._e in (_PINF, _NINF)
+    @property
+    def is_finite(self) -> bool: return self._e not in _SPECIALS
+
+    def as_fraction(self) -> tuple:
+        """Return (numerator, denominator) as exact integers.
+
+        Uses internal _p and _q when available (fast path).
+        Falls back to decoding from encoded value.
+        """
+        if self._p is not None and self._q is not None:
+            return self._p, self._q
+        p, q = to_rational(self._e)
+        from math import gcd
+        g = gcd(abs(p), q) if q else 1
+        return p // g, q // g
+
+    @property
+    def numerator(self) -> int:
+        """Numerator of the canonical fraction representation."""
+        p, q = self.as_fraction()
+        return p
+
+    @property
+    def denominator(self) -> int:
+        """Denominator of the canonical fraction representation."""
+        p, q = self.as_fraction()
+        return q
+
+    def fields(self) -> dict:
+        """Full encoding breakdown for inspection."""
+        if self._e in _SPECIALS:
+            return {'encoded': self._e, 'special': to_str(self._e)}
+        s, digits, dp = unpack(self._e)
+        return {
+            'encoded':    self._e,
+            'sign':       s,
+            'abs_digits': digits,
+            'dot_pos':    dp,
+            'info_bit':   self.info_bit,
+            'rank':       decode_rank(abs(self._e)),
+            'position':   abs(self._e),
+            'axis':       'half-step' if self.info_bit else 'integer',
+            'value':      str(self),
+        }
+
+    # ── Conversion ────────────────────────────────────────────────────
+
+    def __float__(self) -> float:
+        """Convert to Python float (lossy for repeating decimals)."""
+        p, q = to_rational(self._e)
+        if q == 0: return float('nan')
+        return p / q
+
+    def __int__(self) -> int:
+        p, q = to_rational(self._e)
+        if q == 0: return 0
+        return p // q
+
+    def __str__(self) -> str:
+        """String representation: show floating-point version for backward compatibility."""
+        p, q = to_rational(self._e)
+        if q == 0: return 'nan'
+        # Convert to float for display (maintains backward compatibility)
+        return str(p / q)
+
+    def __repr__(self) -> str:
+        """Repr: show as td() constructor for clarity."""
+        s = to_str(self._e)
+        return f'td({s!r})'   # concise; use .fields() for full breakdown
+
+    def __format__(self, spec: str) -> str:
+        if not spec:
+            return str(self)
+        # Support basic format specs by going through float
+        return format(float(self), spec)
+
+    # ── Class-level constants ──────────────────────────────────────────
+
+    NAN  : 'TDFloat'
+    INF  : 'TDFloat'
+    NINF : 'TDFloat'
+    ZERO : 'TDFloat'
+    ONE  : 'TDFloat'
+    TWO  : 'TDFloat'
+    HALF : 'TDFloat'
+    PI   : 'TDFloat'
+    TAU  : 'TDFloat'
+    E    : 'TDFloat'
+    PHI  : 'TDFloat'
+    SQRT2: 'TDFloat'
+    SQRT3: 'TDFloat'
+
+
+# Set class-level constants after class definition
+TDFloat.NAN   = TDFloat(_NAN)
+TDFloat.INF   = TDFloat(_PINF)
+TDFloat.NINF  = TDFloat(_NINF)
+TDFloat.ZERO  = TDFloat.from_int(0)
+TDFloat.ONE   = TDFloat.from_int(1)
+TDFloat.TWO   = TDFloat.from_int(2)
+TDFloat.HALF  = TDFloat.from_frac(1, 2)
+TDFloat.PI    = TDFloat.from_frac(22, 7)
+TDFloat.TAU   = TDFloat.from_frac(44, 7)
+TDFloat.E     = TDFloat.from_frac(19, 7)
+TDFloat.PHI   = TDFloat.from_frac(3, 2)
+TDFloat.SQRT2 = TDFloat.from_frac(7, 5)
+TDFloat.SQRT3 = TDFloat.from_frac(7, 4)
+
+
+# ── Coercion helper ───────────────────────────────────────────────────
+
+def _coerce(x) -> TDFloat:
+    if isinstance(x, TDFloat): return x
+    if isinstance(x, int):     return TDFloat.from_int(x)
+    if isinstance(x, str):     return TDFloat.from_str(x)
+    if isinstance(x, float):   return TDFloat.from_float(x)
+    raise TypeError(f"Cannot convert {type(x).__name__} to TDFloat")
+
+
+# ── Module-level convenience ──────────────────────────────────────────
+
+def td(x) -> TDFloat:
+    """
+    Create a TDFloat from int, str, float, or fraction tuple.
+
+    Examples:
+        td(3)           → integer 3  (integer axis)
+        td('3.14')      → 3.14       (half-step axis)
+        td(0.1)         → exact binary value of Python's 0.1
+        td((1, 3))      → 1/3        (half-step axis, repeating)
+    """
+    if isinstance(x, TDFloat): return x
+    if isinstance(x, tuple) and len(x) == 2:
+        return TDFloat.from_frac(x[0], x[1])
+    return _coerce(x)
+
+def frac(p: int, q: int) -> TDFloat:
+    """Exact rational p/q."""
+    return TDFloat.from_frac(p, q)
+
+def divmod_td(a, b) -> tuple:
+    """Three-term division: returns (quotient, remainder, denominator).
+
+    Returns the complete quotient-remainder decomposition:
+        a/b = quotient + remainder/denominator
+
+    All three terms are TDFloat values. This is the full triadic division
+    semantic that exposes the quotient, remainder, and external denominator.
+
+    Args:
+        a, b: TDFloat or coercible to TDFloat
+
+    Returns:
+        (quotient, remainder, denominator) as a tuple of TDFloat values
+
+    Examples:
+        >>> q, r, d = divmod_td(frac(7, 1), frac(3, 1))
+        >>> q, r, d
+        (td(2), td(1), td(3))
+        >>> q + r / d  # Reconstruct: 2 + 1/3 = 7/3
+        td('2.333...')
+    """
+    a = td(a)
+    b = td(b)
+    return a.divmod_td(b)