# 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. --- ## β—Ό Current focus (as of 2026-06-01) > **Agent entry point.** Read this box first. For model assignments, priority > order, and ready-to-paste prompts, see > [`phase-orchestration.md`](phase-orchestration.md) and > [`session-prompts.md`](session-prompts.md). > Audit-finding sessions run in parallel from `doc/reviewer/`. | Track | Next session | Gating | |---|---|---| | **Audit findings** | S3: H3/H4/H5/V5/V6 β€” Sonnet β†’ Opus review | None β€” start now | | **Phase quick-wins** | P1: 9g.1 + 9h.1 + 9h.2 + 9d.3 β€” Haiku β†’ Opus review | None β€” start now | | **Research: Decorated DCE** | P2: Phase 12 β€” Sonnet β†’ Opus review | None β€” start now | | **Circle pattern + convergence** | P3: 9e + 9d.4 + 9g.2 β€” Sonnet β†’ Opus review | None β€” start now | | **Research: Analytic Hessian** | P4: Phase 9b-analytic β€” Opus | ⏸ awaiting reviewer Q3 | | **Java port: genus > 1** | P5: Phase 9c β€” Opus | ⏸ awaiting reviewer Q4 + G0 | | **CGAL packaging** | S6 (audit system) β€” Opus | β›” blocked on G0 (author reply pending) | --- ## β—Ό 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 ``` --- ## β—Ό Phase 9 β€” Mixed: remaining Java port + first research extensions > **Audit 2026-05-21:** Phase 9 was originally framed as "remaining > porting", but a closer look at the local Java repository revealed: > several Phase-9 items are **not** in Java at all (`InversiveDistanceFunctional` > does not exist; `HyperIdealFunctional.java:295-298` declares `hasHessian()=false`). > The plan below now distinguishes Java-port items from research items. > Full research catalogue: [`research-track.md`](research-track.md). ``` 9a β€” Circle-packing functionals (split 2026-05-19) ───────────────────────────────────────────────────── 9a.1 CPEuclideanFunctional (Java port) β†’ cp_euclidean_functional.hpp Java source: CPEuclideanFunctional.java (260 lines) Mathematical reference: Bobenko-Pinkall-Springborn 2010 Status: 🟑 PR #8 open, 10 tests passing. 9a.2 Inversive-distance functional (RESEARCH, not a port) β†’ inversive_distance_functional.hpp Java source: NONE. Empirically verified. Mathematical reference: Luo 2004 + Bowers-Stephenson 2004 + Glickenstein 2011 Status: 🟑 PR #8 open, 11 tests passing. Cross-validation: G_id(0) = G_eu(0) at 1e-10 (Glickenstein Β§5). 9b β€” HyperIdeal Hessian (RESEARCH β€” Java has no Hessian at all) ───────────────────────────────────────────────────────────────── 9b Block-FD HyperIdeal Hessian β†’ Replace full FD in hyper_ideal_hessian.hpp Java source: NONE (HyperIdealFunctional.java:295-298 declares hasHessian()==false; Java has NO Hessian). Algorithm: per-face 6Γ—6 block, scatter to global sparse matrix. Status: 🟑 PR #9 open, 7 tests passing, ~96Γ— speed-up measured. 9b-analytic Full analytic HyperIdeal Hessian via SchlΓ€fli identity β†’ planned, see research-track.md + session-prompts.md Β§P4 Mathematical source: Springborn 2020 Β§4 + SchlΓ€fli 1858/60 + 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: 805-line LaTeX derivation in doc/math/hyperideal-hessian-derivation.md. Effort: 10–14 days net. Trigger: profiling on V > 5000. Complexity / scaling context: doc/math/complexity.md. ⏸ GATED: awaiting reviewer Q3 answer ("worth ~2 weeks at your mesh sizes?"). 9c β€” Genus g > 1 fundamental domain (Java port + research extensions) ────────────────────────────────────────────────────────────────────── 9c 4g-polygon boundary walk (genus g > 1) β†’ Extend compute_fundamental_domain() beyond genus 1 Java sources: FundamentalPolygonUtility.java (698 lines) + CanonicalFormUtility.java (532 lines) + CuttingUtility / SurgeryUtility (~800 lines) + SurfaceCurveUtility.java (360 lines, 2026-05-28 scan) β€” curve operations on the surface (cut-path tracing / fundamental-domain boundary); supporting infrastructure for the polygon construction. Mathematical source: PoincarΓ© 1882 + Sechelmann 2016 Β§5 Research component: bridging to conformallab++ cut_graph.hpp + holonomy infrastructure. † PRECISION PREREQUISITE: the canonicalisation composes products of hyperbolic isometry generators, whose entries grow exponentially. double fails to verify the group relation ∏gα΅’ = Id; Java uses MathContext(50) (RnBig/PnBig/P2Big). Port a LOCALIZED high-precision substrate (boost::multiprecision::cpp_dec_float_50 or MPFR mpreal) inside the uniformization module only β€” NOT the core or the Eigen solver. See CLAUDE.md Phase-9 note + java-parity.md exception. Effort: ~2 weeks for fundamental polygon, +2 weeks for surgery layer, +1 week integration, +~3 days high-precision substrate. ``` 9d β€” Cone metrics + sphere utilities (Java port + research extension) ──────────────────────────────────────────────────────────────────── ``` 9d.1 ConesUtility (Java port: unwrapper/ConesUtility.java) β†’ cone_singularities.hpp Fills the "⚠️ data structure only" gap in java-parity.md: - Detect interior cone vertices (angle deficit β‰  0) - BFS path from cone to mesh boundary β†’ cut edge set - Auto-placement: conjugate gradient on Θ-gradient magnitude - Quantization: snap cone angles to Ο€/2, Ο€/3, Ο€/6 for quad / triangle / hexagonal atlas targets Java reference: unwrapper/ConesUtility.java Mathematical reference: Troyanov 1991 + Springborn 2020 Β§3 9d.2 Non-Euclidean cone extensions (RESEARCH, not in Java) β†’ extend ConesUtility to HyperIdeal + Spherical modes Java source: NONE β€” Java ConesUtility is Euclidean-only. Mathematical reference: Bobenko, Lutz 2025 "Decorated Discrete Conformal Equivalence in Non-Euclidean Geometries" (Discrete & Comput. Geom. 2025, arXiv:2310.17529) Β§3 β€” decorated DCE framework unifying cone singularities and cusps in hyperbolic + spherical geometry. 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 9d.3 StereographicUnwrapper + SphereUtility (Java port) β†’ stereographic_layout.hpp Stereographic projection SΒ²β†’β„‚βˆͺ{∞} + MΓΆbius centering for genus-0 surfaces. Converts spherical DCE output to a flat 2-D atlas. Java reference: unwrapper/StereographicUnwrapper.java (266 lines) Note (2026-05-28 visualisation scan): plugin/algorithm/ StereographicTextureProjection.java (88 lines) is the texture front-end of this same math β€” no separate item. The supporting math/CP1 + ComplexUtility.stereographic are deliberately NOT ported (redundant with std::complex + the existing MobiusMap, see porting-status.md). Optional companion: MercatorTextureProjection.java (47 lines) β€” a distinct cylindrical conformal display projection; small nice-to-have for the sphere-visualisation bucket, not required. 9d.4 MobiusCenteringFunctional (Java port, optional upgrade) β†’ integrate into layout.hpp normalise_hyperbolic() Variational MΓΆbius centering via Lorentz geometry: E = Ξ£ log(-⟨x,p⟩/√(-⟨x,x⟩)) Supplies gradient + Hessian β€” replaces iterative FrΓ©chet mean. Java reference: functional/MobiusCenteringFunctional.java ``` 9e β€” Circle pattern layout (Java port β€” complement to Phase 9a.1) ──────────────────────────────────────────────────────────────────── ``` 9e CirclePatternLayout + CirclePatternUtility (Java port) β†’ circle_pattern_layout.hpp Phase 9a.1 ported the CPEuclidean energy + solver; this phase adds the embedding step (ρ values β†’ actual vertex positions in ℝ²). - CirclePatternUtility: compute per-face radii ρ via NTR solver - CirclePatternLayout: embed from ρ values (intersection-angle model) - CPEuclideanRotation: rotation-invariant CP functional variant Java references: unwrapper/circlepattern/CirclePattern{Layout,Utility}.java unwrapper/circlepattern/CPEuclideanRotation.java Mathematical reference: Bobenko-Springborn 2004 variational principle + Bobenko-Hoffmann-Springborn 2006 "Minimal surfaces from circle patterns" (Discrete & Comput. Geom. 35, 2006). ``` 9f β€” Polygon Laplacian (RESEARCH β€” no Java equivalent) ────────────────────────────────────────────────────── ``` 9f Discrete Laplacian on general polygonal meshes β†’ polygon_laplacian.hpp Java source: NONE Mathematical reference: Alexa, Wardetzky 2011 "Discrete Laplacians on General Polygonal Meshes" (ACM SIGGRAPH 2011) β€” virtual-node construction, polygon cotangent weights extending the Pinkall-Polthier formula. 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. Status: πŸ”² planned (pure research, no Java source) Effort: medium (~2 weeks core + tests; +1 week Newton integration). 9g β€” Conformal quality measures (Java port β€” 2026-05-28 scan) ────────────────────────────────────────────────────────────────── 9g.1 Quantitative correctness metrics for a computed conformal map β†’ conformal_quality.hpp Lifts the measure math out of the jReality plugin + convergence layers (the math is GUI-independent). High value / low effort: these directly strengthen the validation story for the already- shipped genus-0/1 pipeline (doc/math/validation.md). - IsothermicityMeasure (113 lines) β€” pointwise deviation from conformality (anisotropy of the induced metric). - DiscreteConformalEquivalencemMeasure (82 lines) β€” per-edge length-cross-ratio residual vs. the conformal-equivalence condition. - FlippedTriangles (17 lines) β€” detects inverted / degenerate triangles in a 2-D layout (embedding-validity check). - LengthCrossRatio (12 lines) β€” the discrete conformal invariant itself (per-edge), shared input for the two measures. - ConvergenceUtility measures (~110 lines, math/float only β€” no Mathematica/jReality deps): getMaxMeanSumCrossRatio (q=(aΒ·c)/(bΒ·d), qfun=(q+1/q)/2βˆ’1), getMaxMeanSumMultiRatio (per-face product, =1 iff conformal), and getMaxMeanSumScaleInvariantCircumRadius (R/√A, scale-invariant mesh-quality). The operational counterpart of LengthCrossRatio. Java references: plugin/visualizer/IsothermicityMeasure.java plugin/visualizer/DiscreteConformalEquivalencemMeasure.java plugin/visualizer/FlippedTriangles.java heds/adapter/types/LengthCrossRatio.java convergence/ConvergenceUtility.java Mathematical reference: Springborn-SchrΓΆder-Pinkall 2008 (length cross-ratio = discrete conformal invariant). Status: πŸ”² planned (Java port; no new theory). Effort: small (~3 days incl. gradient-free tests). No dependencies β€” can land before 9a–9f. 9g.2 Period-matrix convergence study (validation experiment β€” optional) β†’ tests/cgal/test_period_matrix_convergence.cpp (experiment, not a library feature) Empirical validation for the already-shipped period_matrix.hpp + discrete_elliptic_utility.hpp: generate a genus-1 elliptic mesh with a known analytic Ο„, then refine / subdivide / add Gaussian vertex noise and plot |Ο„_computed βˆ’ Ο„_expected| β†’ 0. Java reference: convergence/* (~1400 lines) β€” a CLI harness (joptsimple) that drives the same study. Do NOT port the harness: it depends on Mathematica via JLink and on jReality's OBJ reader + LoopLinear subdivision. Port only the *method*: - subdivision β†’ igl::loop (libigl already available) - noise β†’ trivial (vα΅’ += σ·N(0,1)) - error metric β†’ the 9g.1 quality measures + Ο„ residual Status: πŸ”² optional (raises empirical confidence in genus-1 Ο„; no new library surface). Effort: small (~2–3 days). ``` 9h β€” CLI usability extensions (infrastructure β€” no Java equivalent) ────────────────────────────────────────────────────────────────── Identified by usability-audit-2026-05-31 (Finding-U11). Two independent sub-tasks; either can land independently. ``` 9h.1 Newton solver tuning parameters (~30 min) Currently hardcoded in all three run_*() helpers: tol = 1e-8, max_iter = 200 Add to conformallab_cli.cpp: app.add_option("--tol", tol, "Newton gradient tolerance [1e-8]"); app.add_option("--max-iter", max_iter, "Newton iteration limit [200]"); Thread both through run_euclidean / run_spherical / run_hyper_ideal. Update getting-started.md CLI parameter table. Status: πŸ”² planned. Effort: ~30 min. No dependencies. 9h.2 Phase-9a models in CLI (~2–4 hours) The CP-Euclidean and Inversive-Distance functionals are fully implemented in the library and exposed via the CGAL public API (Discrete_circle_packing.h, Discrete_inversive_distance.h), but a CLI user cannot reach them. Add: -g cp_euclidean β†’ run_cp_euclidean() -g inversive_distance β†’ run_inversive_distance() Following the existing run_euclidean() pattern (~60 lines each). Add both geometry strings to the CLI::IsMember validator. Update README + getting-started.md parameter table. Status: πŸ”² planned. Effort: ~2–4 h. Requires: 9a complete βœ…. Java reference: none (both functionals are research / literature ports). ``` --- ## β—Ό New research directions β€” Phases 10d–10g (2026 library scan) These were identified by a full scan of the Java source tree in 2026. They extend significantly beyond the Java port into new mathematical territory. ``` 10d CircleDomainUnwrapper (Koebe–Andreev–Thurston) β†’ circle_domain_unwrapper.hpp Conformal map of a multiply-connected planar region onto a canonical disk-with-holes (classical complex-analysis result). Java reference: unwrapper/CircleDomainUnwrapper.java (570 lines) Mathematical basis: Koebe–Andreev–Thurston + Beardon–Stephenson 1990 10e Quasi-isothermic maps β†’ quasiisothermic.hpp Generalisation of conformal maps for meshes where exact conformality is unachievable (high Gaussian curvature, coarse triangulation). Includes: Delaunay pre-conditioning, discrete Beltrami field, sin-condition functional, Lawson-correspondence parameterization. Java references: unwrapper/quasiisothermic/ (~1 200 lines total) Mathematical basis: Lam 2015 + Bohle–Lam–Pinkall–Reitebuch 2015 10f Koebe polyhedra β†’ koebe_polyhedron.hpp Koebe–Andreev–Thurston theorem: realize every 3-connected planar graph as a convex polyhedron with edges tangent to the unit sphere. Connects circle packing with 3-D convex geometry. Java reference: unwrapper/koebe/KoebePolyhedron.java (321 lines) Mathematical basis: Koebe 1936 + Thurston 1997 (lecture notes) 10g Cyclic-symmetry functionals β†’ cyclic_functional.hpp Euclidean and hyperbolic DCE functionals reduced to a cyclic-symmetry quotient β€” dramatically reduces DOFs for ornamental / symmetric surfaces. Java references: functional/EuclideanCyclicFunctional.java functional/HyperbolicCyclicFunctional.java (~530 lines) ``` --- ## β—Ό 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). Full architecture-level comparison (overlap analysis, adoption rationale, scientific value): [`doc/architecture/geometry-central-comparison.md`](../architecture/geometry-central-comparison.md). Software landscape (libigl, CGAL, pmp-library, geometry-central): [`doc/math/software-landscape.md`](../math/software-landscape.md). --- ## β—Ό Phase 10 β€” Genus g β‰₯ 2 (research with partial Java support) Most Phase-10 items have partial Java references (utility classes for forms and homology) but the **assembly** into a working uniformization pipeline is research. Full catalogue with primary literature: [`research-track.md`](research-track.md). ``` Phase 10 Global uniformization for genus g β‰₯ 2 10a Discrete holomorphic and harmonic 1-forms β†’ Integrate basis 1-forms Ο‰α΅’ along b-cycles of the cut graph. Mathematical reference: Bobenko-Springborn 2004 Β§6 + Mercat 2001. KnΓΆppel, Crane, Pinkall, SchrΓΆder 2015 "Stripe Patterns on Surfaces" (ACM SIGGRAPH 2015) β€” application of discrete holomorphic 1-forms to direction field design; provides an independent C++ reference implementation (geometry-central) for cross-validating the Phase 10a computation. Java sources (partial, port-with-research): CanonicalBasisUtility.java 337 lines (homology basis) HomologyUtility.java 122 lines HomotopyUtility.java 57 lines (2026-05-28 scan) β€” reconstructs the explicit generator *cycles* (bridge edge + tree path via HomologyUtility.findCycle). NOT covered by cut_graph.hpp, which yields only the 2g cut *edges*; the closed loops are needed to integrate 1-forms along b-cycles. DualityUtility.java 308 lines DiscreteHarmonicFormUtility.java 657 lines DiscreteHolomorphicFormUtility.java 285 lines Prerequisite β€” DEC operator layer (2026-05-28 scan, previously unrecorded): the four utilities above are built on the discrete- exterior-calculus primitives in heds/dec/ (DEC.java 76 lines, AbstractDECOperator, DECPairing, DualChain, DualForm β€” the d / ⋆ / primal-dual pairing operators). Port this thin operator layer first; the form utilities assume it exists. Effort: ~3 days. Effort: ~6 weeks net (1 DEC layer + 4 utility ports + 1 integration). 10b Siegel period matrix Ξ© ∈ H_g (gΓ—g complex symmetric, Im(Ξ©) > 0) β†’ Ξ©α΅’β±Ό = ∫_{bβ±Ό} Ο‰α΅’ β†’ Reduction to Siegel fundamental domain via Sp(2g,β„€). Mathematical reference: Bobenko-Springborn 2004 + Gottschling 1959. 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). 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). Requires: 10a. Effort: ~1 week net after 10a. 10b' Alternative methods (parallel research track) β†’ HyperbolicCyclicFunctional (Java, 530 lines) β€” completes the classical three-mode set with hyperbolic energy. β†’ Quasi-isothermic parametrisation (Lawson correspondence): QuasiisothermicUtility.java + SinConditionApplication.java (~1 200 Java lines combined). β†’ MobiusCenteringFunctional (Java, 289 lines) β€” sphere centering. β†’ StereographicUnwrapper (Java, 266 lines) β€” projects the spherical layout SΒ²β†’β„‚ via stereographic projection plus a MΓΆbius centring step. Closes the visualisation gap from `discrete_conformal_map_spherical()` (currently outputs Point_3 on SΒ²; many downstream uses want a 2-D atlas). Effort: small (~3 days). Each independent; can be tackled in any order. 10c Full uniformization for genus g β‰₯ 2 β†’ Embedding as HΒ²/Ξ“ with Ξ“ βŠ‚ PSL(2,ℝ) a Fuchsian group. Mathematical reference: Sechelmann 2016 Β§6 (discrete instance); Bers 1960 (continuous theory). Lutz 2023 "Canonical Tessellations of Decorated Hyperbolic Surfaces" (Geom. Dedicata 217, arXiv:2206.13461) β€” canonical Delaunay tessellations in Penner coordinates; unifies the decorated framework with the fundamental domain construction. Bobenko, Lutz 2024 IMRN (arXiv:2305.10988) β€” discrete uniformization theorem for decorated piecewise Euclidean surfaces. 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. Java reference: NONE β€” Java has the polygon + period matrix pieces but does not assemble them into a Fuchsian-group representation. 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 Koebe Polyhedra and Inversive Distance Circle Packings" (arXiv:2601.22903) β€” theoretical uniqueness backing the KAT construction. β†’ ElectrostaticSphereFunctional (127 lines) β€” sphere distribution baseline. β†’ CirclePatternLayout / CirclePatternUtility β€” face-circle pattern layouts. None of these are required for the genus-g uniformization pipeline; they extend the breadth of methods. ``` --- ## β—Ό Phase 11+ β€” Specialised applications (optional, deferred) > **Status:** out-of-scope for v1.0 but recorded here so that future > contributors don't re-discover them. Both items live in the Java > repo as plugin sub-packages and would benefit from porting *only* > after Phase 10 is complete (they require the period-matrix and > fundamental-domain infrastructure to be in place first). ``` 11a Schottky uniformisation Java plugin: plugin/schottky/* (~12 Java files, ~3 000 LoC) Mathematical basis: Schottky group β€” discrete subgroup Ξ“ βŠ‚ PSL(2,β„‚) generated by hyperbolic loxodromic elements, fundamental domain a sphere with 2g disjoint discs removed. Use case: "handlebody" uniformisation, complement of Phase 10c's Fuchsian-group representation (Schottky represents Riemann surfaces as quotients of domains in SΒ² rather than of HΒ²). Requires: Phase 10b (period matrix) + working MΓΆbius-group machinery from Phase 7. Effort: very large (4–6 weeks) β€” significant Java code, complex-analytic algorithms, substantial test design. 11b Riemann maps (planar conformal mapping) Java plugin: plugin/riemannmap/* (~6 Java files, ~1 500 LoC) Mathematical basis: Riemann mapping theorem β€” every simply connected proper subdomain of β„‚ is conformally equivalent to the unit disc. Discrete version via circle packing or Schwarz-Christoffel-like formulae. Use case: Texture mapping of bounded planar regions; classical conformal mapping for engineering applications (electrostatics, fluid flow). Requires: Phase 10b' QuasiisothermicUtility or the CP-Euclidean machinery from Phase 9a.1 (depending on the chosen discrete-Riemann algorithm). Effort: large (3–4 weeks) β€” smaller than Schottky but still substantial. Heavy on visualisation; consider porting only the algorithmic core. 11c Multiply-connected planar conformal maps (CircleDomainUnwrapper) Java source: unwrapper/CircleDomainUnwrapper.java (570 LoC) Mathematical basis: Riemann mapping theorem for multiply- connected domains β€” every n-connected planar region is conformally equivalent to a disk with (nβˆ’1) round holes (Koebe's "general uniformization theorem", 1909). Use case: Classical complex-analysis problems β€” conformal mapping of an annulus, a torus slit on a plane, fluid flow around obstacles, electrostatics with multiple conductors. **A use-case class conformallab++ does not currently cover.** Requires: Phase 10b' QuasiisothermicUtility or the CP-Euclidean machinery from Phase 9a.1. Effort: large (~2 weeks). 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). ```