docs: add phase roadmap with porting/research boundary to README and architecture doc

Structured the development roadmap into four blocks with an explicit boundary marker separating direct Java ports (Phase 1–7) from infrastructure (Phase 8), remaining porting (Phase 9), and new research territory (Phase 10+). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 13:18:21 +02:00
parent a937edcafe
commit f8686a073c
2 changed files with 193 additions and 31 deletions
--- a/README.md
+++ b/README.md
@@ -545,42 +545,131 @@ docker buildx build \

 ## Roadmap

-```
-Phase 1   Clausen / Lobachevsky / ImLi₂                     ✅ abgeschlossen
-Phase 2   Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ)         ✅ abgeschlossen
-Phase 3   CGAL Infrastruktur + alle drei Funktionale
-          + analytische Hessians (Eucl. + Sphär.)            ✅ abgeschlossen
-Phase 4   Newton-Solver + SparseQR-Fallback + Mesh-I/O
-          + Beispiel-Programme                               ✅ abgeschlossen
-Phase 5   BFS-Layout + CLI + JSON/XML-Serialisierung         ✅ abgeschlossen
-          → 95 Tests
+> **Legende:**  ✅ abgeschlossen · 🔲 geplant
+>
+> **Grenze Portierung / neue Forschung:**  
+> Phase 1–7 sind direkte Portierungen aus dem Java-Original bzw. seiner Dissertation.  
+> Ab Phase 8 geht die Arbeit über den Umfang der Java-Bibliothek hinaus.  
+> — Phase 8 (CGAL-Paket) ist **Infrastruktur**, kein neuer Algorithmus.  
+> — Phase 9 (Inversive-Distance, Analytischer Hessian) ist **Portierung** ausstehender Java-Features.  
+> — Phase 10+ ist **eigenständige Forschung**, die über das Java-Original hinausgeht.

-Phase 6   Layout-Erweiterung (Java-Parität I)                ✅ abgeschlossen
-          → gauss_bonnet.hpp: χ, Genus, Σ(2π-Θ_v) Check + Enforce
-          → cut_graph.hpp: Tree-Cotree (Erickson–Whittlesey 2005), 2g Schnitt-Kanten
+---
+
+### ◼ Portierungsphase abgeschlossen
+
+```
+Phase 1   Clausen / Lobachevsky / ImLi₂                     ✅
+Phase 2   Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ)         ✅
+Phase 3   CGAL-Infrastruktur + alle drei Funktionale
+          + analytische Hessians (Eucl. + Sphär.)            ✅
+Phase 4   Newton-Solver (SimplicialLDLT + SparseQR-Fallback)
+          + Mesh-I/O + Beispielprogramme                     ✅
+Phase 5   Priority-BFS-Layout + CLI + JSON/XML               ✅  95 Tests
+
+Phase 6   Layout-Parität I                                   ✅  121 Tests
+          → gauss_bonnet.hpp  — χ, Genus, Σ(2π-Θ_v) Check + Enforce
+          → cut_graph.hpp     — Tree-Cotree (Erickson–Whittlesey 2005), 2g Schnitt-Kanten
          → Exakte hyperbolische Trilateration (Möbius + Kosinussatz)
          → normalise_{euclidean,hyperbolic,spherical}
-          → CutGraph* + HolonomyData* in allen Layout-Funktionen
-          → 121 Tests (+26 Phase-6-Tests)

-Phase 7   Layout-Erweiterung (Java-Parität II)               ✅ abgeschlossen
-          → layout.hpp: Priority-BFS (Min-Heap, BFS-Tiefe)
-          → layout.hpp: MobiusMap — T(z)=(az+b)/(cz+d), from_three, compose
-          → layout.hpp: halfedge_uv — Naht-bewusstes UV pro Halfedge
-          → layout.hpp: Möbius-Holonomie (SU(1,1) pro Schnitt-Kante, hyperbolisch)
-          → layout.hpp: best_root_face (größte 3D-Fläche, 1.5× Interior-Bonus)
-          → layout.hpp: Flächen-gewichtete iterative Möbius-Zentrierung (Fréchet-Mittel)
-          → period_matrix.hpp: τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ)-Reduktion
-          → fundamental_domain.hpp: CCW-Parallelogramm, Kanten-Identifikationen,
-                                    Kachelkopien; 4g-Polygon-Randlauf → TODO Phase 8
-          → 158 Tests (+37 Phase-7-Tests)
+Phase 7   Layout-Parität II                                  ✅  158 Tests
+          → MobiusMap  — T(z)=(az+b)/(cz+d), from_three, compose, inverse
+          → halfedge_uv — naht-bewusstes UV pro Halfedge (GPU-Texturatlas)
+          → Möbius-Holonomie als SU(1,1)-Isometrie (hyperbolisch)
+          → period_matrix.hpp — τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ)-Reduktion
+          → fundamental_domain.hpp — CCW-Parallelogramm, Kachelung
+```

-Phase 8   (geplant)
-          → Analytischer HyperIdeal-Hessian (direkte Ableitung durch ζ-Kette)
-          → 4g-Polygon-Randlauf für Genus g > 1 (Grenzwert-Walk auf geschnittenem Mesh)
-          → Siegel-Periodenmatrix Ω (g×g, g ≥ 2) via Integration holomorpher Differentiale
-          → Vollständige globale Uniformisierung geschlossener Flächen beliebigen Genus
-          → Inversive-Distance-Funktional (Luo 2004)
+---
+
+### ◼ Infrastruktur (über Java-Bibliothek hinaus)
+
+```
+Phase 8   CGAL-Paket-Struktur                               🔲  (nächste Phase)
+
+  Ziel: conformallab++ als eigenständiges CGAL-Paket, das in CGAL integriert
+  werden kann und dessen Konventionen vollständig erfüllt.
+
+  8a — Traits-Klasse & Konzepte
+       → include/CGAL/Conformal_map_traits.h
+         Trennt MeshType, KernelType, ScalarType vom Algorithmus.
+         Ermöglicht Nutzung mit beliebigem CGAL-kompatiblem Mesh.
+       → Konzept-Checks (static_assert / CGAL_concept_check)
+
+  8b — Öffentliche CGAL-Header-Hierarchie
+       → include/CGAL/Discrete_conformal_map.h  (zentraler Nutzer-Header)
+       → include/CGAL/Conformal_newton_solver.h
+       → include/CGAL/Conformal_layout.h
+       → include/CGAL/Conformal_cut_graph.h
+       → include/CGAL/conformal_map_package.h  (Package-Description)
+       Alle bestehenden include/conformallab/*.hpp bleiben als Impl.-Detail.
+
+  8c — Dokumentation im CGAL-Stil
+       → doc/Conformal_map/PackageDescription.txt
+       → doc/Conformal_map/fig/  (Pipeline-Diagramme)
+       → Doxygen-Kommentare für alle öffentlichen Konzepte + Funktionen
+       → User_manual.md + Reference_manual.md
+
+  8d — CGAL-Testformat
+       → test/Conformal_map/  (CMakeLists.txt im CGAL-Format)
+       Bestehende GTest-Tests bleiben; CGAL-Tests kommen als zweites Format.
+
+  8e — Declarative YAML-Pipeline
+       → Leichtgewichtiges YAML-Format für reproduzierbare Experimente
+         (Spezifikation bereits in doc/architecture/overall_pipeline.md)
+       → Validator: prüft require/provide-Tokens vor der Ausführung
+       → Einbindung in CLI-App: conformallab_core --pipeline experiment.yml
+```
+
+---
+
+### ◼ Ausstehende Portierung (Java-Features noch nicht übertragen)
+
+```
+Phase 9   Verbleibende Java-Parität                         🔲
+
+  9a — Inversive-Distance-Funktional (Luo 2004 / Bowers–Stephenson)
+       → inversive_distance_functional.hpp  (folgt exakt dem Muster der
+         bestehenden drei Funktionale — niedrigstes Risiko)
+       → newton_inversive_distance()
+       → Neue Test-Suite: test_inversive_distance.cpp
+
+  9b — Analytischer HyperIdeal-Hessian
+       → Direkte Ableitung durch die Kette
+         (b_i, a_e) → l_ij → ζ₁₃/ζ₁₄/ζ₁₅ → α_ij / β_i
+       → Ersetzt den symmetrischen FD-Hessian in hyper_ideal_hessian.hpp
+       → Relevant für Meshes > 500 DOFs (aktueller FD-Hessian ist dort langsam)
+       → Aufwand: ~2 Wochen (viele verschachtelte Fallunterscheidungen)
+
+  9c — 4g-Polygon-Randlauf (Genus g > 1)
+       → Boundary-Walk auf dem aufgeschnittenen Mesh
+       → Befüllt fundamental_domain.hpp für g > 1 (aktuell: leeres Objekt)
+       → Algorithmus-Skizze bereits als TODO(Phase 8) in fundamental_domain.hpp
+```
+
+---
+
+### ◼ Neue Forschung (über das Java-Original hinaus)
+
+> Ab hier gibt es keine direkte Java-Referenzimplementierung mehr.
+> Jedes Item ist eigenständige mathematische Arbeit.
+
+```
+Phase 10  Globale Uniformisierung Genus g ≥ 2               🔲  (Forschung)
+
+  10a — Holomorphe Differentiale auf diskreten Flächen
+        Integration ω_i längs der b-Zyklen des Schnittgraphen.
+        Mathematische Grundlage: Bobenko–Springborn (2004), §6.
+
+  10b — Siegel-Periodenmatrix Ω ∈ H_g (g×g, g ≥ 2)
+        Ω_ij = ∫_{b_j} ω_i  — komplexe symmetrische Matrix,
+        Im(Ω) positiv definit (Siegel-Oberhalbebene H_g).
+        Reduktion auf den Siegel-Fundamentalbereich via Sp(2g,ℤ).
+
+  10c — Vollständige Uniformisierung
+        Für g ≥ 2: Einbettung als H²/Γ mit Γ ⊂ PSL(2,ℝ) Fuchssche Gruppe.
+        Erfordert 10a + 10b + stabilen Cut-Graph für g ≥ 2 (Phase 9c).
 ```

 ---
--- a/doc/architecture/overall_pipeline.md
+++ b/doc/architecture/overall_pipeline.md
@@ -471,6 +471,79 @@ This mirrors exactly the contract table in this document.

 ---

+## Development Roadmap
+
+> **Grenze Portierung / neue Forschung:**  
+> Phase 1–7 sind direkte Portierungen aus dem Java-Original (Sechelmann 2016).  
+> Ab Phase 8 geht die Arbeit über den Umfang der Java-Bibliothek hinaus.  
+> — Phase 8 (CGAL-Paket) ist **Infrastruktur**, kein neuer Algorithmus.  
+> — Phase 9 (Inversive-Distance, Analytischer Hessian, 4g-Polygon) ist **Portierung** ausstehender Java-Features.  
+> — Phase 10+ ist **eigenständige Forschung**, die über das Java-Original hinausgeht.
+
+---
+
+### ◼ Portierungsphase abgeschlossen — Phase 1–7
+
+```
+Phase 1   Clausen / Lobachevsky / ImLi₂                             ✅
+Phase 2   Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ)                 ✅
+Phase 3   CGAL-Infrastruktur + alle drei Funktionale (E/S/H)         ✅
+Phase 4   Newton-Solver (SimplicialLDLT + SparseQR-Fallback)         ✅   68 Tests
+Phase 5   Priority-BFS-Layout + CLI + JSON/XML                       ✅   95 Tests
+Phase 6   Gauss–Bonnet, Tree-Cotree-Schnittgraph, Normalisierung     ✅  121 Tests
+Phase 7   MobiusMap, halfedge_uv, Möbius-Holonomie, Periodenmatrix,
+          Fundamentalbereich (Genus 1), Java-Parität abgeschlossen   ✅  158 Tests
+```
+
+---
+
+### ◼ Infrastruktur (über Java-Bibliothek hinaus) — Phase 8: CGAL-Paket
+
+```
+8a   Traits-Klasse & Konzepte          → include/CGAL/Conformal_map_traits.h
+8b   Öffentliche CGAL-Header-Hierarchie → include/CGAL/Discrete_conformal_map.h etc.
+8c   Dokumentation im CGAL-Stil         → doc/Conformal_map/PackageDescription.txt
+8d   CGAL-Testformat                    → test/Conformal_map/
+8e   Declarative YAML-Pipeline          → pipeline validator (require/provide tokens)
+```
+
+See the [Declarative pipeline](#declarative-pipeline-target-for-phase-8) section above
+for the YAML schema that Phase 8e will validate at runtime.
+
+---
+
+### ◼ Ausstehende Portierung (Java-Features noch nicht übertragen) — Phase 9
+
+```
+9a   Inversive-Distance-Funktional (Luo 2004)
+       → InversiveDistanceMaps + functional + Hessian
+       → discrete uniformization via inversive distances
+9b   Analytischer HyperIdeal-Hessian (ζ-Kette)
+       → replace FD Hessian in hyper_ideal_hessian.hpp
+       → reduces Newton iterations for large meshes
+9c   4g-Polygon-Randlauf (Genus g > 1)
+       → extend compute_fundamental_domain() beyond genus 1
+       → algorithm outline already in fundamental_domain.hpp as TODO(Phase 9)
+```
+
+---
+
+### ◼ Neue Forschung (über das Java-Original hinaus) — Phase 10+
+
+```
+Phase 10   Globale Uniformisierung Genus g ≥ 2
+10a  Holomorphe Differentiale auf diskreten Flächen
+       → discrete harmonic 1-forms; integration along cut graph cycles
+10b  Siegel-Periodenmatrix Ω ∈ H_g  (g×g komplex-symmetrisch, Im(Ω) > 0)
+       → extend compute_period_matrix() to genus g ≥ 2
+       → requires holomorphic differentials from 10a
+10c  Vollständige Uniformisierung
+       → uniformize arbitrary genus-g surface to canonical constant-curvature metric
+       → depends on 10a + 10b
+```
+
+---
+
 ## Recommended reading

 ### Primary source — the dissertation this library implements