4f0a3035e4
Some checks failed
C++ Tests / test-fast (push) Successful in 2m50s
C++ Tests / test-fast (pull_request) Successful in 2m36s
API Docs / doc-build (pull_request) Successful in 1m10s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / test-cgal (pull_request) Failing after 10m25s
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>
5.0 KiB
5.0 KiB
References
Primary source
This library implements the algorithms from:
| Sechelmann — Variational Methods for Discrete Surface Parameterization: Applications and Implementation, Doctoral thesis, TU Berlin 2016 | The complete mathematical foundation: discrete conformal equivalence, variational angle-sum functionals, Newton solver, uniformization, period matrices, holonomy. DOI: 10.14279/depositonce-5415 · CC BY-SA 4.0 |
Java reference implementation: github.com/varylab/conformallab
References by module
| Reference | Used in |
|---|---|
| Springborn — Ideal Hyperbolic Polyhedra and Discrete Uniformization, Discrete & Computational Geometry (2020) | hyper_ideal_geometry.hpp — ζ₁₃/ζ₁₄/ζ₁₅ functions; hyper_ideal_functional.hpp |
| Pinkall, Polthier — Computing Discrete Minimal Surfaces and Their Conjugates, Experimental Mathematics (1993) | euclidean_hessian.hpp — cotangent Laplacian |
| Bobenko, Springborn — Variational Principles for Circle Patterns and Koebe's Theorem, Transactions AMS (2004) | Variational angle-sum framework underlying all three functionals |
| Luo — Combinatorial Yamabe Flow on Surfaces, Communications in Contemporary Mathematics (2004) | Inversive-distance functional — new research in Phase 9a.2 (no Java original; implemented from this paper + Glickenstein 2011 + Bowers-Stephenson 2004) |
| Bowers, Stephenson — Uniformizing dessins and Belyĭ maps via circle packing, Memoirs of the AMS 170(805) (2004) | Bowers-Stephenson identity I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j) used to initialise inversive distance from input geometry (Phase 9a.2) |
| Glickenstein — Discrete conformal variations and scalar curvature on piecewise flat manifolds, J. Differential Geometry 87 (2011) | Analytic Hessian of the inversive-distance functional (eq. 4.6) and cross-correspondence I_ij = cos θ_e between vertex-based (9a.2) and face-based (9a.1) circle packings |
| Bobenko, Pinkall, Springborn — Discrete conformal maps and ideal hyperbolic polyhedra, Geometry & Topology 14 (2010) | Face-based circle-packing functional (CPEuclideanFunctional.java → cp_euclidean_functional.hpp, Phase 9a.1) |
| Schläfli — On the multiple integral ∫dx dy …, Quarterly Journal of Pure and Applied Mathematics (1858/60) | Volume differential 2 dV = Σ_e aₑ dαₑ + Σ_v bᵥ dβᵥ — foundation for the analytic HyperIdeal Hessian via Schläfli identity (Phase 9b-analytic, new research beyond Java) |
| Erickson, Whittlesey — Greedy Optimal Homotopy and Homology Generators, SODA (2005) | cut_graph.hpp — tree-cotree algorithm |
| Bobenko, Springborn — A Discrete Laplace–Beltrami Operator for Simplicial Surfaces, Discrete & Computational Geometry (2007) | Background for cotangent weights |
| Desbrun, Kanso, Tong — Discrete Differential Forms for Computational Modeling, SIGGRAPH Course Notes (2006) | Discrete exterior calculus background for Phase 10a |
geometry-central cross-reference (optional comparison track)
These references relate to an alternative implementation of the same mathematical problem. They are not prerequisites for conformallab++, but are relevant for cross-validation and possible algorithmic adoptions (→ GC-1/2/3 in the phase roadmap, → Section 9 in
validation.md).
| Reference | Relevance |
|---|---|
| Gillespie, Springborn, Crane — Discrete Conformal Equivalence of Polyhedral Surfaces, ACM SIGGRAPH 2021. DOI: 10.1145/3450626.3459763 | Implemented in geometry-central. Extends Springborn 2020 with intrinsic triangulations and Ptolemaic flips. Solves the same DCE problem as conformallab++, but with a different algorithm. |
| Sharp, Soliman, Crane — Navigating Intrinsic Triangulations, ACM SIGGRAPH 2019 | Algorithmic basis for SignpostIntrinsicTriangulation in geometry-central — relevant for GC-2 (optional pre-conditioning). |
Note on Springborn 2020:
The paper "Ideal Hyperbolic Polyhedra and Discrete Uniformization"
(Springborn, Discrete & Computational Geometry 2020) is already implemented in
conformallab++ — it is the direct reference for the HyperIdeal geometry mode
(hyper_ideal_geometry.hpp). The geometry-central implementation (Gillespie 2021)
builds on this paper and augments it with Ptolemaic flips.
Phase 10 references (future research)
| Reference | Relevant for |
|---|---|
| Farkas, Kra — Riemann Surfaces, Springer GTM 71 | Siegel period matrix, Teichmüller theory |
| Siegel — Topics in Complex Function Theory, Vol. 2, Wiley | Siegel upper half-space H_g, Sp(2g,ℤ) reduction |
| Bobenko, Mercat, Schmies — Period Matrices of Polyhedral Surfaces, in: Computational Approach to Riemann Surfaces (2011) | Discrete period matrices on polyhedral surfaces |