ConformalLabpp/doc/roadmap/phases.md

Development Roadmap

Legend: ✅ complete · 🔲 planned

Porting / research boundary:
Phases 1–7 are direct ports of the Java original and its dissertation.
From Phase 8 onwards the work goes beyond the scope of the Java library.
Phase 8 (CGAL package) is infrastructure. Phase 9 is porting of remaining Java features.
Phase 10+ is independent research with no direct Java reference implementation.

---

◼ 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 and 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.

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. Software landscape (libigl, CGAL, pmp-library, geometry-central): doc/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.

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).