Skip to content

feat(persistence): rational enclosure of the exponential at nonpositive rational arguments (#1013) - #1014

Merged
t-uda merged 1 commit into
developfrom
ccr-eb669e62-a5kqoa
Nov 20, 2026
Merged

t-uda merged 1 commit into
developfrom
ccr-eb669e62-a5kqoa

Conversation

@t-uda

@t-uda t-uda commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1013

Summary

First unit of #926: an executable rational enclosure of the exponential at the arguments a Gaussian kernel needs.

  • New module TDA.Persistence.Enclosure.Exp. For a rational x ≤ 0 and a rational δ > 0, expEnclosure x δ : ℚ × ℚ is computed by rational arithmetic, contains the actual Real.exp x (expEnclosure_mem) and has width at most δ (expEnclosure_width). expEnclosure? returns it for such a request and none for a positive argument or a nonpositive tolerance.
  • Algorithm: the argument is halved expHalvings x times into [-1, 0]; the Taylor polynomial with expTerms p terms is bounded by Mathlib's Real.exp_bound; the value is rounded outward to the grid 1 / 2 ^ p, widened by one step, clamped to [0, 1] and squared back with outward rounding. p = expHalvings x + toleranceBits δ + 3.
  • New module TDA.Persistence.Enclosure.ExpExamples with kernel-checked fixtures (decide +kernel) and three consumers, among them a bound for one value of the existing WeightedKernel.kernel.
  • New note docs/math/kernel-enclosure.md, registered in docsite/sources.txt and linked from docs/api.md, docs/README.md and docs/math/weighted-kernel-embedding.md; a CHANGELOG.md Unreleased entry.

What is not provided: no enclosure of the Gram sums linearKernel and none of the squared RKHS distance (units 2 and 3 of #926); the width is absolute, not a relative error, and the lower endpoint can be 0; positive arguments are rejected; the cost is documented, not proved.

Branch lifecycle

Ordinary develop topic based on 73f08dd4aaecca958bf128d8fe26ac7876707e2d, target develop, squash merge. Target scope: persistence-image / kernel computation under #926 / #227. Release version: undecided. Propagation: N/A.

Public declarations added / changed

Added in TDA.Persistence.Enclosure (nothing existing is changed):

  • Definitions: roundDown, roundUp, expTaylor, expTerms, expHalvings, toleranceBits, expSquare, expEnclosure, expEnclosure?.
  • Rounding: roundDown_le, lt_roundDown_add, le_roundUp, roundUp_lt_add, roundDown_nonneg, roundUp_le_one.
  • Schedule: two_pow_le_factorial_expTerms, neg_le_two_pow_expHalvings, one_div_two_pow_toleranceBits_lt, abs_exp_sub_expTaylor_le.
  • Enclosure: expEnclosure_mem, expEnclosure_width, expEnclosure_fst_nonneg, expEnclosure_snd_le_one, expEnclosure_fst_le_snd, expEnclosure?_eq_some_iff, expEnclosure?_eq_none_iff, expEnclosure?_spec.

Added in TDA.Persistence.Enclosure.ExpExamples: schedule_zero, schedule_large, expTaylor_five, zero_coarse, one_coarse, one_fine, one_refines, one_tiny, reduced, third, gaussian, huge, positive_argument, zero_tolerance, negative_tolerance, exp_neg_one_bounds, reduced_width, kernel_separated.

These are exactly the declarations of the contract block of #1013 as reviewed, with the same names, definition bodies and types, and the fixture list of its Acceptance section. No statement changed, and no supporting public lemma was added beyond the contract. All 45 public declarations are pinned at the end of scripts/print_axioms/Persistence.lean.

Source ↔ Lean correspondence

Library-derived; there is no paper source. Governing specification #926, contract #1013.

  • expEnclosure_mem and expEnclosure_width are the scalar instance of [PI computation] Certify Gaussian kernel and squared RKHS distance enclosures #926's requirement that each successful interval contains the exact real value and has width at most δ; expEnclosure?_spec states both for every returned interval, and expEnclosure?_eq_none_iff is the explicit rejection.
  • The remainder estimate is Mathlib's Real.exp_bound at the pinned revision 56a005855ea17e0b0958f73ec801ae140b0a1679; no analytic foundation is added.
  • Deviations stated in the contract: positive arguments are rejected, not enclosed; the guarantee is an absolute width; expEnclosure_mem holds for every tolerance because the tolerance only selects the precision.

The statements were checked before admission by an independent reviewer, as recorded in the Admission section of #1013. Changed after that review: nothing in the Lean statements or definitions. The module docstring gained a Scope paragraph, and the documentation named in the contract was written; beyond the files the contract names, this PR also adds the note to docsite/sources.txt and adds one pointer sentence each to docs/README.md and docs/math/weighted-kernel-embedding.md.

Validation

  • Evaluated head: cc106f36da6063d06058d4103bc2fedfca229bee. Base: 73f08dd4aaecca958bf128d8fe26ac7876707e2d.
  • scripts/check.sh on the working tree that became this head: exit 0, CHECK OK.
    • AXIOM AUDIT OK — 13894 declarations within {propext Classical.choice Quot.sound} (base 13849).
    • PRIVATE AUDIT — 10584 private theorem roots (base 10572).
    • COVERAGE OK — 11162 public theorems, all pinned (base 11126).
    • Comparator agreement: accepted.
  • Pre-push gate on cc106f36da6063d06058d4103bc2fedfca229bee: scripts/check.sh --incremental green, gate passed.
  • Hosted check for this head: success — https://github.com/uda-lab/tda-lib/actions/runs/44741379320/job/136305593857 (conclusion read from the check run of head cc106f36da6063d06058d4103bc2fedfca229bee; its log was not re-read for the counts, which are those of the local run above). The hosted build job of the pages workflow (site build and link tests) also succeeded on this head: https://github.com/uda-lab/tda-lib/actions/runs/44741379332/job/136305594062 .
  • Not run: the docsite build and its link tests (mkdocs is not installed in this container; the new links were checked by hand against existing files and anchors), doc-gen4 generation, scripts/check.sh --stable.

Remaining sorry / custom-axiom footprint

None.

Independent review evidence

…ve rational arguments (#1013)

Add TDA.Persistence.Enclosure.Exp: for rational x ≤ 0 and δ > 0, expEnclosure x δ
is a rational interval computed by rational arithmetic that contains Real.exp x
(expEnclosure_mem) and has width at most δ (expEnclosure_width). expEnclosure?
rejects positive arguments and nonpositive tolerances. The argument is halved
into [-1, 0], a Taylor polynomial is bounded by Real.exp_bound and the result is
squared back with outward dyadic rounding.

The width is absolute, not relative; the cost is documented, not proved. This is
the first unit of #926: enclosures of the Gram sums and of the squared RKHS
distance are not included.

Kernel-checked fixtures and consumers are in
TDA.Persistence.Enclosure.ExpExamples; the note is docs/math/kernel-enclosure.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-20T13:07:39.328856Z cc106f3 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

t-uda commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

Reviewed-by: claude-opus read-only reviewer (session distinct from the implementer)

Reviewed head: cc106f36da6063d06058d4103bc2fedfca229bee (base develop 73f08dd4aaecca958bf128d8fe26ac7876707e2d), against #1013 (part 1 of #926), under lean-review-routing § Semantic and API quality.

Verdict: pass with non-substantive notes. No substantive finding.

Findings

  1. (non-substantive) The docstrings for roundDown and roundUp say "below q" and "above q". The functions return q itself when q is already on the grid, so "at most q" and "at least q" would be exact. docs/math/kernel-enclosure.md step 4 has the same wording ("nearest multiple … below and above it"). The proved lemmas (roundDown_le, le_roundUp) state the correct non-strict form.
  2. (non-substantive) One sentence in docs/math/kernel-enclosure.md is not exact at the diagonal. Its intro says the kernel value "is a real number that rational arithmetic cannot represent". That is false at x = 0 (kernel value 1, e.g. on the diagonal). Suggest "in general cannot".
  3. (non-substantive, informational) No public theorem states the width bound (3/4) / 2 ^ s. The module docstring and the note give the final width as (3/4) / 2 ^ s. The proof derives it inside the private expEnclosure_spec (hmul/e2) and then exports only ≤ 1 / 2 ^ toleranceBits δ, and then ≤ δ. The documentation describes the algorithm and does not claim a public theorem, so this is accurate. Expose the bound only if unit 2 wants it.
  4. (non-substantive, reuse) No exact duplicate found in mathlib. Mathlib's Real.expNear/Real.exp_approx (ExponentialBounds) is tactic-oriented support for specific constants, not an executable interval with a width guarantee. Reusing Real.exp_bound is the right choice.

What I checked, with evidence

  • Contract conformance. I wrote a scratch file with an example for every declaration in [PI computation] Rational enclosure of the exponential at nonpositive rational arguments (#926, part 1) #1013's contract block, using the verbatim signatures and closing each with the library declaration. The definitions roundDown, roundUp, expTaylor, expTerms, expHalvings, toleranceBits, expSquare, expEnclosure and expEnclosure? are checked by rfl against the verbatim contract bodies. Everything elaborates. There is no extra hypothesis and no public declaration beyond the contract plus the 18 example names listed in the PR body.

  • Mathematics. I read every proof:

    • The schedule lemmas use Nat.lt_log2_self.
    • The Taylor step applies Real.exp_bound with n ≥ 1 and the inequality (n+1)/(n!·n) ≤ 2/n! ≤ 1/2^p.
    • Rounding goes in the right direction: floor for lower endpoints, ceiling for upper endpoints.
    • The base interval has width ≤ 4/2^p.
    • The squaring invariant (0 ≤ lo, hi ≤ 1, w' + 2ε ≤ 2(w + 2ε)) iterates to 2^k·6ε = (3/4)/2^s.
    • Range reduction uses Real.exp_nat_mul.

    Containment is for Real.exp ((x : ℚ) : ℝ) for every x ≤ 0 and every δ. The width bound needs only x ≤ 0 and 0 < δ. The validated form rejects x > 0 and δ ≤ 0 (_eq_none_iff, plus the fixtures). expEnclosure_snd_le_one correctly handles x > 0 through k = 0. No vacuity: the hypotheses are satisfiable and the conclusions are non-trivial.

  • Axioms. #print axioms on the main theorems gives propext, Classical.choice, Quot.sound, and on expTerms it gives propext only. Rat.mul and Rat.add themselves list Classical.choice, which is consistent with the docstring's explanation.

  • Adversarial #evals. I ran x = -10^30, δ = 1; x = 0 at δ = 1, 1/10^20 and 1000; x = -123456789/987654321 at 1/10^15; -3 at 1/10^25; -1/10^20 at 1/10^40; -5/2 at δ = 1; -20 at 1/10^30; -2^30-1 at 1/10; and -1 at 1/10^50. All endpoints lie in [0,1], with lo ≤ hi and width ≤ δ.

  • Independent containment check. I evaluated a separate exact rational Taylor bracket in Python fractions, with my own halving and a rigorous remainder, of width far below the intervals. The library interval contained it in all 8 cases: -1@1e-50, -123456789/987654321@1e-15, -3@1e-25, -20@1e-30, -1e-20@1e-40, -5/2@1, -7/3@1e-6 and -1/3@1e-12. The width-to-δ ratio was ≤ 0.35 in each.

  • Hygiene.

    • No sorry, admit, native_decide or axiom in the new files.
    • lake env lean on both new files gives no warnings (about 6 s each).
    • The aggregator diffs are one import line each.
    • The pins are 45 appended lines with 0 deletions, matching the 27 + 18 public declarations.
  • Fixtures.

    • Every item in [PI computation] Rational enclosure of the exponential at nonpositive rational arguments (#926, part 1) #1013's acceptance list is present. The values match the contract, including 2^103 and 2^102 for one_tiny, and expTerms at 13/43/103/336 gives 8/16/30/71, as documented.
    • The fixtures are decide +kernel checks of Option (ℚ × ℚ) equalities and ℚ order, so they are real checks.
    • kernel_separated is about the actual library WeightedKernel.kernel (defined in TDA/Persistence/GaussianGram.lean; -((0-1/2)² + (1-2)²)/(2·(1/10)²) = -125/2).
    • exp_neg_one_bounds follows from one_fine: 3085995/8388608 ≈ 0.3678793, 1542999/4194304 ≈ 0.3678799.
  • Documentation.

    • The note's table matches the fixtures.
    • The link references.md#mathlib-56a0058 points to an existing anchor.
    • The sources.txt entry is placed alphabetically. The math-notes index is generated at build time from the H1, so no navigation entry is needed (docsite/hooks.py, docsite/README.md).
    • The hosted pages workflow (build.py --require-clean plus test_site.py, which includes the link and fragment checks) succeeded on this head (run 44741379332).
    • No overclaim. Every document (module docstring, note, api.md, README.md, the weighted-kernel-embedding.md pointer and CHANGELOG) says that Gram sums and RKHS distances are not enclosed, that the width is absolute, and that the cost is documented, not proved.

Not checked

  • I did not run scripts/check.sh, lake build or doc-gen4. For the axiom audit and coverage I rely on the PR's reported gate. Hosted check was still in progress when I reviewed.
  • I did not run the docsite build locally (mkdocs is not installed). I rely on the hosted pages success.
  • I did not measure the timing claims, beyond observing that the examples file elaborates in about 6 s.

Generated by Claude Code

@t-uda
t-uda merged commit 6e7867d into develop Nov 20, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants