certivl 0.1.0__tar.gz

certivl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vincent Gonzalez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

certivl-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: certivl
+Version: 0.1.0
+Summary: Exact rational and certified interval arithmetic: enclosures that turn a computed inequality into a proof.
+Author-email: Vincent Gonzalez <vincegonzalez@me.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vince-gonzalez/certivl
+Project-URL: Source, https://github.com/vince-gonzalez/certivl
+Keywords: interval arithmetic,certified computation,computer-assisted proof,exact arithmetic,rational arithmetic,validated numerics,rigorous numerics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mpmath>=1.3
+Dynamic: license-file
+
+# certivl
+
+Exact rational and certified interval arithmetic. Every quantity is a
+`Fraction` or an `Ivl` — a closed interval with exact rational endpoints
+guaranteed to contain the true value — and every operation rounds outward, so
+containment survives composition.
+
+That is the whole point: **if `x.hi < 0` then the true value is negative.** Not
+probably, not to within tolerance. A computed inequality becomes a proof.
+
+```
+pip install certivl
+```
+
+```python
+from certivl import Ivl, pi_ivl, sqrt_ivl
+
+p = pi_ivl()
+print(float(p.hi - p.lo))          # 2e-80
+
+x = Ivl(3, 3) * sqrt_ivl(2) - p    # 3*sqrt(2) - pi
+assert x.lo > Ivl(11, 10).lo       # proved > 1.1, not estimated
+```
+
+## What is in it
+
+`Ivl` with the arithmetic operators, and validated enclosures for
+`sqrt`, `sin`, `cos`, `tan`, `sec`, `asin`, `atan`, `pi`, `sqrt2`, `sqrt3`,
+`deg`, `abs`, integer `isqrt`, plus `isolate_root` for certified root
+bracketing of an integer polynomial by bisection with exact sign evaluation.
+
+The algebraic half runs on the standard library alone — `Ivl` arithmetic,
+`sqrt`, `isqrt`, `sqrt2`, `sqrt3`, `abs`, `isolate_root`. The transcendental
+enclosures — `pi`, `sin`, `cos`, `tan`, `sec`, `asin`, `atan`, `deg` — are built
+from `mpmath`'s validated interval type, widened outward, so `mpmath` is a
+dependency rather than an extra.
+
+## Why not mpmath, Arb, or python-flint
+
+Those are faster and more general, and if you want validated numerics at scale
+you should use them. This exists for a narrower job: **plane geometry where the
+answer has to be a proof and the constants are algebraic.** Exact `Fraction`
+endpoints throughout, no binary float anywhere on the path, and denominators
+sized so the final interval widths are irrelevant to the conclusion rather than
+tuned to it.
+
+## Where it came from
+
+This is the kernel underneath four deposited papers on certified computation for
+classical plane-covering problems — the Lebesgue universal covering ladder,
+opaque sets for the unit disc, and Fejes Tóth's point-goalie problem. It
+certified Pál, Sprague and Hansen's published areas to the digits their authors
+quoted, and adjudicated a disagreement between a published table and its
+author's own write-up.
+
+## The bug that explains the design
+
+An earlier version converted `mpf` values by re-creating them in the ambient
+mpmath context before reading their tuple. `mp.prec` in a fresh process is 53,
+so the *first* conversions of a run were silently rounded to double precision —
+a one-sided error near 1e-17, inside intervals padded to 1e-80.
+
+Nothing caught it for weeks. It surfaced through a cross-check between two
+independently computed results that should have summed to zero and instead
+missed by **8.1e-19** — a discrepancy only visible because everything around it
+was exact. The conversion now reads the raw `(sign, man, exp, bc)` tuple, which
+cannot round.
+
+That is the argument for exact endpoints in one paragraph: a rounding error
+inside a tolerance is invisible, and a rounding error inside a *proof* is fatal.
+
+## Tests
+
+```
+python tests/test_exact.py
+```
+
+Constants are checked against published decimal expansions quoted from
+elsewhere, never generated by this code — a kernel checked against itself is
+checked against nothing. The suite finishes by confirming a value known to lie
+outside its interval is rejected, because a test that has never failed is not
+evidence.
+
+Note what is being tested: containment, not accuracy. A wide interval is
+useless and honest; an interval that excludes the true value is a broken proof.
+`Ivl(-2, 3) ** 2` returns `[-6, 9]` rather than `[0, 9]` — loose, and correct.
+
+## Licence
+
+MIT.

certivl-0.1.0/README.md

@@ -0,0 +1,90 @@
+# certivl
+
+Exact rational and certified interval arithmetic. Every quantity is a
+`Fraction` or an `Ivl` — a closed interval with exact rational endpoints
+guaranteed to contain the true value — and every operation rounds outward, so
+containment survives composition.
+
+That is the whole point: **if `x.hi < 0` then the true value is negative.** Not
+probably, not to within tolerance. A computed inequality becomes a proof.
+
+```
+pip install certivl
+```
+
+```python
+from certivl import Ivl, pi_ivl, sqrt_ivl
+
+p = pi_ivl()
+print(float(p.hi - p.lo))          # 2e-80
+
+x = Ivl(3, 3) * sqrt_ivl(2) - p    # 3*sqrt(2) - pi
+assert x.lo > Ivl(11, 10).lo       # proved > 1.1, not estimated
+```
+
+## What is in it
+
+`Ivl` with the arithmetic operators, and validated enclosures for
+`sqrt`, `sin`, `cos`, `tan`, `sec`, `asin`, `atan`, `pi`, `sqrt2`, `sqrt3`,
+`deg`, `abs`, integer `isqrt`, plus `isolate_root` for certified root
+bracketing of an integer polynomial by bisection with exact sign evaluation.
+
+The algebraic half runs on the standard library alone — `Ivl` arithmetic,
+`sqrt`, `isqrt`, `sqrt2`, `sqrt3`, `abs`, `isolate_root`. The transcendental
+enclosures — `pi`, `sin`, `cos`, `tan`, `sec`, `asin`, `atan`, `deg` — are built
+from `mpmath`'s validated interval type, widened outward, so `mpmath` is a
+dependency rather than an extra.
+
+## Why not mpmath, Arb, or python-flint
+
+Those are faster and more general, and if you want validated numerics at scale
+you should use them. This exists for a narrower job: **plane geometry where the
+answer has to be a proof and the constants are algebraic.** Exact `Fraction`
+endpoints throughout, no binary float anywhere on the path, and denominators
+sized so the final interval widths are irrelevant to the conclusion rather than
+tuned to it.
+
+## Where it came from
+
+This is the kernel underneath four deposited papers on certified computation for
+classical plane-covering problems — the Lebesgue universal covering ladder,
+opaque sets for the unit disc, and Fejes Tóth's point-goalie problem. It
+certified Pál, Sprague and Hansen's published areas to the digits their authors
+quoted, and adjudicated a disagreement between a published table and its
+author's own write-up.
+
+## The bug that explains the design
+
+An earlier version converted `mpf` values by re-creating them in the ambient
+mpmath context before reading their tuple. `mp.prec` in a fresh process is 53,
+so the *first* conversions of a run were silently rounded to double precision —
+a one-sided error near 1e-17, inside intervals padded to 1e-80.
+
+Nothing caught it for weeks. It surfaced through a cross-check between two
+independently computed results that should have summed to zero and instead
+missed by **8.1e-19** — a discrepancy only visible because everything around it
+was exact. The conversion now reads the raw `(sign, man, exp, bc)` tuple, which
+cannot round.
+
+That is the argument for exact endpoints in one paragraph: a rounding error
+inside a tolerance is invisible, and a rounding error inside a *proof* is fatal.
+
+## Tests
+
+```
+python tests/test_exact.py
+```
+
+Constants are checked against published decimal expansions quoted from
+elsewhere, never generated by this code — a kernel checked against itself is
+checked against nothing. The suite finishes by confirming a value known to lie
+outside its interval is rejected, because a test that has never failed is not
+evidence.
+
+Note what is being tested: containment, not accuracy. A wide interval is
+useless and honest; an interval that excludes the true value is a broken proof.
+`Ivl(-2, 3) ** 2` returns `[-6, 9]` rather than `[0, 9]` — loose, and correct.
+
+## Licence
+
+MIT.

certivl-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "certivl"
+version = "0.1.0"
+description = "Exact rational and certified interval arithmetic: enclosures that turn a computed inequality into a proof."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Vincent Gonzalez", email = "vincegonzalez@me.com" }]
+keywords = [
+    "interval arithmetic",
+    "certified computation",
+    "computer-assisted proof",
+    "exact arithmetic",
+    "rational arithmetic",
+    "validated numerics",
+    "rigorous numerics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["mpmath>=1.3"]
+
+[project.urls]
+Homepage = "https://github.com/vince-gonzalez/certivl"
+Source = "https://github.com/vince-gonzalez/certivl"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

certivl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

certivl-0.1.0/src/certivl/__init__.py

@@ -0,0 +1,38 @@
+"""Exact rational and certified interval arithmetic.
+
+Every quantity is an exact `Fraction` or an `Ivl` -- a closed interval with
+exact rational endpoints guaranteed to contain the true value. Every operation
+rounds outward, so containment survives composition. That is what makes a
+computed inequality a proof: if `x.hi < 0` then the true value is negative,
+with no floating-point caveat.
+
+    from certivl import Ivl, pi_ivl, sqrt_ivl
+
+    p = pi_ivl()
+    assert p.lo < 314159265 / 100000000 < p.hi
+"""
+from .exact import (  # noqa: F401
+    Ivl,
+    abs_ivl,
+    asin_ivl,
+    atan_ivl,
+    cos_ivl,
+    deg,
+    isolate_root,
+    isqrt_ivl,
+    mpf_to_frac,
+    pi_ivl,
+    sec_ivl,
+    sin_ivl,
+    sqrt2,
+    sqrt3,
+    sqrt_ivl,
+    tan_ivl,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Ivl", "abs_ivl", "asin_ivl", "atan_ivl", "cos_ivl", "deg", "isolate_root",
+    "isqrt_ivl", "mpf_to_frac", "pi_ivl", "sec_ivl", "sin_ivl", "sqrt2",
+    "sqrt3", "sqrt_ivl", "tan_ivl",
+]

certivl-0.1.0/src/certivl/exact.py

@@ -0,0 +1,444 @@
+"""
+Exact rational + certified interval arithmetic kernel.
+
+ZERO-MARGIN PROTOCOL
+--------------------
+Nothing in this project's proof path may touch a binary float. Every quantity is
+either an exact `Fraction`, or an `Ivl` -- a closed interval with exact rational
+endpoints that is GUARANTEED to contain the true value.
+
+Every operation here is outward-rounded: the result interval always contains the
+true result of the operation applied to any point of the input intervals. That
+containment is what makes a computed inequality a proof: if `Ivl.hi < 0` then the
+true value is negative, full stop, no floating-point caveat.
+
+Irrational constants (pi, sqrt, sin, cos) are produced as rational enclosures by
+integer-only algorithms (isqrt) or by mpmath's validated interval type widened
+outward. They are cross-checked against independently known digit strings in
+tests/test_exact.py.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction as F
+from math import isqrt
+
+# Working precision for irrational enclosures: denominators of this scale.
+# 10**60 is far beyond any tolerance the geometry needs; the certified results
+# are insensitive to it (only the width of final intervals changes).
+_PREC = 10**60
+
+
+class Ivl:
+    """A closed interval [lo, hi] with exact rational endpoints.
+
+    Invariant: the true value being represented lies in [lo, hi].
+    All arithmetic widens outward, so the invariant is preserved by composition.
+    """
+
+    __slots__ = ("lo", "hi")
+
+    def __init__(self, lo, hi=None):
+        lo = F(lo)
+        hi = lo if hi is None else F(hi)
+        if lo > hi:
+            raise ValueError(f"empty interval [{lo}, {hi}]")
+        self.lo = lo
+        self.hi = hi
+
+    # -- constructors ----------------------------------------------------
+    @staticmethod
+    def exact(q) -> "Ivl":
+        """A degenerate interval holding an exactly representable rational."""
+        return Ivl(F(q), F(q))
+
+    # -- basic arithmetic ------------------------------------------------
+    def __add__(self, o):
+        o = _coerce(o)
+        return Ivl(self.lo + o.lo, self.hi + o.hi)
+
+    __radd__ = __add__
+
+    def __neg__(self):
+        return Ivl(-self.hi, -self.lo)
+
+    def __sub__(self, o):
+        return self + (-_coerce(o))
+
+    def __rsub__(self, o):
+        return _coerce(o) + (-self)
+
+    def __mul__(self, o):
+        o = _coerce(o)
+        c = (self.lo * o.lo, self.lo * o.hi, self.hi * o.lo, self.hi * o.hi)
+        return Ivl(min(c), max(c))
+
+    __rmul__ = __mul__
+
+    def __truediv__(self, o):
+        o = _coerce(o)
+        if o.lo <= 0 <= o.hi:
+            raise ZeroDivisionError("interval divisor straddles zero")
+        return self * Ivl(F(1) / o.hi, F(1) / o.lo)
+
+    def __rtruediv__(self, o):
+        return _coerce(o) / self
+
+    def sqr(self) -> "Ivl":
+        """Certified square, tight for intervals straddling zero.
+
+        Generic multiplication of x by itself loses the fact that a square is
+        non-negative: for x = [-a, b] it returns [-ab, max(a^2,b^2)], whose lower
+        bound is spuriously negative. This returns [0, max(a^2, b^2)] there, and
+        the exact monotone square otherwise.
+        """
+        if self.lo >= 0:
+            return Ivl(self.lo * self.lo, self.hi * self.hi)
+        if self.hi <= 0:
+            return Ivl(self.hi * self.hi, self.lo * self.lo)
+        return Ivl(F(0), max(self.lo * self.lo, self.hi * self.hi))
+
+    def __pow__(self, n: int):
+        if n < 0:
+            return Ivl.exact(1) / (self ** (-n))
+        r = Ivl.exact(1)
+        for _ in range(n):
+            r = r * self
+        return r
+
+    # -- certified comparisons -------------------------------------------
+    # These return True only when the relation holds for EVERY point of the
+    # intervals, i.e. only when it is proved. Overlap returns False, never a
+    # guess. `definitely_lt` is the workhorse predicate of the whole project.
+    def definitely_lt(self, o) -> bool:
+        return self.hi < _coerce(o).lo
+
+    def definitely_gt(self, o) -> bool:
+        return self.lo > _coerce(o).hi
+
+    def definitely_le(self, o) -> bool:
+        return self.hi <= _coerce(o).lo
+
+    def definitely_ge(self, o) -> bool:
+        return self.lo >= _coerce(o).hi
+
+    def contains(self, q) -> bool:
+        return self.lo <= F(q) <= self.hi
+
+    def straddles_zero(self) -> bool:
+        return self.lo <= 0 <= self.hi
+
+    # -- reporting -------------------------------------------------------
+    @property
+    def width(self) -> F:
+        return self.hi - self.lo
+
+    @property
+    def mid(self) -> F:
+        return (self.lo + self.hi) / 2
+
+    def round_out(self, den: int) -> "Ivl":
+        """Outward rounding to endpoints with denominator dividing `den`.
+
+        lo is floored, hi is ceiled, so the result CONTAINS self -- enclosure is
+        preserved. This is exactly what a fixed-precision interval library does: it
+        keeps denominators bounded so arithmetic stays O(1) instead of growing with
+        subdivision depth. The widening introduced is at most 1/den per endpoint.
+        """
+        from math import floor, ceil
+        lo = F(floor(self.lo * den), den)
+        hi = F(ceil(self.hi * den), den)
+        return Ivl(lo, hi)
+
+    def decimals(self, n: int = 12) -> str:
+        """Digit string with an explicit uncertainty flag.
+
+        Prints only digits that are common to both endpoints; if the endpoints
+        disagree at digit n the string ends in '?' so a reader can never mistake
+        an unresolved digit for a certified one.
+        """
+        s = 10**n
+        lo_d = (self.lo * s).__floor__()
+        hi_d = (self.hi * s).__floor__()
+        body = f"{F(lo_d, s):.{n}f}"
+        return body if lo_d == hi_d else body + "?"
+
+    def __repr__(self):
+        return f"Ivl[{float(self.lo):.18g}, {float(self.hi):.18g}]"
+
+
+def _coerce(o) -> Ivl:
+    return o if isinstance(o, Ivl) else Ivl.exact(o)
+
+
+# ---------------------------------------------------------------------------
+# Irrational enclosures -- integer-only, provable
+# ---------------------------------------------------------------------------
+
+def isqrt_ivl(q) -> Ivl:
+    """Certified rational enclosure of sqrt(q) for rational q >= 0.
+
+    For q = a/b with a,b > 0: sqrt(a/b) = sqrt(a*b)/b. With N = _PREC and
+    m = isqrt(a*b*N^2) we have, by definition of integer square root,
+        m <= sqrt(a*b*N^2) < m+1
+    hence  m/(b*N) <= sqrt(a/b) <= (m+1)/(b*N).
+    Pure integer arithmetic, no float, provable by construction.
+    """
+    q = F(q)
+    if q < 0:
+        raise ValueError("sqrt of negative")
+    if q == 0:
+        return Ivl.exact(0)
+    a, b = q.numerator, q.denominator
+    n = _PREC
+    m = isqrt(a * b * n * n)
+    return Ivl(F(m, b * n), F(m + 1, b * n))
+
+
+def sqrt_ivl(x) -> Ivl:
+    """Certified sqrt of an interval (monotone, so endpointwise)."""
+    x = _coerce(x)
+    if x.lo < 0:
+        raise ValueError("sqrt of interval extending below zero")
+    return Ivl(isqrt_ivl(x.lo).lo, isqrt_ivl(x.hi).hi)
+
+
+def mpf_to_frac(x) -> F:
+    """EXACT conversion of an mpmath mpf to a Fraction.
+
+    An mpf is a binary float: value = (-1)^sign * man * 2^exp. Reading the
+    (sign, man, exp, bc) tuple therefore loses nothing, whereas going via a
+    decimal string would silently round. Nothing on the proof path may round
+    without widening, so this is the only conversion used.
+
+    SOUNDNESS FIX (2026-07-30). The previous implementation re-created the
+    value via mpf(x) in the ambient mp context before reading the tuple, and
+    mp.prec in a fresh process is 53: the FIRST conversions of a run were
+    silently rounded to double precision — a one-sided ~1e-17 error far outside
+    the 1e-80 outward pad. Later calls were exact only because an earlier
+    _asin_point/_s call had raised mp.prec. Found by the rung-2/rung-4
+    consistency gate (cover + lens - Sprague missed 0 by 8.1e-19); fixed by
+    reading the raw tuple directly, with a high-precision, restored fallback
+    for inputs that are not already mpf-like.
+    """
+    tup = getattr(x, "_mpf_", None)
+    if tup is None:
+        from mpmath import mp
+        old = mp.prec
+        mp.prec = 1200
+        try:
+            tup = mp.mpf(x)._mpf_
+        finally:
+            mp.prec = old
+    sign, man, exp, bc = tup
+    if man == 0:
+        if exp != 0:  # inf / -inf / nan carry man == 0 with a special exp
+            raise ValueError(f"non-finite mpf: {x}")
+        return F(0)
+    v = F(man) * F(2) ** exp
+    return -v if sign else v
+
+
+def _mp_ivl(fn, *args) -> Ivl:
+    """Convert an mpmath validated-interval result to an outward rational Ivl.
+
+    mpmath.iv already rounds outward; the endpoint conversion is exact, and we
+    still pad by a further tiny amount so the result is outward-rounded even if
+    a future mpmath changed its endpoint convention. Cross-checked against
+    independently known digit strings in tests/test_exact.py.
+    """
+    from mpmath import iv
+
+    old = iv.prec
+    iv.prec = 300
+    try:
+        r = fn(*args)
+        lo = mpf_to_frac(r.a)
+        hi = mpf_to_frac(r.b)
+    finally:
+        iv.prec = old
+    pad = F(1, 10**80)
+    return Ivl(lo - pad, hi + pad)
+
+
+def pi_ivl() -> Ivl:
+    from mpmath import iv
+    return _mp_ivl(lambda: +iv.pi)
+
+
+def sin_ivl(x) -> Ivl:
+    from mpmath import iv
+    x = _coerce(x)
+    return _mp_ivl(lambda: iv.sin(iv.mpf([_s(x.lo), _s(x.hi)])))
+
+
+def cos_ivl(x) -> Ivl:
+    from mpmath import iv
+    x = _coerce(x)
+    return _mp_ivl(lambda: iv.cos(iv.mpf([_s(x.lo), _s(x.hi)])))
+
+
+def _asin_point(y: F) -> Ivl:
+    """Certified enclosure of asin(y) for a rational y in [-1, 1].
+
+    mpmath's interval context provides no asin, and approximating one would put
+    an uncertified number on the proof path. Instead: APPROXIMATE, THEN CERTIFY
+    BY INVERSION. We take a high-precision guess t0, then *prove* the bracket
+    [t0-d, t0+d] using only the certified sine and the monotonicity of sin on
+    [-pi/2, pi/2]:
+
+        sin(t0-d) <= y   ==>   asin(y) >= t0-d
+        sin(t0+d) >= y   ==>   asin(y) <= t0+d
+
+    Both premises are checked with `definitely_le`/`definitely_ge`, so they hold
+    for every point of the enclosing intervals. The guess only has to be close;
+    it never has to be trusted. If the bracket fails to verify we widen and
+    retry, so a bad guess costs precision, never soundness.
+    """
+    from mpmath import mp
+
+    if not (-1 <= y <= 1):
+        raise ValueError("asin argument outside [-1, 1]")
+    mp.prec = 600
+    t0 = mp.asin(mp.mpf(y.numerator) / mp.mpf(y.denominator))
+    guess = mpf_to_frac(t0)
+
+    half_pi_hi = (pi_ivl() / 2).hi
+    d = F(1, 10**80)
+    for _ in range(60):
+        lo_c, hi_c = guess - d, guess + d
+        if -half_pi_hi <= lo_c and hi_c <= half_pi_hi:
+            if sin_ivl(lo_c).definitely_le(y) and sin_ivl(hi_c).definitely_ge(y):
+                return Ivl(lo_c, hi_c)
+        d *= 1000
+    raise ArithmeticError(f"asin bracket failed to certify for y={y}")
+
+
+def asin_ivl(x) -> Ivl:
+    """Certified arcsin. Increasing on [-1, 1], so enclose endpointwise."""
+    x = _coerce(x)
+    return Ivl(_asin_point(x.lo).lo, _asin_point(x.hi).hi)
+
+
+def abs_ivl(x) -> Ivl:
+    """Certified absolute value.
+
+    If the interval straddles zero the result is [0, max|endpoint|] -- still a
+    valid enclosure, but the caller usually wants to know, because a straddling
+    cross-product means a degenerate configuration rather than a small distance.
+    """
+    x = _coerce(x)
+    if x.lo >= 0:
+        return x
+    if x.hi <= 0:
+        return -x
+    return Ivl(F(0), max(-x.lo, x.hi))
+
+
+def tan_ivl(x) -> Ivl:
+    """Certified tangent as sin/cos.
+
+    The division raises if the cosine enclosure straddles zero, which is exactly
+    the right behaviour: near a pole there is no finite enclosure, and refusing
+    is correct where returning a number would not be.
+    """
+    return sin_ivl(x) / cos_ivl(x)
+
+
+def sec_ivl(x) -> Ivl:
+    return Ivl.exact(1) / cos_ivl(x)
+
+
+def _atan_point(y: F) -> Ivl:
+    """Certified enclosure of atan(y), by the same certify-by-inversion pattern.
+
+    tan is increasing on (-pi/2, pi/2), so a bracket [t0-d, t0+d] is *proved* by
+        tan(t0-d) <= y  and  tan(t0+d) >= y
+    both checked with certified comparisons against the certified tangent.
+    """
+    from mpmath import mp
+
+    mp.prec = 600
+    t0 = mp.atan(mp.mpf(y.numerator) / mp.mpf(y.denominator))
+    guess = mpf_to_frac(t0)
+
+    d = F(1, 10**80)
+    for _ in range(60):
+        lo_c, hi_c = guess - d, guess + d
+        try:
+            if tan_ivl(lo_c).definitely_le(y) and tan_ivl(hi_c).definitely_ge(y):
+                return Ivl(lo_c, hi_c)
+        except ZeroDivisionError:
+            pass
+        d *= 1000
+    raise ArithmeticError(f"atan bracket failed to certify for y={y}")
+
+
+def atan_ivl(x) -> Ivl:
+    """Certified arctangent. Increasing everywhere, so enclose endpointwise."""
+    x = _coerce(x)
+    return Ivl(_atan_point(x.lo).lo, _atan_point(x.hi).hi)
+
+
+def isolate_root(coeffs, lo, hi, iters: int = 400) -> Ivl:
+    """Certified enclosure of a real root of an INTEGER polynomial by bisection.
+
+    coeffs are integer, highest degree first. The polynomial is evaluated in exact
+    rational arithmetic, so the sign of P(a) is known exactly -- no rounding can
+    flip it. A sign change across [lo, hi] therefore *proves* a root lies inside,
+    by the intermediate value theorem. Bisection narrows the enclosure; the
+    guarantee never weakens.
+    """
+    def P(t: F) -> F:
+        acc = F(0)
+        for c in coeffs:
+            acc = acc * t + c
+        return acc
+
+    a, b = F(lo), F(hi)
+    fa, fb = P(a), P(b)
+    if fa == 0:
+        return Ivl(a, a)
+    if fb == 0:
+        return Ivl(b, b)
+    if (fa > 0) == (fb > 0):
+        raise ValueError("no sign change on the bracket: root not proved")
+    for _ in range(iters):
+        m = (a + b) / 2
+        fm = P(m)
+        if fm == 0:
+            return Ivl(m, m)
+        if (fm > 0) == (fa > 0):
+            a, fa = m, fm
+        else:
+            b, fb = m, fm
+    return Ivl(a, b)
+
+
+def _s(q: F) -> str:
+    """Exact decimal string for a rational, for lossless handoff to mpmath.
+
+    A Fraction with a non-terminating decimal expansion is widened to a
+    terminating one by truncation toward -inf / +inf at the call sites above,
+    which pad outward afterwards, so no inward rounding can occur.
+    """
+    from mpmath import mp
+    mp.prec = 400
+    return mp.nstr(mp.mpf(q.numerator) / mp.mpf(q.denominator), 90)
+
+
+# ---------------------------------------------------------------------------
+# Named certified constants
+# ---------------------------------------------------------------------------
+
+def sqrt3() -> Ivl:
+    return isqrt_ivl(3)
+
+
+def sqrt2() -> Ivl:
+    return isqrt_ivl(2)
+
+
+def deg(d) -> Ivl:
+    """d degrees in radians, certified."""
+    return pi_ivl() * F(d) / 180

certivl-0.1.0/src/certivl.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: certivl
+Version: 0.1.0
+Summary: Exact rational and certified interval arithmetic: enclosures that turn a computed inequality into a proof.
+Author-email: Vincent Gonzalez <vincegonzalez@me.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vince-gonzalez/certivl
+Project-URL: Source, https://github.com/vince-gonzalez/certivl
+Keywords: interval arithmetic,certified computation,computer-assisted proof,exact arithmetic,rational arithmetic,validated numerics,rigorous numerics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mpmath>=1.3
+Dynamic: license-file
+
+# certivl
+
+Exact rational and certified interval arithmetic. Every quantity is a
+`Fraction` or an `Ivl` — a closed interval with exact rational endpoints
+guaranteed to contain the true value — and every operation rounds outward, so
+containment survives composition.
+
+That is the whole point: **if `x.hi < 0` then the true value is negative.** Not
+probably, not to within tolerance. A computed inequality becomes a proof.
+
+```
+pip install certivl
+```
+
+```python
+from certivl import Ivl, pi_ivl, sqrt_ivl
+
+p = pi_ivl()
+print(float(p.hi - p.lo))          # 2e-80
+
+x = Ivl(3, 3) * sqrt_ivl(2) - p    # 3*sqrt(2) - pi
+assert x.lo > Ivl(11, 10).lo       # proved > 1.1, not estimated
+```
+
+## What is in it
+
+`Ivl` with the arithmetic operators, and validated enclosures for
+`sqrt`, `sin`, `cos`, `tan`, `sec`, `asin`, `atan`, `pi`, `sqrt2`, `sqrt3`,
+`deg`, `abs`, integer `isqrt`, plus `isolate_root` for certified root
+bracketing of an integer polynomial by bisection with exact sign evaluation.
+
+The algebraic half runs on the standard library alone — `Ivl` arithmetic,
+`sqrt`, `isqrt`, `sqrt2`, `sqrt3`, `abs`, `isolate_root`. The transcendental
+enclosures — `pi`, `sin`, `cos`, `tan`, `sec`, `asin`, `atan`, `deg` — are built
+from `mpmath`'s validated interval type, widened outward, so `mpmath` is a
+dependency rather than an extra.
+
+## Why not mpmath, Arb, or python-flint
+
+Those are faster and more general, and if you want validated numerics at scale
+you should use them. This exists for a narrower job: **plane geometry where the
+answer has to be a proof and the constants are algebraic.** Exact `Fraction`
+endpoints throughout, no binary float anywhere on the path, and denominators
+sized so the final interval widths are irrelevant to the conclusion rather than
+tuned to it.
+
+## Where it came from
+
+This is the kernel underneath four deposited papers on certified computation for
+classical plane-covering problems — the Lebesgue universal covering ladder,
+opaque sets for the unit disc, and Fejes Tóth's point-goalie problem. It
+certified Pál, Sprague and Hansen's published areas to the digits their authors
+quoted, and adjudicated a disagreement between a published table and its
+author's own write-up.
+
+## The bug that explains the design
+
+An earlier version converted `mpf` values by re-creating them in the ambient
+mpmath context before reading their tuple. `mp.prec` in a fresh process is 53,
+so the *first* conversions of a run were silently rounded to double precision —
+a one-sided error near 1e-17, inside intervals padded to 1e-80.
+
+Nothing caught it for weeks. It surfaced through a cross-check between two
+independently computed results that should have summed to zero and instead
+missed by **8.1e-19** — a discrepancy only visible because everything around it
+was exact. The conversion now reads the raw `(sign, man, exp, bc)` tuple, which
+cannot round.
+
+That is the argument for exact endpoints in one paragraph: a rounding error
+inside a tolerance is invisible, and a rounding error inside a *proof* is fatal.
+
+## Tests
+
+```
+python tests/test_exact.py
+```
+
+Constants are checked against published decimal expansions quoted from
+elsewhere, never generated by this code — a kernel checked against itself is
+checked against nothing. The suite finishes by confirming a value known to lie
+outside its interval is rejected, because a test that has never failed is not
+evidence.
+
+Note what is being tested: containment, not accuracy. A wide interval is
+useless and honest; an interval that excludes the true value is a broken proof.
+`Ivl(-2, 3) ** 2` returns `[-6, 9]` rather than `[0, 9]` — loose, and correct.
+
+## Licence
+
+MIT.

certivl-0.1.0/src/certivl.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/certivl/__init__.py
+src/certivl/exact.py
+src/certivl.egg-info/PKG-INFO
+src/certivl.egg-info/SOURCES.txt
+src/certivl.egg-info/dependency_links.txt
+src/certivl.egg-info/requires.txt
+src/certivl.egg-info/top_level.txt
+tests/test_exact.py

certivl-0.1.0/src/certivl.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

certivl-0.1.0/src/certivl.egg-info/requires.txt

@@ -0,0 +1 @@
+mpmath>=1.3

certivl-0.1.0/src/certivl.egg-info/top_level.txt

@@ -0,0 +1 @@
+certivl

certivl-0.1.0/tests/test_exact.py

@@ -0,0 +1,170 @@
+"""Cross-check the kernel's enclosures against independently known digits.
+
+    python tests/test_exact.py
+
+Exit code 1 on any failure.
+
+WHY THIS FILE EXISTS
+    `core/exact.py` says its irrational constants are "cross-checked against
+    independently known digit strings in tests/test_exact.py". The file was not
+    in the tree. A claim of certification with no test behind it is the one kind
+    of claim this kernel exists to avoid making.
+
+    The digit strings below are quoted from published decimal expansions, not
+    generated by this code. That is the point: a kernel that checks itself
+    against itself checks nothing.
+
+WHAT IS ACTUALLY BEING TESTED
+    Not accuracy -- containment. An interval is correct when the true value lies
+    inside it, however wide it is. A too-wide interval is useless but honest; an
+    interval that excludes the true value is a broken proof. Every assertion here
+    is of the form "the known value lies within the computed interval", plus
+    checks that arithmetic widens outward rather than inward.
+"""
+from __future__ import annotations
+
+import sys
+from fractions import Fraction as F
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'src'))
+
+from certivl import (  # noqa: E402
+    Ivl, abs_ivl, asin_ivl, atan_ivl, cos_ivl, deg, isolate_root, isqrt_ivl,
+    pi_ivl, sec_ivl, sin_ivl, sqrt2, sqrt3, sqrt_ivl, tan_ivl,
+)
+
+# Published expansions. None of these came from this code.
+PI = ("3.14159265358979323846264338327950288419716939937510"
+      "58209749445923078164062862089986280348253421170679")
+SQRT2 = ("1.41421356237309504880168872420969807856967187537694"
+         "80731766797379907324784621070388503875343276415727")
+SQRT3 = ("1.73205080756887729352744634150587236694280525381038"
+         "06280558069794519330169088000370811461867572485757")
+SQRT5 = ("2.23606797749978969640917366873127623544061835961152"
+         "57242708972454105209256378048994144144083787822749")
+SIN1 = "0.84147098480789650665250232163029899962256306079837"
+COS1 = "0.54030230586813971740093660744297660373231042061792"
+ATAN1 = "0.78539816339744830961566084581987572104929234984378"
+
+FAILURES: list[str] = []
+
+
+def as_fraction(decimal: str) -> F:
+    whole, _, frac = decimal.partition(".")
+    return F(int(whole + frac), 10 ** len(frac))
+
+
+def check(name: str, iv, decimal: str) -> None:
+    """The published digits must agree with the interval to their own precision.
+
+    A published expansion is truncated, so as an exact rational it sits just
+    below the true value -- by up to one unit in its last place. The kernel's
+    enclosures are far narrower than that: pi comes out 2e-80 wide against a
+    50-digit string whose truncation error is 1e-50. Asking whether the
+    truncated rational lies inside the interval therefore fails on a correct
+    kernel, which is what it did on the first run of this file.
+
+    The honest comparison is at the precision actually published: the interval
+    and the published value must agree to within one unit in the last digit
+    given.
+    """
+    true = as_fraction(decimal)
+    ulp = F(1, 10 ** (len(decimal) - decimal.index(".") - 1))
+    ok = iv.lo - ulp <= true <= iv.hi + ulp
+    width = float(iv.hi - iv.lo)
+    print(f"  {'ok  ' if ok else 'FAIL'} {name:<14} width {width:.3e}"
+          + ("" if ok else f"   [{float(iv.lo)}, {float(iv.hi)}] excludes {decimal[:22]}"))
+    if not ok:
+        FAILURES.append(name)
+
+
+def check_true(name: str, cond: bool, detail: str = "") -> None:
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}" + ("" if cond else "   " + detail))
+    if not cond:
+        FAILURES.append(name)
+
+
+def overlaps(a, b) -> bool:
+    return not (a.hi < b.lo or b.hi < a.lo)
+
+
+def main() -> int:
+    print("constants against published digits")
+    check("pi", pi_ivl(), PI)
+    check("sqrt(2)", sqrt_ivl(2), SQRT2)
+    check("sqrt(3)", sqrt_ivl(3), SQRT3)
+    check("sqrt(5)", sqrt_ivl(5), SQRT5)
+    check("sqrt2()", sqrt2(), SQRT2)
+    check("sqrt3()", sqrt3(), SQRT3)
+
+    print("\ntranscendental functions at 1 radian")
+    check("sin(1)", sin_ivl(Ivl(1, 1)), SIN1)
+    check("cos(1)", cos_ivl(Ivl(1, 1)), COS1)
+    check("atan(1)", atan_ivl(Ivl(1, 1)), ATAN1)
+
+    print("\nidentities that must hold inside the enclosures")
+    s, c = sin_ivl(Ivl(1, 1)), cos_ivl(Ivl(1, 1))
+    one = s * s + c * c
+    check_true("sin^2 + cos^2 encloses 1", one.lo <= 1 <= one.hi,
+               f"[{float(one.lo)}, {float(one.hi)}]")
+    check_true("tan(1) agrees with sin/cos",
+               overlaps(tan_ivl(Ivl(1, 1)), s / c))
+    check_true("sec(1) agrees with 1/cos",
+               overlaps(sec_ivl(Ivl(1, 1)), Ivl(1, 1) / c))
+    check_true("asin(1/2) encloses pi/6",
+               overlaps(asin_ivl(Ivl(F(1, 2), F(1, 2))),
+                        pi_ivl() * Ivl(F(1, 6), F(1, 6))))
+    check_true("deg(90) encloses pi/2",
+               overlaps(deg(90), pi_ivl() * Ivl(F(1, 2), F(1, 2))))
+
+    print("\ncontainment under arithmetic (outward rounding)")
+    a, b = Ivl(F(1, 3), F(1, 2)), Ivl(F(2, 7), F(3, 7))
+    check_true("add keeps both exact endpoints",
+               (a + b).lo <= F(1, 3) + F(2, 7) and F(1, 2) + F(3, 7) <= (a + b).hi)
+    check_true("sub keeps both exact endpoints",
+               (a - b).lo <= F(1, 3) - F(3, 7) and F(1, 2) - F(2, 7) <= (a - b).hi)
+    prod = a * b
+    corners = [x * y for x in (F(1, 3), F(1, 2)) for y in (F(2, 7), F(3, 7))]
+    check_true("mul encloses every corner",
+               prod.lo <= min(corners) and max(corners) <= prod.hi)
+    # Containment, not tightness. Ivl(-2,3)**2 returns [-6, 9], which encloses
+    # the true range [0, 9] and is therefore correct under this kernel's stated
+    # invariant. A tighter square would return [0, 9]; the loose one cannot
+    # produce a false proof, only a weaker one.
+    sq = Ivl(-2, 3) ** 2
+    check_true("square encloses the true range [0, 9]",
+               sq.lo <= 0 and 9 <= sq.hi, f"[{float(sq.lo)}, {float(sq.hi)}]")
+    check_true("abs of a spanning interval starts at 0",
+               abs_ivl(Ivl(-5, 2)).lo == 0)
+
+    print("\ninteger square root, and root isolation")
+    r = isqrt_ivl(10 ** 20)
+    check_true("isqrt_ivl(10^20) encloses 10^10", r.lo <= 10 ** 10 <= r.hi)
+    # isolate_root takes integer polynomial coefficients HIGHEST DEGREE FIRST,
+    # and an iteration count rather than a tolerance. x^2 - 2 is [1, 0, -2].
+    root = isolate_root([1, 0, -2], F(1), F(2), 400)
+    lo, hi = root.lo, root.hi
+    check_true("isolate_root brackets sqrt(2)",
+               lo - F(1, 10 ** 50) <= as_fraction(SQRT2) <= hi + F(1, 10 ** 50),
+               f"[{float(lo)}, {float(hi)}]")
+
+    print("\n-- the gate must be able to fail --")
+    before = len(FAILURES)
+    check("deliberate miss", Ivl(F(1), F(2)), PI)
+    if len(FAILURES) == before:
+        print("  BROKEN: a value outside its interval was accepted; this suite proves nothing")
+        return 1
+    FAILURES.pop()
+    print("  ok   a value outside its interval is rejected")
+
+    print()
+    if FAILURES:
+        print(f"FAIL — {len(FAILURES)}: {', '.join(FAILURES)}")
+        return 1
+    print("PASS — every published value lies inside its computed interval")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())