From ca936b7652fc40e8b7a824bf9b7ac9516ddd04ad Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Thu, 28 May 2026 07:41:23 +0200 Subject: [PATCH] docs: note high-precision requirement for Phase 9c/10 uniformization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Java uniformization classes (FundamentalPolygonUtility, CanonicalFormUtility) rely on the *Big arbitrary-precision geometry (MathContext(50)) because products of hyperbolic isometry generators grow exponentially and double fails to verify the group relation ∏gᵢ = Id. Record this planning-relevant prerequisite and resolve the contradiction in java-parity.md, which previously listed *Big as permanently out of scope. - CLAUDE.md: † note on the Phase-9 not-yet-ported table - java-parity.md: *Big exception (localized high-precision substrate for 9c/10) - phases.md: precision prerequisite as 9c sub-task + effort estimate - design-decisions.md: new "Scalar type: double, with one localized exception" Core flattening (Newton/energy/Eigen solver) stays double; the substrate (cpp_dec_float_50 / mpreal) is localized to the uniformization module only. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 6 ++++-- doc/architecture/design-decisions.md | 20 ++++++++++++++++++++ doc/roadmap/java-parity.md | 11 ++++++++++- doc/roadmap/phases.md | 9 ++++++++- 4 files changed, 42 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 59458b4..3b35b4c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -191,13 +191,15 @@ The Java library under `de.varylab.discreteconformal` contains these items not y |---|---|---| | `InversiveDistanceFunctional` | `inversive_distance_functional.hpp` | 9a | | Analytic HyperIdeal Hessian | `hyper_ideal_hessian.hpp` (replace FD) | 9b | -| 4g-polygon boundary walk in `FundamentalDomainUtility` | `fundamental_domain.hpp` (extend) | 9c | +| 4g-polygon boundary walk in `FundamentalDomainUtility` | `fundamental_domain.hpp` (extend) | 9c † | | `DiscreteHarmonicFormUtility` | Phase 10a prerequisite | 10 | | `DiscreteHolomorphicFormUtility` | Phase 10a | 10 | -| `HomologyUtility`, `CanonicalBasisUtility` | Phase 10 | 10 | +| `HomologyUtility`, `CanonicalBasisUtility` | Phase 10 † | 10 | When porting a Java class, locate the original in `de.varylab.discreteconformal.*` at [github.com/varylab/conformallab](https://github.com/varylab/conformallab) and use it as the reference implementation. +**† High-precision requirement (Phase 9c / 10):** The Java uniformization classes (`FundamentalPolygon`, `CanonicalFormUtility`) use `RnBig`/`PnBig`/`P2Big` with `MathContext(50)` — 50 significant decimal digits. Reason: products of hyperbolic isometry generators grow exponentially, so `double` fails when verifying the group relation ∏gᵢ = Id. When porting, replicate this **locally** with `boost::multiprecision::cpp_dec_float_50` (or MPFR `mpreal`) — only inside the uniformization module, NOT globally and NOT in the Eigen solver. The core flattening (Newton/energy) stays `double` (see `conformal_mesh.hpp:45`). + ## Test design patterns ### "Natural theta" — constructing a known equilibrium at x* = 0 diff --git a/doc/architecture/design-decisions.md b/doc/architecture/design-decisions.md index 9e40bb2..6416071 100644 --- a/doc/architecture/design-decisions.md +++ b/doc/architecture/design-decisions.md @@ -46,6 +46,26 @@ and linear system infrastructure to serve all three without branching. --- +## Scalar type: `double`, with one localized exception + +The kernel is `CGAL::Simple_cartesian` and the whole numerical core +(functionals, Hessians, Newton, Eigen sparse solvers) is `double`. Conformal +flattening minimises a smooth energy over transcendental (floating-point) lengths +and angles, so exact/extended arithmetic buys nothing there — the Java original is +`double` here too. The CGAL wrapper (`include/CGAL/*.h`) is templated on `FT` for +API genericity, but delegates to the `double` core. + +**The one exception (deferred, Phase 9c/10):** hyperbolic uniformization +(`FundamentalPolygonUtility`, `CanonicalFormUtility`) composes products of isometry +generators whose entries grow exponentially; `double` then fails to verify the group +relation ∏gᵢ = Id. The Java original handles this with `RnBig`/`PnBig`/`P2Big` at +`MathContext(50)`. When ported, this needs a **localized** high-precision substrate +(`boost::multiprecision::cpp_dec_float_50` or MPFR `mpreal`) **inside the +uniformization module only** — never the core or the Eigen solver. See `CLAUDE.md` +Phase-9 note and `doc/roadmap/java-parity.md` (`*Big` exception). + +--- + ## Priority-BFS layout A naive BFS layout places faces in arbitrary order; trilateration errors accumulate diff --git a/doc/roadmap/java-parity.md b/doc/roadmap/java-parity.md index dd357f7..e2cc0d1 100644 --- a/doc/roadmap/java-parity.md +++ b/doc/roadmap/java-parity.md @@ -89,7 +89,16 @@ items were unrecorded and have now been added above: Everything else unmentioned is intentionally out of scope: the `plugin/*` jReality Swing GUI, the `MTJ*`/`Tao*`/`*PETSc` solver bindings (replaced by Eigen), the convergence/`*Series` test harness, and the `*Big` arbitrary-precision geometry -(`P2Big`/`PnBig`/`RnBig` — deliberately dropped in favour of `Simple_cartesian`). +(`P2Big`/`PnBig`/`RnBig` — deliberately dropped from the core in favour of `Simple_cartesian`). + +> **Exception — `*Big` is NOT permanently out of scope.** The Phase 9c/10 uniformization +> classes (`FundamentalPolygonUtility`, `CanonicalFormUtility`, rows 55–56 above) build on +> the `*Big` classes in Java for a reason: products of hyperbolic isometry generators grow +> exponentially, so `double` fails when verifying the group relation ∏gᵢ = Id (`MathContext(50)` +> = 50 significant digits in Java). When those classes are ported, a localized high-precision +> substrate (`boost::multiprecision::cpp_dec_float_50` or MPFR `mpreal`) must be reintroduced — +> **only inside the uniformization module**, not in the core flattening or the Eigen solver. +> See the Phase-9 note in `CLAUDE.md`. --- diff --git a/doc/roadmap/phases.md b/doc/roadmap/phases.md index ae311f1..84c3c8b 100644 --- a/doc/roadmap/phases.md +++ b/doc/roadmap/phases.md @@ -131,8 +131,15 @@ mesh type. 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. + layer, +1 week integration, +~3 days high-precision substrate. ``` 9d — Cone metrics + sphere utilities (Java port + research extension)