# Research Track — items beyond the Java port

> **Purpose:** This document consolidates everything in conformallab++
> that goes *beyond* a port of `de.varylab.discreteconformal`.  Items
> listed here are **new research**, drawn from published mathematical
> sources (not from Java code).  They are separated from the
> port-tracking sheet `doc/roadmap/java-parity.md` so that the porting
> work and the research work can be planned independently.
>
> **Companion documents:**
> - [`doc/math/novelty-statement.md`](../math/novelty-statement.md) — why these
>   contributions are novel and who the target audience is.
> - [`doc/math/software-landscape.md`](../math/software-landscape.md) — how
>   conformallab++ relates to libigl, geometry-central, and CGAL (relevant for
>   deciding research vs. duplication at the boundary cases).
> - [`phase-orchestration.md`](phase-orchestration.md) — model assignments and
>   session prompts for implementing items in this document.
>
> **Created:** 2026-05-21, after a full doc audit that identified four
> items previously mislabelled as "ports".  This document corrects the
> record and extends it with the explicit research plan for Phase
> 9b-analytic.

---

## How to read this document

Every entry has the structure:

```
### <item>
* Mathematical source(s):  <papers with year, journal, equation/section>
* Java reference:          NONE  (or:  partial — <class>, with the note "<what>")
* Status:                  🔲 planned · 🟡 PR open · ✅ landed · ❌ blocked
* Acceptance criteria:     <what tests/proofs must pass>
* Effort:                  small / medium / large
* Phase:                   9b-analytic / 9c / 10a / 10b / 10c
```

The phase numbers match `doc/roadmap/phases.md`.

---

## Items already on `main` (research, not port)

### Hyper-ideal Hessian — FD (Phase 4a, ✅ landed)
* **Mathematical source:** symmetric central difference of the
  analytic gradient `G = (β − Θ, α − θ)` (Springborn 2020 §4 for the
  gradient itself).
* **Java reference:** `HyperIdealFunctional.java:295-298` declares
  `hasHessian() { return false; }` — **Java has no Hessian at all**.
* **Status:** ✅ landed in `code/include/hyper_ideal_hessian.hpp` Phase 4a.
* **Why a research item, not a port:** the existing Phase 4a label
  describes only *when* it was added to the C++ project, not Java
  parity.  The Hessian is a conformallab++ addition.
* **Effort:** small (already done).

### Period matrix τ for genus 1 (Phase 7, ✅ landed)
* **Mathematical source:**
  - Sechelmann (2016) *Variational Methods for Discrete Surface
    Parameterization* §4 — SL(2,ℤ) reduction algorithm.
  - Bobenko-Springborn (2004) §6 — period matrix definition.
* **Java reference:** partial — `PeriodMatrixUtility.java` exists in Java
  with similar functionality (this *is* a port).
* **Status:** ✅ landed in `code/include/period_matrix.hpp`.
* **Note:** listed here only because parts of `phase-9a-validation.md`
  reference it as research; clarification — the genus-1 period matrix is
  a Java port, the **genus g ≥ 2** extension (Phase 10b) is research.

### Möbius holonomy in SU(1,1) (Phase 7, ✅ landed)
* **Mathematical source:** Bobenko-Springborn (2004) §5; Sechelmann
  (2016) §3 for the SU(1,1) representation.
* **Java reference:** partial — Java has Möbius transformations but not
  the holonomy-around-cut-graph computation in the same form.
* **Status:** ✅ landed in `code/include/layout.hpp` (`MobiusMap` class).
* **Why partially research:** the half-edge `uv` storage for proper
  seam-aware texture atlasing is new in conformallab++.

### Cross-API consistency tests (Phase 7 stubs, ✅ landed)
* `EuclideanFunctional.GradientCheck_Hessian` and the spherical analog
  were ported from Java `@Ignore` stubs and given real bodies.
* See `doc/architecture/phase-9a-validation.md` for the full mapping.

---

## Items currently on open PRs

### CP-Euclidean functional (Phase 9a.1, 🟡 PR #8)
* **Mathematical source:** Bobenko, Pinkall, Springborn (2010).
  *Discrete conformal maps and ideal hyperbolic polyhedra.*
  Geometry & Topology 19(4) (2015), 2155–2215. arXiv:1005.2698.
* **Java reference:** ✅ `CPEuclideanFunctional.java` (260 lines + 88-line
  `CPEuclideanFunctionalTest.java`).  **This one IS a port.**
* **Status:** 🟡 PR #8 open, 10 tests including Java-test parity.
* **Note:** listed here because the *face-based* DOF structure is new in
  conformallab++ (existing functionals all have vertex/edge DOFs); the
  trait API generalisation needed for it is research-flavoured but the
  algorithm itself is a port.

### Inversive-distance functional (Phase 9a.2, 🟡 PR #8)
* **Mathematical sources:**
  - **Luo, F.** (2004). *Combinatorial Yamabe Flow on Surfaces.*
    Comm. Contemp. Math. 6(5), 765–780.  → edge-length formula §3,
    gradient identity Lemma 3.1.
  - **Bowers, P. L. & Stephenson, K.** (2004). *Uniformizing dessins
    and Belyĭ maps via circle packing.* Memoirs of the AMS 170(805).
    → introduces inversive-distance circle packings. NB: the formula
    `I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j)` is the *classical* inversive
    distance (= Glickenstein §5.2 η), not a B–S-specific identity.
  - **Glickenstein, D.** (2011). *Discrete conformal variations and
    scalar curvature on piecewise flat two- and three-dimensional
    manifolds.* J. Diff. Geom. 87(2), 201–238.  → §5.2 inversive-distance
    parametrization ℓ²=r_i²+r_j²+2r_ir_jη; correspondence I_ij = cos θ_e
    holds only up to sign/supplement (intersection at arccos(−η)).
    The paper does **not** number equations as "(4.6)".
* **Java reference:** ❌ **none.**  Verified empirically:
  ```bash
  $ find /Users/tarikmoussa/Desktop/conformallab -iname "*nversive*"
  (zero matches)
  ```
* **Status:** 🟡 PR #8 open, 11 tests including limit-case verification
  and cross-validation with `euclidean_functional.hpp` at `u = 0`.
* **Acceptance criteria (all met):**
  - Three limit-cases of Luo's `ℓ²` formula at machine precision
    (tangent, orthogonal, inside-tangent).
  - Bowers-Stephenson round-trip identity at machine precision.
  - FD-vs-analytic gradient check ≤ 1e-6 on triangle, quad-strip, tetra.
  - Cross-validation `G_id(0) = G_eu(0)` at 1e-10 (Glickenstein §5).

### Hyper-ideal Hessian — block-FD (Phase 9b, 🟡 PR #9)
* **Mathematical source:** per-face locality lemma:
  `∂G_x/∂y = Σ_{f: x,y ∈ local(f)} ∂(β or α)/∂y at f`.
  Same gradient as Phase 4a (Springborn 2020 §4).
* **Java reference:** ❌ none (`hasHessian() == false`).
* **Status:** 🟡 PR #9 open, 7 tests, measured 96× speed-up over Phase 4a.
* **Why research:** the locality lemma + 6×6 block-scatter is a
  conformallab++ algorithmic contribution; it makes Hessian-based Newton
  viable on meshes that the upstream Java cannot solve in reasonable
  time at all (since it has no Hessian).

---

## Planned research (not yet PR)

### Hyper-ideal volume formulas for 2- and 3-ideal-vertex faces (Phase 9b+, 🔲 planned)

* **Mathematical sources:**
  - **Kolpakov, A. & Mednykh, A.** (2012). *Spherical structures on torus
    knots and links.* Sibirsk. Mat. Zh. 53(3), 535–541 — see the earlier
    arXiv:math/0603097 for the one-ideal-vertex formula already implemented
    as `calculateTetrahedronVolumeWithIdealVertexAtGamma`.
  - **Milnor, J.** (1982). *Hyperbolic geometry: The first 150 years.*
    Bull. Amer. Math. Soc. 6(1), 9–24.  → Volume of an ideal tetrahedron
    via Clausen function; this is the all-ideal case with 4 ideal vertices.
  - **Vinberg, E. B.** (1985). *Hyperbolic reflection groups.*
    Uspekhi Mat. Nauk 40(1), 29–66. → general semi-ideal / orthoscheme approach.
  - Study arXiv:math/0603097 §3–4 carefully to determine whether the
    one-ideal formula already yields the correct limit as γ₂ → 0
    (ideal v2): if Л(0) = 0 absorbs the second ideal vertex naturally,
    the extension to 2-ideal may be free; if not, a different formula is needed.

* **Java reference:** ❌ **none.**  `HyperIdealUtility.java` has exactly two
  volume functions; the Java `HyperIdealFunctional` silently falls through the
  `if/else-if` cascade for 2+ideal faces (uses the one-ideal formula for the
  first ideal vertex found, ignoring subsequent ideal vertices).  C++ now
  throws `std::logic_error` instead (fixed 2026-05-30, Finding-A).

* **Context:**
  In the standard workflow (`assign_all_dof_indices`) every vertex is
  hyper-ideal and no face has ideal vertices — the currently missing formulas
  are never reached.  They only matter for:
  (a) mixed configurations with some pinned (ideal) vertices; and
  (b) cusped hyperbolic surfaces (Θᵥ = 0 for a cusp vertex).
  Use case (b) is the main motivation for eventually implementing these.

* **Acceptance criteria:**
  - Identify the correct formula for a hyper-ideal tetrahedron with exactly
    2 ideal vertices from the literature (check Kolpakov-Mednykh generalisations
    and Vinberg orthoscheme decomposition).
  - Implement `calculateTetrahedronVolumeWithTwoIdealVertices(…)` analogous
    to the existing Kolpakov-Mednykh function.
  - Implement `calculateTetrahedronVolumeWithThreeIdealVertices(…)` (one
    hyper-ideal + three ideal = fully cusp-like case).
  - Replace the `throw std::logic_error` in `face_energy()` with the correct
    branch for each case; update the guard to throw only for `ideal_count > 3`
    (which is topologically impossible).
  - Gradient check passes for each new configuration at machine precision
    (central FD vs. analytic, tol = 1e-4).
  - Limiting-behaviour test: as `b_v → 0` for a hyper-ideal vertex, the
    energy from the 0-ideal formula must converge to the 1-ideal formula to
    1e-6 (continuity witness).

* **Effort:** medium (3–5 days: 1–2 days literature study + derivation,
  1–2 days implementation, 1 day tests).

* **Phase:** 9b+ (add to Phase 9b milestone once the analytic Hessian PR lands;
  the two features are independent).

* **Note:** The `throw` introduced in the 2026-05-30 fix is the **correct
  safe behaviour** until this item is resolved.  Do not remove it without
  implementing and testing the replacement formulas.

---

### Hyper-ideal Hessian — full analytic (Phase 9b-analytic, 🔲 planned)

* **Mathematical sources:**
  - **Schläfli, L.** (1858/60). *On the multiple integral
    ∫dx dy …*  Quart. J. Pure & Appl. Math.  → second-order Schläfli
    identity: `2 dV = Σ_e aₑ dαₑ + Σ_v bᵥ dβᵥ` for any hyperbolic
    polyhedron, with corresponding bilinear differential on second
    derivatives.
  - **Springborn, B.** (2020). *Ideal Hyperbolic Polyhedra and
    Discrete Uniformization.* Discrete & Comput. Geom.  → §4 for the
    hyper-ideal energy whose gradient is `(β − Θ, α − θ)`, hence
    Hessian is the Schläfli bilinear form's restriction to the
    constraint surface.
  - **Cho, Y. & Kim, H.** (1999). *On the volume formula for
    hyperbolic tetrahedra.*  Discr. Comput. Geom. 22, 347–366.
    → explicit derivative formulas for `∂α/∂a`, `∂α/∂b`, `∂β/∂a`,
    `∂β/∂b` at hyperbolic tetrahedra.
  - **Glickenstein, D.** (2011) §4 — analogous derivation for the
    cone-vertex case (extending the formulas across the ideal /
    hyper-ideal vertex boundary).

* **Java reference:** ❌ none.

* **Chain of differentiation:**

  ```
  (bᵢ, aₑ)  →  ℓᵢⱼ           via lij()      (closed form: ζ₁₃, ζ₁₄, ζ₁₅)
            →  βᵢ            via zeta()     (law of cosines)
            →  αᵢⱼ           via alpha_ij() (zeta + sigma_i + sigma_ij)
  ```

  Each arrow is a smooth function in the interior of its domain.  The
  chain rule then gives, for each face:

  ```
  ∂βᵢ/∂(bⱼ, aₑ)  =  Σ_k  (∂βᵢ/∂ℓₖ) · (∂ℓₖ/∂(bⱼ, aₑ))
  ∂αᵢⱼ/∂(bₖ, aₑ) =  (similar, with β-dependence factored)
  ```

  These are then assembled into the local 6×6 block, scattered the
  same way as block-FD (Phase 9b).

* **Acceptance criteria:**
  - Each of the four partial-derivative formulas (`∂α/∂a`, `∂α/∂b`,
    `∂β/∂a`, `∂β/∂b`) cross-checked against block-FD at random `x` on
    every supported vertex configuration:
      - all hyper-ideal vertices (general case)
      - one ideal vertex (`σᵢ`/`σⱼ`/`σₖ` ideal branches)
      - two ideal vertices
  - Schläfli identity `H · x = 0` for the constant-vector `x` that
    corresponds to a global Möbius dilation must hold numerically
    (gauge null space).
  - PSD property preserved (Springborn 2020 §4.3).
  - Measured speed-up over Phase 9b block-FD ≥ 3× (asymptotic ~6×).
  - **Correctness proof:** a short LaTeX note in
    `doc/math/hyperideal-hessian-derivation.tex` showing each
    Schläfli + chain-rule step with edge-cases.

* **Effort:** large (10–14 days net).  Significant share of the time
  is the formal derivation note and the per-case symbolic verification.

* **Phase:** 9b-analytic.

* **Why deferred:** Phase 9b (block-FD) already removes the practical
  Hessian bottleneck (96× speed-up measured).  Analytic gives only
  another ~6× but at substantial implementation + verification cost.
  Land on demand when profiling on a real V > 5000 application points
  to it as the new bottleneck.

---

### Inversive-distance Hessian — full analytic (Phase 9a.2-analytic, 🔲 planned)

* **Mathematical source:** Glickenstein, D. (2011) §5.2 (inversive-distance parametrization ℓ²=r_i²+r_j²+2r_ir_jη).
* **Java reference:** ❌ none.
* **Chain:** `(uᵢ, uⱼ) → ℓᵢⱼ → αᵢⱼ` with `∂ℓ²/∂u_i = 2(r_i² + I r_i r_j)`.
* **Effort:** medium (5–7 days, less involved than HyperIdeal because
  the chain has fewer levels and no `σ` intermediaries).
* **Status:** 🔲 planned, mirrors Phase 9b-analytic in spirit.

---

### Non-Euclidean cone extensions (Phase 9d.2, 🔲 planned)

* **Mathematical sources:**
  - **Bobenko, Lutz** (2025). *Decorated Discrete Conformal Equivalence in
    Non-Euclidean Geometries.* Discrete & Comput. Geom. arXiv:2310.17529.
    → §3: Penner-coordinate decoration unifies cone singularities (Θᵥ ≠ 2π)
    and hyperideal cusps (Θᵥ = 0) in a single algebraic framework valid in
    Euclidean, spherical, and hyperbolic geometry.
  - **Soliman, Slepčev, Crane** (2018). *Optimal Cone Singularities
    for Conformal Flattening.* ACM Trans. Graph. 37(4), Art. 105. DOI: 10.1145/3197517.3201367.
    → L¹-optimal cone placement via a sparse-recovery optimisation over the
    curvature deficit Kᵥ = 2π − Θᵥ; directly gives the set of cone angles
    to prescribe for a near-flat conformal parametrisation.
  - **Lutz** (2024). *PhD thesis, TU Berlin.* DOI: 10.14279/depositonce-20357.
    → Full proofs for both non-Euclidean decorated DCE variants; single reference
    covering 9d.2, 10b, and 10c.

* **Java reference:** ❌ **none.** Java `ConesUtility.java` handles only the
  Euclidean case; the non-Euclidean extension is new research.

* **Scope:**
  - Extend `cones_utility.hpp` (Phase 9d.1, Java port) to accept prescribed
    cone angles in HyperIdeal and Spherical modes.
  - Integrate the Bobenko-Lutz decoration into the variational framework of
    `hyper_ideal_functional.hpp` and `spherical_functional.hpp`.
  - Optionally: implement the Crane 2018 L¹-optimiser as a helper that
    suggests cone positions automatically from the input curvature.

* **Status:** 🔲 planned; no PR yet.
* **Effort:** medium (1–2 weeks for Euclidean→HyperIdeal/Spherical extension;
  +1 week if Crane 2018 optimiser is included).
* **Acceptance criteria:**
  - Prescribed Θᵥ ≠ 2π in HyperIdeal mode: Gauss-Bonnet check passes with
    `2π·χ = Σ Θᵥ − Σ αᵢⱼ` for given cone angles.
  - Newton convergence on a mesh with two manually placed cone singularities
    (Euclidean, Spherical, HyperIdeal).
  - Cross-validation: at Θᵥ = 2π for all v, output equals existing non-cone solver.

---

### Polygon Laplacian (Phase 9f, 🔲 planned)

* **Mathematical sources:**
  - **Alexa, Wardetzky** (2011). *Discrete Laplacians on General Polygonal
    Meshes.* ACM SIGGRAPH 2011. DOI: 10.1145/1964921.1964997.
    → Virtual-node construction: each polygon face is replaced by a virtual
    central node connected to all vertices; cotangent weights are computed
    per sub-triangle; the resulting operator is symmetric and positive
    semi-definite, mirroring Pinkall-Polthier for triangulations.
  - **Bunge, Herholz, Kazhdan, Botsch** (2020). *Polygon Laplacian Made Simple.*
    Computer Graphics Forum 39(2), 303–313. DOI: 10.1111/cgf.13931.
    → virtual-vertex construction with error analysis. (DEC alternative:
    de Goes, Butts, Desbrun 2020, ACM TOG 39(4), DOI 10.1145/3386569.3392389.)

* **Java reference:** ❌ **none.**

* **Scope:**
  - Implement `polygon_laplacian.hpp` following the virtual-node construction.
  - Slot it into `newton_solver.hpp` as a drop-in replacement for
    `euclidean_hessian.hpp` when the input mesh is non-triangular.
  - No change to the energy functional — only the Hessian approximation changes.

* **Status:** 🔲 planned; pure research, no Java reference.
* **Effort:** medium (~2 weeks core + tests; +1 week Newton integration).
* **Acceptance criteria:**
  - Operator is symmetric and PSD (checked via `LDLT.info() == Success`).
  - On a pure triangle mesh, output equals `euclidean_hessian.hpp` result.
  - Newton convergence on a quad mesh (e.g., structured grid) with the
    polygon Laplacian Hessian.

---

### Genus g ≥ 2 fundamental domain (Phase 9c, 🔲 planned)
* **Mathematical sources:**
  - **Poincaré, H.** (1882). *Théorie des groupes fuchsiens.*
    Acta Math. 1, 1–62. → 4g-gon construction.
  - **Sechelmann** (2016) §5 for the canonical-form algorithm.
* **Java reference:** ✅ partial — `FundamentalPolygonUtility.java`
  (698 lines) + `CanonicalFormUtility.java` (532 lines) exist; this is
  a port-with-research-extensions (the C++ side will need to bridge to
  the cut-graph + holonomy infrastructure already in conformallab++).
* **Effort:** large (10–14 days).
* **Status:** roadmap item, no PR yet.
* **Known prerequisite bug (latent, 2026-05-29):** the holonomy-extraction
  blocks in `spherical_layout` and `hyper_ideal_layout` (`layout.hpp`)
  repeat the flawed single-development pattern that produced garbage τ for
  the Euclidean path before the 2026-05-29 fix.  They read the
  translation / Möbius deck transformation from one full-surface
  development plus a one-sided apex trilateration, instead of developing
  across only the **dual** spanning tree and measuring the shared-edge
  displacement between two independent developments (as the corrected
  `detail::euclidean_holonomy` now does).  These blocks are currently dead
  code — every caller passes `holonomy == nullptr` — but Phase 9c/10b will
  exercise the hyperbolic path.  Fix = add `detail::spherical_holonomy` /
  `detail::hyperbolic_holonomy` mirroring `detail::euclidean_holonomy`.
  The hyperbolic mirror additionally needs `cpp_dec_float_50` (group-relation
  product ∏gᵢ = Id overflows `double`; see CLAUDE.md high-precision note).

---

### Discrete holomorphic and harmonic 1-forms (Phase 10a, 🔲 planned)
* **Mathematical sources:**
  - **Mercat, C.** (2001). *Discrete Riemann surfaces and the Ising
    model.* Comm. Math. Phys. 218, 177–216. → discrete complex
    structure on a quad mesh.
  - **Bobenko, A. I. & Springborn, B.** (2004) §6 — discrete
    harmonic and holomorphic 1-forms on triangulated surfaces.
* **Java reference:** ✅ `DiscreteHarmonicFormUtility.java` (657 lines)
  + `DiscreteHolomorphicFormUtility.java` (285 lines).  Port-with-
  research:  the C++ port can choose between literal Java translation
  and a redesign that uses `cut_graph.hpp` + `period_matrix.hpp`
  natively (research opportunity).
* **Effort:** very large (3+ weeks); see java-parity.md.

---

### Siegel period matrix Ω ∈ H_g (Phase 10b, 🔲 planned)
* **Mathematical sources:**
  - **Bobenko-Springborn (2004)** §6 for the discrete formula
    `Ω_{ij} = ∫_{b_j} ω_i`.
  - Siegel-fundamental-domain reduction algorithm (Gottschling 1959).
* **Java reference:** ✅ partial — `DiscreteRiemannUtility.java`
  (186 lines).
* **Acceptance criteria:** `Ω` symmetric, `Im(Ω) > 0`, in the standard
  fundamental domain of `Sp(2g, ℤ)`.
* **Effort:** medium (1 week after 10a).

---

### Full uniformization for genus g ≥ 2 (Phase 10c, 🔲 planned)
* **Mathematical source:** classical (Poincaré 1883; Bers 1960);
  Sechelmann 2016 §6 for the discrete instance.
* **Java reference:** ❌ none — Java has the polygon + period matrix
  pieces but does not assemble them into a Fuchsian group representation.
* **Status:** **fully new research** — depends on 9c + 10a + 10b.
* **⚠️ Scope boundary:** 10c delivers the *infrastructure* (Fuchsian-group
  representation + H²/Γ embedding on the Sechelmann/Bobenko-Springborn path).
  The Lutz-*specific* algorithms (canonical Delaunay tessellation in Penner
  coordinates, Epstein-Penner hull, Weeks-flip, polyhedral realisation) are
  **not** auto-delivered by reaching 10c — they are split out as **Phase 13**
  (Chain B capstone), which sits on top of this runway.

---

### Decorated DCE & geometric transition (Phase 12, 🔲 planned — near-term, Chain A)
* **Mathematical sources:**
  - **Bobenko, Lutz** (2025). *Decorated Discrete Conformal Equivalence in
    Non-Euclidean Geometries.* Discrete & Comput. Geom. arXiv:2310.17529. §3
    — Penner-coordinate decoration unifying Euclidean/spherical/hyperbolic
    DCE; continuous deformation at fixed discrete conformal invariant.
  - **Lutz** (2024). *PhD thesis, TU Berlin.* DOI: 10.14279/depositonce-20357.
* **Java reference:** ❌ none.
* **Builds on (✅ landed):** `inversive_distance_functional.hpp` (9a.2),
  `hyper_ideal_functional.hpp` (Springborn 2020), `spherical_functional.hpp`
  — the decoration is a re-parametrisation of these, not a new solver.
* **Does NOT require:** 9c / 10a / 10b / holonomy-bug fix. This is the
  **short path**: the earliest Lutz-adjacent result, independent of Chain B.
* **Scope:** (1) Penner-coordinate decoration layer ↔ classical inversive
  distance `ℓ²=r_i²+r_j²+2r_ir_jη`; (2) curvature-transition driver κ∈{+,0,−}
  at fixed invariant; (3) validation harness + example gallery.
* **Acceptance criteria:**
  - Decoration round-trip `I_ij ↔ (r_i,r_j,ℓ)` at machine precision.
  - At κ=0 bit-for-bit match with the existing Euclidean/inversive path.
  - Gauss-Bonnet per geometry; invariant constant across the κ-transition
    to tol (numerical witness of the Bobenko-Lutz master theorem).
  - Cross-geometry agreement of the invariant on one test surface.
* **Effort:** medium (functionals exist; reparametrisation + driver + tests).

---

### Decorated canonical tessellations & polyhedral realisation (Phase 13, 🔲 planned — Chain B capstone)
* **Mathematical sources:**
  - **Lutz** (2023). *Canonical Tessellations of Decorated Hyperbolic
    Surfaces.* Geom. Dedicata 217. arXiv:2206.13461 — canonical (weighted-
    Delaunay-analogue) tessellation + dual; Epstein-Penner convex hull in
    Minkowski space; Weeks-flip extension.
  - **Bobenko, Lutz** (2024). IMRN 2024(12), 9505–9534. arXiv:2305.10988 —
    discrete uniformization theorem for decorated surfaces.
  - **Lutz** (2024). *PhD thesis* (depositonce-20357) — polyhedral realisation.
  - Rigidity backing: **Bowers, Bowers, Lutz** (2026), arXiv:2601.22903.
* **Java reference:** ❌ none.
* **Prerequisites (the "given Voraussetzungen", all must be in place):**
  ✅ `cut_graph.hpp` (2g seams) · 🔲 Phase 9c (fundamental domain) ·
  🔲 Phase 10a (1-forms) · 🔲 Phase 10b (period matrix Ω) ·
  🔲 Phase 10c (Fuchsian group / H²/Γ) ·
  🔲 holonomy-bug fix (`detail::spherical_holonomy` /
  `detail::hyperbolic_holonomy` + `cpp_dec_float_50`; see Phase 9c block) ·
  🟡 Phase 12 (Penner-coordinate decoration layer — reused here; land first).
* **Scope:** (1) Penner-coordinate canonical tessellation + dual on the
  H²/Γ embedding from 10c; (2) Epstein-Penner hull + Weeks-flip to reach the
  canonical decomposition; (3) polyhedral realisation of the uniformised
  genus-g surface.
* **Acceptance criteria:**
  - Canonical tessellation unique & flip-stable (Weeks-flip terminates,
    start-triangulation-independent).
  - Penner-coordinate consistency with the Phase 12 decoration layer.
  - Gauss-Bonnet + holonomy closure `∏[a_i,b_i] = Id` (high precision).
  - Rigidity witness: Newton finds the unique realisation on the
    tangency-case test set (Bowers-Bowers-Lutz 2026).
* **Effort:** very large — gated on the full 9c/10a/10b/10c chain; the Lutz
  algorithms themselves ≈ several weeks on top.

---

### geometry-central cross-comparison track (Optional, 🔲 exploratory)
Three independent items (GC-1/2/3) tracked separately in
`doc/roadmap/phases.md` and analysed in detail in
`doc/architecture/geometry-central-comparison.md`.  They are **purely
exploratory**, not roadmap commitments.

| ID | Item | Effort |
|---|---|---|
| GC-1 | Output-vector cross-validation against geometry-central | small (2 days) |
| GC-2 | Intrinsic Delaunay pre-conditioning via Ptolemaic flips | medium (1 week) |
| GC-3 | Ptolemaic flip-based solver as alternative backend | research (Phase 10+) |

---

## Java features still worth porting

These are tracked separately in
[`java-parity.md`](java-parity.md), summarised here only for cross-reference:

| Java class | Lines | Suggested phase | Effort |
|---|---|---|---|
| `FundamentalPolygonUtility` + `CanonicalFormUtility` | 698 + 532 | 9c | 2 weeks |
| `CuttingUtility` + `SurgeryUtility` | 584 + 217 | 9c foundation | 2 weeks |
| `DiscreteHarmonicFormUtility` | 657 | 10a | 2 weeks |
| `DiscreteHolomorphicFormUtility` | 285 | 10a | 2 weeks |
| `CanonicalBasisUtility` | 337 | 10a prereq | 1 week |
| `DualityUtility` + `HomologyUtility` | 308 + 122 | 10a support | 1 week |
| `DiscreteRiemannUtility` | 186 | 10b | small |
| `HyperbolicCyclicFunctional` | 530 | 10b–c | 2 weeks |
| `QuasiisothermicUtility` + `SinConditionApplication` | ~1 200 | 10b | 3 weeks |
| `KoebePolyhedron` | 321 | 10c | 2 weeks |
| `StereographicUnwrapper` | 266 | 10b' (Sphere→ℂ atlas) | small (~3 days) |
| `CircleDomainUnwrapper` | 570 | 11+ (multiply-connected planar regions) | large (~2 weeks) |
| `MobiusCenteringFunctional`, `ElectrostaticSphereFunctional` | 289 + 127 | 10c (optional) | small |

Total identified backlog: ~6 500 Java lines, estimated ~5 months of work
to bring it all over.  None of it changes the **mathematical** scope —
all 11 items above sit within Phases 9c, 10a, 10b, 10c.

---

## Maintenance rule

If a future PR claims "ports X from Java", **first verify** by:

```bash
find /Users/tarikmoussa/Desktop/conformallab -iname "*X*"
grep -r "ClassName" /Users/tarikmoussa/Desktop/conformallab/src
```

If either returns zero matches, the item is research and belongs in
**this** document, not in `java-parity.md`.  Add it with the structured
template above, including the primary literature reference and the
acceptance criteria.