ConformalLabpp/doc/roadmap/phases.md

Development Roadmap

Legend: ✅ complete · 🔲 planned

Porting / research boundary:
Phases 1–7 are direct ports of the Java original and its dissertation.
From Phase 8 onwards the work goes beyond the scope of the Java library.
Phase 8 (CGAL package) is infrastructure. Phase 9 is porting of remaining Java features.
Phase 10+ is independent research with no direct Java reference implementation.

---

◼ Porting complete — Phases 1–7

Phase 1   Clausen / Lobachevsky / ImLi₂ special functions            ✅
Phase 2   Hyper-ideal geometry  (ζ, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ)             ✅
Phase 3   CGAL Surface_mesh infrastructure + all three functionals
          (Euclidean, Spherical, HyperIdeal)
          + analytical Hessians for Euclidean + Spherical
          (HyperIdeal Hessian: symmetric FD — analytic deferred to 9b) ✅
Phase 4   Newton solver (SimplicialLDLT + SparseQR fallback)
          + Mesh I/O (OFF/OBJ/PLY) + example programs                ✅   68 tests
Phase 5   Priority-BFS layout + CLI app + JSON/XML serialisation      ✅   95 tests
Phase 6   Gauss–Bonnet check/enforce, tree-cotree cut graph (2g),
          exact hyperbolic trilateration, layout normalisation        ✅  121 tests
Phase 7   MobiusMap, halfedge_uv, Möbius holonomy (SU(1,1)),
          period matrix τ∈ℍ + SL(2,ℤ) reduction,
          fundamental domain parallelogram + tiling                  ✅  176 tests

---

◼ Infrastructure — Phase 8: CGAL Package

Goal: conformallab++ as a standalone CGAL package, submission-ready, fulfilling all CGAL package conventions with a traits-class design compatible with any CGAL-conforming mesh type.

8a   Traits class & concepts
       → include/CGAL/Conformal_map_traits.h
       Separates MeshType, KernelType, ScalarType from the algorithm.
       Enables use with any CGAL-compatible mesh, not just Surface_mesh.
       → Concept checks via static_assert / CGAL_concept_check

8b   Public CGAL header hierarchy
       → include/CGAL/Discrete_conformal_map.h     (user-facing entry header)
       → include/CGAL/Conformal_newton_solver.h
       → include/CGAL/Conformal_layout.h
       → include/CGAL/Conformal_cut_graph.h
       All existing include/conformallab/*.hpp remain as implementation details.

8c   CGAL-style documentation
       → doc/Conformal_map/PackageDescription.txt
       → doc/Conformal_map/fig/                    (pipeline diagrams)
       → Doxygen comments on all public concepts and functions
       → User_manual.md + Reference_manual.md

8d   CGAL test format
       → test/Conformal_map/CMakeLists.txt         (CGAL-style CMake)
       Existing GTest tests remain; CGAL-format tests are added alongside.

8e   Declarative YAML pipeline
       → Lightweight YAML format for reproducible experiments
         (specification in doc/api/cgal-package.md)
       → Validator: checks require/provide tokens before execution
       → CLI integration: conformallab_core --pipeline experiment.yml

---

◼ Phase 9 — Mixed: remaining Java port + first research extensions

Audit 2026-05-21: Phase 9 was originally framed as "remaining porting", but a closer look at the local Java repository revealed: several Phase-9 items are not in Java at all (InversiveDistanceFunctional does not exist; HyperIdealFunctional.java:295-298 declares hasHessian()=false). The plan below now distinguishes Java-port items from research items. Full research catalogue: research-track.md.

9a — Circle-packing functionals  (split 2026-05-19)
─────────────────────────────────────────────────────

9a.1   CPEuclideanFunctional  (Java port)
         → cp_euclidean_functional.hpp
         Java source: CPEuclideanFunctional.java (260 lines)
         Mathematical reference: Bobenko-Pinkall-Springborn 2010
         Status: 🟡 PR #8 open, 10 tests passing.

9a.2   Inversive-distance functional  (RESEARCH, not a port)
         → inversive_distance_functional.hpp
         Java source: NONE.  Empirically verified.
         Mathematical reference: Luo 2004 + Bowers-Stephenson 2004 + Glickenstein 2011
         Status: 🟡 PR #8 open, 11 tests passing.
         Cross-validation: G_id(0) = G_eu(0) at 1e-10 (Glickenstein §5).

9b — HyperIdeal Hessian  (RESEARCH — Java has no Hessian at all)
─────────────────────────────────────────────────────────────────

9b     Block-FD HyperIdeal Hessian
         → Replace full FD in hyper_ideal_hessian.hpp
         Java source: NONE (HyperIdealFunctional.java:295-298 declares
                      hasHessian()==false; Java has NO Hessian).
         Algorithm: per-face 6×6 block, scatter to global sparse matrix.
         Status: 🟡 PR #9 open, 7 tests passing, ~96× speed-up measured.

9b-analytic   Full analytic HyperIdeal Hessian via Schläfli identity
         → planned, see research-track.md
         Mathematical source: Springborn 2020 §4 + Schläfli 1858/60
                              + Cho-Kim 1999 + Glickenstein 2011 §4
         Algorithm: explicit chain rule through (bᵢ,aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ
         Includes: short LaTeX correctness note in doc/math/.
         Effort: 10–14 days net.  Trigger: profiling on V > 5000.

9c — Genus g > 1 fundamental domain  (Java port + research extensions)
──────────────────────────────────────────────────────────────────────

9c     4g-polygon boundary walk (genus g > 1)
         → Extend compute_fundamental_domain() beyond genus 1
         Java sources: FundamentalPolygonUtility.java (698 lines)
                     + CanonicalFormUtility.java (532 lines)
                     + CuttingUtility / SurgeryUtility (~800 lines)
         Mathematical source: Poincaré 1882 + Sechelmann 2016 §5
         Research component: bridging to conformallab++ cut_graph.hpp
                             + holonomy infrastructure.
         Effort: ~2 weeks for fundamental polygon, +2 weeks for surgery
                 layer, +1 week integration.

9d — Cone metrics + sphere utilities (Java port — 2026 library scan) ────────────────────────────────────────────────────────────────────

9d.1   ConesUtility  (Java port: unwrapper/ConesUtility.java)
         → cone_singularities.hpp
         Fills the "⚠️ data structure only" gap in java-parity.md:
         - Detect interior cone vertices (angle deficit ≠ 0)
         - BFS path from cone to mesh boundary → cut edge set
         - Auto-placement: conjugate gradient on Θ-gradient magnitude
         - Quantization: snap cone angles to π/2, π/3, π/6 for
           quad / triangle / hexagonal atlas targets
         Java reference: unwrapper/ConesUtility.java

9d.2   StereographicUnwrapper + SphereUtility  (Java port)
         → stereographic_layout.hpp
         Stereographic projection S²→ℂ∪{∞} + Möbius centering for
         genus-0 surfaces. Converts spherical DCE output to a flat 2-D atlas.
         Java reference: unwrapper/StereographicUnwrapper.java (266 lines)

9d.3   MobiusCenteringFunctional  (Java port, optional upgrade)
         → integrate into layout.hpp normalise_hyperbolic()
         Variational Möbius centering via Lorentz geometry:
           E = Σ log(-⟨x,p⟩/√(-⟨x,x⟩))
         Supplies gradient + Hessian — replaces iterative Fréchet mean.
         Java reference: functional/MobiusCenteringFunctional.java

9e — Circle pattern layout (Java port — complement to Phase 9a.1) ────────────────────────────────────────────────────────────────────

9e     CirclePatternLayout + CirclePatternUtility  (Java port)
         → circle_pattern_layout.hpp
         Phase 9a.1 ported the CPEuclidean energy + solver; this phase
         adds the embedding step (ρ values → actual vertex positions in ℝ²).
         - CirclePatternUtility: compute per-face radii ρ via NTR solver
         - CirclePatternLayout: embed from ρ values (intersection-angle model)
         - CPEuclideanRotation: rotation-invariant CP functional variant
         Java references: unwrapper/circlepattern/CirclePattern{Layout,Utility}.java
                          unwrapper/circlepattern/CPEuclideanRotation.java

---

◼ New research directions — Phases 10d–10g (2026 library scan)

These were identified by a full scan of the Java source tree in 2026. They extend significantly beyond the Java port into new mathematical territory.

10d   CircleDomainUnwrapper  (Koebe–Andreev–Thurston)
         → circle_domain_unwrapper.hpp
         Conformal map of a multiply-connected planar region onto a
         canonical disk-with-holes (classical complex-analysis result).
         Java reference: unwrapper/CircleDomainUnwrapper.java (570 lines)
         Mathematical basis: Koebe–Andreev–Thurston + Beardon–Stephenson 1990

10e   Quasi-isothermic maps
         → quasiisothermic.hpp
         Generalisation of conformal maps for meshes where exact conformality
         is unachievable (high Gaussian curvature, coarse triangulation).
         Includes: Delaunay pre-conditioning, discrete Beltrami field,
                   sin-condition functional, Lawson-correspondence parameterization.
         Java references: unwrapper/quasiisothermic/ (~1 200 lines total)
         Mathematical basis: Lam 2015 + Bohle–Lam–Pinkall–Reitebuch 2015

10f   Koebe polyhedra
         → koebe_polyhedron.hpp
         Koebe–Andreev–Thurston theorem: realize every 3-connected planar
         graph as a convex polyhedron with edges tangent to the unit sphere.
         Connects circle packing with 3-D convex geometry.
         Java reference: unwrapper/koebe/KoebePolyhedron.java (321 lines)
         Mathematical basis: Koebe 1936 + Thurston 1997 (lecture notes)

10g   Cyclic-symmetry functionals
         → cyclic_functional.hpp
         Euclidean and hyperbolic DCE functionals reduced to a cyclic-symmetry
         quotient — dramatically reduces DOFs for ornamental / symmetric surfaces.
         Java references: functional/EuclideanCyclicFunctional.java
                          functional/HyperbolicCyclicFunctional.java (~530 lines)

---

◼ Optional / Hypothetical — geometry-central Cross-Comparison

Status: no planned phase — purely exploratory.
These items are not prerequisites for Phase 8–10. They are of interest because geometry-central (Keenan Crane, CMU) is built on the same mathematical foundations as conformallab++ — in particular Springborn 2020 and its direct extension by Gillespie, Springborn & Crane (SIGGRAPH 2021).
The key difference: geometry-central solves the same problem (discrete conformal equivalence) using intrinsic triangulations + Ptolemaic flips, while conformallab++ applies Newton on the original triangulation.

GC-1  [optional, possible now]
      Mathematical output comparison
        → load the same test meshes (cathead.obj, brezel.obj, torus_4x4.off) into
          both libraries
        → compare UV coordinates, u-vector, residual norm
        → align normalisation conventions (u mean, scaling)
      Goal: independent cross-validation of convergence points.
      Effort: small Python/C++ comparison script, no library restructuring.

GC-2  [optional, useful after Phase 8]
      Intrinsic Delaunay pre-conditioning
        → before the Newton solver: apply geometry-central SignpostIntrinsicTriangulation
          to the input
        → Ptolemaic flips pre-condition the Hessian matrix
        → hypothesis: fewer Newton iterations on non-Delaunay inputs
        → implementable as an optional cmake flag: -DWITH_GC_PRECOND=ON
      Dependency: geometry-central as an optional external dependency
      (header-only parts suffice for the flip algorithm).

GC-3  [hypothetical, Phase 10+ research]
      Ptolemaic flip-based solver as an alternative backend
        → instead of Newton: Ptolemaic flips + penultimate-step normalisation
          (Gillespie–Springborn–Crane 2021 algorithm)
        → comparison: convergence radius, robustness on pathological meshes,
          numerical stability on high-genus surfaces
        → relevant for conformallab++ because the Newton approach can become
          unstable on strongly non-Delaunay meshes (e.g. after remeshing).
      No implementation planned — conceptual note for Phase 10 research.

Connection to the literature:
The Springborn 2020 paper ("Ideal Hyperbolic Polyhedra and Discrete Uniformization") is already implemented in conformallab++ as the HyperIdeal geometry mode (Phase 2/3). The Gillespie–Springborn–Crane 2021 extension — implemented in geometry-central — augments this with intrinsic triangulations and makes the algorithm robust against poor input triangulations. Both share the same mathematical core (discrete conformal equivalence, Gauss–Bonnet, variational principle of Bobenko–Springborn 2004).

---

◼ Phase 10 — Genus g ≥ 2 (research with partial Java support)

Most Phase-10 items have partial Java references (utility classes for forms and homology) but the assembly into a working uniformization pipeline is research. Full catalogue with primary literature: research-track.md.

Phase 10   Global uniformization for genus g ≥ 2

10a  Discrete holomorphic and harmonic 1-forms
       → Integrate basis 1-forms ωᵢ along b-cycles of the cut graph.
       Mathematical reference: Bobenko-Springborn 2004 §6 + Mercat 2001.
       Java sources (partial, port-with-research):
         CanonicalBasisUtility.java        337 lines  (homology basis)
         HomologyUtility.java              122 lines
         DualityUtility.java               308 lines
         DiscreteHarmonicFormUtility.java  657 lines
         DiscreteHolomorphicFormUtility.java 285 lines
       Effort: ~6 weeks net (4 utility ports + 1 integration).

10b  Siegel period matrix Ω ∈ H_g  (g×g complex symmetric, Im(Ω) > 0)
       → Ωᵢⱼ = ∫_{bⱼ} ωᵢ
       → Reduction to Siegel fundamental domain via Sp(2g,ℤ).
       Mathematical reference: Bobenko-Springborn 2004 + Gottschling 1959.
       Java partial reference: DiscreteRiemannUtility.java (186 lines).
       Requires: 10a.
       Effort: ~1 week net after 10a.

10b'  Alternative methods (parallel research track)
       → HyperbolicCyclicFunctional (Java, 530 lines) — completes the
         classical three-mode set with hyperbolic energy.
       → Quasi-isothermic parametrisation (Lawson correspondence):
         QuasiisothermicUtility.java + SinConditionApplication.java
         (~1 200 Java lines combined).
       → MobiusCenteringFunctional (Java, 289 lines) — sphere centering.
       → StereographicUnwrapper (Java, 266 lines) — projects the
         spherical layout S²→ℂ via stereographic projection plus a
         Möbius centring step.  Closes the visualisation gap from
         `discrete_conformal_map_spherical()` (currently outputs
         Point_3 on S²; many downstream uses want a 2-D atlas).
         Effort: small (~3 days).
       Each independent; can be tackled in any order.

10c  Full uniformization for genus g ≥ 2
       → Embedding as H²/Γ with Γ ⊂ PSL(2,ℝ) a Fuchsian group.
       Mathematical reference: Sechelmann 2016 §6 (discrete instance);
                               Bers 1960 (continuous theory).
       Java reference: NONE — Java has the polygon + period matrix
                              pieces but does not assemble them into
                              a Fuchsian-group representation.
       Status: **fully new research.**
       Requires: 10a + 10b + Phase 9c.

10c'  Optional Java-port additions (low priority)
       → KoebePolyhedron.java (321 lines) — Koebe-Andreev-Thurston
         circle packings.  Adds a fifth DCE method.
       → ElectrostaticSphereFunctional (127 lines) — sphere
         distribution baseline.
       → CirclePatternLayout / CirclePatternUtility — face-circle
         pattern layouts.
       None of these are required for the genus-g uniformization
       pipeline; they extend the breadth of methods.

---

◼ Phase 11+ — Specialised applications (optional, deferred)

Status: out-of-scope for v1.0 but recorded here so that future contributors don't re-discover them. Both items live in the Java repo as plugin sub-packages and would benefit from porting only after Phase 10 is complete (they require the period-matrix and fundamental-domain infrastructure to be in place first).

11a   Schottky uniformisation
        Java plugin:        plugin/schottky/* (~12 Java files, ~3 000 LoC)
        Mathematical basis: Schottky group — discrete subgroup
                            Γ ⊂ PSL(2,ℂ) generated by hyperbolic loxodromic
                            elements, fundamental domain a sphere with
                            2g disjoint discs removed.
        Use case:           "handlebody" uniformisation, complement of
                            Phase 10c's Fuchsian-group representation
                            (Schottky represents Riemann surfaces as
                            quotients of domains in S² rather than of H²).
        Requires:           Phase 10b (period matrix) + working
                            Möbius-group machinery from Phase 7.
        Effort:             very large (4–6 weeks) — significant Java
                            code, complex-analytic algorithms,
                            substantial test design.

11b   Riemann maps (planar conformal mapping)
        Java plugin:        plugin/riemannmap/* (~6 Java files, ~1 500 LoC)
        Mathematical basis: Riemann mapping theorem — every simply
                            connected proper subdomain of ℂ is conformally
                            equivalent to the unit disc.  Discrete version
                            via circle packing or Schwarz-Christoffel-like
                            formulae.
        Use case:           Texture mapping of bounded planar regions;
                            classical conformal mapping for engineering
                            applications (electrostatics, fluid flow).
        Requires:           Phase 10b' QuasiisothermicUtility or the
                            CP-Euclidean machinery from Phase 9a.1
                            (depending on the chosen discrete-Riemann
                            algorithm).
        Effort:             large (3–4 weeks) — smaller than Schottky
                            but still substantial.  Heavy on
                            visualisation; consider porting only the
                            algorithmic core.

11c   Multiply-connected planar conformal maps  (CircleDomainUnwrapper)
        Java source:        unwrapper/CircleDomainUnwrapper.java (570 LoC)
        Mathematical basis: Riemann mapping theorem for multiply-
                            connected domains — every n-connected planar
                            region is conformally equivalent to a disk
                            with (n−1) round holes (Koebe's "general
                            uniformization theorem", 1909).
        Use case:           Classical complex-analysis problems —
                            conformal mapping of an annulus, a torus
                            slit on a plane, fluid flow around obstacles,
                            electrostatics with multiple conductors.
                            **A use-case class conformallab++ does not
                            currently cover.**
        Requires:           Phase 10b' QuasiisothermicUtility or the
                            CP-Euclidean machinery from Phase 9a.1.
        Effort:             large (~2 weeks).

All three items are tracked here so the project memory is preserved;
none of them are roadmap commitments.  See `research-track.md` for the
formal research-versus-port classification before starting any.