Math-correctness audit (2026-05-29) + Euclidean holonomy/τ fix + spherical oracle #26

Merged

user2595 merged 2 commits from docs/uniformization-precision-note into main 2026-05-29 10:58:22 +00:00

Conversation 0 Commits 2 Files Changed 26 +1107 -169

user2595 commented 2026-05-28 05:41:42 +00:00

Owner

Copy Link

Summary

Bundles the 2026-05-29 Java↔C++ math-correctness audit (doc/reviewer/java-port-audit.md, 11 findings) with two follow-up fixes.

Audit code changes

• Finding 3 (spherical_functional): edge-DOF replacement parameterization via spher_eff_lambda; edge gradient α_opp⁺+α_opp⁻−θ_e (drops the additive −(S⁺+S⁻)/2 term). Vertex-only path bit-for-bit unchanged.
• Finding 4 (spherical_hessian): always-compiled edge-DOF throw guard.
• Finding 6 (period_matrix): faithful normalizeModulus (0≤Re≤½, Im≥0, |τ|≥1).
• Finding 9 (inversive_distance): degenerate-face limiting angles instead of skipping.
• Findings 1/2 (euclidean): degenerate gradient limiting angles + Hessian edge-DOF guard.

Euclidean holonomy / τ end-to-end fix

• Develop the cut surface across the dual spanning tree only (cut_graph now exposes is_dual_tree), so genus-1 cut edges yield non-degenerate lattice generators.
• Previously τ came out 0 / NaN / 1e13 on the bundled tori; now matches the analytic revolution modulus i·√(R²−r²)/r.
• Re-enabled τ reporting in the Euclidean CLI; rewrote validation.md §3/§4.

Tests — 240 CGAL, 0 skipped

• HolonomyEndToEnd ×3 — tori of revolution (4×4, hex 6×6, 8×8) vs analytic modulus.
• SphericalFunctional.EdgeGradient_RegularTetClosedForm — independent closed-form π/3 oracle locking Finding 3 (the path-integral FD check cannot detect a wrong-but-conservative gradient).

Also

• Documents the latent spherical/hyperbolic holonomy-extraction bug (same single-development pattern, dead code today) in research-track.md (Phase 9c/10).
• Adds favour / normalisations to the codespell ignore list.

Test plan

• cmake -S code -B build -DWITH_CGAL_TESTS=ON && cmake --build build --target conformallab_cgal_tests → 240/240 pass
• non-CGAL conformallab_tests → 23/23 pass
• BUILD_DIR=build bash scripts/check-test-counts.sh → OK (non-CGAL 23, CGAL 240)
• four required quality gates (license-headers, cgal-conventions, codespell, shellcheck) → all pass
• CLI: torus_4x4 / hex_6x6 / 8x8 print τ = 1.793151i / 2.850258i / 2.841296i

## Summary Bundles the **2026-05-29 Java↔C++ math-correctness audit** (`doc/reviewer/java-port-audit.md`, 11 findings) with two follow-up fixes. **Audit code changes** - **Finding 3** (`spherical_functional`): edge-DOF *replacement* parameterization via `spher_eff_lambda`; edge gradient `α_opp⁺+α_opp⁻−θ_e` (drops the additive `−(S⁺+S⁻)/2` term). Vertex-only path bit-for-bit unchanged. - **Finding 4** (`spherical_hessian`): always-compiled edge-DOF `throw` guard. - **Finding 6** (`period_matrix`): faithful `normalizeModulus` (`0≤Re≤½, Im≥0, |τ|≥1`). - **Finding 9** (`inversive_distance`): degenerate-face limiting angles instead of skipping. - **Findings 1/2** (`euclidean`): degenerate gradient limiting angles + Hessian edge-DOF guard. **Euclidean holonomy / τ end-to-end fix** - Develop the cut surface across the **dual** spanning tree only (`cut_graph` now exposes `is_dual_tree`), so genus-1 cut edges yield non-degenerate lattice generators. - Previously τ came out `0 / NaN / 1e13` on the bundled tori; now matches the analytic revolution modulus `i·√(R²−r²)/r`. - Re-enabled τ reporting in the Euclidean CLI; rewrote `validation.md` §3/§4. **Tests — 240 CGAL, 0 skipped** - `HolonomyEndToEnd ×3` — tori of revolution (4×4, hex 6×6, 8×8) vs analytic modulus. - `SphericalFunctional.EdgeGradient_RegularTetClosedForm` — independent closed-form `π/3` oracle locking Finding 3 (the path-integral FD check cannot detect a wrong-but-conservative gradient). **Also** - Documents the **latent** spherical/hyperbolic holonomy-extraction bug (same single-development pattern, dead code today) in `research-track.md` (Phase 9c/10). - Adds `favour` / `normalisations` to the codespell ignore list. ## Test plan - [x] `cmake -S code -B build -DWITH_CGAL_TESTS=ON && cmake --build build --target conformallab_cgal_tests` → 240/240 pass - [x] non-CGAL `conformallab_tests` → 23/23 pass - [x] `BUILD_DIR=build bash scripts/check-test-counts.sh` → OK (non-CGAL 23, CGAL 240) - [x] four required quality gates (license-headers, cgal-conventions, codespell, shellcheck) → all pass - [x] CLI: `torus_4x4 / hex_6x6 / 8x8` print τ = 1.793151i / 2.850258i / 2.841296i

user2595 added 2 commits 2026-05-28 05:41:43 +00:00

docs: record 2026-05-28 full-library scan findings in roadmap ... 1ff5382c8b

Cross-referenced all 232 Java classes against the roadmap. New plan
entries for genuinely-useful, previously-unplanned items:
- 9g.1 conformal quality measures (Isothermicity, ConformalEquivalence,
  FlippedTriangles, LengthCrossRatio + ConvergenceUtility metrics)
- 9g.2 optional period-matrix convergence experiment (method only;
  Java harness depends on Mathematica/JLink + jReality, not ported)
- DEC operator layer (heds/dec/) noted as a 10a prerequisite
- HomotopyUtility -> 10a (explicit generator cycles; not covered by
  cut_graph.hpp, which yields only the 2g cut edges)
- SurfaceCurveUtility -> 9c; MercatorTextureProjection -> 9d.3 companion

Documented as deliberately out-of-scope: SpanningTreeUtility (subsumed
by cut_graph.hpp), convergence/* harness, datasource/* (jReality viewer
decoration), *Big arbitrary-precision geometry, jReality GUI, and the
MTJ/Tao/PETSc solver bindings.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs: note high-precision requirement for Phase 9c/10 uniformization ... ca936b7652

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>

user2595 added 1 commit 2026-05-29 10:50:25 +00:00

fix+test: Euclidean holonomy/τ end-to-end + spherical edge-DOF oracle (2026-05-29 audit) ... a3ee9576d4

Bundles the 2026-05-29 Java↔C++ math-correctness audit (doc/reviewer/
java-port-audit.md, 11 findings) with two follow-up fixes.

Audit code changes:
- Finding 3 (spherical_functional): edge-DOF replacement parameterization via
  spher_eff_lambda; edge gradient α_opp⁺+α_opp⁻−θ_e (drops additive −(S⁺+S⁻)/2)
- Finding 4 (spherical_hessian): always-compiled edge-DOF throw guard
- Finding 6 (period_matrix): faithful normalizeModulus (0≤Re≤½, Im≥0, |τ|≥1)
- Finding 9 (inversive_distance): degenerate-face limiting angles, no skip
- Findings 1/2 (euclidean): degenerate gradient limiting angles + Hessian guard

Euclidean holonomy/τ fix: develop the cut surface across the dual spanning tree
only (cut_graph now exposes is_dual_tree), so genus-1 cut edges yield
non-degenerate lattice generators. Previously τ came out 0 / NaN / 1e13 on the
bundled tori; now matches the analytic revolution modulus i·√(R²−r²)/r. Re-enabled
τ reporting in the Euclidean CLI; rewrote validation.md §3/§4 accordingly.

Tests (240 CGAL, 0 skipped):
- HolonomyEndToEnd ×3 — tori of revolution (4×4, hex 6×6, 8×8) vs analytic modulus
- SphericalFunctional.EdgeGradient_RegularTetClosedForm — independent closed-form
  π/3 oracle locking the Finding-3 edge formula (the path-integral FD check cannot
  detect a wrong-but-conservative gradient)

Also documents the latent spherical/hyperbolic holonomy-extraction bug (same
single-development pattern, dead code today) in research-track.md (Phase 9c/10),
and adds favour/normalisations to the codespell ignore list.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

user2595 changed title from docs: note high-precision requirement for Phase 9c/10 uniformization to Math-correctness audit (2026-05-29) + Euclidean holonomy/τ fix + spherical oracle 2026-05-29 10:50:44 +00:00

user2595 merged commit 18b9c61492 into main 2026-05-29 10:58:22 +00:00

user2595 referenced this issue from a commit 2026-05-29 10:58:23 +00:00

Merge pull request 'Math-correctness audit (2026-05-29) + Euclidean holonomy/τ fix + spherical oracle' (#26) from docs/uniformization-precision-note into main

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

carl.lutz user2595

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: conformallab/ConformalLabpp#26

No description provided.