ConformalLabpp/doc/roadmap/java-parity.md

Java ConformalLab vs. conformallab++ — Feature Parity

Reference: github.com/varylab/conformallab
Java package root: de.varylab.discreteconformal

When porting a Java class, locate the original in the Java repository and use it as the reference implementation for expected behaviour, edge cases, and test cases.

---

Algorithm parity

Mathematical layer	Java ConformalLab	conformallab++	Notes
Euclidean functional — energy, gradient	✅	✅
Spherical functional — energy, gradient, gauge-fix	✅	✅
HyperIdeal functional — energy, gradient	✅	✅
Inversive-distance functional (Luo 2004)	❌ (not in Java)	❌ Phase 9a.2	No Java source. Implemented in C++ from Luo 2004 + Glickenstein 2011 + Bowers-Stephenson 2004 — new research, not a port. Verified: find /Users/tarikmoussa/Desktop/conformallab -iname "*nversive*" returns zero.
CP-Euclidean functional (BPS 2010)	✅	❌ Phase 9a.1	CPEuclideanFunctional.java (260 lines) — face-based circle packing
Euclidean Hessian — cotangent Laplacian	✅ analytic	✅ analytic	Pinkall–Polthier (1993)
Spherical Hessian — ∂α/∂u via law of cosines	✅ analytic	✅ analytic
HyperIdeal Hessian — analytic via ζ → l → β/α	❌ (hasHessian()==false)	⚠️ FD (Phase 4a) → block-FD (Phase 9b)	Java has NO Hessian for HyperIdeal (verified: HyperIdealFunctional.java:295-298 declares hasHessian() { return false; }). Both C++ Hessian variants are new research beyond Java; analytic Schläfli-based variant is Phase 9b-analytic.
Newton solver	✅	✅
SparseQR fallback for gauge modes	unknown	✅	New in C++
Cone metrics — prescribed Θᵥ ≠ 2π	✅ fully	⚠️ data structure only
Layout / embedding — ℝ² / H² / S²	✅	✅ priority-BFS all three
Exact hyperbolic trilateration	✅ Möbius	✅ Möbius + law of cosines
halfedge_uv — seam-aware UV (texture atlas)	✅	✅
Gauss–Bonnet consistency check	✅	✅
Tree-cotree cut graph (2g edges)	✅	✅ Erickson–Whittlesey (2005)
Holonomy — Euclidean (translations)	✅	✅
Holonomy — Hyperbolic (SU(1,1) Möbius maps)	✅	✅
Period matrix τ — genus 1, SL(2,ℤ)-reduced	✅	✅
Fundamental domain — genus 1	✅	✅ CCW parallelogram
4g-polygon boundary walk — genus g > 1	✅	❌ Phase 9c	FundamentalDomainUtility.java
Siegel period matrix Ω — genus g ≥ 2	✅	❌ Phase 10b
Global uniformization — genus g ≥ 2	✅	❌ Phase 10c
Clausen / Lobachevsky / ImLi₂	✅	✅
Poincaré disk / Lorentz boost visualisation	✅	✅
Mesh I/O + serialisation	✅ XML/CoHDS	✅ OFF/OBJ/PLY + JSON/XML
Interactive viewer	✅ jReality	✅ libigl/GLFW

---

Java utility classes not yet ported

These exist in de.varylab.discreteconformal.util in the Java library. They are candidates for Phase 9 or Phase 10.

Java class	Description	Phase
CPEuclideanFunctional	Face-based circle-packing energy (BPS 2010)	9a.1
FundamentalPolygonUtility (698 lines)	Construction + canonicalisation of 4g-gons for genus-g	9c
CanonicalFormUtility (532 lines)	High-level wrapper for 9c — drives canonicalisation pipeline	9c
CuttingUtility + SurgeryUtility (~800 lines)	Mesh cuts and gluing operations needed for fundamental domains	9c (foundation)
DiscreteHarmonicFormUtility (657 lines)	Discrete harmonic 1-forms via cotangent Laplacian (Hodge theory)	10a prerequisite
DiscreteHolomorphicFormUtility (285 lines)	Holomorphic differentials via Mercat complex structure	10a (Bobenko-Springborn 2004 §6)
CanonicalBasisUtility (337 lines)	Symplectic homology basis with intersection-form normalisation	10a prerequisite
DiscreteRiemannUtility (186 lines)	Period matrix τ, Siegel reduction (genus g)	10b
DualityUtility (308 lines), HomologyUtility (122 lines)	Primal/dual cohomology, cycle generators	10a support
HyperbolicCyclicFunctional (530 lines)	Discrete hyperbolic conformal energy (analogue of Euclidean) — completes the geometry suite	10b–c
QuasiisothermicUtility + SinConditionApplication (~1200 lines)	Lawson-correspondence parametrisation, sin-condition functional	10b
KoebePolyhedron (321 lines)	Koebe–Andreev–Thurston circle-packing construction	10c
ElectrostaticSphereFunctional, MobiusCenteringFunctional	Sphere-domain pre-processing functionals	10c (optional)

Note: items marked as new research (e.g. Inversive Distance, HyperIdeal Hessian variants) are tracked separately in doc/roadmap/research-track.md. | HomotopyUtility | Homotopy generators | 9c | | SpanningTreeUtility | Spanning tree algorithms | 8 / infrastructure | | SurgeryUtility | Mesh surgery (cut/glue) | — | | StitchingUtility | Seam stitching | — | | CuttingUtility | Advanced cutting (beyond tree-cotree) | 9c | | HyperellipticUtility | Hyperelliptic surfaces | 10 | | LaplaceUtility | Discrete Laplace operators | 9 / infrastructure | | ConformalStructureUtility | Conformal structure extraction | 10 |

---

HyperIdeal Hessian — correction of an earlier mis-claim

2026-05-21 audit: A previous version of this document claimed "the Java library computes the HyperIdeal Hessian analytically through the chain (bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ". This is incorrect. The Java source file HyperIdealFunctional.java line 295-298 declares

@Override
public boolean hasHessian() {
    return false;
}

i.e. the upstream Java implementation supplies no HyperIdeal Hessian at all — neither analytic nor numerical. The chain rule above is the mathematical formulation (from Springborn 2020 §4 + Schläfli 1858), not something the Java code implements.

Actual state of HyperIdeal Hessian in conformallab++

Variant	Status	Notes
Phase 4a — full FD H[i,j] = (G(x+εeⱼ)[i] − G(x−εeⱼ)[i]) / (2ε)	✅ implemented	O(n·F) cost; PSD by Springborn 2020 strict convexity
Phase 9b — block-FD (per-face 6×6 local block, scatter to global)	✅ implemented (PR #9)	O(F·36) cost; ~96× speed-up over Phase 4a measured on V=200 mesh
Phase 9b-analytic — Schläfli identity + chain rule through ζ₁₃/ζ₁₄/ζ₁₅	🔲 planned (research)	See doc/roadmap/research-track.md for the formal plan and citations

All three are new research beyond the Java port. Java parity for HyperIdeal stops at the gradient.