pythonic-peano-arithmetic 0.3.0__py3-none-any.whl

peano/__init__.py

@@ -0,0 +1,66 @@
+"""Public API from Peano arithmetic through algebraic-root approximation."""
+
+from .algebraic_root import (
+    AlgebraicRoot,
+    RationalInterval,
+    algebraic_root,
+)
+from .integer import Z_MINUS_ONE, Z_ONE, Z_ZERO, Integer, integer, n2z
+from .natural_number import N_ONE, N_ZERO, NaturalNumber, natural_number, successor
+from .polynomial import (
+    P_ONE,
+    P_ZERO,
+    Polynomial,
+    count_real_roots,
+    n2p,
+    polynomial,
+    r2p,
+    sign_variations,
+    sturm_sequence,
+    z2p,
+)
+from .rational import (
+    Q_MINUS_ONE,
+    Q_ONE,
+    Q_ZERO,
+    Rational,
+    n2r,
+    rational,
+    z2r,
+)
+from .utils import config_log
+
+__all__ = [
+    "NaturalNumber",
+    "natural_number",
+    "successor",
+    "N_ZERO",
+    "N_ONE",
+    "Integer",
+    "integer",
+    "n2z",
+    "Z_ZERO",
+    "Z_ONE",
+    "Z_MINUS_ONE",
+    "Rational",
+    "rational",
+    "n2r",
+    "z2r",
+    "Q_ZERO",
+    "Q_ONE",
+    "Q_MINUS_ONE",
+    "Polynomial",
+    "polynomial",
+    "n2p",
+    "z2p",
+    "r2p",
+    "P_ZERO",
+    "P_ONE",
+    "sturm_sequence",
+    "sign_variations",
+    "count_real_roots",
+    "RationalInterval",
+    "AlgebraicRoot",
+    "algebraic_root",
+    "config_log",
+]

peano/algebraic_root.py

@@ -0,0 +1,180 @@
+"""Observe non-rational roots through shrinking rational intervals."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fractions import Fraction
+
+from .natural_number import NaturalNumber
+from .polynomial import Polynomial, count_real_roots
+from .rational import Rational, rational
+from .utils import LogMessage, localized, log
+
+
+@dataclass(frozen=True, slots=True)
+class RationalInterval:
+    """A closed interval with rational endpoints.
+
+    Equal endpoints are allowed and represent one exact rational point.
+    """
+
+    lower: Rational
+    upper: Rational
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.lower, Rational) or not isinstance(self.upper, Rational):
+            raise TypeError("interval endpoints must be Rational values")
+        lower_fraction = _as_fraction(self.lower)
+        upper_fraction = _as_fraction(self.upper)
+        if lower_fraction > upper_fraction:
+            raise ValueError("lower must be less than or equal to upper")
+        object.__setattr__(self, "lower", _from_fraction(lower_fraction))
+        object.__setattr__(self, "upper", _from_fraction(upper_fraction))
+
+    @property
+    def width(self) -> Rational:
+        return _from_fraction(_as_fraction(self.upper) - _as_fraction(self.lower))
+
+    @property
+    def midpoint(self) -> Rational:
+        return _from_fraction((_as_fraction(self.lower) + _as_fraction(self.upper)) / 2)
+
+    @property
+    def is_point(self) -> bool:
+        return _as_fraction(self.lower) == _as_fraction(self.upper)
+
+    def contains(self, value: Rational) -> bool:
+        point = _as_fraction(value)
+        return _as_fraction(self.lower) <= point <= _as_fraction(self.upper)
+
+    def __str__(self) -> str:
+        return f"[{self.lower}, {self.upper}]"
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class AlgebraicRoot:
+    """Identify one real polynomial root by an isolating interval.
+
+    This educational object is not a complete real-number type. It deliberately
+    omits arithmetic and general equality and focuses on shrinking rational
+    intervals while preserving one root.
+    """
+
+    polynomial: Polynomial
+    interval: RationalInterval
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.polynomial, Polynomial):
+            raise TypeError("polynomial must be a Polynomial")
+        if not isinstance(self.interval, RationalInterval):
+            raise TypeError("interval must be a RationalInterval")
+        if self.polynomial.degree <= 0:
+            raise ValueError("a root-defining polynomial must have positive degree")
+        if self.interval.is_point:
+            raise ValueError("the initial interval must have positive width")
+
+        lower_sign = self.polynomial.sign_at(self.interval.lower)
+        upper_sign = self.polynomial.sign_at(self.interval.upper)
+        if lower_sign == 0 or upper_sign == 0:
+            raise ValueError("initial interval endpoints cannot be roots")
+        if lower_sign == upper_sign:
+            raise ValueError("the polynomial must change sign across the endpoints")
+
+        number_of_roots = count_real_roots(
+            self.polynomial,
+            self.interval.lower,
+            self.interval.upper,
+        )
+        if number_of_roots != 1:
+            raise ValueError(
+                "the initial interval must contain exactly one distinct real root "
+                f"(found {number_of_roots})"
+            )
+
+    def approximate(self, steps: int | NaturalNumber) -> RationalInterval:
+        """Bisect ``steps`` times and return a closed interval containing the root."""
+
+        count = _step_count(steps)
+        interval = self.interval
+        for _ in range(count):
+            if interval.is_point:
+                break
+            interval = _bisect(self.polynomial, interval)
+        return interval
+
+    def trace(self, steps: int | NaturalNumber) -> tuple[RationalInterval, ...]:
+        """Return every bisection interval, including the initial interval."""
+
+        count = _step_count(steps)
+        intervals = [self.interval]
+        for _ in range(count):
+            if intervals[-1].is_point:
+                break
+            intervals.append(_bisect(self.polynomial, intervals[-1]))
+        return tuple(intervals)
+
+    def __repr__(self) -> str:
+        return f"<AlgebraicRoot({self.polynomial!r}, {self.interval})>"
+
+    def __str__(self) -> str:
+        return f"root of {self.polynomial} in {self.interval}"
+
+
+@log(log_level=41)
+def _bisect(
+    polynomial_value: Polynomial,
+    interval: RationalInterval,
+) -> tuple[RationalInterval, LogMessage]:
+    midpoint = interval.midpoint
+    midpoint_sign = polynomial_value.sign_at(midpoint)
+
+    if midpoint_sign == 0:
+        result = RationalInterval(midpoint, midpoint)
+        return (
+            result,
+            lambda: localized(
+                f"{polynomial_value!r}: midpoint {midpoint!r} is a root",
+                f"{polynomial_value!r}: 中点 {midpoint!r} は根",
+            ),
+        )
+
+    lower_sign = polynomial_value.sign_at(interval.lower)
+    if lower_sign != midpoint_sign:
+        result = RationalInterval(interval.lower, midpoint)
+    else:
+        result = RationalInterval(midpoint, interval.upper)
+    return (
+        result,
+        lambda: f"{polynomial_value!r}: {interval} -> {result}",
+    )
+
+
+def algebraic_root(
+    polynomial_value: Polynomial,
+    lower: tuple[int, int],
+    upper: tuple[int, int],
+) -> AlgebraicRoot:
+    """Construct an algebraic root from Python integer endpoint pairs."""
+
+    return AlgebraicRoot(
+        polynomial_value,
+        RationalInterval(rational(*lower), rational(*upper)),
+    )
+
+
+def _step_count(value: int | NaturalNumber) -> int:
+    if isinstance(value, NaturalNumber):
+        return int(value)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError("steps must be an int or NaturalNumber")
+    if value < 0:
+        raise ValueError("steps must be non-negative")
+    return value
+
+
+def _as_fraction(value: Rational) -> Fraction:
+    return Fraction(int(value.p), int(value.q))
+
+
+def _from_fraction(value: Fraction) -> Rational:
+    return rational(value.numerator, value.denominator)

peano/integer.py

@@ -0,0 +1,345 @@
+"""Construct integers as equivalence classes of natural-number differences."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import total_ordering
+from typing import TYPE_CHECKING, cast
+
+from .natural_number import N_ONE, N_ZERO, NaturalNumber, natural_number
+from .utils import LogMessage, log
+
+if TYPE_CHECKING:
+    from .rational import Rational
+
+
+@total_ordering
+@dataclass(frozen=True, slots=True, eq=False, repr=False)
+class Integer:
+    """Represent the difference ``a - b`` by a pair of natural numbers.
+
+    ``(a, b) ~ (c, d)`` is defined by ``a + d = b + c``. Representations are
+    deliberately not normalized automatically, so equivalent representatives
+    remain observable.
+    """
+
+    a: NaturalNumber
+    b: NaturalNumber
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.a, NaturalNumber) or not isinstance(
+            self.b, NaturalNumber
+        ):
+            raise TypeError("Integer.a and Integer.b must be NaturalNumber values")
+
+    def __repr__(self) -> str:
+        return f"<Z({int(self.a)},{int(self.b)})>"
+
+    def __str__(self) -> str:
+        return str(int(self))
+
+    def __int__(self) -> int:
+        return int(self.a) - int(self.b)
+
+    def __abs__(self) -> NaturalNumber:
+        if self.a >= self.b:
+            return self.a - self.b
+        return self.b - self.a
+
+    @log(log_level=11)
+    def __eq__(self, other: object) -> tuple[bool, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(bool, NotImplemented),
+                lambda: f"{self!r} == {other!r} = NotImplemented",
+            )
+        result = self.a + converted.b == self.b + converted.a
+        return (
+            result,
+            lambda: (
+                f"{self!r} == {converted!r} ⇔ "
+                f"{self.a!r} + {converted.b!r} == "
+                f"{self.b!r} + {converted.a!r}"
+            ),
+        )
+
+    @log(log_level=12)
+    def __lt__(self, other: object) -> tuple[bool, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(bool, NotImplemented),
+                lambda: f"{self!r} < {other!r} = NotImplemented",
+            )
+        result = self.a + converted.b < self.b + converted.a
+        return (
+            result,
+            lambda: (
+                f"{self!r} < {converted!r} ⇔ "
+                f"{self.a!r} + {converted.b!r} < "
+                f"{self.b!r} + {converted.a!r}"
+            ),
+        )
+
+    @log(log_level=12)
+    def __le__(self, other: object) -> tuple[bool, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(bool, NotImplemented),
+                lambda: f"{self!r} <= {other!r} = NotImplemented",
+            )
+        result = self.a + converted.b <= self.b + converted.a
+        return (
+            result,
+            lambda: (
+                f"{self!r} <= {converted!r} ⇔ "
+                f"{self.a!r} + {converted.b!r} <= "
+                f"{self.b!r} + {converted.a!r}"
+            ),
+        )
+
+    @log(log_level=14)
+    def __add__(self, other: object) -> tuple[Integer, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(Integer, NotImplemented),
+                lambda: f"{self!r} + {other!r} = NotImplemented",
+            )
+        result = Integer(self.a + converted.a, self.b + converted.b)
+        return (
+            result,
+            lambda: (
+                f"{self!r} + {converted!r} = "
+                f"({self.a!r} + {converted.a!r}, "
+                f"{self.b!r} + {converted.b!r})"
+            ),
+        )
+
+    def __radd__(self, other: object) -> Integer:
+        return self + other
+
+    @log(log_level=14)
+    def __neg__(self) -> tuple[Integer, LogMessage]:
+        return (
+            Integer(self.b, self.a),
+            lambda: f"-{self!r} = ({self.b!r}, {self.a!r})",
+        )
+
+    @log(log_level=14)
+    def __sub__(self, other: object) -> tuple[Integer, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(Integer, NotImplemented),
+                lambda: f"{self!r} - {other!r} = NotImplemented",
+            )
+        return (
+            self + -converted,
+            lambda: f"{self!r} - {converted!r} = {self!r} + (-{converted!r})",
+        )
+
+    def __rsub__(self, other: object) -> Integer:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return cast(Integer, NotImplemented)
+        return converted - self
+
+    @log(log_level=15)
+    def __mul__(self, other: object) -> tuple[Integer, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(Integer, NotImplemented),
+                lambda: f"{self!r} * {other!r} = NotImplemented",
+            )
+        result = Integer(
+            self.a * converted.a + self.b * converted.b,
+            self.a * converted.b + self.b * converted.a,
+        )
+        return (
+            result,
+            lambda: (
+                f"{self!r} * {converted!r} = "
+                f"({self.a!r} * {converted.a!r} + "
+                f"{self.b!r} * {converted.b!r}, "
+                f"{self.a!r} * {converted.b!r} + "
+                f"{self.b!r} * {converted.a!r})"
+            ),
+        )
+
+    def __rmul__(self, other: object) -> Integer:
+        return self * other
+
+    @log(log_level=15)
+    def __truediv__(self, other: object) -> tuple[Rational, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast("Rational", NotImplemented),
+                lambda: f"{self!r} / {other!r} = NotImplemented",
+            )
+        from .rational import Rational
+
+        result = Rational(self, converted)
+        return result, lambda: f"{self!r} / {converted!r} = {result!r}"
+
+    def __rtruediv__(self, other: object) -> Rational:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return cast("Rational", NotImplemented)
+        return converted / self
+
+    def _divmod(self, divisor: Integer) -> tuple[Integer, Integer]:
+        if not divisor:
+            raise ZeroDivisionError("division by zero")
+
+        quotient_magnitude, remainder_magnitude = divmod(abs(self), abs(divisor))
+        same_sign = (self < Z_ZERO) == (divisor < Z_ZERO)
+
+        if same_sign:
+            quotient = Integer(quotient_magnitude, N_ZERO)
+            remainder = Integer(remainder_magnitude, N_ZERO)
+        elif not remainder_magnitude:
+            quotient = Integer(N_ZERO, quotient_magnitude)
+            remainder = Z_ZERO
+        else:
+            quotient = Integer(N_ZERO, quotient_magnitude + N_ONE)
+            remainder = Integer(abs(divisor) - remainder_magnitude, N_ZERO)
+
+        if divisor < Z_ZERO:
+            remainder = -remainder
+        return quotient, remainder
+
+    @log(log_level=15)
+    def __floordiv__(self, other: object) -> tuple[Integer, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(Integer, NotImplemented),
+                lambda: f"{self!r} // {other!r} = NotImplemented",
+            )
+        quotient, _ = self._divmod(converted)
+        return (
+            quotient,
+            lambda: (
+                f"{self!r} = ({quotient!r}) * {converted!r} + "
+                f"({self!r} % {converted!r})"
+            ),
+        )
+
+    def __rfloordiv__(self, other: object) -> Integer:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return cast(Integer, NotImplemented)
+        return converted // self
+
+    @log(log_level=15)
+    def __mod__(self, other: object) -> tuple[Integer, LogMessage]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return (
+                cast(Integer, NotImplemented),
+                lambda: f"{self!r} % {other!r} = NotImplemented",
+            )
+        _, remainder = self._divmod(converted)
+        return (
+            remainder,
+            lambda: (
+                f"{self!r} % {converted!r} = {remainder!r}, "
+                f"sign(remainder) = sign({converted!r})"
+            ),
+        )
+
+    def __rmod__(self, other: object) -> Integer:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return cast(Integer, NotImplemented)
+        return converted % self
+
+    def __divmod__(self, other: object) -> tuple[Integer, Integer]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return cast(tuple[Integer, Integer], NotImplemented)
+        return self._divmod(converted)
+
+    def __rdivmod__(self, other: object) -> tuple[Integer, Integer]:
+        converted = _coerce_integer(other)
+        if converted is None:
+            return cast(tuple[Integer, Integer], NotImplemented)
+        return converted._divmod(self)
+
+    @log(log_level=16)
+    def __pow__(self, exponent: object) -> tuple[Integer, LogMessage]:
+        if not isinstance(exponent, NaturalNumber):
+            return (
+                cast(Integer, NotImplemented),
+                lambda: f"{self!r} ** {exponent!r} = NotImplemented",
+            )
+        if exponent == N_ZERO:
+            return Z_ONE, lambda: f"{self!r} ** {exponent!r} = {Z_ONE!r}"
+        return (
+            (self ** (exponent - N_ONE)) * self,
+            lambda: (
+                f"{self!r} ** {exponent!r} = "
+                f"({self!r} ** ({exponent!r} - {N_ONE!r})) * {self!r}"
+            ),
+        )
+
+    def __bool__(self) -> bool:
+        return self.a != self.b
+
+    def __hash__(self) -> int:
+        return hash(int(self))
+
+    def __pos__(self) -> Integer:
+        return self
+
+    def normalize(self) -> Integer:
+        """Return the representative ``(n, 0)`` or ``(0, n)``."""
+
+        if self.a >= self.b:
+            return Integer(self.a - self.b, N_ZERO)
+        return Integer(N_ZERO, self.b - self.a)
+
+
+def integer(value: int) -> Integer:
+    """Construct the canonical difference representation of a Python integer."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError("only int values can be converted to Integer")
+    if value >= 0:
+        return Integer(natural_number(value), N_ZERO)
+    return Integer(N_ZERO, natural_number(-value))
+
+
+def n2z(value: NaturalNumber) -> Integer:
+    """Embed a natural number into the integers."""
+
+    if not isinstance(value, NaturalNumber):
+        raise TypeError("n2z expects a NaturalNumber")
+    return Integer(value, N_ZERO)
+
+
+def _coerce_integer(value: object) -> Integer | None:
+    if isinstance(value, NaturalNumber):
+        return n2z(value)
+    if isinstance(value, Integer):
+        return value
+    return None
+
+
+def cast2z(value: object) -> Integer:
+    """Coerce a ``NaturalNumber`` or ``Integer`` to ``Integer``."""
+
+    converted = _coerce_integer(value)
+    if converted is None:
+        raise TypeError(f"{value!r} is not an Integer")
+    return converted
+
+
+Z_ZERO = Integer(N_ZERO, N_ZERO)
+Z_ONE = Integer(N_ONE, N_ZERO)
+Z_MINUS_ONE = Integer(N_ZERO, N_ONE)