2 Commits

Author	SHA1	Message	Date
Tarik Moussa	f50ef4a305	Phase 9b: Hyper-ideal Hessian — block-FD optimisation (96× speed-up) ... Replaces the O(n·F) full-FD Hessian with an O(F·36) block-local variant that exploits the per-face locality of the hyper-ideal functional. Both variants are kept (full-FD as correctness reference, block-FD as default) and proven to match to FD rounding tolerance on all test configurations. Java parity note ──────────────── HyperIdealFunctional.java line 295-298 declares: public boolean hasHessian() { return false; } i.e. the upstream Java functional has NO Hessian implementation, analytic or numerical. Both Hessian variants in this file are conformallab++ extensions beyond the Java port. Analytic Hessian via Schläfli-type differentiation through (b_i, a_e) → l_ij → ζ_13/ζ_14/ζ_15 → α_ij/β_i is deferred to a future PR. Implementation ────────────── * code/include/hyper_ideal_functional.hpp - New pure-math helper face_angles_from_local_dofs() takes 6 input DOFs (b1, b2, b3, a12, a23, a31) + variability flags and returns the 6 output angles (β1, β2, β3, α12, α23, α31). - Used by block-FD Hessian as the inner loop; identical semantics to the existing compute_face_angles(). * code/include/hyper_ideal_hessian.hpp - hyper_ideal_hessian_block_fd() — new, default production path - hyper_ideal_hessian_block_fd_sym() — symmetrised variant - hyper_ideal_hessian() — full-FD baseline, kept for cross-validation - hyper_ideal_hessian_sym() — symmetrised baseline - Header docblock documents speed-up curve: ~33× at cathead.obj scale, ~1166× at brezel.obj scale. Tests (7 new in test_hyper_ideal_hessian.cpp) ───────────────────────────────────────────── * PureHelperMatchesMeshHelper — refactor sanity * BlockFD_MatchesFullFD_ClosedTetrahedron * BlockFD_MatchesFullFD_Open3FaceMesh (boundary edge path) * BlockFD_MatchesFullFD_PinnedDOFs (partial-DOF path) * BlockFD_IsPSD (Springborn 2020 convexity) * BlockFD_SparsityMatchesFaceAdjacency (structural correctness) * BlockFD_FasterThanFullFD (performance assertion: ≥ 3×) Measured speed-up on the 200-face tet strip (603 DOFs): full-FD: 226 591 µs block-FD: 2 347 µs ratio: 96.5× The assertion uses ≥ 3× to leave wide CI-hardware tolerance. Test count ────────── CGAL suite: 184 → 191 (+7). Zero skips. Why not full analytic now ───────────────────────── Full analytic Hessian via the chain rule (b_i, a_e) → l_ij → ζ_{13,14,15} → α_ij / β_i requires Schläfli-type differentiation with multiple cases for the ideal / hyper-ideal vertex mix. It would add another ~6× over block-FD but at significantly higher implementation and verification cost. Block-FD already removes the practical bottleneck for meshes up to ~10k faces; analytic optimisation can land later when justified by a concrete profiling result. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-21 20:58:33 +02:00
Tarik Moussa	3f124eb071	feat(phase4): HyperIdeal Newton solver, SparseQR fallback, examples, docs ... Phase 4 complete — 87 CGAL tests pass, 2 skipped. Newton solver (phase4a): - hyper_ideal_hessian.hpp: symmetric FD Hessian (O(ε²), PSD by convexity) - newton_hyper_ideal(): Newton + backtracking for the HyperIdeal functional - detail::solve_with_fallback(): optional bool* fallback_used parameter - solve_linear_system(): public API exposing LDLT→SparseQR fallback SparseQR fallback tests (SparseQRFallback.*): - FullRankSystem_CorrectSolution: LDLT path, fallback_used=false - SingularMatrix_FallbackActivated: zero-pivot → QR activated, fallback_used=true - Euclidean_ClosedMeshNoPinConverges: gauge-mode null space handled via QR HyperIdeal Newton tests (NewtonSolver.HyperIdeal_*): - ConvergesTriangleAllVariable, ResultFieldsConsistent, ConvergesTetrahedron, SparseQRFallbackNoCrash - Natural-target base point (b=1.0, a=0.5) — x=0 is degenerate in log-space Pipeline tests (test_pipeline.cpp): - End-to-end: all three geometries, mesh I/O round-trip, solve+export Example programs (code/examples/): - example_euclidean.cpp: headless Euclidean pipeline - example_hyper_ideal.cpp: headless HyperIdeal pipeline - example_viewer.cpp: interactive libigl viewer with jet colour map README: - Mathematical scope table: C++ vs Java original (18 rows) - "For mathematicians" section: mental model, step-by-step new-functional guide, half-edge traversal snippets, recommended reading Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-13 00:11:25 +02:00