docs: full audit — fix 4 port/research mis-labels + consolidated research-track #10
Reference in New Issue
Block a user
No description provided.
Delete Branch "feature/doc-audit-and-research-roadmap"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Full audit of all 27 markdown files in
doc/+ root level against actual ground truth (C++ code onmain+ local Java repo at/Users/tarikmoussa/Desktop/conformallab/). Four pre-existing mis-labels and one stale test count corrected; new consolidatedresearch-track.mddocument added.Code untouched — pure documentation PR.
What was wrong (and is now fixed)
1.
InversiveDistanceFunctionalmis-labelled as Java port (4 sites)Empirical verification:
The class does not exist in
de.varylab.discreteconformal. The C++ implementation (Phase 9a.2, PR #8) is from Luo 2004 + Glickenstein 2011 + Bowers-Stephenson 2004 — new research, not a port.2. HyperIdeal Hessian mis-labelled as analytic in Java
Empirical verification:
HyperIdealFunctional.java:295-298:Java has no Hessian for HyperIdeal. Both the Phase 4a FD and Phase 9b block-FD variants in C++ are research beyond Java.
3. Stale test count
README.md:87said "28 suites, 170 tests" — actual is 35 suites, 176 CGAL + 36 non-CGAL.4. Tutorial framing
add-inversive-distance.mdframed as "portingInversiveDistanceFunctional.java" that does not exist. Rewritten end-to-end as "Implementing from Luo 2004" with prominent verification block at top.New document —
doc/roadmap/research-track.mdConsolidates everything in conformallab++ that goes beyond a Java port:
Already on
main(research)uvstorageOn open PRs
Planned with full citations
Java backlog summary
A parallel survey of
/Users/tarikmoussa/Desktop/conformallab/src/identified 11 worth-porting Java classes totalling ~6 500 lines, organised by phase:Total identified backlog: ~5 months work to fully exhaust the Java reference.
Maintenance rule (codified in CLAUDE.md)
Before claiming any future work "ports X from Java":
If zero matches → research → goes in
research-track.md, notjava-parity.md.Files changed
CLAUDE.md— new maintenance rule section + doc map count 23 → 24README.md— test count fix (170 → 176+36)doc/math/references.md— Luo 2004 reframed + 4 new entries (Bowers-Stephenson, Glickenstein, BPS 2010, Schläfli)doc/roadmap/phases.md— Phase 9 reorganised (9a.1 vs 9a.2, 9b research-tag), Phase 10 expanded with Java prerequisites + line countsdoc/roadmap/java-parity.md— Inversive-Distance row corrected, HyperIdeal Hessian section rewritten with correction notice, worth-porting table replaced with survey resultsdoc/tutorials/add-inversive-distance.md— full rewritedoc/roadmap/research-track.md— new, consolidated research catalogue with citations and acceptance criteriaWhy a separate PR
This is pure documentation that:
A full audit of `doc/` plus root-level markdown files (27 files) against the actual ground truth in the C++ code and the local Java repository at `/Users/tarikmoussa/Desktop/conformallab/` revealed four pre-existing mis-labels and a stale test count. All are corrected here. Audit findings — corrected ───────────────────────── 1. **`InversiveDistanceFunctional` mis-labelled as Java port** (4 doc sites) Empirical verification: find /Users/tarikmoussa/Desktop/conformallab -iname "*nversive*" (zero matches) The class does NOT exist in `de.varylab.discreteconformal`. The C++ implementation is built from Luo 2004 + Glickenstein 2011 + Bowers- Stephenson 2004 — new research, not a port. Fixed in: java-parity.md, references.md, add-inversive-distance.md. 2. **HyperIdeal Hessian mis-labelled as "Java has analytic Hessian"** Empirical verification: `HyperIdealFunctional.java:295-298`: public boolean hasHessian() { return false; } Java has NO Hessian at all. Both the FD (Phase 4a) and the block-FD (Phase 9b) Hessians in C++ are research beyond the Java port. The chain rule (b,a) → ℓ → ζ → α/β is the *mathematical formulation* from Springborn 2020, not something Java implements. Fixed in: java-parity.md. 3. **Stale test count** README:87 said "28 suites, 170 tests" — current actual is 35 suites, 176 CGAL + 36 non-CGAL. Fixed. 4. **Tutorial framing** — `add-inversive-distance.md` was framed as "porting an InversiveDistanceFunctional.java" that does not exist. Rewritten as "Implementing the Inversive-Distance functional from Luo 2004" with prominent verification block at top. New document: `doc/roadmap/research-track.md` ───────────────────────────────────────────── Consolidates everything in conformallab++ that goes beyond a Java port: * Items already on `main`: HyperIdeal FD Hessian, period matrix τ partial-research components, Möbius holonomy storage. * Items on open PRs: CP-Euclidean (PR #8, port), Inversive-Distance (PR #8, research), block-FD Hessian (PR #9, research). * Planned research with full citations: - **Phase 9b-analytic** — full analytic HyperIdeal Hessian via Schläfli identity (Schläfli 1858/60) and chain rule through ζ₁₃/ζ₁₄/ζ₁₅, citing Springborn 2020 §4, Cho-Kim 1999, Glickenstein 2011 §4. Includes acceptance-criteria checklist (per-case derivative cross-checks, gauge null space, PSD, measured ≥ 3× speed-up, LaTeX correctness note). - **Phase 9a.2-analytic** — analytic inversive-distance Hessian via Glickenstein 2011 eq. (4.6). - **Phase 10c** — full uniformization for genus g ≥ 2 (Fuchsian group representation) — fully new research, no Java reference. - **geometry-central** GC-1/2/3 exploratory track. * Java backlog summary: 11 worth-porting Java classes identified by the parallel survey (FundamentalPolygonUtility, DiscreteHarmonicForm- Utility, DiscreteHolomorphicFormUtility, CanonicalBasisUtility, HyperbolicCyclicFunctional, QuasiisothermicUtility, KoebePolyhedron, …). ~6 500 Java lines, ~5 months of porting work, organised by phase. Updated documents ───────────────── * CLAUDE.md - New "Port-vs-research maintenance rule" with empirical verification command and the four corrected mis-labels. - Doc map: 23 → 24 documents (research-track.md added). * README.md - Test count corrected (170 → 176+36). * doc/math/references.md - Luo 2004 entry corrected ("new research" instead of "not yet ported"). - New entries for Bowers-Stephenson 2004, Glickenstein 2011, Bobenko-Pinkall-Springborn 2010, Schläfli 1858/60. * doc/roadmap/phases.md - Phase 9 reorganised: 9a split into 9a.1 (port) / 9a.2 (research), 9b clarified as research (Java has no Hessian), 9c expanded with Java line counts and effort estimates. - Phase 10 reorganised: 10a/10b/10c with their Java prerequisites explicitly listed; 10c flagged as "fully new research". - Phase 10b' added: parallel research track (hyperbolic functional, quasi-isothermic, Möbius centering). - Phase 10c' added: optional Java-port additions (Koebe, circle patterns, electrostatic sphere). * doc/roadmap/java-parity.md - Inversive-distance row: ❌ Java, ❌ C++ (Phase 9a.2) — new research. - CP-Euclidean row added: ✅ Java, ❌ C++ (Phase 9a.1) — port. - HyperIdeal Hessian row: ❌ Java, ⚠️ FD + block-FD in C++. - Worth-porting table replaced with the survey results (12 classes, Java line counts, suggested phases). - "HyperIdeal Hessian: FD vs analytic" section rewritten with the correction notice. * doc/tutorials/add-inversive-distance.md - Rewritten end-to-end with prominent verification block at top. - Now correctly framed as "Implementing the Inversive-Distance functional from Luo 2004" — research, not port. - Includes the four required cross-validations: limit cases, Bowers-Stephenson round-trip, FD-vs-analytic, cross-validation against euclidean_functional at u=0. - New "How to know if it's a port or research" closing section with the empirical verification command. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>