docs: note high-precision requirement for Phase 9c/10 uniformization
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m0s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 54s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m14s

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 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-28 07:41:23 +02:00
parent 1ff5382c8b
commit ca936b7652
4 changed files with 42 additions and 4 deletions

View File

@@ -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<double>` 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