ff9c9ec11b
Audit found that 2 of the 4 Java-port candidates from the conformal-
mapping discussion were missing from the documentation:
* StereographicUnwrapper (266 Java LoC) — projects spherical layout
S² → ℂ via stereographic projection + Möbius centring. Closes the
visualisation gap from discrete_conformal_map_spherical() which
currently returns Point_3 on S²; downstream uses typically want a
2-D atlas. Suggested phase: 10b' (alternative methods, parallel
to Hyperbolic / Quasi-isothermic). Effort: small (~3 days).
* CircleDomainUnwrapper (570 Java LoC) — conformal map of a
multiply-connected planar region onto a disk-with-holes (Koebe's
general uniformization theorem 1909). A use-case class
conformallab++ does not currently cover (annulus, slit torus,
fluid flow around obstacles, electrostatics with multiple
conductors). Suggested phase: 11c. Effort: large (~2 weeks).
Added to all three roadmap documents:
* doc/roadmap/java-parity.md — worth-porting table extended
* doc/roadmap/research-track.md — Java-backlog summary extended
* doc/roadmap/phases.md — Phase 10b' bullet + new
Phase 11c block with full math
context (Koebe 1909 reference,
classical complex-analysis use cases).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
108 lines
7.1 KiB
Markdown
108 lines
7.1 KiB
Markdown
# 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π | ✅ 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 |
|
||
| `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) |
|
||
|
||
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
|
||
> ```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.
|