Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 95 additions & 1 deletion research/interval/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,10 +74,63 @@ from research.interval import (Interval, sqrt, exp, log, sin, cos, pi,
`erfc` and `normal_sf` (`normal_sf(x) = P(X > x) = 1 - Phi(x)`) carry the tail
mass as the primary quantity. **Use them for a tail bound; do not write
`1 - Phi(x)`.** The subtraction itself is exact, but the enclosure it subtracts
is rounded to a fixed number of significant bits, so beyond about `x = 26` the
is rounded to a fixed number of significant bits, so past a threshold in `x` the
upper endpoint of `Phi` rounds up to exactly 1 and the difference is `[0, …]` —
sound, and useless.

**That threshold is a function of `prec`, not a constant.** `Phi` finishes with
`round_out(4 * g + 32)` where `g = prec + 20`, so it keeps `4 * prec + 112`
significand bits, and `1 - Phi(x)` goes vacuous once the true tail mass falls
below `2 ** -(4 * prec + 112)`:

| `prec` | significand bits kept | smallest `x` with `(1 - Phi(x)).lo == 0` |
|---|---|---|
| 1 | 116 | 13 |
| 5 | 132 | 14 |
| 10 | 152 | 15 |
| 20 | 192 | **17** |
| 30 | 232 | 18 |
| 50 | 312 | 21 |
| 100 | 512 | 27 |

Measured. `tests/test_interval.py` asserts two rows directly and the rest through a
certified ceiling helper.

`ceil(sqrt(2 ln2 (4 prec + 112)))` reproduces **every row above**, and it is a
**fit, not the threshold**. It is a continuous approximation to an integer
crossing, and it rounds up by one whenever the crossing lands just inside an
integer. In `prec = 1..30` that happens five times:

| `prec` | measured | the closed form predicts |
|---|---|---|
| 3 | 13 | 14 |
| 8 | 14 | 15 |
| 13 | 15 | 16 |
| 19 | 16 | 17 |
| 25 | 17 | 18 |

Every one overshoots by exactly one, and the seven tabulated rows all happen to
agree — which is why a seven-row fit must not be called "the threshold". A
nonauthor engineering review found this and named `prec = 3`; the other four came
out of checking the rest of the range.

**Direction, because it decides how much it matters.** The fit predicts a
threshold one step *later* than the truth, so a consumer trusting it at
`prec = 3, x = 13` expects a usable bound and gets `[0, …]` — sound, and useless.
That is the same trap the correction below is about, one row further down, and it
is not a containment failure. The opposite direction would be worse and is pinned
by its own control: `test_the_closed_form_never_predicts_earlier_than_the_truth`.

At `prec = 20`, `1 - Phi(20)` is
`[0, 7.97e-59]` while `normal_sf(20)` is `2.75e-89` — and even at `x = 16`, one
short of the threshold, the subtraction has already lost the low digits
(`6.372e-58` against `normal_sf`'s `6.389e-58`).

`Phi`'s own docstring says "beyond about 26" as a flat constant. That is the
`prec = 100` row and it is **optimistic everywhere below it** — see the 2026-09-26
documentation audit below. `transcendental.py` is pinned by four certificates, so
the constant stands in the bytes and the correction lives here.

Deliberate refusals, each part of the contract:

* `float` endpoints raise `TypeError`. `Fraction(0.1)` is not `1/10`.
Expand Down Expand Up @@ -175,6 +228,47 @@ each reproduced on the unfixed code before anything was changed:
| the `j_hi - j_lo > 32` branch in `_sin_cos` is unreachable | kept (returning `[-1, 1]` is always sound) and documented as such; a test now measures the reduced-index span directly, so a regression shows up there rather than being masked |
| the `sin`/`cos` reduction docstring asserted `\|s\| <= pi/4` and `< 1` without the supporting inequality | the inequality is written out in `_sin_cos_point`, with `\|j\|` rather than `j`, and the margin (`1e-14` against `0.2146`) is stated. Containment does not rest on it: `_sin_cos_reduced` re-tests `mag(s) <= 1` and raises |

### The 2026-09-26 documentation audit

A fifth pass attacked the *documentation* rather than the arithmetic: every
numeric assertion in the README and in the library docstrings was re-derived or
re-measured against the code as it stands. **No containment violation was found,
and none of the three findings moves a bound.** Two are false statements in the
package's own prose, both in the *unsafe* direction — each claims something
tighter or safer than what the code does — and one is a coverage gap.

| Reported | Status |
|---|---|
| `transcendental.py` line 688 asserts "`pi(P)` has width below `10**-P`" as a premise of the `sin`/`cos` reduction sketch. **False at exactly `P = 64` (width `1.051e-64`) and `P = 102` (width `1.084e-102`)**, and true for every other `P` in 1..129. `pi` takes `target = _tol(key)/32` and then `round_out(4*key + 96)`, and the outward significand rounding can push the width back above `10**-P` where the binary and decimal boundaries line up. | Errata recorded here; the file is pinned and the bytes stand. **The sketch's conclusion survives**: the same paragraph states the argument tolerates `pi` being "about `10**13` times more loosely" certified, and the shortfall is a factor of 1.05. Containment never rested on it either — `_sin_cos_reduced` re-tests `mag(s) <= 1` and raises. A test now pins the exceptional set, so a future `pi` that misses the hint at a *third* precision is a test failure rather than a discovery. |
| `Phi`'s docstring, and the README, gave "beyond about `x = 26`" as a flat constant for where `1 - Phi(x)` collapses to `[0, …]`. The threshold moves with `prec` — measured 13 at `prec = 1`, **17 at `prec = 20`**, 27 at `prec = 100`. "About 26" is the `prec = 100` row. `ceil(sqrt(2 ln2 (4 prec + 112)))` fits those rows but is **not** the threshold: it overshoots by one at `prec` 3, 8, 13, 19 and 25, and the first revision of this correction called it the threshold anyway. | README corrected above with the measured table and the closed form; two rows asserted by tests. The docstring's constant is errata: `transcendental.py` is pinned. A consumer at `prec = 20` reading "about 26" would have taken `1 - Phi(20) = [0, 7.97e-59]` for a tail bound, where `normal_sf(20) = 2.75e-89`. |
| Two certificates carried **no control that names them**: the `sin`/`cos` alternating-series remainder in `_sin_cos_reduced`, and the **upper** branch of the Mills bracket (`b = 1 - 3/(2z^2)`, valid for `z >= 1`). The lower branch had one; the upper did not, and the Machin remainder control covers `atan`, not `sin`/`cos`. | Both added (NC13, NC14), each verified by mutating a copy of the library built outside the repository. Stated precisely, because the mutation exercise refined the finding: neither mutant survived the old suite — the `sin` one was already caught *incidentally* by the Pythagorean-identity and addition-formula tests, and the Mills one by twenty tests at once. What was missing was a control that **names the mutation**, so a failure points at the remainder bound instead of at trigonometry in general. |

**The mutants.** Both new controls were verified by mutating a copy of
`transcendental.py` **outside the repository** — never by editing the library —
one weakening each, in a subprocess with `PYTHONDONTWRITEBYTECODE=1`:

| mutation | the suite | the control that names it |
|---|---|---|
| `bound` advanced one index in `_sin_cos_reduced` (remainder taken from `a_(k+2)` instead of the first omitted term) | fails: 4 tests | NC13 `..._sin_remainder_off_by_one_loses_containment` |
| `4*zz*zz + 2*zz - 3` written `+ 1` in the upper quotient of `_erfc_mills` (i.e. `b = 1`, which is the proved *lower* bound) | fails: 20 tests | NC14 `..._mills_upper_bound_without_the_b_correction` |

NC14 is rigorous only **below** `ERF_CROSSOVER`, and the test says so rather than
hiding it: above the crossover `erfc` *is* this bracket, so the library holds no
independent enclosure to contradict. At `z <= 6` the series gives one 14 to 31
orders tighter and the broken value falls clean below its lower endpoint; above
it, the test asserts the other symptom — the mutation collapses the claimed
relative width from the honest `~3/(4 z^4)` to the rounding floor, claiming
thirty digits of a quantity the bracket pins to four.

**What this audit does not establish.** It read prose against code. It verified
no mathematics, tightened no bound, and moved no status. A corrected threshold is
a corrected sentence: `OBL-H5-JETMOD`, `OBL-H5-ZBAND`, `OBL-H5-REMOTE-THRESHOLD`,
`OBL-D1-PROMOTE`, `D3-LEMMA-RN-UNIF`, `PERC-DECAY` and `OBL-B1-BRANCH` stand
exactly where `docs/OPEN_PROBLEMS.md` has them. Two of the three findings are
corrections to documentation *about* pinned bytes, which the bytes do not carry;
a reader of `transcendental.py` alone still reads the false constant, and that is
the cost of the pin, stated rather than hidden.

**What the fixes do not establish.** Nothing here promotes, closes, discharges
or reclassifies any claim, premise or obligation. A faster, better-bounded
arithmetic layer is not a certified result. `OBL-H5-JETMOD`, `OBL-H5-ZBAND`,
Expand Down
Loading
Loading