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`](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.
```

---

## ◼ 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`](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.
       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.

Both items are tracked here so the project memory is preserved; they
are NOT roadmap commitments.  See `research-track.md` for the formal
research-versus-port classification before starting either.
```