diff --git a/README.md b/README.md index 7f2997e..4f5cbec 100644 --- 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). ``` --- diff --git a/doc/architecture/overall_pipeline.md b/doc/architecture/overall_pipeline.md index b8bdc7a..1213226 100644 --- 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