ConformalLabpp/doc/roadmap/java-parity.md

# Java ConformalLab vs. conformallab++ — Feature Parity

Reference: [github.com/varylab/conformallab](https://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.Matrix`** | 4×4 matrix wrapper (times, print) | ✅ → Eigen `Matrix4d` | `Matrix.times` = matrix multiplication; call-sites replace it with Eigen `operator*`. No separate port needed. |
| **`de.jreality.math.P2`** | Projective plane geometry: `lineFromPoints`, `pointFromLines`, `projectP3ToP2`, `makeDirectIsometryFromFrames`, `imbedMatrixP2InP3`, `chopConvexPolygonWithLine` | ⚠️ **port inline with Phase 9c** | Used almost exclusively by `FundamentalPolygonUtility` + `CanonicalFormUtility` + `SurfaceCurveUtility` (all Phase 9c). Port these ~5 functions as a `p2_geometry.hpp` at the start of the Phase 9c session, not before. `lineFromPoints` / `pointFromLines` = cross products in ℙ²; `makeDirectIsometryFromFrames` = direct isometry from two point-pairs (~25 LOC). |
| **`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. **⚠️ jReality dependency:** uses `P2.makeDirectIsometryFromFrames`, `P2.projectP3ToP2`, `P2.imbedMatrixP2InP3` → port these as `p2_geometry.hpp` at the start of the Phase 9c session (see Infrastructure table above). Also uses `P2Big.*` (high-precision counterparts) + requires `cpp_dec_float_50` for the group-relation product ∏gᵢ = Id. | 9c |
| `CanonicalFormUtility` (532 lines) | High-level wrapper for 9c — drives canonicalisation pipeline. **⚠️ jReality dependency:** same `P2.*` methods as above via `FundamentalPolygonUtility`. | 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
> ```java
> @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.