diff --git a/CLAUDE.md b/CLAUDE.md index 6fe13ae..432a611 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -156,7 +156,7 @@ Hessian sign and solver per model: - **Spherical:** H is NSD (concave energy) → `SimplicialLDLT(−H)` (sign flip inside `newton_spherical`). - **HyperIdeal:** H is PSD (strictly convex) → `SimplicialLDLT(H)`. Phase 9b uses a **block-FD Hessian** (per-face 6×6 local block, ~96× speed-up vs full FD on V=200). Full analytic Hessian via the chain `(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ` is planned research — see `doc/roadmap/research-track.md` Phase 9b-analytic. - **CP-Euclidean:** analytic 2×2-per-edge `h_jk = sin θ / (cosh Δρ − cos θ)` (BPS 2010), strictly convex → `SimplicialLDLT(H)`. -- **Inversive-Distance:** FD Hessian (inline in `newton_inversive_distance`). Analytic via Glickenstein 2011 eq. (4.6) is planned research (Phase 9a.2-analytic). +- **Inversive-Distance:** FD Hessian (inline in `newton_inversive_distance`). Analytic via Glickenstein 2011 §5.2 is planned research (Phase 9a.2-analytic). When `SimplicialLDLT` fails (rank-deficient H — gauge mode on a closed mesh without pinned vertex/face), the solver automatically retries with `Eigen::SparseQR` to find the minimum-norm step orthogonal to the null space. Public API: `solve_linear_system(H, rhs, &used_fallback)`. diff --git a/doc/architecture/phase-9a-validation.md b/doc/architecture/phase-9a-validation.md index f8b664e..20f5edc 100644 --- a/doc/architecture/phase-9a-validation.md +++ b/doc/architecture/phase-9a-validation.md @@ -124,7 +124,7 @@ energy-evaluation cost and the FD-gradient validation pattern. ### 2.5 Hessian — finite difference for now -Glickenstein 2011 eq. (4.6) gives an analytic Hessian for the inversive- +Glickenstein 2011 §5.2 gives an analytic Hessian for the inversive- distance variational principle, but is more involved than the Springborn cot-Laplacian. For MVP we rely on FD; the analytic form is a future optimisation (joining the Phase 9b roadmap for HyperIdeal as a sibling @@ -173,7 +173,7 @@ same Newton-time-zero gradient". | Angles | half-tangent law of cosines | (face-internal angles via `p(θ*, Δρ)`) | half-tangent law of cosines (reuses `euclidean_angles`) | | Gradient | `Θ_v − Σ α_v(f)` | `φ_f − Σ_{h:face(h)=f} (p+θ*)` | `Θ_v − Σ α_v(f)` | | Energy form | path integral (10-pt GL) | closed form via `½ p Δρ + Λ(θ*+p) − θ* ρ` | path integral (10-pt GL) | -| Hessian | analytic (cotangent Laplacian) | analytic (`sin θ / (cosh Δρ − cos θ)`) | finite difference (analytic deferred — Glickenstein 2011 eq. 4.6) | +| Hessian | analytic (cotangent Laplacian) | analytic (`sin θ / (cosh Δρ − cos θ)`) | finite difference (analytic deferred — Glickenstein 2011 §5.2) | | Convexity | strictly convex after gauge fix | strictly convex after gauge fix | locally convex on triangle-inequality domain (Luo 2004 Thm 1.2) | | Gauge fix | pin one vertex (`v_idx = −1`) | pin one face (`f_idx = −1`) | pin one vertex (`v_idx = −1`) | @@ -213,8 +213,9 @@ form. It does share the Clausen function via `clausen2()` from `clausen.hpp`. ## 6. References -- Bobenko, A. I., Pinkall, U. & Springborn, B. (2010). *Discrete conformal - maps and ideal hyperbolic polyhedra.* Geometry & Topology 14, 379–426. +- Bobenko, A. I., Pinkall, U. & Springborn, B. *Discrete conformal + maps and ideal hyperbolic polyhedra.* Geometry & Topology 19(4) (2015), + 2155–2215. arXiv:1005.2698. - Bowers, P. L. & Stephenson, K. (2004). *Uniformizing dessins and Belyĭ maps via circle packing.* Memoirs of the AMS 170(805). - Glickenstein, D. (2011). *Discrete conformal variations and scalar diff --git a/doc/math/novelty-statement.md b/doc/math/novelty-statement.md index b559d44..9f6cb7b 100644 --- a/doc/math/novelty-statement.md +++ b/doc/math/novelty-statement.md @@ -87,7 +87,9 @@ finite-difference approximations, which is required for reproducible research. The discrete period matrix τ_discrete is a computable invariant of the triangulated surface. Its convergence to the smooth Riemannian τ_smooth under mesh refinement -is an open research question that this library is designed to investigate. +is an open research question in general that this library is designed to investigate +— though it has already been proven for the special class of ramified coverings of +the Riemann sphere by Bobenko–Bücking (2021). ### 3.4 — Full test coverage of analytic invariants diff --git a/doc/math/references.md b/doc/math/references.md index 3de48d2..8ca8e0b 100644 --- a/doc/math/references.md +++ b/doc/math/references.md @@ -14,27 +14,39 @@ Java reference implementation: [github.com/varylab/conformallab](https://github. ## References by module +> **Status-Konvention.** Die „Used in"-Spalte nennt das Modul *oder* die Phase. +> Ein Verweis auf eine **ausgelieferte** Phase (Code existiert, getestet) ist mit +> ✅ markiert; ein Verweis auf eine **geplante/Forschungs**-Phase mit 🔜. Nur die +> ✅-Quellen sind Grundlage des aktuellen Codes; 🔜-Quellen belegen Roadmap-Ziele +> (vgl. auch Abschnitt „Phase 10 references (future research)" unten und +> `novelty-statement.md` §6 „What conformallab++ is not"). +> +> | Marker | Bedeutung | Phasen | +> |---|---|---| +> | ✅ | implementiert & getestet | 9a.1, 9a.2, 9b-analytic, Cut-Graph, Hessians | +> | 🔜 | geplant / Forschung | 9d.2, 9f, 10a, 10b, 10c | + | Reference | Used in | |---|---| -| **Springborn** — *Ideal Hyperbolic Polyhedra and Discrete Uniformization*, Discrete & Computational Geometry (2020) | `hyper_ideal_geometry.hpp` — ζ₁₃/ζ₁₄/ζ₁₅ functions; `hyper_ideal_functional.hpp` | +| ✅ **Springborn** — *Ideal Hyperbolic Polyhedra and Discrete Uniformization*, Discrete & Computational Geometry **64** (2020), pp. 63–108. DOI: [10.1007/s00454-019-00132-8](https://doi.org/10.1007/s00454-019-00132-8) | `hyper_ideal_geometry.hpp` — ζ₁₃/ζ₁₄/ζ₁₅ functions; `hyper_ideal_functional.hpp` | | **Pinkall, Polthier** — *Computing Discrete Minimal Surfaces and Their Conjugates*, Experimental Mathematics (1993) | `euclidean_hessian.hpp` — cotangent Laplacian | | **Bobenko, Springborn** — *Variational Principles for Circle Patterns and Koebe's Theorem*, Transactions AMS (2004) | Variational angle-sum framework underlying all three functionals | | **Luo** — *Combinatorial Yamabe Flow on Surfaces*, Communications in Contemporary Mathematics (2004) | Inversive-distance functional — **new research** in Phase 9a.2 (no Java original; implemented from this paper + Glickenstein 2011 + Bowers-Stephenson 2004) | -| **Bowers, Stephenson** — *Uniformizing dessins and Belyĭ maps via circle packing*, Memoirs of the AMS 170(805) (2004) | Bowers-Stephenson identity I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j) used to initialise inversive distance from input geometry (Phase 9a.2) | -| **Glickenstein** — *Discrete conformal variations and scalar curvature on piecewise flat manifolds*, J. Differential Geometry 87 (2011) | Analytic Hessian of the inversive-distance functional (eq. 4.6) and cross-correspondence I_ij = cos θ_e between vertex-based (9a.2) and face-based (9a.1) circle packings | -| **Bobenko, Pinkall, Springborn** — *Discrete conformal maps and ideal hyperbolic polyhedra*, Geometry & Topology 14 (2010) | Face-based circle-packing functional (`CPEuclideanFunctional.java` → `cp_euclidean_functional.hpp`, Phase 9a.1) | -| **Schläfli** — *On the multiple integral ∫dx dy …*, Quarterly Journal of Pure and Applied Mathematics (1858/60) | Volume differential `2 dV = Σ_e aₑ dαₑ + Σ_v bᵥ dβᵥ` — foundation for the analytic HyperIdeal Hessian via Schläfli identity (Phase 9b-analytic, **new research beyond Java**) | +| **Bowers, Stephenson** — *Uniformizing dessins and Belyĭ maps via circle packing*, Memoirs of the AMS 170(805) (2004) | Introduces **inversive-distance circle packings** (used in Phase 9a.2). *Hinweis:* die zur Initialisierung benutzte Formel I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j) ist die **klassische** inversive Distanz (vgl. Glickenstein §5.2: ℓ²=r_i²+r_j²+2r_ir_jη), nicht eine eigene „Bowers-Stephenson-Identität" — B–S liefern die Packungstheorie, nicht diese Formel. | +| **Glickenstein** — *Discrete conformal variations and scalar curvature on piecewise flat two- and three-dimensional manifolds*, J. Differential Geometry **87**(2) (2011), pp. 201–238 | Analytic Hessian of the inversive-distance functional. ⚠️ *Korrektur:* die Arbeit nummeriert Gleichungen **nicht** im Format „(4.6)" — der Verweis ist durch die **§5.2**-Parametrisierung ℓ²_ij = r²_i + r²_j + 2 r_i r_j η_ij zu ersetzen. Cross-correspondence: η_ij ist die inversive Distanz und entspricht dem Kosinus des **Supplements** des Schnittwinkels (Schnitt bei arccos(−η_ij)) — also I_ij = cos θ_e **nur bis aufs Vorzeichen/Supplement**, nicht wörtlich. | +| **Bobenko, Pinkall, Springborn** — *Discrete conformal maps and ideal hyperbolic polyhedra*, Geometry & Topology **19**(4) (2015), pp. 2155–2215. arXiv: [1005.2698](https://arxiv.org/abs/1005.2698) | Face-based circle-packing functional (`CPEuclideanFunctional.java` → `cp_euclidean_functional.hpp`, Phase 9a.1) | +| **Schläfli** — *On the multiple integral ∫dx dy …*, Quarterly Journal of Pure and Applied Mathematics (1858/60) | Klassische Schläfli-Differentialformel (dV = −½ Σ_e ℓ_e dθ_e). ⚠️ *Hinweis:* die in Phase 9b-analytic benutzte **Randterm-Form** `2 dV = Σ_e aₑ dαₑ + Σ_v bᵥ dβᵥ` steht **nicht** bei Schläfli 1858, sondern ist die verallgemeinerte Fassung für Mannigfaltigkeiten mit Rand → korrekter Beleg: **Rivin–Schlenker 1999** (Phase-10-Liste). Schläfli 1858 nur als historischer Ursprung zitieren. | | **Erickson, Whittlesey** — *Greedy Optimal Homotopy and Homology Generators*, SODA (2005) | `cut_graph.hpp` — tree-cotree algorithm | | **Bobenko, Springborn** — *A Discrete Laplace–Beltrami Operator for Simplicial Surfaces*, Discrete & Computational Geometry (2007) | Background for cotangent weights | | **Desbrun, Kanso, Tong** — *Discrete Differential Forms for Computational Modeling*, SIGGRAPH Course Notes (2006) | Discrete exterior calculus background for Phase 10a | -| **Crane, Soliman, Ben-Chen, Schröder** — *Optimal Cone Singularities for Conformal Flattening*, ACM SIGGRAPH (2018). DOI: [10.1145/3197517.3201367](https://doi.org/10.1145/3197517.3201367) | L¹-optimal automatic cone placement — **Phase 9d.2** (non-Euclidean cone extensions). Provides the optimisation algorithm for choosing cone positions automatically; complements Bobenko-Lutz 2025 on non-Euclidean settings. | +| **Soliman, Slepčev, Crane** — *Optimal Cone Singularities for Conformal Flattening*, ACM Transactions on Graphics **37**(4), Article 105 (2018). DOI: [10.1145/3197517.3201367](https://doi.org/10.1145/3197517.3201367) | L¹-optimal automatic cone placement — **Phase 9d.2** (non-Euclidean cone extensions). Provides the optimisation algorithm for choosing cone positions automatically; complements Bobenko-Lutz 2025 on non-Euclidean settings. | | **Bobenko, Lutz** — *Decorated Discrete Conformal Equivalence in Non-Euclidean Geometries*, Discrete & Computational Geometry (2025). arXiv: [2310.17529](https://arxiv.org/abs/2310.17529) | **Phase 9d.2**: extends DCE to hyperbolic + spherical geometry with Penner-coordinate decorations; unifies cone singularities and hyperideal cusps in one algebraic framework. | | **Bobenko, Lutz** — *Decorated Discrete Conformal Maps and Convex Polyhedral Cusps*, IMRN 2024(12), pp. 9505–9534. arXiv: [2305.10988](https://arxiv.org/abs/2305.10988) | **Phase 10b/10c**: discrete uniformization theorem for decorated piecewise Euclidean surfaces; connects Phase 2/3 hyperideal vertices (cusps at ∞) to the period matrix and fundamental domain. | | **Lutz** — *Canonical Tessellations of Decorated Hyperbolic Surfaces*, Geometriae Dedicata 217 (2023). arXiv: [2206.13461](https://arxiv.org/abs/2206.13461) | **Phase 10c**: canonical Delaunay tessellations in Penner coordinates; unifies the decorated framework with the fundamental domain construction for genus g ≥ 2. | | **Lutz** — *Decorated Discrete Conformal Equivalence, Canonical Tessellations, and Polyhedral Realization* (PhD thesis, TU Berlin, 2024). DOI: [10.14279/depositonce-20357](https://doi.org/10.14279/depositonce-20357) | Comprehensive single reference for Phases 9d.2, 10b, 10c — collects Bobenko-Lutz 2024/2025 and Lutz 2023 with complete proofs. | -| **Bowers, Bowers, Lutz** — *Rigidity of circle polyhedra and hyperideal polyhedra: the tangency case* (2026). arXiv: [2601.22903](https://arxiv.org/abs/2601.22903) | **Phase 9b-analytic + Phase 10c'** (KoebePolyhedron): theoretical uniqueness/rigidity for hyperideal polyhedra in the tangency case; supports correctness of the analytic Hessian and the KAT construction. | +| **Bowers, Bowers, Lutz** — *Rigidity of Koebe Polyhedra and Inversive Distance Circle Packings* (2026). arXiv: [2601.22903](https://arxiv.org/abs/2601.22903) | **Phase 9b-analytic + Phase 10c'** (KoebePolyhedron): theoretical uniqueness/rigidity for Koebe polyhedra and inversive-distance circle packings (incl. the tangency case); supports correctness of the analytic Hessian and the KAT construction. | | **Alexa, Wardetzky** — *Discrete Laplacians on General Polygonal Meshes*, ACM SIGGRAPH (2011). DOI: [10.1145/1964921.1964997](https://doi.org/10.1145/1964921.1964997) | **Phase 9f**: virtual-node polygon Laplacian extending Pinkall-Polthier to non-triangular meshes. Enables DCE on quad/Voronoi meshes without triangulation. | -| **Alexa** — *Discrete Laplacians on General Polygonal Meshes*, ACM TOG 39(6) (2020). DOI: [10.1145/3414685.3417840](https://doi.org/10.1145/3414685.3417840) | **Phase 9f** (extended journal version): error bounds, generalised polygon cotangent weights, convergence analysis. | +| **Bunge, Herholz, Kazhdan, Botsch** — *Polygon Laplacian Made Simple*, Computer Graphics Forum **39**(2) (2020), pp. 303–313. DOI: [10.1111/cgf.13931](https://doi.org/10.1111/cgf.13931) | **Phase 9f**: virtual-vertex polygon Laplacian — fügt pro Polygon einen virtuellen Knoten ein (impliziter Triangle-Fan), erweitert die cotangent-Diskretisierung auf nicht-konvexe/nicht-planare Polygone. (Alternative DEC-Variante: **de Goes, Butts, Desbrun**, *Discrete Differential Operators on Polygonal Meshes*, ACM TOG **39**(4) (2020), DOI [10.1145/3386569.3392389](https://doi.org/10.1145/3386569.3392389).) | --- @@ -66,9 +78,9 @@ builds on this paper and augments it with Ptolemaic flips. | **Farkas, Kra** — *Riemann Surfaces*, Springer GTM 71 | Siegel period matrix, Teichmüller theory | | **Siegel** — *Topics in Complex Function Theory, Vol. 2*, Wiley | Siegel upper half-space H_g, Sp(2g,ℤ) reduction | | **Bobenko, Mercat, Schmies** — *Period Matrices of Polyhedral Surfaces*, in: Computational Approach to Riemann Surfaces (2011) | Discrete period matrices on polyhedral surfaces | -| **Bobenko, Bücking** — *Conformal Structures and Period Matrices of Polyhedral Surfaces* (2009) | Phase 10b: explicit algorithm for computing the discrete Siegel period matrix Ωᵢⱼ on a polyhedral surface from cotangent-weighted integration. | -| **Rivin, Springborn** — *The Schläfli formula in Einstein manifolds with boundary*, Electron. Res. Announc. AMS 5 (1999) | Phase 9b-analytic: modern form of the Schläfli identity `2 dV = Σ aₑ dαₑ` for manifolds with boundary — the bilinear form used to derive the analytic HyperIdeal Hessian. | -| **Springborn** — *A discrete version of Liouville's theorem on conformal maps* (2019). arXiv: [1911.00966](https://arxiv.org/abs/1911.00966) | Phase 10b uniqueness: proves that the discrete conformal structure (and hence Ω) is a conformal invariant — the discrete Liouville theorem. Justifies that conformallab++ outputs a canonical representative. | -| **Springborn, Veselov** — *Quasiconformal distortion of projective transformations and discrete conformal maps*, Int. Math. Res. Not. (2015) | Phase 10c error analysis: quantifies how well the discrete H²/Γ embedding approximates the smooth hyperbolic metric; error bounds for the Fuchsian group representation. | +| **Bobenko, Bücking** — *Convergence of discrete period matrices and discrete holomorphic integrals for ramified coverings of the Riemann sphere*, Math. Phys. Anal. Geom. **24**, Art. 23 (2021). DOI: [10.1007/s11040-021-09394-2](https://doi.org/10.1007/s11040-021-09394-2) | Phase 10b: discrete Siegel period matrix Ωᵢⱼ from cotangent-weighted integration **plus** the convergence result Ω_discrete → Ω_smooth under refinement (für ramified coverings) — belegt die Diskret-zu-glatt-Aussage in `novelty-statement.md §3.3. | +| **Rivin, Schlenker** — *The Schläfli formula in Einstein manifolds with boundary*, Electron. Res. Announc. AMS **5** (1999), pp. 18–23 | Phase 9b-analytic: modern form of the Schläfli identity `2 dV = Σ aₑ dαₑ` for manifolds with boundary — the bilinear form used to derive the analytic HyperIdeal Hessian. | +| **Pinkall, Springborn** — *A discrete version of Liouville's theorem on conformal maps*, Geometriae Dedicata **214** (2021), pp. 389–398. arXiv: [1911.00966](https://arxiv.org/abs/1911.00966) | Phase 10b uniqueness: proves that the discrete conformal structure (and hence Ω) is a conformal invariant — the discrete Liouville theorem. Justifies that conformallab++ outputs a canonical representative. | +| **Born, Bücking, Springborn** — *Quasiconformal distortion of projective transformations and discrete conformal maps*, arXiv: [1505.01341](https://arxiv.org/abs/1505.01341) (2015) | Phase 10c error analysis: quantifies how well the discrete H²/Γ embedding approximates the smooth hyperbolic metric; error bounds for the Fuchsian group representation. | | **Knöppel, Crane, Pinkall, Schröder** — *Stripe Patterns on Surfaces*, ACM SIGGRAPH (2015). DOI: [10.1145/2766890](https://doi.org/10.1145/2766890) | Phase 10a cross-validation: applies discrete holomorphic 1-forms to direction field design; geometry-central provides an independent C++ implementation to cross-check the Phase 10a `DiscreteHolomorphicFormUtility` port. | -| **Sawhney, Crane** — *Boundary First Flattening*, ACM TOG 36(1) (2017). DOI: [10.1145/3132705](https://doi.org/10.1145/3132705) | Complementary method to Phase 9d: boundary-prescribed conformal flattening — user specifies boundary shape, interior conforms freely. Contrast: conformallab++ prescribes cone angles in the interior; BFF prescribes the boundary. Alternative approach for applications needing controlled boundary. | +| **Sawhney, Crane** — *Boundary First Flattening*, ACM TOG **37**(1), Article 5 (2017). DOI: [10.1145/3132705](https://doi.org/10.1145/3132705) | Complementary method to Phase 9d: boundary-prescribed conformal flattening — user specifies boundary shape, interior conforms freely. Contrast: conformallab++ prescribes cone angles in the interior; BFF prescribes the boundary. Alternative approach for applications needing controlled boundary. | diff --git a/doc/reviewer/briefing.md b/doc/reviewer/briefing.md index e147b06..7f2b92e 100644 --- a/doc/reviewer/briefing.md +++ b/doc/reviewer/briefing.md @@ -46,12 +46,12 @@ research-only phases the reader can shape at design stage. | **Canonical Delaunay tessellations of decorated hyperbolic surfaces** (Lutz 2023, *Geom. Dedicata*; Lutz 2024 PhD thesis) | cut-graph + period matrix + hyperbolic-disk layout as scaffolding; canonical-tessellation algorithm itself outlined | **10c** planned | | **Hyperideal polyhedra rigidity** (Bowers–Bowers–Lutz 2026) | HyperIdeal functional + analytic Hessian derivation (805-line LaTeX note) | **9b-analytic** derived; **10c′** KAT planned | | **Optimal cone placement / non-Euclidean cone metrics** (Crane et al. 2018) | Cone-singularity port via `ConesUtility` scoped; the *non-Euclidean* extension is the research delta | **9d.1** port + **9d.2** RESEARCH | -| **Polygon Laplacian on general meshes** (Alexa–Wardetzky 2011; Alexa 2020) | *no Java parent* — first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) | +| **Polygon Laplacian on general meshes** (Alexa–Wardetzky 2011; Bunge et al. 2020) | *no Java parent* — first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) | | **Quasi-isothermic maps** (generalising conformality where exact conformality is impossible — Lawson-correspondence parameterisation) | scoped as a 6-class port (~800 lines) from the Java original: `QuasiisothermicLayout`, `DBFSolution` (discrete Beltrami field), `SinConditionApplication`, `QuasiisothermicDelaunay`, `QuasiisothermicUtility`, `ConformalStructureUtility` | **10e** planned | -| **Higher-genus + hyperelliptic surfaces** (Bobenko–Bücking 2009 on polyhedral surfaces; period matrices with block-diagonal Z₂ structure) | port of `HyperellipticUtility` + `HyperIdealHyperellipticUtility` scoped; existing period-matrix code as scaffolding | **10b** planned | +| **Higher-genus + hyperelliptic surfaces** (Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021 on polyhedral period matrices; block-diagonal Z₂ structure) | port of `HyperellipticUtility` + `HyperIdealHyperellipticUtility` scoped; existing period-matrix code as scaffolding | **10b** planned | | **Möbius centring for Poincaré-disk layouts** as a variational problem (Lorentz geometry: `E = Σ log(−⟨x,p⟩/√(−⟨x,x⟩))`) | currently we use iterative Fréchet mean in `normalise_hyperbolic()`; the principled variational alternative is scoped via the Java `MobiusCenteringFunctional` port (full gradient + Hessian) | **9d.4** planned | -| **Boundary-First / interactive flattening** (Crane et al. 2017 BFF; Bonneel et al. 2015 *Stripe Patterns on Surfaces*) | not on the roadmap as ports; documented in [`references.md`](../math/references.md) as comparison points / inspiration for future API design | — | -| **Schläfli-based variational machinery** (Rivin–Springborn 1999) | derivation done, implementation gated on your view of whether the ~6× speedup over our block-FD path matters at your mesh sizes | **9b-analytic** ready to implement | +| **Boundary-First / interactive flattening** (Sawhney–Crane 2017 BFF; Knöppel–Crane–Pinkall–Schröder 2015 *Stripe Patterns on Surfaces*) | not on the roadmap as ports; documented in [`references.md`](../math/references.md) as comparison points / inspiration for future API design | — | +| **Schläfli-based variational machinery** (Rivin–Schlenker 1999) | derivation done, implementation gated on your view of whether the ~6× speedup over our block-FD path matters at your mesh sizes | **9b-analytic** ready to implement | See [`doc/roadmap/phases.md`](../roadmap/phases.md) for the per-phase porting plan, [`doc/roadmap/research-track.md`](../roadmap/research-track.md) @@ -71,11 +71,12 @@ rationale). Tier-1/2. Decorated-DCE / canonical-tessellation / hyperideal line: Bobenko–Lutz 2024 IMRN; Bobenko–Lutz 2025 *DCG*; Lutz 2023 *Geom. Dedicata*; Lutz 2024 PhD; Bowers–Bowers–Lutz 2026. Cones, - polyhedra, period matrices: Crane et al. 2018; Springborn 2019 - (hyperbolic polyhedra); Bobenko–Bücking 2009; Rivin–Springborn 1999. - Polygon Laplacians: Alexa–Wardetzky 2011; Alexa 2020. Integrable + - practical-flattening context: Springborn–Veselov 2015 (cluster - dynamics); Crane et al. 2017 (BFF); Bonneel et al. 2015 (Stripe + polyhedra, period matrices: Soliman–Slepčev–Crane 2018; Pinkall–Springborn + 2021 (discrete Liouville); Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking + 2021; Rivin–Schlenker 1999. + Polygon Laplacians: Alexa–Wardetzky 2011; Bunge et al. 2020. Integrable + + practical-flattening context: Born–Bücking–Springborn 2015 (quasiconformal + distortion); Sawhney–Crane 2017 (BFF); Knöppel et al. 2015 (Stripe Patterns). - **Phase 9f** (polygon Laplacian on non-triangular meshes) added as RESEARCH-only — no Java parent — so you can influence its design diff --git a/doc/reviewer/hub.html b/doc/reviewer/hub.html index e803a1c..524c3b3 100644 --- a/doc/reviewer/hub.html +++ b/doc/reviewer/hub.html @@ -250,16 +250,16 @@ per-phase entry in doc/roadmap/.

Quasi-isothermic maps (Lawson correspondence, ~800 lines, discrete Beltrami-field solver) scoped as a 6-class Java port: QuasiisothermicLayout, DBFSolution, SinConditionApplication, QuasiisothermicDelaunay, QuasiisothermicUtility, ConformalStructureUtility 10e planned -Higher-genus + hyperelliptic surfaces (Bobenko–Bücking 2009; block-diagonal period matrices with Z₂ symmetry) +Higher-genus + hyperelliptic surfaces (Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021 period matrices; block-diagonal Z₂ symmetry) port of HyperellipticUtility + HyperIdealHyperellipticUtility scoped; existing period-matrix code as scaffolding 10b planned Möbius centring as a variational problem (Lorentz energy, full gradient + Hessian) currently iterative Fréchet mean in normalise_hyperbolic(); the principled variational alternative is scoped via the Java MobiusCenteringFunctional port 9d.4 planned -Boundary-First / interactive flattening (Crane et al. 2017 BFF; Bonneel et al. 2015 Stripe Patterns) +Boundary-First / interactive flattening (Sawhney–Crane 2017 BFF; Knöppel–Crane–Pinkall–Schröder 2015 Stripe Patterns) not on the roadmap as ports; documented in references.md as comparison points / inspiration — -Schläfli-based variational machinery (Rivin–Springborn 1999) +Schläfli-based variational machinery (Rivin–Schlenker 1999) derivation done; implementation gated on the reader's view of whether the ~6× speedup over our block-FD path matters at their mesh sizes 9b-analytic ready @@ -320,15 +320,16 @@ sufficient answer.

Decorated-DCE / canonical-tessellation / hyperideal line: Bobenko–Lutz 2024 IMRN; Bobenko–Lutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD; Bowers–Bowers–Lutz 2026. - Cones, polyhedra, period matrices: Crane et al. 2018; - Springborn 2019; Bobenko–Bücking 2009; Rivin–Springborn 1999. - Polygon Laplacians: Alexa–Wardetzky 2011; Alexa 2020. Integrable - and practical-flattening context: Springborn–Veselov 2015; - Crane et al. 2017 (BFF); Bonneel et al. 2015 (Stripe Patterns). + Cones, polyhedra, period matrices: Soliman–Slepčev–Crane 2018; + Pinkall–Springborn 2021 (discrete Liouville); Bobenko–Mercat–Schmies + 2011 / Bobenko–Bücking 2021; Rivin–Schlenker 1999. + Polygon Laplacians: Alexa–Wardetzky 2011; Bunge et al. 2020. Integrable + and practical-flattening context: Born–Bücking–Springborn 2015; + Sawhney–Crane 2017 (BFF); Knöppel et al. 2015 (Stripe Patterns).
  • +1 RESEARCH phase with no Java parent — Phase 9f (polygon Laplacian on non-triangular meshes, - Alexa-Wardetzky 2011 / Alexa 2020) — the first phase a reviewer + Alexa-Wardetzky 2011 / Bunge et al. 2020) — the first phase a reviewer can shape at design stage.
  • output_uv_map now covers 4 of 5 DCE solvers (Inversive-Distance added; CP-Euclidean deferred to @@ -427,9 +428,9 @@ folder for the per-document table.

    - + - +
    DocumentWhat it covers
    references.md +13 refsPer-phase literature index. 13 new citations added: decorated DCE in non-Euclidean geometries (Bobenko–Lutz 2025); canonical tessellations (Lutz 2023 / 2024); hyperideal polyhedra rigidity (Bowers–Bowers–Lutz 2026); polygon Laplacians (Alexa–Wardetzky 2011 / Alexa 2020); optimal cone placement (Crane et al. 2018); Schläfli identity (Rivin–Springborn 1999); hyperbolic polyhedra (Springborn 2019); polyhedral period matrices (Bobenko–Bücking 2009); integrable cluster dynamics (Springborn–Veselov 2015); BFF (Crane et al. 2017); stripe patterns (Bonneel et al. 2015).
    Per-phase literature index. 13 new citations added: decorated DCE in non-Euclidean geometries (Bobenko–Lutz 2025); canonical tessellations (Lutz 2023 / 2024); hyperideal polyhedra rigidity (Bowers–Bowers–Lutz 2026); polygon Laplacians (Alexa–Wardetzky 2011 / Bunge et al. 2020); optimal cone placement (Soliman–Slepčev–Crane 2018); Schläfli identity (Rivin–Schlenker 1999); discrete Liouville theorem (Pinkall–Springborn 2021); polyhedral period matrices (Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021); quasiconformal distortion (Born–Bücking–Springborn 2015); BFF (Sawhney–Crane 2017); stripe patterns (Knöppel–Crane–Pinkall–Schröder 2015).
    hyperideal-hessian-derivation.mdFull LaTeX-formatted derivation of the analytic HyperIdeal Hessian via the Schläfli identity (805 lines, 8 sections + 2 appendices). Cited sources: Schläfli 1858, Milnor 1982, Vinberg 1993, Cho–Kim 1999, Glickenstein 2011, Rivin–Springborn 1999, Springborn 2020.
    Full LaTeX-formatted derivation of the analytic HyperIdeal Hessian via the Schläfli identity (805 lines, 8 sections + 2 appendices). Cited sources: Schläfli 1858, Milnor 1982, Vinberg 1993, Cho–Kim 1999, Glickenstein 2011, Rivin–Schlenker 1999, Springborn 2020.
    diff --git a/doc/reviewer/questions.md b/doc/reviewer/questions.md index 9d09c85..4338949 100644 --- a/doc/reviewer/questions.md +++ b/doc/reviewer/questions.md @@ -35,7 +35,7 @@ phases whose existence is settled but whose priority is open: | **9f** | RESEARCH | Discrete Laplace–Beltrami on **non-triangular** polygonal meshes (virtual-node / generalised cotangent), making DCE work on quad / Voronoi tessellations without re-triangulation | Polygon Laplacians (2011 *SIGGRAPH* + 2020 *TOG*) | | **10c + 10c′** | planned | Canonical Delaunay tessellations of decorated hyperbolic surfaces; Koebe polyhedron realisation (KAT) with rigidity-aware Newton | Canonical tessellations of decorated hyperbolic surfaces (2023, *Geom. Dedicata*); rigidity of circle / hyperideal polyhedra (2026, preprint) | | **10e** | planned | Quasi-isothermic maps (~800 lines Lawson-correspondence) — generalises conformality to meshes where exact conformality is impossible. Six new classes including a discrete Beltrami-field solver. | Java original `QuasiisothermicUtility` line; no obvious single-paper reference in the existing literature index | -| **10b** | planned | Hyperelliptic surfaces (genus g ≥ 2 with Z₂ symmetry); period matrices with block-diagonal structure; Penner-coordinate variant via `HyperIdealHyperellipticUtility` | Bobenko–Bücking 2009 *Conformal Structures and Period Matrices of Polyhedral Surfaces* | +| **10b** | planned | Hyperelliptic surfaces (genus g ≥ 2 with Z₂ symmetry); period matrices with block-diagonal structure; Penner-coordinate variant via `HyperIdealHyperellipticUtility` | Bobenko–Mercat–Schmies 2011 *Period Matrices of Polyhedral Surfaces* / Bobenko–Bücking 2021 *Convergence of discrete period matrices* | | **9d.4** | planned | Möbius centring of Poincaré-disk layouts as a *variational* problem (Lorentz energy with full gradient + Hessian), replacing today's iterative Fréchet-mean fallback in `normalise_hyperbolic()` | Java original `MobiusCenteringFunctional`; closest published context: decorated-DCE Möbius normalisation, also used in canonical-tessellation post-processing | **Question A:** which of these (if any) would unblock concrete @@ -104,7 +104,7 @@ We have: [`doc/math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) (805 lines, all sign pitfalls covered, references Schläfli 1858, Milnor 1982, Vinberg 1993, Cho–Kim 1999, Glickenstein 2011, - Springborn 2020, Rivin–Springborn 1999). + Springborn 2020, Rivin–Schlenker 1999). **Question:** diff --git a/doc/roadmap/phases.md b/doc/roadmap/phases.md index 84c3c8b..3a939f4 100644 --- a/doc/roadmap/phases.md +++ b/doc/roadmap/phases.md @@ -109,8 +109,8 @@ mesh type. 9b-analytic Full analytic HyperIdeal Hessian via Schläfli identity → planned, see research-track.md Mathematical source: Springborn 2020 §4 + Schläfli 1858/60 - + Rivin, Springborn 1999 "The Schläfli formula in - Einstein manifolds with boundary" (ERA-AMS 5) + + Rivin, Schlenker 1999 "The Schläfli formula in + Einstein manifolds with boundary" (ERA-AMS 5, 18–23) + Cho-Kim 1999 + Glickenstein 2011 §4 Algorithm: explicit chain rule through (bᵢ,aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ Includes: short LaTeX correctness note in doc/math/. @@ -165,8 +165,8 @@ mesh type. Non-Euclidean Geometries" (Discrete & Comput. Geom. 2025, arXiv:2310.17529) §3 — decorated DCE framework unifying cone singularities and cusps in hyperbolic + spherical geometry. - Crane, Soliman, Ben-Chen, Schröder 2018 "Optimal Cone Singularities - for Conformal Flattening" (ACM SIGGRAPH 2018) — L¹-optimal + Soliman, Slepčev, Crane 2018 "Optimal Cone Singularities + for Conformal Flattening" (ACM TOG 37(4), Art. 105) — L¹-optimal automatic cone placement; directly applicable to 9d.2 algorithm. Status: 🔲 planned @@ -223,8 +223,10 @@ mesh type. Alexa, Wardetzky 2011 "Discrete Laplacians on General Polygonal Meshes" (ACM SIGGRAPH 2011) — virtual-node construction, polygon cotangent weights extending the Pinkall-Polthier formula. - Alexa 2020 "Discrete Laplacians on General Polygonal Meshes" - (ACM TOG 39, 2020) — extended journal treatment, error bounds. + Bunge, Herholz, Kazhdan, Botsch 2020 "Polygon Laplacian Made + Simple" (Computer Graphics Forum 39(2), 303–313) — virtual-vertex + construction with error analysis. (DEC alternative: de Goes, + Butts, Desbrun 2020, ACM TOG 39(4).) Enables: DCE energy evaluation on quad-dominant / Voronoi / polygon meshes without forced triangulation. Replaces euclidean_hessian.hpp for non-triangular inputs. @@ -425,15 +427,19 @@ Phase 10 Global uniformization for genus g ≥ 2 → Ωᵢⱼ = ∫_{bⱼ} ωᵢ → Reduction to Siegel fundamental domain via Sp(2g,ℤ). Mathematical reference: Bobenko-Springborn 2004 + Gottschling 1959. - Bobenko, Bücking 2009 "Conformal Structures and - Period Matrices of Polyhedral Surfaces" — discrete - period matrix Ωᵢⱼ on polyhedral surfaces. + Bobenko, Mercat, Schmies 2009/2011 "Conformal + Structures / Period Matrices of Polyhedral + Surfaces" (arXiv:0909.1305) + Bobenko, Bücking 2021 + "Convergence of discrete period matrices ..." + (Math. Phys. Anal. Geom. 24, Art. 23) — discrete + period matrix Ωᵢⱼ on polyhedral surfaces + convergence. Bobenko, Lutz 2024 IMRN "Decorated Discrete Conformal Maps and Convex Polyhedral Cusps" — uniformization theorem connecting cusps ↔ hyperideal vertices (bridges Phase 2/3 HyperIdeal geometry to 10b). - Springborn 2019 "A discrete version of Liouville's - theorem on conformal maps" (arXiv:1911.00966) — + Pinkall, Springborn 2021 "A discrete version of + Liouville's theorem on conformal maps" + (Geom. Dedicata 214, 389–398; arXiv:1911.00966) — proves uniqueness/rigidity of the discrete conformal structure; justifies that Ω is a conformal invariant. Java partial reference: DiscreteRiemannUtility.java (186 lines). @@ -467,9 +473,9 @@ Phase 10 Global uniformization for genus g ≥ 2 Bobenko, Lutz 2024 IMRN (arXiv:2305.10988) — discrete uniformization theorem for decorated piecewise Euclidean surfaces. - Springborn, Veselov 2015 "Quasiconformal distortion - of projective transformations and discrete conformal - maps" (Int. Math. Res. Not.) — error estimates for + Born, Bücking, Springborn 2015 "Quasiconformal + distortion of projective transformations and discrete + conformal maps" (arXiv:1505.01341) — error estimates for the discrete-to-smooth conformal approximation; quantifies how well H²/Γ approximates the smooth hyperbolic metric. @@ -479,11 +485,22 @@ Phase 10 Global uniformization for genus g ≥ 2 Status: **fully new research.** Requires: 10a + 10b + Phase 9c. + ⚠️ SCOPE BOUNDARY (was 10c delivers vs. was offen bleibt): + 10c as scoped here builds the *infrastructure* — Fuchsian-group + representation + H²/Γ embedding on the Sechelmann/Bobenko-Springborn + uniformisation path. The Lutz-SPECIFIC algorithms it references + (canonical Delaunay tessellation in Penner coordinates, Epstein-Penner + convex-hull construction, Weeks-flip extension, polyhedral realisation) + are NOT delivered automatically by reaching 10c — they sit ON TOP of + this infrastructure and are their own implementation effort. + → that effort is split out as **Phase 13** (Chain B capstone). + 10c = runway; Phase 13 = the Lutz algorithms that land on it. + 10c' Optional Java-port additions (low priority) → KoebePolyhedron.java (321 lines) — Koebe-Andreev-Thurston circle packings. Adds a fifth DCE method. - Rigidity: Bowers, Bowers, Lutz 2026 "Rigidity of circle polyhedra - and hyperideal polyhedra: the tangency case" (arXiv:2601.22903) + Rigidity: Bowers, Bowers, Lutz 2026 "Rigidity of Koebe Polyhedra + and Inversive Distance Circle Packings" (arXiv:2601.22903) — theoretical uniqueness backing the KAT construction. → ElectrostaticSphereFunctional (127 lines) — sphere distribution baseline. @@ -560,3 +577,102 @@ All three items are tracked here so the project memory is preserved; none of them are roadmap commitments. See `research-track.md` for the formal research-versus-port classification before starting any. ``` + +--- + +## ◼ Phase 12 — Decorated DCE & geometric transition (RESEARCH, near-term) + +> **Note on ordering:** despite the higher number, Phase 12 is *near-term +> and independent* of Phases 9c–11. It builds ONLY on already-landed code +> and is the **short path (Chain A)** to a first Lutz-adjacent scientific +> result. It does **not** require the genus-g≥2 chain (9c/10a/10b/10c) or +> the holonomy-bug fix — those gate Phase 13 (Chain B), not this. + +``` +12 Decorated DCE & geometric transition (no Java parent) + → Numerical demonstration of the Bobenko-Lutz "master theory": + one discrete conformal invariant, continuously deformable across + Euclidean / spherical / hyperbolic background geometry. + Mathematical reference: + Bobenko, Lutz 2025 "Decorated Discrete Conformal Equivalence in + Non-Euclidean Geometries" (Discrete & Comput. Geom.; + arXiv:2310.17529) §3 — Penner-coordinate decoration unifying the + three background geometries; continuous deformation at fixed + discrete conformal invariant. + Lutz 2024 PhD thesis (depositonce-20357) — full proofs. + Builds on (✅ already landed): + inversive_distance functional (9a.2), hyper_ideal (Springborn 2020), + spherical functional — the decoration is a RE-PARAMETRISATION of + these, not a new solver. + Does NOT require: 9c / 10a / 10b / holonomy-bug fix. + Scope: + 1. Decoration layer: per-vertex circle/horocycle radius as Penner + coordinate; map ↔ existing inversive distance I_ij (classical + formula ℓ²=r_i²+r_j²+2r_ir_jη). + 2. Transition driver: deform background curvature κ ∈ {+,0,−} while + holding the discrete conformal invariant fixed; solve per geometry. + 3. Validation harness producing example galleries. + Acceptance criteria: + - Decoration round-trip I_ij ↔ (r_i,r_j,ℓ) at machine precision. + - At κ=0: bit-for-bit match with existing euclidean/inversive path. + - Gauss-Bonnet per geometry; invariant constant across the κ-transition + to tol (numerical witness of the Bobenko-Lutz master theorem). + - Cross-geometry: one test surface solved in all three backgrounds + shares the invariant. + Effort: medium (functionals exist; reparametrisation + driver + tests). + Status: 🔲 planned (proposed 2026-05-29). +``` + +--- + +## ◼ Phase 13 — Decorated canonical tessellations & polyhedral realisation (Chain B capstone) + +> **This is the genus-g≥2 Lutz contribution.** It sits ON TOP of the +> infrastructure built by Phases 9c + 10a + 10b + 10c (see the 10c SCOPE +> BOUNDARY note above) and implements Lutz's *specific* algorithms that the +> 10c "runway" does not deliver by itself. + +``` +13 Decorated canonical tessellations + polyhedral realisation (no Java parent) + → Canonical Delaunay tessellation of a decorated hyperbolic surface + in Penner coordinates, its dual decomposition, and the polyhedral + realisation of the uniformised genus-g≥2 surface. + Mathematical reference: + Lutz 2023 "Canonical Tessellations of Decorated Hyperbolic Surfaces" + (Geom. Dedicata 217; arXiv:2206.13461) — canonical (weighted- + Delaunay-analogue) tessellation + dual; Epstein-Penner convex-hull + construction in Minkowski space; Weeks-flip extension. + Bobenko, Lutz 2024 IMRN (arXiv:2305.10988) — discrete uniformization + theorem for decorated surfaces (cusps ↔ hyperideal vertices). + Lutz 2024 PhD thesis (depositonce-20357) — polyhedral realisation + + complete proofs for 9d.2 / 10b / 10c / 13. + Rigidity backing: Bowers, Bowers, Lutz 2026 (arXiv:2601.22903). + PREREQUISITES (the "given Voraussetzungen" — all must be in place): + ✅ cut_graph.hpp (2g seams) — landed + 🔲 Phase 9c — 4g-gon fundamental domain + 🔲 Phase 10a — holomorphic/harmonic 1-forms + 🔲 Phase 10b — Siegel period matrix Ω ∈ H_g + 🔲 Phase 10c — Fuchsian-group representation / H²/Γ embedding + 🔲 holonomy-bug fix — detail::spherical_holonomy / + detail::hyperbolic_holonomy (+ cpp_dec_float_50 for the + group-relation product ∏gᵢ = Id); see research-track.md §9c. + 🟡 Phase 12 — decoration layer (Penner coords) is reused here; + strongly recommended to land Phase 12 first so the Penner- + coordinate machinery already exists. + Scope: + 1. Penner-coordinate weighted-Delaunay (canonical) tessellation + + dual decomposition on the H²/Γ embedding from 10c. + 2. Epstein-Penner convex-hull construction (Minkowski space) to + obtain the canonical decomposition; Weeks-flip to reach it. + 3. Polyhedral realisation of the uniformised surface. + Acceptance criteria: + - Canonical tessellation is unique & flip-stable (Weeks-flip + terminates; result independent of start triangulation). + - Decoration / Penner-coordinate consistency with Phase 12 layer. + - Gauss-Bonnet + holonomy closure ∏[a_i,b_i] = Id (high precision). + - Rigidity witness: Newton finds the unique realisation on the + tangency-case test set (Bowers-Bowers-Lutz 2026). + Effort: very large (depends on the full 9c/10a/10b/10c chain landing + first; the Lutz algorithms themselves ≈ several weeks on top). + Status: 🔲 planned (Chain B capstone; gated on prerequisites above). +``` diff --git a/doc/roadmap/research-track.md b/doc/roadmap/research-track.md index 5595fad..e9cbc0d 100644 --- a/doc/roadmap/research-track.md +++ b/doc/roadmap/research-track.md @@ -79,7 +79,7 @@ The phase numbers match `doc/roadmap/phases.md`. ### CP-Euclidean functional (Phase 9a.1, 🟡 PR #8) * **Mathematical source:** Bobenko, Pinkall, Springborn (2010). *Discrete conformal maps and ideal hyperbolic polyhedra.* - Geometry & Topology 14, 379–426. + Geometry & Topology 19(4) (2015), 2155–2215. arXiv:1005.2698. * **Java reference:** ✅ `CPEuclideanFunctional.java` (260 lines + 88-line `CPEuclideanFunctionalTest.java`). **This one IS a port.** * **Status:** 🟡 PR #8 open, 10 tests including Java-test parity. @@ -95,11 +95,15 @@ The phase numbers match `doc/roadmap/phases.md`. gradient identity Lemma 3.1. - **Bowers, P. L. & Stephenson, K.** (2004). *Uniformizing dessins and Belyĭ maps via circle packing.* Memoirs of the AMS 170(805). - → inversive-distance identity `I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j)`. + → introduces inversive-distance circle packings. NB: the formula + `I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j)` is the *classical* inversive + distance (= Glickenstein §5.2 η), not a B–S-specific identity. - **Glickenstein, D.** (2011). *Discrete conformal variations and - scalar curvature on piecewise flat manifolds.* J. Diff. Geom. - 87(2), 201–238. → §5 correspondence `I_ij = cos θ_e`, eq. 4.6 - analytic Hessian (used later by Phase 9b-analytic mirror). + scalar curvature on piecewise flat two- and three-dimensional + manifolds.* J. Diff. Geom. 87(2), 201–238. → §5.2 inversive-distance + parametrization ℓ²=r_i²+r_j²+2r_ir_jη; correspondence I_ij = cos θ_e + holds only up to sign/supplement (intersection at arccos(−η)). + The paper does **not** number equations as "(4.6)". * **Java reference:** ❌ **none.** Verified empirically: ```bash $ find /Users/tarikmoussa/Desktop/conformallab -iname "*nversive*" @@ -202,7 +206,7 @@ The phase numbers match `doc/roadmap/phases.md`. ### Inversive-distance Hessian — full analytic (Phase 9a.2-analytic, 🔲 planned) -* **Mathematical source:** Glickenstein, D. (2011) eq. (4.6). +* **Mathematical source:** Glickenstein, D. (2011) §5.2 (inversive-distance parametrization ℓ²=r_i²+r_j²+2r_ir_jη). * **Java reference:** ❌ none. * **Chain:** `(uᵢ, uⱼ) → ℓᵢⱼ → αᵢⱼ` with `∂ℓ²/∂u_i = 2(r_i² + I r_i r_j)`. * **Effort:** medium (5–7 days, less involved than HyperIdeal because @@ -219,8 +223,8 @@ The phase numbers match `doc/roadmap/phases.md`. → §3: Penner-coordinate decoration unifies cone singularities (Θᵥ ≠ 2π) and hyperideal cusps (Θᵥ = 0) in a single algebraic framework valid in Euclidean, spherical, and hyperbolic geometry. - - **Crane, Soliman, Ben-Chen, Schröder** (2018). *Optimal Cone Singularities - for Conformal Flattening.* ACM SIGGRAPH 2018. DOI: 10.1145/3197517.3201367. + - **Soliman, Slepčev, Crane** (2018). *Optimal Cone Singularities + for Conformal Flattening.* ACM Trans. Graph. 37(4), Art. 105. DOI: 10.1145/3197517.3201367. → L¹-optimal cone placement via a sparse-recovery optimisation over the curvature deficit Kᵥ = 2π − Θᵥ; directly gives the set of cone angles to prescribe for a near-flat conformal parametrisation. @@ -260,9 +264,10 @@ The phase numbers match `doc/roadmap/phases.md`. central node connected to all vertices; cotangent weights are computed per sub-triangle; the resulting operator is symmetric and positive semi-definite, mirroring Pinkall-Polthier for triangulations. - - **Alexa** (2020). *Discrete Laplacians on General Polygonal Meshes.* - ACM TOG 39(6). DOI: 10.1145/3414685.3417840. - → Extended journal version with error bounds and convergence analysis. + - **Bunge, Herholz, Kazhdan, Botsch** (2020). *Polygon Laplacian Made Simple.* + Computer Graphics Forum 39(2), 303–313. DOI: 10.1111/cgf.13931. + → virtual-vertex construction with error analysis. (DEC alternative: + de Goes, Butts, Desbrun 2020, ACM TOG 39(4), DOI 10.1145/3386569.3392389.) * **Java reference:** ❌ **none.** @@ -345,6 +350,72 @@ The phase numbers match `doc/roadmap/phases.md`. * **Java reference:** ❌ none — Java has the polygon + period matrix pieces but does not assemble them into a Fuchsian group representation. * **Status:** **fully new research** — depends on 9c + 10a + 10b. +* **⚠️ Scope boundary:** 10c delivers the *infrastructure* (Fuchsian-group + representation + H²/Γ embedding on the Sechelmann/Bobenko-Springborn path). + The Lutz-*specific* algorithms (canonical Delaunay tessellation in Penner + coordinates, Epstein-Penner hull, Weeks-flip, polyhedral realisation) are + **not** auto-delivered by reaching 10c — they are split out as **Phase 13** + (Chain B capstone), which sits on top of this runway. + +--- + +### Decorated DCE & geometric transition (Phase 12, 🔲 planned — near-term, Chain A) +* **Mathematical sources:** + - **Bobenko, Lutz** (2025). *Decorated Discrete Conformal Equivalence in + Non-Euclidean Geometries.* Discrete & Comput. Geom. arXiv:2310.17529. §3 + — Penner-coordinate decoration unifying Euclidean/spherical/hyperbolic + DCE; continuous deformation at fixed discrete conformal invariant. + - **Lutz** (2024). *PhD thesis, TU Berlin.* DOI: 10.14279/depositonce-20357. +* **Java reference:** ❌ none. +* **Builds on (✅ landed):** `inversive_distance_functional.hpp` (9a.2), + `hyper_ideal_functional.hpp` (Springborn 2020), `spherical_functional.hpp` + — the decoration is a re-parametrisation of these, not a new solver. +* **Does NOT require:** 9c / 10a / 10b / holonomy-bug fix. This is the + **short path**: the earliest Lutz-adjacent result, independent of Chain B. +* **Scope:** (1) Penner-coordinate decoration layer ↔ classical inversive + distance `ℓ²=r_i²+r_j²+2r_ir_jη`; (2) curvature-transition driver κ∈{+,0,−} + at fixed invariant; (3) validation harness + example gallery. +* **Acceptance criteria:** + - Decoration round-trip `I_ij ↔ (r_i,r_j,ℓ)` at machine precision. + - At κ=0 bit-for-bit match with the existing Euclidean/inversive path. + - Gauss-Bonnet per geometry; invariant constant across the κ-transition + to tol (numerical witness of the Bobenko-Lutz master theorem). + - Cross-geometry agreement of the invariant on one test surface. +* **Effort:** medium (functionals exist; reparametrisation + driver + tests). + +--- + +### Decorated canonical tessellations & polyhedral realisation (Phase 13, 🔲 planned — Chain B capstone) +* **Mathematical sources:** + - **Lutz** (2023). *Canonical Tessellations of Decorated Hyperbolic + Surfaces.* Geom. Dedicata 217. arXiv:2206.13461 — canonical (weighted- + Delaunay-analogue) tessellation + dual; Epstein-Penner convex hull in + Minkowski space; Weeks-flip extension. + - **Bobenko, Lutz** (2024). IMRN 2024(12), 9505–9534. arXiv:2305.10988 — + discrete uniformization theorem for decorated surfaces. + - **Lutz** (2024). *PhD thesis* (depositonce-20357) — polyhedral realisation. + - Rigidity backing: **Bowers, Bowers, Lutz** (2026), arXiv:2601.22903. +* **Java reference:** ❌ none. +* **Prerequisites (the "given Voraussetzungen", all must be in place):** + ✅ `cut_graph.hpp` (2g seams) · 🔲 Phase 9c (fundamental domain) · + 🔲 Phase 10a (1-forms) · 🔲 Phase 10b (period matrix Ω) · + 🔲 Phase 10c (Fuchsian group / H²/Γ) · + 🔲 holonomy-bug fix (`detail::spherical_holonomy` / + `detail::hyperbolic_holonomy` + `cpp_dec_float_50`; see Phase 9c block) · + 🟡 Phase 12 (Penner-coordinate decoration layer — reused here; land first). +* **Scope:** (1) Penner-coordinate canonical tessellation + dual on the + H²/Γ embedding from 10c; (2) Epstein-Penner hull + Weeks-flip to reach the + canonical decomposition; (3) polyhedral realisation of the uniformised + genus-g surface. +* **Acceptance criteria:** + - Canonical tessellation unique & flip-stable (Weeks-flip terminates, + start-triangulation-independent). + - Penner-coordinate consistency with the Phase 12 decoration layer. + - Gauss-Bonnet + holonomy closure `∏[a_i,b_i] = Id` (high precision). + - Rigidity witness: Newton finds the unique realisation on the + tangency-case test set (Bowers-Bowers-Lutz 2026). +* **Effort:** very large — gated on the full 9c/10a/10b/10c chain; the Lutz + algorithms themselves ≈ several weeks on top. --- diff --git a/doc/tutorials/add-inversive-distance.md b/doc/tutorials/add-inversive-distance.md index 8d92795..e123f3b 100644 --- a/doc/tutorials/add-inversive-distance.md +++ b/doc/tutorials/add-inversive-distance.md @@ -78,7 +78,7 @@ the domain where every triangle is valid); we use the same 10-point Gauss-Legendre quadrature as `euclidean_functional.hpp`. The Hessian is finite-difference for the MVP; an analytic form -(Glickenstein 2011 eq. 4.6) is documented in the research-track roadmap. +(Glickenstein 2011 §5.2) is documented in the research-track roadmap. --- diff --git a/doc/tutorials/block-fd-hessian.md b/doc/tutorials/block-fd-hessian.md index 7849f26..7640202 100644 --- a/doc/tutorials/block-fd-hessian.md +++ b/doc/tutorials/block-fd-hessian.md @@ -107,7 +107,7 @@ controlling the degenerate-vertex clamps inherited from The global gradient is the angle-defect / Schläfli-type sum ``` -G_{b,v} = Σ_{f ∋ v} β_v(f) − Θ_v (Springborn 2020 eq. 4.6) +G_{b,v} = Σ_{f ∋ v} β_v(f) − Θ_v (Springborn 2020 §4, variational gradient) G_{a,e} = Σ_{f ∋ e} α_e(f) − θ_e ```