ConformalLabpp/doc/reviewer/math-derivation-citation-audit-2026-05-31.md

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

// 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.