ConformalLabpp/doc/roadmap/research-track.md

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.

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 14, 379–426.
• 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). → inversive-distance identity I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j).
  • Glickenstein, D. (2011). Discrete conformal variations and scalar curvature on piecewise flat manifolds. J. Diff. Geom. 87(2), 201–238. → §5 correspondence I_ij = cos θ_e, eq. 4.6 analytic Hessian (used later by Phase 9b-analytic mirror).
• Java reference: ❌ none. Verified empirically:

  $ 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 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) eq. (4.6).
• 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.

---

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.

---

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.

---

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, 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:

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.