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.

---

◼ 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
         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: short LaTeX correctness note in doc/math/.
         Effort: 10–14 days net.  Trigger: profiling on V > 5000.

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

---

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

---

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