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)	✅	❌ Phase 9a	InversiveDistanceFunctional.java
Euclidean Hessian — cotangent Laplacian	✅ analytic	✅ analytic	Pinkall–Polthier (1993)
Spherical Hessian — ∂α/∂u via law of cosines	✅ analytic	✅ analytic
HyperIdeal Hessian — ζ → lᵢⱼ → β/α chain	✅ analytic	⚠️ symmetric FD	Phase 9b
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
InversiveDistanceFunctional	Inversive-distance conformal energy	9a
DiscreteHarmonicFormUtility	Discrete harmonic 1-forms	10a prerequisite
DiscreteHolomorphicFormUtility	Holomorphic differentials on discrete surfaces	10a
DiscreteRiemannUtility	Discrete Riemann surfaces	10
CanonicalBasisUtility	Canonical homology basis for genus g	9c / 10
HomologyUtility	Homology computation	9c
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: FD vs. analytic

The Java library computes the HyperIdeal Hessian analytically through the chain:

(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ

conformallab++ uses a symmetric finite-difference approximation:

H[i,j] = ( G(x + ε·eⱼ)[i] − G(x − ε·eⱼ)[i] ) / (2ε),   ε = 1e-5

Accuracy: O(ε²) ≈ 10⁻¹⁰ relative error. PSD guaranteed by strict convexity (Springborn 2020). Cost: n extra gradient evaluations per Newton step. Impact: negligible for meshes < 500 DOFs; measurable for larger meshes.

The analytic Hessian is deferred to Phase 9b.