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