Phase 9a-Newton: newton_cp_euclidean + newton_inversive_distance
Some checks failed
C++ Tests / test-fast (push) Has been cancelled
C++ Tests / test-cgal (push) Has been cancelled
C++ Tests / test-fast (pull_request) Successful in 2m28s
API Docs / doc-build (pull_request) Successful in 52s
C++ Tests / test-cgal (pull_request) Failing after 11m29s

Wires the two Phase-9a functionals into the Newton-solver layer so
they are operational end-to-end.  CGAL test count: 212 → 219 (+7).

Solvers
───────
* newton_cp_euclidean(mesh, x0, m, tol, max_iter)
    - Uses cp_euclidean_hessian — analytic 2×2-per-edge BPS-2010
      formula h_jk = sin θ / (cosh Δρ − cos θ).
    - SparseQR fallback handles the gauge-singular case when no face
      is pinned (caller error, but we recover gracefully).
    - Strictly-convex energy ⇒ quadratic convergence near optimum.

* newton_inversive_distance(mesh, x0, m, tol, max_iter, hess_eps)
    - Uses an inline FD Hessian (n × gradient evaluations per step) —
      mirrors the Phase 4a HyperIdeal solver in spirit.
    - Analytic alternative via Glickenstein 2011 eq. (4.6) is tracked
      in doc/roadmap/research-track.md as Phase 9a.2-analytic.
    - Sensitive to initial point; the test suite always starts from
      a natural-theta setup (u = 0 is the equilibrium when
      compute_inversive_distance_init_from_mesh was called).

Tests (test_newton_phase9a.cpp, 7 cases)
────────────────────────────────────────
* CPEuclidean_NaturalPhi_ClosedTetrahedron_ConvergesInZeroIterations
* CPEuclidean_PerturbedStart_ConvergesBackToEquilibrium
* CPEuclidean_OpenTetrahedron_NaturalPhi_Converges
* InversiveDistance_NaturalTheta_Triangle_ConvergesInZero
* InversiveDistance_PerturbedQuadStrip_Converges
* InversiveDistance_PerturbedTetrahedron_Converges
* CPEuclidean_UsesAnalyticHessian
    Regression guard: 3-DOF problem converges in ≤ 10 iterations even
    with strong perturbation, confirming the analytic Hessian path is
    actually used.

All seven tests pass.  Full CGAL suite: 219/219 PASSED, 0 SKIPPED.

Roadmap additions (`doc/roadmap/phases.md`)
───────────────────────────────────────────
New Phase 11+ section flags two Java sub-packages as optional/deferred
ports, recorded for project memory but not roadmap commitments:

* 11a — Schottky uniformisation (Java plugin/schottky/*, ~3000 LoC)
        Hyperbolic loxodromic group acting on S²; complement of the
        Phase 10c Fuchsian-group representation in H².  Requires
        Phase 10b period matrix + Möbius-group machinery from Phase 7.
        Effort: very large (4-6 weeks).

* 11b — Riemann maps (Java plugin/riemannmap/*, ~1500 LoC)
        Discrete Riemann mapping theorem; texture mapping of bounded
        planar regions, classical conformal mapping for engineering.
        Requires Phase 10b' quasi-isothermic or Phase 9a.1 CP-Euclidean.
        Effort: large (3-4 weeks).

Both are explicitly NOT roadmap commitments — they live in the doc so
they aren't re-discovered.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-21 21:10:00 +02:00
parent c5917754d8
commit dd87b8007b
4 changed files with 505 additions and 0 deletions

View File

@@ -245,3 +245,54 @@ Phase 10 Global uniformization for genus g ≥ 2
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 (46 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 (34 weeks) — smaller than Schottky
but still substantial. Heavy on
visualisation; consider porting only the
algorithmic core.
Both items are tracked here so the project memory is preserved; they
are NOT roadmap commitments. See `research-track.md` for the formal
research-versus-port classification before starting either.
```