test: Java golden-value oracles for the five DCE math cores + P1-2/P1-3 fixes #27

user2595 · 2026-05-29T17:09:12Z

user2595 commented

2026-05-29 17:09:12 +00:00

Java golden-value oracles for the five DCE math cores (P0) + P1-2/P1-3 fixes

Pins the C++ math/functional cores bit-for-bit (1e-12) against the compiled upstream Java library (de.varylab.discreteconformal.*, openjdk 17). Unlike the existing FD gradient checks — which only prove curl-freeness, since the C++ energy is the path-integral of its own gradient — these lock absolute values against an independent implementation.

New oracle suites

HyperIdealGoldenJava — Clausen/Л/ImLi₂, ζ₁₃/₁₄/₁₅/ζ, both tetrahedron-volume formulas (real Clausen / HyperIdealUtility).
EuclideanGoldenJava / SphericalGoldenJava — angle formulas + β relations + Л energy terms, plus full-mesh oracles driving the real EuclideanCyclicFunctional / SphericalFunctional on a shared tetrahedron: per-vertex gradient Θ−Σα and ΔE = E(x)−E(0) (C++ Gauss-Legendre path integral vs Java closed form — two independent methods).
SphericalGoldenJava.FullMeshEdgeDofGradient — edge-DOF gradient (vertex + edge components, α_opp⁺+α_opp⁻−θ_e) vs raw conformalEnergyAndGradient, locking Finding 3 at the solution level (audit items 4 & 5).
PeriodMatrix.NormalizeModulus_GoldenJava — τ-reduction fold convention vs the real DiscreteEllipticUtility.normalizeModulus (audit items 7 & 8).

Subtlety documented: the spherical oracles call Java's raw conformalEnergyAndGradient, not evaluate() — evaluate() pre-runs a 1-D Brent maximization over the global-scale gauge (maximizeInNegativeDirection), which C++ factors into the Newton solver's spherical_gauge_shift instead.

Bundled fixes

P1-2 (layout.hpp): Euclidean holonomy uses a per-cut-edge rigid-motion fit g(z)=a·z+b, exposing residual_rotation = |arg(a)| as a diagnostic. Non-regressive (flat case a=1 reduces to the old midpoint formula).
P1-3 (period_matrix.hpp): is_in_fundamental_domain fixed to the correct half-open SL(2,ℤ) domain (−½ ≤ Re < ½). The now-exposed ComputePeriodMatrix_ReducedTau_InFD was updated to assert the normalizeModulus domain (closed +½ edge) instead.

Verification

Full CGAL suite: 246/246 pass, 0 skipped; non-CGAL 26/26. Counts consistent across doc/api/tests.md (single source of truth) and CLAUDE.md; check-test-counts.sh green.
Four required quality gates pass; codespell clean on all touched files.

Scope note

This MR deliberately contains only the test/oracle + P1-2/P1-3 work. The parallel literature-review edits (doc/math/references.md, novelty-statement.md, roadmap/reviewer docs, and the Glickenstein §5.2 line in CLAUDE.md) are intentionally excluded and will land via their own MR.

🤖 Generated with Claude Code

## Java golden-value oracles for the five DCE math cores (P0) + P1-2/P1-3 fixes Pins the C++ math/functional cores **bit-for-bit (1e-12)** against the compiled upstream Java library (`de.varylab.discreteconformal.*`, openjdk 17). Unlike the existing FD gradient checks — which only prove curl-freeness, since the C++ energy is the path-integral of its own gradient — these lock absolute values against an independent implementation. ### New oracle suites - **`HyperIdealGoldenJava`** — Clausen/Л/ImLi₂, ζ₁₃/₁₄/₁₅/ζ, both tetrahedron-volume formulas (real `Clausen` / `HyperIdealUtility`). - **`EuclideanGoldenJava`** / **`SphericalGoldenJava`** — angle formulas + β relations + Л energy terms, **plus full-mesh oracles** driving the real `EuclideanCyclicFunctional` / `SphericalFunctional` on a shared tetrahedron: per-vertex gradient `Θ−Σα` and `ΔE = E(x)−E(0)` (C++ Gauss-Legendre **path integral** vs Java **closed form** — two independent methods). - **`SphericalGoldenJava.FullMeshEdgeDofGradient`** — edge-DOF gradient (vertex + edge components, `α_opp⁺+α_opp⁻−θ_e`) vs raw `conformalEnergyAndGradient`, locking **Finding 3** at the solution level (audit items 4 & 5). - **`PeriodMatrix.NormalizeModulus_GoldenJava`** — τ-reduction fold convention vs the real `DiscreteEllipticUtility.normalizeModulus` (audit items 7 & 8). **Subtlety documented:** the spherical oracles call Java's raw `conformalEnergyAndGradient`, *not* `evaluate()` — `evaluate()` pre-runs a 1-D Brent maximization over the global-scale gauge (`maximizeInNegativeDirection`), which C++ factors into the Newton solver's `spherical_gauge_shift` instead. ### Bundled fixes - **P1-2** (`layout.hpp`): Euclidean holonomy uses a per-cut-edge rigid-motion fit `g(z)=a·z+b`, exposing `residual_rotation = |arg(a)|` as a diagnostic. Non-regressive (flat case `a=1` reduces to the old midpoint formula). - **P1-3** (`period_matrix.hpp`): `is_in_fundamental_domain` fixed to the correct half-open SL(2,ℤ) domain (`−½ ≤ Re < ½`). The now-exposed `ComputePeriodMatrix_ReducedTau_InFD` was updated to assert the `normalizeModulus` domain (closed `+½` edge) instead. ### Verification - Full CGAL suite: **246/246 pass, 0 skipped**; non-CGAL **26/26**. Counts consistent across `doc/api/tests.md` (single source of truth) and `CLAUDE.md`; `check-test-counts.sh` green. - Four required quality gates pass; codespell clean on all touched files. ### Scope note This MR deliberately contains **only** the test/oracle + P1-2/P1-3 work. The parallel literature-review edits (`doc/math/references.md`, `novelty-statement.md`, roadmap/reviewer docs, and the `Glickenstein §5.2` line in `CLAUDE.md`) are intentionally **excluded** and will land via their own MR. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

user2595 added 1 commit 2026-05-29 17:09:13 +00:00

test: Java golden-value oracles for the five DCE math cores + P1-2/P1-3 fixes

C++ Tests / test-fast (pull_request) Successful in 1m57s

Details

API Docs / doc-build (pull_request) Successful in 59s

Details

Markdown link check / check (pull_request) Successful in 51s

Details

C++ Tests / test-cgal (pull_request) Has been skipped

Details

C++ Tests / quality-gates (pull_request) Successful in 2m19s

Details

ba83974525

Add bit-for-bit (1e-12) golden-value oracle tests pinning the C++ pure-math
and functional cores against the compiled upstream Java library (openjdk 17):

- HyperIdealGoldenJava: Clausen/Л/ImLi2, ζ13/14/15/ζ, both tetrahedron-volume
  formulas (real de.varylab…Clausen / HyperIdealUtility).
- EuclideanGoldenJava / SphericalGoldenJava: angle formulas + β relations + Л
  energy terms, plus FULL-MESH oracles driving the real EuclideanCyclicFunctional
  / SphericalFunctional on a shared tetrahedron — per-vertex gradient (Θ−Σα) and
  ΔE = E(x)−E(0) (C++ Gauss-Legendre path integral vs Java closed form).
- SphericalGoldenJava.FullMeshEdgeDofGradient: edge-DOF gradient (vertex + edge
  components, α_opp⁺+α_opp⁻−θ_e) vs raw conformalEnergyAndGradient — locks
  Finding 3 at the solution level (audit items 4 & 5).
- PeriodMatrix.NormalizeModulus_GoldenJava: τ-reduction fold convention vs the
  real DiscreteEllipticUtility.normalizeModulus (audit items 7 & 8).

Subtlety documented: the spherical oracles call Java's raw
conformalEnergyAndGradient, not evaluate() (which pre-runs a Brent gauge
maximization that C++ factors into the Newton solver's spherical_gauge_shift).

Also:
- P1-2 (layout.hpp): Euclidean holonomy now uses a per-cut-edge rigid-motion fit
  g(z)=a·z+b, exposing residual_rotation = |arg(a)| as a diagnostic; non-
  regressive (flat case a=1 reduces to the old midpoint formula).
- P1-3 (period_matrix.hpp): is_in_fundamental_domain fixed to the correct
  half-open SL(2,ℤ) domain (−½ ≤ Re < ½). Updated the now-exposed
  ComputePeriodMatrix_ReducedTau_InFD to assert the normalizeModulus domain
  (closed +½ edge) instead.

Test counts (single source of truth = doc/api/tests.md): 272/272 pass, 0
skipped (26 non-CGAL + 246 CGAL).

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

user2595 referenced this issue from a commit

2026-05-29 21:38:29 +00:00

docs(reviewer): cross-validation analysis of Java @Ignore tests

~~user2595 referenced this pull request 2026-05-29 21:38:55 +00:00~~

feat(euclidean): edge-DOF (cyclic) Hessian — block-FD + full analytic + Java cross-validation #29

user2595 merged commit 03e8000ac6 into main

2026-05-30 08:01:02 +00:00

user2595 referenced this issue from a commit

2026-05-30 08:01:04 +00:00

Merge pull request 'test: Java golden-value oracles for the five DCE math cores + P1-2/P1-3 fixes' (#27) from tests/java-golden-oracles into main

user2595 referenced this issue from a commit

2026-05-30 15:33:13 +00:00