Skip to content

feat(persistence): identify the executed Rips simplex list with the Rips diagram and homology (#1011) - #1012

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 #1011

Summary

Second and final unit of #922. For a valid DistanceTable, the list executed by ripsInput (#1009) is identified with the actual Rips filtration of the table metric, in the diagrams and in homology.

  • TDA/Persistence/SublevelDiagramVertexMap.lean (new): dgm_eq_of_vertexMaps, the invariance of real sublevel diagrams under mutually inverse vertex maps between filtered complexes on two vertex types, with the two homology lemmas it rests on.
  • TDA/Persistence/Reduction/RipsInputDiagram.lean (new): outputDiagram_ripsInput (FiniteInput.outputDiagram of the list, with integer grades read as real numbers, is dgm (ZMod 2) (Rips.filter (D.metric hD)) in every degree); the vertex map ripsLabelMap and its isomorphism in homology, natural in the threshold; the degree-indexed consumer ripsRunInDegree, none for an invalid table in every degree; equal diagrams for relabelled tables.
  • TDA/Persistence/Reduction/RipsInputDiagramExamples.lean (new): fixtures for no label, one label and two labels; the four-cycle with the existing reduction checked by the kernel on its fifteen faces, the Rips diagram in degrees 0, 1 and 2, and the dimension of the first homology of the actual Rips complex at thresholds 1 and 2; rejection of the five invalid tables in every degree; the relabelled line.
  • docs/api.md, docs/math/finite-ph-computation.md, CHANGELOG.md: what is and is not provided, and the two wording fixes carried over from [Metric computation] Executable Rips simplex list from an integer distance table (#922, part 1) #1009 (the module name in docs/api.md; FiniteInput.Valid in the notes).

Not provided: a bound on the cost of the existing reduction (left unbounded by decision; documented as at least quadratic in the number of faces), representatives for the Rips complex, a statement for invalid tables beyond rejection, a transport of diagrams for grades outside the real numbers.

Branch lifecycle

Ordinary develop topic based on 8bc02626c97e826bcf92e63df0d3135ad8eccf0b, target develop, squash merge. Target scope: metric computation under #922 / #227. Release version: undecided. Propagation: N/A.

Public declarations added / changed

Added, none changed.

TDA/Persistence/SublevelDiagramVertexMap.lean:

  • TDA.Simplicial.simplicialHomologyMap_congr
  • TDA.Simplicial.simplicialHomologyMap_comp_eq_id
  • TDA.Persistence.dgm_eq_of_vertexMaps

TDA/Persistence/Reduction/RipsInputDiagram.lean:

  • TDA.Persistence.intCastOrderEmbedding, intCastOrderEmbedding_apply
  • TDA.Persistence.Reduction.DistanceTable.mem_sublevel_rips_filter, mem_sublevel_gradeFilter_ripsInput
  • DistanceTable.outputDiagram_ripsInput
  • DistanceTable.ripsLabelMap, ripsLabelMap_apply, simplicialHomologyMap_ripsLabelMap_isIso, simplicialHomologyMap_ripsLabelMap_naturality
  • DistanceTable.ripsRunInDegree, ripsRunInDegree_eq_some_iff, ripsRunInDegree_eq_none_iff, ripsRunInDegree_correct
  • DistanceTable.valid_of_relabel, outputDiagram_ripsInput_of_relabel

TDA/Persistence/Reduction/RipsInputDiagramExamples.lean: 36 fixture declarations in TDA.Persistence.Reduction.RipsInputDiagramExamples; faceIncidence and boundary_eq_faceIncidence are private.

All 54 public declarations are pinned at the end of scripts/print_axioms/Persistence.lean.

Differences from the contract as reviewed before admission (recorded in the Admission section of #1011); no statement content changed:

  • Module placement: dgm_eq_of_vertexMaps is in its own module TDA/Persistence/SublevelDiagramVertexMap.lean instead of the Reduction module. Its statement is unchanged.
  • As a consequence of that placement, the two homology lemmas that both modules use, simplicialHomologyMap_congr and simplicialHomologyMap_comp_eq_id, are public supporting lemmas (private helpers in the reviewed draft), as the contract permits.
  • Rename and move: DistanceTable.gradeEmbedding is TDA.Persistence.intCastOrderEmbedding, outside the DistanceTable namespace, with the same definition; every statement that mentions it has the same content.
  • Rename: mem_sublevel_rips_metric is mem_sublevel_rips_filter.

Source ↔ Lean correspondence

Library-derived; no external source is translated. Governing specification #922, statement contract #1011. The statements were checked before admission by an independent read-only reviewer against 8bc0262 (record in #1011): the comparison is with dgm (ZMod 2) of Rips.filter for the metric built from the table on Rips.fullComplex (Fin N); the caller supplies no metric, isomorphism or certificate; Valid is required exactly where the metric is used; ripsRunInDegree p = none holds if and only if the table is invalid, whatever p.

Changed after that review, and to be covered by the final-head review: the module placement of the transport theorem, the two supporting lemmas made public by it, and the two renames listed above.

Validation

  • Evaluated head 8d52a4b932d887b96f4c73bddc3453c5bd70f872, base 8bc02626c97e826bcf92e63df0d3135ad8eccf0b.
  • Local scripts/check.sh on the evaluated head: exit 0, CHECK OK. AXIOM AUDIT OK — 13849 (base 13795), PRIVATE AUDIT — 10572 (base 10559), COVERAGE OK — 11126 (base 11079).
  • Pre-push gate on the evaluated head: textual guards and scripts/check.sh --incremental green; gate passed.
  • TDA.Persistence.Reduction.RipsInputDiagramExamples builds in 23 seconds, about 20 of them the kernel check of the reduction on the fifteen faces of the four-cycle; the other two new modules build in about 3 seconds each.
  • Hosted check for this head: success — https://github.com/uda-lab/tda-lib/actions/runs/44734461417/job/136282229365 (conclusion read from the check run of head 8d52a4b932d887b96f4c73bddc3453c5bd70f872; its log was not re-read for the counts, which are those of the local run above).
  • Not run: scripts/check.sh --stable, API documentation generation, the Comparator test suites beyond the gate's own Comparator step.

Remaining sorry / custom-axiom footprint

none

Independent review evidence

  • Read-only final-head review by a reviewer distinct from the implementer, on head 8d52a4b932d887b96f4c73bddc3453c5bd70f872: pass with non-substantive notes — feat(persistence): identify the executed Rips simplex list with the Rips diagram and homology (#1011) #1012 (comment) . Its notes (N1: simplicialHomologyMap_congr is a special case of the existing Contiguous.simplicialHomologyMap_eq and could cross-reference it; N2: Diagram.map_injective could be public; N3: two lemmas without docstrings; N4: one long line in docs/api.md) were not acted on, so the reviewed head is the head evaluated above.
  • Codex automatic review on this head: completed with no findings.

…ips diagram and homology (#1011)

For a valid DistanceTable, prove that FiniteInput.outputDiagram of the executed list, with integer grades read as real numbers, is the F₂ diagram of Rips.filter for the table metric in every degree, and that the inclusion of the labels induces an isomorphism from the homology of the Rips complexes to the sublevel homology of the list, natural in the threshold. Add ripsRunInDegree, which returns the records of one degree and none for an invalid table in every degree, and the equality of diagrams for relabelled tables. The new module SublevelDiagramVertexMap proves dgm_eq_of_vertexMaps, the invariance of real sublevel diagrams under mutually inverse vertex maps between complexes on two vertex types. The four-cycle is a kernel-checked fixture read against the actual Rips diagram and homology. Also fix two sentences of the Rips input notes.

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-20T12:18:13.248833Z 8d52a4b 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: 8d52a4b932d887b96f4c73bddc3453c5bd70f872 (base develop 8bc02626c97e826bcf92e63df0d3135ad8eccf0b), against #1011 as it now stands and #922.

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

Evidence

  1. Contract conformance. A scratch file restating every declaration of the [Metric computation] Diagram and homology of the executed Rips simplex list (#922, part 2) #1011 contract block verbatim as example … := <decl> (plus rfl for the bodies of intCastOrderEmbedding and ripsRunInDegree) elaborates against the head with no error. Both modules have the stated imports and are imported by TDA/Persistence.lean in the stated order. The four post-admission changes match the contract: the transport is in its own module; TDA.Persistence.intCastOrderEmbedding sits outside DistanceTable and has the same body; the lemma is named mem_sublevel_rips_filter; and simplicialHomologyMap_congr / simplicialHomologyMap_comp_eq_id are public in TDA.Simplicial, over every ring, with hypotheses on faces only. Their statements are correct and well named. No lemma in TDA/Simplicial/ has the same statement (see note N1).
  2. Mathematics. dgm_eq_of_vertexMaps: the sublevel isomorphisms are built from simplicialHomologyMap of the two vertex maps. The square with the inclusions is closed by functoriality, the ranks are equated through a private iso-square lemma, and rank_sublevelHomologyMap with multiset_eq_of_rankCounts_eq gives the conclusion. Nothing is vacuous, and φ and ψ are not required to be injective or monotone. outputDiagram_ripsInput covers N = 0 with dgm_empty_faces on both sides and 0 < N with clamp and Fin.val. No isomorphism or certificate is assumed. The isomorphism (with inverse clampMap, and the zero object for N = 0) and the naturality are proved, not assumed. ripsRunInDegree_eq_none_iff has no degree on its right side. ripsRunInDegree_correct is stated about the returned out and the actual dgm … (Rips.filter (D.metric hD)). The relabelling goes through Diagram.map_injective and Rips.dgm_eq_of_isometryEquiv. #print axioms on the main theorems and fixtures shows only propext, Classical.choice and Quot.sound.
  3. Hygiene. No sorry, admit, native_decide, axiom or heartbeat options. The aggregators contain only imports. All 54 public declarations of the three files are pinned, and the pin file diff is 54 lines added, 0 removed. Running lake env lean on each new file gives no warning (about 6 s, 6 s and 26 s).
  4. Fixtures. fourCycle_boundary rewrites the library's FiniteInput.boundary by the private boundary_eq_faceIncidence. That lemma is fully proved: the (-1)^a = 1 case analysis, the unique erased vertex, and the zero case. decide +kernel then checks the result against the explicit matrix, and fourCycle_reduced unfolds the existing reduced/trace, so this is a real kernel check. By hand: degree 0 has three points (0,1) and (0,⊤), and degree 1 has (1,2). There are 7 pivot pairs and 5 records, and the triangle {0,2,3} reduces to [4,5,6,7] and pairs with edge 7. All of this agrees. fourCycle_dgm_* and fourCycle_finrank_one/two are about the actual Rips.filter diagram and the actual sublevel homology, via finrank_sublevelHomology_eq_countP (at threshold 2, 2 < 2 fails, which gives 0). fourCycle_listed_finrank_one uses asIso of ripsLabelMap. Every acceptance item is covered: empty is Fin.elim0; single and pair; pair gives some [] in degree 1; five invalid tables return none in every degree; shortcut in degree 5 is checked by decide +kernel; the relabelling is swap 0 1. A compiled #eval also runs fourCycle.ripsRunInDegree 1 and gives [(1,1,some 2)].
  5. [Metric computation] Generate certified Rips simplex input from integer distances #922 completeness. With [Metric computation] Executable Rips simplex list from an integer distance table (#922, part 1) #1009, every item of [Metric computation] Generate certified Rips simplex input from integer distances #922 is delivered. The only exception is a bound on the cost of the existing reduction. That is left unbounded by decision and documented as at least quadratic, honestly so in [Metric computation] Diagram and homology of the executed Rips simplex list (#922, part 2) #1011, the PR body, the module docstring and finite-ph-computation.md. The reconciliation comment on [Metric computation] Generate certified Rips simplex input from integer distances #922 is still due after merge, as [Metric computation] Diagram and homology of the executed Rips simplex list (#922, part 2) #1011 requires.
  6. Documentation. Both carried-over wording fixes are present: "the module TDA.Persistence.Reduction.RipsInput" in the api paragraph, and "ripsInput_valid proves FiniteInput.Valid" in the notes. The sentence "not provided by this module" was removed from api.md. The part-1 forward reference in the notes now links to the new section. The new anchor #diagram-and-homology-of-the-rips-input resolves from all three places. I found no overclaim. The cost wording is not a proof claim. The part-1 CHANGELOG entry ("not part of this change") and the RipsInput.lean docstring ("not in this module") remain accurate.

Non-substantive notes

  • N1. simplicialHomologyMap_congr is a special case of the existing TDA.Simplicial.Contiguous.simplicialHomologyMap_eq (TDA/Simplicial/ContiguityHomotopy.lean:544), because maps that agree on faces are contiguous. I derived it from that lemma in 5 lines in scratch. The direct chain-level proof avoids the homotopy import, so this is not a duplicate. A cross-reference in the docstring would help.
  • N2. The private Diagram.map_injective (in RipsInputDiagram.lean, namespace TDA.Persistence) would fit naturally as a public lemma in DiagramMap.lean. This is optional.
  • N3. ripsRunInDegree_eq_some_iff and ripsRunInDegree_eq_none_iff have no docstrings (the contract shows none either). This is optional.
  • N4. The reflow at docs/api.md line 1554 leaves one line well over the paragraph's width. This is cosmetic.

Not checked

I did not run scripts/check.sh, lake build or doc-gen4. At review time, hosted check for this head was in_progress, and it must succeed before merge. I did not read the implementer's scratch directories.


Generated by Claude Code

@t-uda
t-uda merged commit 73f08dd 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