# 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 ``` --- ## ◼ Remaining porting — Phase 9 Java features from `de.varylab.discreteconformal` not yet in C++: ``` 9a Circle-packing / inversive-distance functionals ─────────────────────────────────────────────── Status: discovered during 9a-prep audit (2026-05-19) that the original roadmap mention "inversive_distance_functional.hpp" was based on a misreading — the Java repo at de.varylab.discreteconformal does NOT contain InversiveDistanceFunctional.java. It contains the related CPEuclideanFunctional.java which is the face-dual variant (Bobenko-Pinkall-Springborn 2010). These are two mathematically distinct models that both belong in this phase. Plan split: 9a.1 CPEuclideanFunctional (FACE-based circle packing) → cp_euclidean_functional.hpp Java reference: CPEuclideanFunctional.java (260 lines) + test Mathematical reference: Bobenko, Pinkall, Springborn (2010) — "Discrete conformal maps and ideal hyperbolic polyhedra", Geom. Topol. 14, 379-426. DOFs: ρ_f per FACE (log-radius of the face-circle) Constants: θ_e per edge (intersection angle, π/2 = orthogonal) φ_f per face (target face-angle sum, default 2π) Energy: E(ρ) = -Σ_f φ_f·ρ_f + Σ_e [½·p(θ*_e, Δρ_e)·Δρ_e + Λ(θ*_e + p)] where p = 2·atan(tan(θ*/2)·tanh(Δρ/2)), Λ = Clausen function, θ* = π − θ. Hessian: analytic, 2×2 per interior edge: h_jk = sin(θ) / (cosh(Δρ) − cos(θ)) Gauge: first face is pinned (ρ_0 = 0) New CGAL entry: CGAL::discrete_circle_packing_euclidean(mesh, np) Test suite: test_cp_euclidean_functional.cpp (Dodecahedron-with-removed-face, θ=π/2, FD gradient check, FD-vs-analytic Hessian check) 9a.2 Inversive-distance functional (VERTEX-based) → inversive_distance_functional.hpp Java reference: NONE (does not exist upstream) Mathematical reference: Luo, F. (2004) "Combinatorial Yamabe Flow on Surfaces", Commun. Contemp. Math. 6(5), 765-780. Bowers, P. & Stephenson, K. (2004) "Uniformizing dessins and Belyĭ maps via circle packing", Mem. AMS 170(805). Glickenstein, D. (2011) "Discrete conformal variations and scalar curvature on piecewise flat manifolds", J. Diff. Geom. 87(2), 201-238 (analytic Hessian). DOFs: u_i per VERTEX (u_i = log r_i) Constants: I_ij per edge (inversive distance, computed once from initial geometry: I_ij = (ℓ_ij² − r_i² − r_j²) / (2 r_i r_j)) Θ_v per vertex (target cone angle, default 2π) Edge length: ℓ_ij(u)² = e^{2u_i} + e^{2u_j} + 2 I_ij e^{u_i+u_j} Angles: identical half-tangent atan2 form to Euclidean Gradient: ∂E/∂u_v = Θ_v − Σ_{T∋v} α_v(T) (Luo 2004 Lemma 3.1) Energy: path integral E(u) = ∫₀¹⟨G(tu),u⟩dt (Luo's 1-form is closed; no general closed form, use 10-point Gauss-Legendre as in Euclidean) Hessian: FD for MVP; analytic (Glickenstein 2011 eq. 4.6) as future optimisation Gauge: first vertex pinned (u_0 = 0) New CGAL entry: CGAL::discrete_inversive_distance_map(mesh, np) Test suite: test_inversive_distance_functional.cpp (small triangle + quad + tetra, FD gradient check, convergence test, special case I=1 coincides with tangential circle packing) Cross-validation between 9a.1 and 9a.2 (Glickenstein 2011 §5): In the tangential limit (θ_e = 0 in 9a.1 ⇔ I_ij = 1 in 9a.2), both functionals describe the same circle packing. Their converged radii must satisfy ρ_f(9a.1) vs ½·log(r_i·r_j) (9a.2) under the appropriate vertex↔face dual correspondence. This cross-check is part of the Phase 9a acceptance tests. 9b Analytic HyperIdeal Hessian → Replace FD Hessian in hyper_ideal_hessian.hpp Direct differentiation through the chain: (bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ Relevant for meshes > 500 DOFs (current FD Hessian is slow there). 9c 4g-polygon boundary walk (genus g > 1) → Extend compute_fundamental_domain() beyond genus 1 Algorithm outline already in fundamental_domain.hpp as TODO(Phase 9). Java reference: FundamentalDomainUtility.java ``` --- ## ◼ 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). --- ## ◼ New research — Phase 10+ No direct Java reference implementation exists for these items. ``` Phase 10 Global uniformization for genus g ≥ 2 10a Discrete holomorphic differentials Integrate basis 1-forms ωᵢ along b-cycles of the cut graph. Mathematical basis: Bobenko–Springborn (2004), §6. Java partial reference: DiscreteHolomorphicFormUtility.java 10b Siegel period matrix Ω ∈ H_g (g×g complex symmetric, Im(Ω) > 0) Ωᵢⱼ = ∫_{bⱼ} ωᵢ Reduction to Siegel fundamental domain via Sp(2g,ℤ). Requires: 10a 10c Full uniformization for genus g ≥ 2 Embedding as H²/Γ with Γ ⊂ PSL(2,ℝ) a Fuchsian group. Requires: 10a + 10b + stable cut graph for g ≥ 2 (Phase 9c) ```