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
```

---

## ◼ Remaining porting — Phase 9

Java features from `de.varylab.discreteconformal` not yet in C++:

```
9a   Circle-packing / inversive-distance functionals
     ───────────────────────────────────────────────
     Status: discovered during 9a-prep audit (2026-05-19) that the
     original roadmap mention "inversive_distance_functional.hpp" was
     based on a misreading — the Java repo at de.varylab.discreteconformal
     does NOT contain InversiveDistanceFunctional.java.  It contains the
     related CPEuclideanFunctional.java which is the face-dual variant
     (Bobenko-Pinkall-Springborn 2010).  These are two mathematically
     distinct models that both belong in this phase.  Plan split:

9a.1 CPEuclideanFunctional (FACE-based circle packing)
       → cp_euclidean_functional.hpp
       Java reference: CPEuclideanFunctional.java (260 lines) + test
       Mathematical reference:
         Bobenko, Pinkall, Springborn (2010) — "Discrete conformal maps
         and ideal hyperbolic polyhedra", Geom. Topol. 14, 379-426.
       DOFs:           ρ_f per FACE  (log-radius of the face-circle)
       Constants:      θ_e per edge  (intersection angle, π/2 = orthogonal)
                       φ_f per face  (target face-angle sum, default 2π)
       Energy:         E(ρ) = -Σ_f φ_f·ρ_f
                            + Σ_e [½·p(θ*_e, Δρ_e)·Δρ_e + Λ(θ*_e + p)]
                       where p = 2·atan(tan(θ*/2)·tanh(Δρ/2)),
                       Λ = Clausen function, θ* = π − θ.
       Hessian:        analytic, 2×2 per interior edge:
                       h_jk = sin(θ) / (cosh(Δρ) − cos(θ))
       Gauge:          first face is pinned (ρ_0 = 0)

       New CGAL entry:  CGAL::discrete_circle_packing_euclidean(mesh, np)
       Test suite:      test_cp_euclidean_functional.cpp
                        (Dodecahedron-with-removed-face, θ=π/2,
                         FD gradient check, FD-vs-analytic Hessian check)

9a.2 Inversive-distance functional (VERTEX-based)
       → inversive_distance_functional.hpp
       Java reference: NONE (does not exist upstream)
       Mathematical reference:
         Luo, F. (2004) "Combinatorial Yamabe Flow on Surfaces",
            Commun. Contemp. Math. 6(5), 765-780.
         Bowers, P. & Stephenson, K. (2004) "Uniformizing dessins
            and Belyĭ maps via circle packing", Mem. AMS 170(805).
         Glickenstein, D. (2011) "Discrete conformal variations and
            scalar curvature on piecewise flat manifolds",
            J. Diff. Geom. 87(2), 201-238  (analytic Hessian).
       DOFs:           u_i per VERTEX  (u_i = log r_i)
       Constants:      I_ij per edge   (inversive distance, computed
                                        once from initial geometry:
                                        I_ij = (ℓ_ij² − r_i² − r_j²)
                                             / (2 r_i r_j))
                       Θ_v per vertex  (target cone angle, default 2π)
       Edge length:    ℓ_ij(u)² = e^{2u_i} + e^{2u_j} + 2 I_ij e^{u_i+u_j}
       Angles:         identical half-tangent atan2 form to Euclidean
       Gradient:       ∂E/∂u_v = Θ_v − Σ_{T∋v} α_v(T)
                       (Luo 2004 Lemma 3.1)
       Energy:         path integral E(u) = ∫₀¹⟨G(tu),u⟩dt
                       (Luo's 1-form is closed; no general closed form,
                        use 10-point Gauss-Legendre as in Euclidean)
       Hessian:        FD for MVP; analytic (Glickenstein 2011 eq. 4.6)
                       as future optimisation
       Gauge:          first vertex pinned (u_0 = 0)

       New CGAL entry:  CGAL::discrete_inversive_distance_map(mesh, np)
       Test suite:      test_inversive_distance_functional.cpp
                        (small triangle + quad + tetra, FD gradient
                         check, convergence test, special case I=1
                         coincides with tangential circle packing)

Cross-validation between 9a.1 and 9a.2 (Glickenstein 2011 §5):
       In the tangential limit (θ_e = 0 in 9a.1 ⇔ I_ij = 1 in 9a.2),
       both functionals describe the same circle packing.  Their
       converged radii must satisfy
            ρ_f(9a.1)  vs  ½·log(r_i·r_j) (9a.2)
       under the appropriate vertex↔face dual correspondence.  This
       cross-check is part of the Phase 9a acceptance tests.

9b   Analytic HyperIdeal Hessian
       → Replace FD Hessian in hyper_ideal_hessian.hpp
       Direct differentiation through the chain:
         (bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ
       Relevant for meshes > 500 DOFs (current FD Hessian is slow there).

9c   4g-polygon boundary walk (genus g > 1)
       → Extend compute_fundamental_domain() beyond genus 1
       Algorithm outline already in fundamental_domain.hpp as TODO(Phase 9).
       Java reference: FundamentalDomainUtility.java
```

---

## ◼ 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).

---

## ◼ New research — Phase 10+

No direct Java reference implementation exists for these items.

```
Phase 10   Global uniformization for genus g ≥ 2

10a  Discrete holomorphic differentials
       Integrate basis 1-forms ωᵢ along b-cycles of the cut graph.
       Mathematical basis: Bobenko–Springborn (2004), §6.
       Java partial reference: DiscreteHolomorphicFormUtility.java

10b  Siegel period matrix Ω ∈ H_g  (g×g complex symmetric, Im(Ω) > 0)
       Ωᵢⱼ = ∫_{bⱼ} ωᵢ
       Reduction to Siegel fundamental domain via Sp(2g,ℤ).
       Requires: 10a

10c  Full uniformization for genus g ≥ 2
       Embedding as H²/Γ with Γ ⊂ PSL(2,ℝ) a Fuchsian group.
       Requires: 10a + 10b + stable cut graph for g ≥ 2 (Phase 9c)
```