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. ℹ️ NOTE — Holonomy translation assumes zero residual rotation

detail::euclidean_holonomy (layout.hpp) develops each face along a dual tree that never crosses a cut edge, then reads each generator's translation as the midpoint displacement ω = midA − midB of the shared cut edge between its two independent developments. This equals the true deck-translation only when the two developments differ by a pure translation (linear part = identity), i.e. for a perfectly flat cone metric (Θ ≡ 2π). When Newton has not fully converged (small residual cone-angle defect), there is a residual rotation and the midpoint displacement is a first-order approximation rather than the exact ω. A fully robust version would fit the rigid motion mapping edge (Bs,Bt)↦(At,As) and read its translation part. Acceptable for converged flat tori (the torus_8x8 test passes); worth tightening if higher-genus or under-converged inputs are used.

---

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. ⚠️ PARTLY DONE (2026-05-29) — added EdgeGradient_RegularTetClosedForm: an independent closed-form oracle that pins each edge-DOF gradient to π/3 (= 2·(2π/3) − π) on the regular spherical tetrahedron, where the corner angle 2π/3 follows from the spherical law of cosines. This locks the Finding-3 formula α_opp⁺ + α_opp⁻ − θ_e against a value the path-integral FD check cannot detect (the energy is the integral of G, so FD only proves curl-freeness). Still open: (i) 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; (ii) a live-Java golden-value oracle still requires running the upstream library.

5. Cross-check vs Java numeric oracles — there is no test that pins C++ functional/gradient values against recorded Java outputs on a fixed mesh. A handful of golden-value tests (energy + gradient at a known x) would catch any future silent divergence from the reference far more directly than the self-consistent FD checks (which only verify curl-freeness, since the C++ energy is itself the path-integral of its own gradient).

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. Period-matrix domain convention (Finding 6) — production now uses normalizeModulus (folds Re ≥ 0). Add a torus whose true τ has Re(τ) < 0 before reduction and assert the resulting Re(τ) ≥ 0 convention, so any future switch back to reduce_to_fundamental_domain is caught. Pair with a golden τ recorded from the Java DiscreteEllipticUtility on the same mesh.

8. normalizeModulus vs Java oracle (Finding 6) — the faithful normalizeModulus is only checked against ad-hoc values. Add a few recorded Java normalizeModulus outputs as golden values to lock the Re ≥ 0 fold.

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.