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

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