0f5ab27461
arXiv:math/0603097 is Springborn 2008 ("A variational principle for weighted
Delaunay triangulations and hyperideal polyhedra"), not a Kolpakov-Mednykh paper.
The author pair Kolpakov & Mednykh has no joint publication from 2006; their
earliest collaboration is arXiv:1008.0312 (2010, on torus knots, unrelated).
The wrong author name was introduced during the Java→C++ port — the Java source
correctly links to math/0603097 without naming the authors; whoever ported it
invented "Kolpakov-Mednykh". The S1 citation audit (2026-05-31) then cemented
the error by adding the incorrect row to references.md.
Files corrected (7):
- code/include/hyper_ideal_utility.hpp
- code/include/hyper_ideal_functional.hpp
- code/tests/cgal/test_hyper_ideal_functional.cpp
- doc/math/references.md
- doc/roadmap/research-track.md
- doc/architecture/project-structure.md
- doc/api/tests.md
Also:
- doc/reviewer/math-derivation-citation-audit-2026-05-31.md: M1 post-correction noted
- doc/reviewer/finding-orchestration.md: lesson-learned section added (AI citation
audits can introduce plausible-but-wrong attributions; human expert review required
before CGAL submission)
- papers/MANUAL-DOWNLOAD.md: overview of papers requiring manual download (paywalled
journals, TU Berlin theses, books)
- .gitignore: papers/*.pdf excluded (downloaded arXiv PDFs, not tracked)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
210 lines
10 KiB
Markdown
210 lines
10 KiB
Markdown
# 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
|
||
|
||
> **✅ Resolution status (2026-05-31, Session 1):** **M1 ✅** (Kolpakov–Mednykh +
|
||
> Meyerhoff/Ushijima added to `references.md`), **M2 ✅** (BPS year unified to the
|
||
> published 2015), **M4 ✅** (citation format normalized). **M3** (re-verify
|
||
> future-dated/arXiv citations) **open** → S4; **M5** (prose derivation review)
|
||
> needs a **domain expert** (out of model scope). See
|
||
> [`finding-orchestration.md`](finding-orchestration.md).
|
||
>
|
||
> **⚠️ M1 Nachkorrektur (2026-06-04):** Die ursprüngliche M1-Auflösung war selbst
|
||
> fehlerhaft — arXiv:math/0603097 ist **Springborn 2008** (*A variational principle
|
||
> for weighted Delaunay triangulations and hyperideal polyhedra*), nicht
|
||
> Kolpakov–Mednykh. Kolpakov und Mednykh haben 2006 kein gemeinsames Paper
|
||
> veröffentlicht (früheste Zusammenarbeit: 2010). Der falsche Autorenname wurde beim
|
||
> Java→C++-Port erfunden; die Java-Quelle verlinkt korrekt auf math/0603097 ohne
|
||
> Autorennamen. Korrekturen angewendet in: `hyper_ideal_utility.hpp`,
|
||
> `hyper_ideal_functional.hpp`, `test_hyper_ideal_functional.cpp`,
|
||
> `doc/math/references.md`.
|
||
|
||
> **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.
|