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   ✅
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                  ✅  158 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   Inversive-distance functional (Luo 2004 / Bowers–Stephenson)
       → inversive_distance_functional.hpp
       Follows the exact same pattern as the three existing functionals.
       → newton_inversive_distance()
       → New test suite: test_inversive_distance.cpp

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: keine geplante Phase — rein explorativ.**  
> Diese Punkte sind keine Voraussetzung für Phase 8–10. Sie sind
> interessant, weil geometry-central (Keenan Crane, CMU) auf denselben
> mathematischen Grundlagen wie conformallab++ aufbaut — insbesondere auf
> **Springborn 2020** und der direkten Weiterentwicklung durch
> **Gillespie, Springborn & Crane (SIGGRAPH 2021)**.  
> Der entscheidende Unterschied: geometry-central löst dasselbe Problem
> (diskrete konforme Äquivalenz) mit **intrinsischen Triangulierungen +
> Ptolemäischen Flips**, während conformallab++ **Newton auf der
> Original-Triangulierung** anwendet.

```
GC-1  [optional, jetzt möglich]
      Mathematischer Output-Vergleich
        → gleiche Testnetze (cathead.obj, brezel.obj, torus_4x4.off) in
          beide Bibliotheken laden
        → UV-Koordinaten, u-Vektor, Residualnorm vergleichen
        → Normalisierungskonventionen abgleichen (u-Mittelwert, Skalierung)
      Ziel: unabhängige Kreuz-Validierung der Konvergenzpunkte.
      Aufwand: kleines Python/C++ Vergleichsskript, kein Bibliotheks-Umbau.

GC-2  [optional, sinnvoll nach Phase 8]
      Intrinsic Delaunay Pre-Conditioning
        → Vor dem Newton-Solver: geometry-central SignpostIntrinsicTriangulation
          auf die Eingabe anwenden
        → Ptolemäische Flips konditionieren die Hessian-Matrix vor
        → Hypothese: weniger Newton-Iterationen auf nicht-Delaunay-Eingaben
        → Implementierbar als optionaler cmake-Flag: -DWITH_GC_PRECOND=ON
      Abhängigkeit: geometry-central als optionale externe Abhängigkeit
      (header-only Teile genügen für den Flip-Algorithmus).

GC-3  [hypothetisch, Phase 10+ Forschung]
      Ptolemäische Flip-basierter Solver als alternativer Backend
        → Statt Newton: Ptolemäische Flips + penultimate-step Normalisierung
          (Gillespie–Springborn–Crane 2021 Algorithmus)
        → Vergleich: Konvergenzradius, Robustheit auf pathologischen Netzen,
          numerische Stabilität auf hohen Genus-Flächen
        → Für conformallab++ interessant, weil der Newton-Ansatz auf
          stark nicht-Delaunay Netzen (z.B. nach Remeshing) instabil
          werden kann.
      Keine Implementierung geplant — Konzeptnotiz für Phase 10-Forschung.
```

**Verbindung zur Literatur:**  
Das Springborn 2020-Papier ("Ideal Hyperbolic Polyhedra and Discrete
Uniformization") ist in conformallab++ als HyperIdeal-Geometriemodus
bereits implementiert (Phase 2/3). Die Gillespie–Springborn–Crane
2021-Erweiterung — die geometry-central implementiert — ergänzt dies um
intrinsische Triangulierungen und macht den Algorithmus robust gegen
schlechte Eingangs-Triangulierungen. Beide teilen denselben
mathematischen Kern (diskrete konforme Äquivalenz, Gauss–Bonnet,
Variationsprinzip von 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)
```