docs(reviewer): add math-derivation & citation audit
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 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
192
doc/reviewer/math-derivation-citation-audit-2026-05-31.md
Normal file
192
doc/reviewer/math-derivation-citation-audit-2026-05-31.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user