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π (Euclidean)	✅ fully	❌ Phase 9d.1 (port)	Java Euclidean-only; ConesUtility.java ~200 lines
Cone metrics — non-Euclidean (HyperIdeal / Spherical)	❌ (not in Java)	❌ Phase 9d.2 (research)	No Java source. Mathematical basis: Bobenko-Lutz 2025 (decorated DCE) + Crane et al. 2018 (optimal cone placement).
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

---

Infrastructure / support layers

These are not algorithmic phases but shared geometry substrates that multiple phases depend on. Porting them once unblocks all downstream consumers.

Java library	What it provides	C++ status	Notes
de.jreality.math.Pn	Projective-metric primitives: inner product, norm, distance, geodesic interpolation in Euclidean / Elliptic / Hyperbolic signatures	⚠️ partial → pn_geometry.hpp (2026-05-30)	6 functions (~30 LOC) cover the entire surface used by the Java algorithmic core (27 files, ≈106 imports). Unblocks: HyperbolicLayout, SphericalLayout, FundamentalPolygon (9c), KoebePolyhedron (10c'), quasi-isothermic (10e), hyperelliptic θ, CircleDomain (11c).
de.jreality.math.Rn	Real vector / matrix utilities (add, sub, scale, dot, norm, …)	⚠️ partial → Eigen	The Rn surface used in the core (16 distinct methods) maps directly onto Eigen VectorXd / MatrixXd operations. No separate port needed; call-sites replace Rn.foo(a,b) with Eigen expressions inline.
de.jreality.math.MatrixBuilder	Isometry construction: rotateFromTo, translateFromTo in Euclidean / Hyperbolic models	❌ not yet	Used only by HyperIdealHyperellipticUtility (hyperelliptic θ). Port on demand when that utility is needed.
conformallab XML types (de.varylab.conformallab.types.*)	JAXB-generated persistence format for Java GUI state (HalfedgeEmbedding, UniformizationData, …)	❌ not planned	GUI / persistence layer, not an algorithmic substrate. conformallab++ has its own serialisation (serialization.hpp). Asset-specific parsers (e.g. for lawson_curve_source.xml) are added on demand, not as a general port.

---

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
ConesUtility (~200 lines)	Prescribed cone angles Θᵥ ≠ 2π — Euclidean mode only	9d.1
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
HomotopyUtility (57 lines)	Reconstructs explicit generator cycles (bridge + tree path) — NOT covered by cut_graph.hpp (which gives only the 2g cut edges). Verified 2026-05-28.	10a
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
StereographicUnwrapper (266 lines)	Stereographic projection S²→ℂ + Möbius centring — converts the Spherical-DCE output into a 2-D atlas	10b' (Sphere visualisation)
CircleDomainUnwrapper (570 lines)	Conformal map of a multiply-connected planar region onto a disk-with-holes — classical complex-analysis use case	11+ (new use-case class)
ElectrostaticSphereFunctional, MobiusCenteringFunctional	Sphere-domain pre-processing functionals	10c (optional)
IsothermicityMeasure (113), DiscreteConformalEquivalencemMeasure (82), FlippedTriangles (17), LengthCrossRatio (12)	Quantitative conformal-quality / embedding-validity measures (math is GUI-independent)	9g (added 2026-05-28)
DEC, AbstractDECOperator, DECPairing, DualChain, DualForm (heds/dec/)	Discrete-exterior-calculus operator layer (d / ⋆ / pairing) — foundation the Phase-10a form utilities sit on	10a prerequisite (added 2026-05-28)
SurfaceCurveUtility (360)	Curve operations on the surface (cut-path tracing) — supports 9c polygon construction	9c (added 2026-05-28)

Note: items marked as new research (e.g. Inversive Distance, HyperIdeal Hessian variants) are tracked separately in doc/roadmap/research-track.md.

2026-05-28 scan — valuable items that had been in no phase

A class-by-class cross-reference of all 232 Java production classes against the roadmap found that the "big math" (Schottky 11a, Koebe 10c′/10f, quasi-isothermic 10e, circle-pattern layout 9e) is all already planned. Three genuinely useful items were unrecorded and have now been added above:

1. Conformal-quality measures → new Phase 9g (small, no dependencies; raises validation coverage for the already-shipped pipeline).
2. DEC operator layer (heds/dec/) → noted as a Phase 10a prerequisite (the form utilities assume these primitives exist).
3. SurfaceCurveUtility → folded into the Phase 9c source list.

Everything else unmentioned is intentionally out of scope: the plugin/* jReality Swing GUI, the MTJ*/Tao*/*PETSc solver bindings (replaced by Eigen), the convergence/*Series test harness, and the *Big arbitrary-precision geometry (P2Big/PnBig/RnBig — deliberately dropped from the core in favour of Simple_cartesian<double>).

Exception — *Big is NOT permanently out of scope. The Phase 9c/10 uniformization classes (FundamentalPolygonUtility, CanonicalFormUtility, rows 55–56 above) build on the *Big classes in Java for a reason: products of hyperbolic isometry generators grow exponentially, so double fails when verifying the group relation ∏gᵢ = Id (MathContext(50) = 50 significant digits in Java). When those classes are ported, a localized high-precision substrate (boost::multiprecision::cpp_dec_float_50 or MPFR mpreal) must be reintroduced — only inside the uniformization module, not in the core flattening or the Eigen solver. See the Phase-9 note in CLAUDE.md.

---

Java packages not yet in the roadmap — 2026 full-library scan

A complete scan of the Java source tree (de.varylab.discreteconformal) revealed the following packages and classes not yet covered by Phases 1–9c or the Phase-10 plan. Organised by value / effort.

Functional package (de.varylab.discreteconformal.functional)

Java class	What it does	Proposed phase
ConesUtility (in unwrapper/)	Cone singularity detection, BFS-path cutting from cone to boundary, auto-placement via conjugate gradient, quantization to π/2 / π/3 / π/6 — fills the "⚠️ data structure only" gap in the parity table	9d
MobiusCenteringFunctional	Variational Möbius centering via Lorentz geometry: E = Σ log(−⟨x,p⟩/√(−⟨x,x⟩)). Supplies full gradient + Hessian — more principled than the iterative Fréchet mean in normalise_hyperbolic()	9d
ElectrostaticSphereFunctional	Repulsive electrostatic energy on S² (E = Σ 0.5/d² + sphere constraint). Useful as initialization heuristic for spherical uniformization	9d (optional)
EuclideanCyclicFunctional	Euclidean DCE functional reduced to a cyclic-symmetry quotient — reduces DOFs for surfaces with cyclic symmetry group	10g
HyperbolicCyclicFunctional	Hyperbolic analogue of above	10g

Circle pattern package (de.varylab.discreteconformal.unwrapper.circlepattern)

Java class	What it does	Proposed phase
CirclePatternUtility	Computes circle pattern radii (ρ per face) via Newton trust-region on CPEuclidean energy — the solver side	9e
CirclePatternLayout	Embeds a circle pattern in the plane from the ρ values — the layout side. Required complement to cp_euclidean_functional.hpp already ported in 9a.1	9e
CPEuclideanRotation	Rotation-invariant variant of the CP-Euclidean functional	9e

Uniformization package (de.varylab.discreteconformal.uniformization)

Java class	What it does	Proposed phase
CutAndGlueUtility	Mesh surgery beyond tree-cotree: arbitrary cut paths, gluing cut surfaces back together — needed for genus g > 1 canonical polygon construction	9c (add to existing plan)
VisualizationUtility	Java/jReality specific — do not port	—
Uniformizer	High-level pipeline driver — already covered by our CLI + pipeline API	—

Unwrapper package — additional classes

Java class	What it does	Proposed phase
StereographicUnwrapper	Stereographic projection S²→ℂ∪{∞} + Möbius centring — converts spherical DCE output to 2-D atlas for genus-0	9d
SphereUtility	Sphere-specific utilities (area centroid, antipodal, normalization helpers)	9d
CircleDomainUnwrapper	Conformal map of multiply-connected planar region onto disk-with-holes (Koebe-Andreev-Thurston)	10d

Quasi-isothermic package (de.varylab.discreteconformal.unwrapper.quasiisothermic)

Quasi-isothermic maps generalize conformal maps to meshes where exact conformality is impossible. Entirely absent from the current roadmap.

Java class	What it does	Proposed phase
QuasiisothermicDelaunay	Delaunay-conformal triangulation as QI preprocessing	10e
QuasiisothermicLayout	Embedding from quasi-isothermic DOFs	10e
QuasiisothermicUtility	Lawson-correspondence parameterization (~800 lines)	10e
DBFSolution	Discrete Beltrami field solution	10e
SinConditionApplication	Sin-condition functional for QI maps	10e
ConformalStructureUtility	Conformal structure extraction from QI solution	10e

Koebe package (de.varylab.discreteconformal.unwrapper.koebe)

Java class	What it does	Proposed phase
KoebePolyhedron	Koebe–Andreev–Thurston theorem: realization of every 3-connected planar graph as a convex polyhedron with edges tangent to the unit sphere (321 lines)	10f

Util package — additional classes not yet in roadmap

Java class	What it does	Proposed phase
DualityUtility	Hodge-star operator + dual cycles via cotangent weights — prerequisite for Phase 10a (discrete holomorphic forms need the dual mesh)	10a prerequisite (consider 9c)
HyperellipticUtility	Hyperelliptic surfaces (genus g ≥ 2 with Z₂ symmetry) — period matrix has block-diagonal structure	10b
HyperIdealHyperellipticUtility	HyperIdeal variant for hyperelliptic surfaces	10b
PathUtility	Mesh path operations — supporting infrastructure for Phase 9c homology basis	9c
LaplaceUtility	Discrete Laplace operators (cotangent + combinatorial)	9 / infrastructure
EdgeUtility	Edge orientation and classification helpers	infrastructure
StitchingUtility	Seam stitching after cut-and-glue	9c

Do not port — Java-specific or superseded

Java class	Reason
ColtIterationReporterImpl	Colt sparse matrix library — replaced by Eigen
NodeIndexComparator	Java Comparator — replaced by std::less
SimpleMatrixPrintUtility	Debug print — Eigen .format() is sufficient
EuclideanUnwrapperPETSc / SphericalNormalizerPETSc	PETSc solver binding — replaced by Eigen
Search	CoHDS-specific graph search — replaced by CGAL halfedge iteration
SparseUtility	Colt sparse matrix utils — replaced by Eigen
SpanningTreeUtility	Primal + dual spanning tree — already implemented inline in cut_graph.hpp (tree-cotree Steps 1+2). Verified 2026-05-28.
convergence/* harness (CLI driver, ~1400 lines)	The driver depends on Mathematica (JLink) + jReality OBJ reader + LoopLinear. Do not port the harness — only its math: quality measures → 9g.1, study method → 9g.2 (optional). Verified 2026-05-28.
datasource/* (ConicalEdgesDataSource, CylinderEdgesDataSource)	jReality SceneGraph viewer decoration (draws cone/cylinder edge arcs) — NOT example geometry; nothing to harvest. Verified 2026-05-28.

---

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.