From b213ad2265962380200523464d2e71d5514095bd Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sun, 31 May 2026 10:20:36 +0200 Subject: [PATCH] docs(reviewer): add math-derivation & citation audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Checks code/docs against the published mathematics (vs java-port-audit which checks code vs Java): - M1: Kolpakov-Mednykh volume formula used in code but missing from references.md - M2: BPS circle-packing paper cited as '2010' in code vs '2015' in references.md - M3: post-2023/preprint citations back unimplemented phases — re-verify + clarify scope before submission - M4: no canonical citation-key convention - M5: large derivations numerically validated but prose unreviewed — expert sign-off Co-Authored-By: Claude Opus 4.8 --- ...th-derivation-citation-audit-2026-05-31.md | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 doc/reviewer/math-derivation-citation-audit-2026-05-31.md diff --git a/doc/reviewer/math-derivation-citation-audit-2026-05-31.md b/doc/reviewer/math-derivation-citation-audit-2026-05-31.md new file mode 100644 index 0000000..2db1ba5 --- /dev/null +++ b/doc/reviewer/math-derivation-citation-audit-2026-05-31.md @@ -0,0 +1,192 @@ +# Math-Derivation & Citation Audit — ConformalLabpp + +**Date:** 2026-05-31 +**Auditor:** External reviewer (Claude Opus 4.8) +**Scope:** Correctness of the mathematical derivations in `doc/math/` and the +integrity/consistency of the literature citations in code comments and docs. +**Focus:** Are the derivations sound and are the citations accurate, complete, and +consistent? Distinct from `java-port-audit.md` (which checks code vs. Java) — this +checks code/docs vs. *the published mathematics*. + +Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish + +> **Good news up front:** `doc/math/references.md` is unusually scholarly and already +> contains several *self-corrections* (the Glickenstein "eq. (4.6)" numbering fix → +> §5.2 parametrization; the Schläfli boundary-term re-attribution to Rivin–Schlenker +> 1999; the Bowers–Stephenson formula-vs-theory clarification). That is exemplary and +> rare. The findings below are the gaps that remain *despite* this strong baseline. + +--- + +## Summary table + +| ID | Sev | Title | Location | +|----|-----|-------|----------| +| M1 | 🟡 | Kolpakov–Mednykh volume formula is used in code but **absent from `references.md`** | `hyper_ideal_utility.hpp:80`, `hyper_ideal_functional.hpp:321` | +| M2 | 🟡 | BPS circle-packing paper cited as **"2010"** in code but **"2015"** in `references.md` — inconsistent year for a load-bearing reference of an *implemented* phase | `cp_euclidean_functional.hpp`, `newton_solver.hpp`, `Discrete_circle_packing.h` vs `references.md` | +| M3 | 🟡 | Future-dated / arXiv-only citations (2025, 2026) back *unimplemented* phases but sit alongside implemented ones — re-verify against published versions before submission | `references.md` | +| M4 | 🔵 | No canonical citation-key convention — the same work appears as `Luo 2004` / `Luo-2004` / `Luo (2004)` / `Luo's 2004` etc. | code + docs | +| M5 | 🔵 | The large hand-derivations (notably `hyperideal-hessian-derivation.md`, 34 KB) have their *results* numerically validated but the *prose derivations* are unreviewed by a domain expert | `doc/math/*-derivation.md` | + +--- + +## M1 — 🟡 Kolpakov–Mednykh volume formula not in references.md + +### Evidence +```cpp +// hyper_ideal_utility.hpp:80 +/// the Kolpakov-Mednykh formula (arxiv math/0603097). Same as Java … +// hyper_ideal_functional.hpp:321 +/// * Exactly one vertex ideal (…) → Kolpakov-Mednykh volume +``` +`grep -c Kolpakov doc/math/references.md` → **0**. + +### Problem +The hyper-ideal **volume** computation — a core ingredient of the Springborn-2020 +functional and the energy itself — rests on the Kolpakov–Mednykh formula (and a +Meyerhoff/Ushijima component, cited 6× elsewhere). The code cites it inline by arXiv +ID, but `references.md`, the stated "citation source of truth", omits it entirely. A +reviewer auditing the math foundation against the references file would find a +load-bearing formula with no entry. + +### Fix +Add a `references.md` row: Kolpakov, Mednykh — *(full title)*, arXiv `math/0603097`, +mapped to `hyper_ideal_utility.hpp`. Likewise confirm the Meyerhoff / Ushijima 2006 +volume reference (cited in code) has a row. + +### Acceptance criteria +- Every formula cited inline in `code/include/` has a matching `references.md` entry. + +--- + +## M2 — 🟡 BPS paper: "2010" in code vs "2015" in references.md + +### Evidence +- Code/docs cite it as **2010** (e.g. `cp_euclidean_functional.hpp`, + `newton_solver.hpp`, `CGAL/Discrete_circle_packing.h`, plus 26 doc hits of + "Bobenko-Pinkall-Springborn 2010"). +- `references.md` lists it as **2015**: *"Discrete conformal maps and ideal hyperbolic + polyhedra, Geometry & Topology 19(4) (2015), arXiv 1005.2698."* + +### Problem +Both are "correct" in a sense — the arXiv preprint (`1005.2698`) is **2010**, the +published Geometry & Topology version is **2015** — but the project uses the two years +interchangeably for the *same* paper, including in the public CGAL header +(`Discrete_circle_packing.h`) and the `phase-9a-validation.md` mapping. This is the +reference for an **implemented, shipped** phase (9a.1 CP-Euclidean), so the +inconsistency is user-visible and would be flagged in CGAL review. + +### Fix +Pick one canonical citation (recommend the **published 2015** Geometry & Topology +version, with the arXiv 2010 ID noted) and use it everywhere. Update the code comments +and docs that say "2010" to match `references.md`, or vice-versa — but make them agree. + +### Acceptance criteria +- The BPS circle-packing paper is cited with a single, consistent year across code and + docs (matching `references.md`). + +--- + +## M3 — 🟡 Future-dated / preprint citations must be re-verified before submission + +### Evidence +`references.md` cites, among others: +- Bobenko, Lutz **2025** (arXiv 2310.17529) — Phase 9d.2 (🔜 planned) +- Bowers, Bowers, Lutz **2026** (arXiv 2601.22903) — Phase 9b-analytic / 10c′ +- Lutz **2024** PhD thesis; Bobenko-Lutz 2024 IMRN + +### Problem +Two issues: +1. **Verification:** arXiv-only and future-dated (2025/2026) references can change + (version bumps, final published venue, even withdrawal). Before any public release + or CGAL submission, each should be re-checked against its final published form. The + arXiv ID `2601.22903` in particular (Jan 2026) is very recent relative to this + audit and warrants a manual confirmation that it resolves. +2. **Scope confusion:** these back **unimplemented "future research"** phases (🔜), + but the Bowers-Bowers-Lutz 2026 row claims it "supports correctness of the analytic + Hessian" — which *is* implemented (Phase 9b-analytic, ✅). A reader could conclude + the shipped analytic Hessian *depends* on a 2026 preprint. Clarify that the + implemented derivation stands on its own (it is numerically validated, see M5) and + the 2026 paper is corroborating, not foundational. + +### Fix +- Re-verify every 2024–2026 / arXiv-only citation against its published version; add + DOIs once available. +- Sharpen the wording so implemented-phase correctness is never described as resting + on an unpublished/future reference. + +### Acceptance criteria +- All post-2023 citations are confirmed to resolve; no implemented-phase correctness + claim depends solely on a preprint/future reference. + +--- + +## M4 — 🔵 No canonical citation-key convention + +### Evidence +The same works appear in many surface forms across code and docs: +`Luo 2004` / `Luo-2004` / `Luo (2004)` / `Luo's 2004`; `Springborn 2020` / +`Springborn (2020)` / `Springborn-2020`; `Bowers-Stephenson` vs `Bowers, Stephenson`. + +### Problem +Cosmetic but it defeats grep-ability and cross-referencing (cf. the false-negative in +this audit's own tooling: `Bowers-Bowers-Lutz 2026` did not match the comma-form +`Bowers, Bowers, Lutz`). For a library aiming at CGAL, a consistent citation key +(e.g. `[SpringbornDCG2020]`) referenced from both code and `references.md` is the +clean solution. + +### Fix +Define short citation keys in `references.md` and use them verbatim in code comments +and docs. + +### Acceptance criteria +- One canonical key per reference; code/docs cite the key, not free-form variants. + +--- + +## M5 — 🔵 Large derivations: results validated, prose unreviewed + +### Evidence +`doc/math/hyperideal-hessian-derivation.md` (34 KB) derives the analytic HyperIdeal +Hessian; `validation.md` and the FD-vs-analytic tests (`test_hyper_ideal_hessian.cpp`, +block-FD vs full-FD) check the *result* numerically. + +### Problem +The derivation **result** is well-protected — the analytic Hessian is tested against +finite differences, so an algebra error would surface as a test failure. But the +**prose derivation itself** (the step-by-step algebra a reader would follow to trust +or extend it) has not been reviewed by a domain expert, and a derivation that "happens +to match FD at the tested points" can still contain a sign/indexing slip that the +specific test meshes don't excite. + +### Fix +- Have a discrete-differential-geometry expert read `hyperideal-hessian-derivation.md` + and `discrete-conformal-theory.md` for derivational soundness (this is naturally + part of the planned reviewer meeting — see `briefing.md`). +- Strengthen confidence cheaply by adding a randomized/property-based FD check (random + valid DOF vectors on several genera) so the numerical safety net covers more than the + fixed smoke meshes. + +### Acceptance criteria +- The key derivations are signed off by a domain reviewer, and/or the FD validation is + randomized rather than fixed-mesh-only. + +--- + +## What is already good + +- `references.md` is **scholarly and self-correcting** — it explicitly fixes its own + earlier over-citations (Glickenstein equation numbering, Schläfli→Rivin–Schlenker, + Bowers–Stephenson). This is well above typical project hygiene. +- Implemented vs. planned references are marked ✅ / 🔜 — the reader can tell which + citations underpin shipped code (M3 only asks to keep that discipline airtight). +- The primary source (Sechelmann 2016 PhD thesis, CC BY-SA 4.0) is correctly + identified, and the Java provenance is linked — directly relevant to CGAL audit G0. +- Derivation results are numerically validated (FD vs analytic) — the right safety net + (M5 just asks to widen it and get a human sign-off). + +## Suggested order +1. **M2** (BPS year) + **M1** (Kolpakov–Mednykh) — quick citation fixes, user-visible. +2. **M3** (re-verify post-2023 refs; fix scope wording) — before any submission. +3. **M5** (expert sign-off + randomized FD) — fold into the reviewer meeting. +4. **M4** (citation keys) — polish.