ConformalLabpp/doc/reviewer/java-port-audit.md

Java → C++ Port Audit — Anomalies & Missing Test Cases

Systematic comparison of the C++ port (code/include/*.hpp) against the original Java reference (~/Desktop/conformallab, de.varylab.discreteconformal.functional.*). Focus: math correctness, logic, and faithfulness to the reference.

Status legend: ✅ fixed · ⚠️ open / needs decision · ℹ️ note (no action)

---

Files compared (math-critical)

Java	C++	Verdict
Clausen.java	clausen.hpp	✅ faithful (incl. inits return, clausen2, Л, ImLi2)
EuclideanCyclicFunctional.java	euclidean_functional.hpp, euclidean_geometry.hpp	✅ angles + gradient assembly match; degenerate handling fixed
— Hessian (triangleHessian/conformalHessian)	euclidean_hessian.hpp	cotangent + vertex block match; edge block not implemented (now guarded)
SphericalFunctional.java	spherical_functional.hpp, spherical_geometry.hpp	✅ vertex-mode + edge-DOF replacement parameterization now match (Finding 3)
HyperIdealFunctional.java	hyper_ideal_functional.hpp, hyper_ideal_geometry.hpp	✅ faithful (incl. degenerate (π,0,0) angles)
HyperIdealUtility.java	hyper_ideal_utility.hpp	✅ ζ, ζ₁₃, ζ₁₄, ζ₁₅, both tetrahedron-volume formulas match
CPEuclideanFunctional.java	cp_euclidean_functional.hpp	✅ p(), gradient, energy match
DiscreteEllipticUtility.java	discrete_elliptic_utility.hpp, period_matrix.hpp	✅ normalizeModulus faithful and now wired into compute_period_matrix (Finding 6)
HomologyUtility.java, CanonicalBasisUtility.java, SpanningTreeUtility.java	cut_graph.hpp	tree-cotree only; no canonical/symplectic basis ℹ️ (Finding 7)
EuclideanLayout.java (holonomy)	layout.hpp (detail::euclidean_holonomy)	translation via midpoint displacement; ignores residual rotation ℹ️ (Finding 8)

---

Findings

1. ✅ FIXED — Degenerate triangle handling (Euclidean + Spherical gradient)

The Java reference assigns the limiting corner angles to a degenerate (triangle-inequality-violating) face — the corner opposite the over-long edge is π, the other two 0. This is the convex C¹ extension that keeps the BPS energy well-defined on the infeasible region, so Newton can pass through a flip without stalling.

The C++ port returned {0,0,0} and skipped the whole face in the gradient. Tell-tale: the hyper-ideal port already mirrors Java's (π,0,0) fallback — euclidean/spherical were inconsistent oversights.

Fix: euclidean_geometry.hpp / spherical_geometry.hpp degenerate branches now return the limiting angles (still valid=false, so the cotangent Hessian keeps skipping — matching Java, whose triangleHessian zeroes cotangents on degenerate faces). euclidean_functional.hpp / spherical_functional.hpp gradients no longer skip. All 237 tests pass; solution unchanged (only affects evaluations that previously contributed zero).

2. ✅ FIXED — euclidean_hessian missing edge-DOF guard

Doc comment claimed "the function asserts that no edge DOF is variable" — but no such guard existed. With edge DOFs assigned (assign_euclidean_all_dof_indices), the Java conformalHessian's edge-edge and vertex-edge blocks are absent, so the C++ would silently build a Hessian with all-zero edge rows/cols (singular → LDLT fails → QR least-squares garbage). Fix: added an always-compiled throw std::logic_error guard.

3. ✅ FIXED — Spherical edge-DOF parameterization now matches Java

Java's spherical functional drops the u_i + u_j vertex terms when an edge is a variable (replacement parameterization, SphericalFunctional.java:398–400), whereas the C++ previously used additive Λ = λ⁰ + u_i + u_j + λ_e always. That made the C++ spherical edge gradient carry an extra −(S_f⁺+S_f⁻)/2 term absent from Java's G.add(i, αk + αl − π) (SphericalFunctional.java:283–292).

Fix: added helper spher_eff_lambda implementing the replacement convention (Λ_ij = λ_e when the edge carries a DOF, else λ⁰ + u_i + u_j); spherical_gradient Pass 1 now uses it, and the edge gradient is α_opp⁺ + α_opp⁻ − θ_e (θ_e default π), exactly matching Java. The energy is the path integral of this gradient, so it follows automatically. The vertex-only path is bit-for-bit unchanged (no edge DOFs → identical to before). All 237 tests pass.

4. ✅ FIXED — Spherical Hessian edge-DOF guard added

spherical_hessian.hpp builds only the vertex block; Java's spherical conformalHessian includes edge terms. Same limitation as the Euclidean Hessian but previously without the edge-DOF guard added in Finding 2. Fix: added an always-compiled throw std::logic_error guard at the top of spherical_hessian (mirrors Finding 2), so any attempt to use edge DOFs with the spherical Hessian fails loudly instead of silently building a singular matrix. All 237 tests pass.

5. ℹ️ NOTE — CP-Euclidean energy uses clausen2, Java uses clausen

CPEuclideanFunctional.java:226 calls Clausen.clausen (the BORDERLINE-2.0944 polynomial); the C++ energy calls clausen2 (the Chebyshev variant). Both compute the same Cl₂ integral to ~machine precision, and the term appears only in the energy (not the Newton-driving gradient). No functional impact. The C++ never ported the clausen() variant at all — harmless.

6. ✅ FIXED — Period-matrix reduction now uses the faithful Java port

Two reductions coexist:

• discrete_elliptic_utility.hpp::normalizeModulus is a faithful line-by-line port of Java DiscreteEllipticUtility.normalizeModulus — it folds τ into 0 ≤ Re(τ) ≤ ½, Im(τ) ≥ 0, |τ| ≥ 1 (the extra Re ≥ 0 fold uses the mirror symmetry τ ≅ −τ̄).
• period_matrix.hpp::reduce_to_fundamental_domain reduces to the standard SL(2,ℤ) domain −½ ≤ Re(τ) < ½, |τ| ≥ 1 (no Re ≥ 0 fold).

compute_period_matrix (the production path, and the one the torus_8x8 τ test exercises) calls reduce_to_fundamental_domain, so normalizeModulus is never used outside its own unit test (verified by grep). Consequence: the C++ production τ can land with Re(τ) < 0 where Java would report the mirrored +|Re(τ)|. Same conformal type up to orientation, but not equal to the Java oracle value — this will bite any golden-value cross-check (missing-test item 5).

Fix (option a): compute_period_matrix now calls normalizeModulus, so the production τ matches the Java oracle exactly (folds into 0 ≤ Re ≤ ½, Im ≥ 0, |τ| ≥ 1 via the mirror symmetry). normalizeModulus is no longer dead code. The existing torus_8x8 τ test still passes (Re ∈ [0,½] ⊂ [−½,½] so it satisfies is_in_fundamental_domain too). reduce_to_fundamental_domain is retained for callers that explicitly want the canonical (non-mirror-folded) SL(2,ℤ) domain.

7. ℹ️ NOTE — Cut graph is tree-cotree, not a canonical homology basis

cut_graph.hpp (compute_cut_graph) runs the Erickson–Whittlesey tree-cotree algorithm: primal BFS tree, dual BFS cotree, the remaining 2g edges generate H₁. Java's CanonicalBasisUtility.getCanonicalHomologyBasis goes further — it builds the intersection form on the generators and solves for a canonical symplectic basis {a₁..a_g, b₁..b_g} (and uses weighted shortest-path cycles, not unweighted BFS).

• Genus 1: harmless — there is only one generator pair, and compute_period_matrix reduces τ to the fundamental domain, so the basis choice washes out. The common case matches.
• Genus > 1: the C++ omega[] ordering is arbitrary (edge-iteration order), so τ = ω₂/ω₁ is not the canonical Riemann period matrix. This is already flagged in the period_matrix.hpp header ("Computing Ω from holonomy data requires integration of holomorphic differentials — not implemented") so it is consistent with the documented contract, not a regression.

8. ✅ FIXED — Holonomy now fits the full deck isometry (was: midpoint only)

detail::euclidean_holonomy (layout.hpp) develops each face along a dual tree that never crosses a cut edge. It previously read each generator's translation as the midpoint displacement ω = midA − midB of the shared cut edge between its two independent developments — exact only when the two developments differ by a pure translation (linear part = identity), i.e. a perfectly flat cone metric (Θ ≡ 2π). Under residual cone-angle defect that was a first-order approximation.

Fix (2026-05-29): it now fits the full orientation-preserving deck isometry g(z) = a·z + b to the correspondence (Bs,Bt) ↦ (As,At) (a = (At−As)/(Bt−Bs), b = As − a·Bs). Because both faces use the same edge length, |a| = 1 exactly, so the fit is an exact isometry; ω = b is its translation part and |arg(a)| is exposed per cut edge as HolonomyData::residual_rotation (a convergence diagnostic). For a flat cone metric a = 1 and b reduces to midA − midB, so converged flat tori are bit-for-bit unchanged — all 240 CGAL tests still pass, including HolonomyEndToEnd.{Torus4x4,TorusHex6x6,Torus8x8}. Note: when |arg(a)| is non-negligible the holonomy is a genuine rotation and no lattice translation is well-defined; the diagnostic now surfaces that instead of silently averaging.

---

Findings in non-ported (conformallab++-only) math modules

These modules have no Java reference — they were ported from the literature (Luo 2004, Glickenstein 2011, Bowers–Stephenson 2004) or are original additions. They were audited against the cited formulas / first principles rather than Java.

9. ✅ FIXED — Inversive-distance gradient now uses limiting angles (consistent with Finding 1)

inversive_distance_functional.hpp::inversive_distance_gradient previously detected a triangle-inequality-violating face two ways and skipped it in both:

• if (l12sq <= 0 || l23sq <= 0 || l31sq <= 0) continue; (non-real circle config)
• if (!fa.valid) continue; (degenerate-but-real triangle)

The second skip was the same situation Finding 1 fixed for Euclidean/Spherical: euclidean_angles returns the limiting angles (π opposite the over-long edge, 0/0 for the others) with valid=false, but this code threw them away.

Fix: removed the if (!fa.valid) continue; skip so the limiting angles flow into the gradient (the BPS-style convex C¹ extension), mirroring Finding 1; added a comment explaining the rationale. The first skip (l*sq <= 0, a genuinely non-real circle configuration with no limiting angle) is kept. All 237 tests pass.

10. ℹ️ NOTE — Inversive-distance edge length has no overflow centring

id_detail::edge_length_squared computes ℓ² = rᵢ² + rⱼ² + 2·I·rᵢ·rⱼ with r = exp(u) directly — no log-centring like euclidean_angles's μ. The angle computation is still safe (it re-centres internally on log ℓ²), but the raw ℓ² can overflow for extreme |u|. Cosmetic robustness only; not hit in practice.

11. ℹ️ NOTE — Verified correct (no action)

Audited against the literature and found faithful:

• trilaterate_2d / _sph / _hyp (layout.hpp) — circle-circle intersection (ℝ²), spherical law of cosines via α·pa+β·pb+γ·(pa×pb), and hyperbolic law of cosines + Poincaré-disk Möbius placement. All three exact; left/CCW side correct.
• newton_solver.hpp — merit f = ½‖G‖²; Newton dir is always a descent dir (∇f·dx = −‖G‖²), Armijo tests algebraically correct in both phases; spherical solver factorises −H (PSD) and d_sd = −H·G = −∇f uses the un-negated H — all consistent. SparseQR fallback handles the gauge null space (valid because Gauss–Bonnet makes G ⟂ 𝟙).
• gauss_bonnet.hpp — χ=V−E+F, g=(2−χ)/2, enforce shift δ=(lhs−rhs)/V makes the new sum equal 2π·χ exactly.
• Normalisations — Euclidean PCA, spherical Rodrigues (mean→north), hyperbolic weighted Fréchet-mean Möbius centring: all correct (spherical has a benign antipodal-mean edge case that no-ops).

---

Missing test cases (gaps observed during the audit)

1. Degenerate / flipped-triangle gradient — no test drives a face through the triangle-inequality boundary to lock in Finding 1. Add: build a triangle with one edge length > sum of the others, assert the gradient picks up the π corner (not 0). Cover both Euclidean and Spherical.

2. euclidean_hessian edge-DOF guard — no test asserts the new throw fires when assign_euclidean_all_dof_indices is used. Add an EXPECT_THROW.

3. ✅ DONE (2026-05-29) — Holonomy / period matrix end-to-end now covers three tori of revolution (HolonomyEndToEnd.{Torus4x4,TorusHex6x6,Torus8x8}), each asserting τ against the analytic modulus i·√(R²−r²)/r and Re(τ) ≈ 0. (This also fixed the Euclidean holonomy extraction — develop across the dual tree only — see layout.hpp / cut_graph.hpp.)

4. ✅ DONE (2026-05-29) — the Finding-3 spherical edge-DOF gradient is now locked at two levels: (a) EdgeGradient_RegularTetClosedForm — an independent closed-form oracle pinning each edge-DOF gradient to π/3 (= 2·(2π/3) − π) on the regular spherical tetrahedron; and (b) SphericalGoldenJava.FullMeshEdgeDofGradient_Tetrahedron — a live-Java full-mesh oracle (item 5) on a generic asymmetric configuration that pins BOTH the vertex gradient AND the edge gradient α_opp⁺ + α_opp⁻ − θ_e to 1e-12 vs the real raw conformalEnergyAndGradient. The vertex-DOF spherical path is likewise locked by SphericalGoldenJava.FullMeshGradientAndEnergy_…. Still open (solver feature, not a correctness gap): Newton-to-convergence with edge DOFs is blocked by the Finding-4 spherical-Hessian guard (throw on edge DOFs), so a converged-metric test needs an FD-Hessian or guard relaxation first.

5. ✅ DONE (2026-05-29) — golden-value oracles now span both levels: • pure-math / per-triangle (1e-12 vs compiled upstream, openjdk 17): HyperIdealGoldenJava (Clausen/Л/ImLi₂, ζ₁₃/₁₄/₁₅/ζ, both tetrahedron-volume formulas), EuclideanGoldenJava (angle formula + 2·Л energy), SphericalGoldenJava (law-of-cosines angles + β relations + Л energy), PeriodMatrix.NormalizeModulus_GoldenJava (item 8). • full-mesh energy + gradient at a known x — the originally-fragile part, now solved via a shared OBJ tetrahedron loaded identically in both languages: EuclideanGoldenJava.FullMeshGradientAndEnergy_Tetrahedron and SphericalGoldenJava.FullMeshGradientAndEnergy_Tetrahedron drive the REAL EuclideanCyclicFunctional / SphericalFunctional and pin every per-vertex gradient Θ−Σα (matched by vertex position) AND ΔE = E(x)−E(0) to 1e-12. The ΔE check is doubly independent: C++ computes energy as a Gauss-Legendre PATH INTEGRAL of its gradient, Java as a CLOSED-FORM sum — the initialEnergy constant and the φ·λ⁰ term cancel in the difference (no edge DOFs here). • full-mesh EDGE-DOF gradient — SphericalGoldenJava.FullMeshEdgeDofGradient_Tetrahedron makes two opposite tetrahedron edges variable (replacement parameterization λ_e = x[e_idx]) and pins BOTH the vertex gradient AND the edge gradient α_opp⁺+α_opp⁻−θ_e to 1e-12 vs the real raw conformalEnergyAndGradient, closing the Finding-3 solution-level gap (item 4). It is a pure gradient oracle (no ΔE): with an edge DOF, x=0 ⇒ λ_e=0 ⇒ arc length π is degenerate, so the path-integral-from- origin energy reference is ill-defined; the fixed-x gradient is the unambiguous quantity. It never touches the Hessian, so the Finding-4 edge-DOF Hessian guard does not block it. Harness: /tmp/oracle/SphereEdgeOracle.java. Subtlety surfaced: the spherical oracle must call Java's raw conformalEnergyAndGradient, not evaluate(); evaluate() first runs a 1-D Brent maximization over the global-scale gauge (maximizeInNegativeDirection), which the C++ spherical_gradient deliberately omits (C++ factors that gauge into the Newton solver's spherical_gauge_shift). Harnesses: /tmp/oracle/{tet.obj,EucMeshOracle.java,SphereMeshOracle.java,SphereEdgeOracle.java}. The edge-DOF full-mesh gradient oracle is now also done (item 4, SphereEdgeOracle.java).

6. CP-Euclidean clausen vs clausen2 — a single test asserting |clausen(x) − clausen2(x)| < 1e-12 across a sweep would document Finding 5 and guard against an approximation regression.

7. ⚠️ PARTLY DONE (2026-05-29) — the Re ≥ 0 fold convention is now locked at the function level by item 8 (NormalizeModulus_GoldenJava, including Re < 0 inputs). Still open: an end-to-end torus whose true τ has Re(τ) < 0 before reduction, asserting the production pipeline yields Re(τ) ≥ 0 (so any future switch back to reduce_to_fundamental_domain is caught at the mesh level, not just the function level).

8. ✅ DONE (2026-05-29) — PeriodMatrix.NormalizeModulus_GoldenJava pins the C++ normalizeModulus against five recorded outputs of the real Java DiscreteEllipticUtility.normalizeModulus (1e-12), including Re < 0 mirror folds, large-Re T-steps, and |τ| < 1 S-inversions — locking the 0 ≤ Re ≤ ½ fold convention. (Generated via /tmp/oracle/TauOracle.java.) This also surfaced a real interaction: compute_period_matrix can land exactly on Re = +½ (the closed right edge of normalizeModulus's mirror- folded domain), which the half-open SL(2,ℤ) is_in_fundamental_domain (−½ ≤ Re < ½, P1-3) correctly excludes; ComputePeriodMatrix_ReducedTau_InFD was updated to assert the normalizeModulus domain rather than the SL(2,ℤ) one.

9. Higher-genus cut graph (Finding 7) — only genus-1 is exercised end-to-end. Add a genus-2 mesh and assert compute_cut_graph returns exactly 2g = 4 cut edges and genus == 2, documenting that the basis is not canonical (so no τ correctness is claimed there).

10. Inversive-distance degenerate face (Finding 9) — no test drives an inversive-distance triangle through the triangle-inequality boundary. Now that Finding 9 mirrors Finding 1 (limiting angles used, not skipped), add the analogue of missing-test item 1: assert the corner opposite the over-long edge is picked up as π rather than silently skipped.