Completes the work begun in the previous commit on this branch. Every
public symbol under code/include/ now carries a brief Doxygen comment
(0 undocumented per scripts/doxygen-coverage.sh, with the `detail::`
implementation namespaces excluded as before).
Trajectory on this branch:
start (after Doxyfile fix): 24.0 % (165 / 437 in the no-detail set
was 105 / 437 when detail counted)
after PR #17 base commit : 42.4 % (165 / 396)
this commit : 100.0 % (396 / 396)
Files touched (all .hpp / .h headers under code/include/):
* cgal/Conformal_map_traits.h
* clausen.hpp, conformal_mesh.hpp, constants.hpp (already docd)
* cp_euclidean_functional.hpp, cut_graph.hpp, discrete_elliptic_utility.hpp
* euclidean_functional.hpp, euclidean_geometry.hpp, euclidean_hessian.hpp
* fundamental_domain.hpp, gauss_bonnet.hpp
* hyper_ideal_{functional,geometry,hessian,utility,visualization_utility}.hpp
* inversive_distance_functional.hpp, layout.hpp
* matrix_utility.hpp, mesh_builder.hpp, mesh_io.hpp
* newton_solver.hpp, p2_utility.hpp, period_matrix.hpp, projective_math.hpp
* serialization.hpp, spherical_functional.hpp, spherical_geometry.hpp
* spherical_hessian.hpp, viewer_utils.h
CI:
.gitea/workflows/doxygen-pages.yml now enforces
`scripts/doxygen-coverage.sh --threshold 100`, so any future regression
(a new public function landed without a `///` brief) fails the build
before the Doxygen HTML is published to Codeberg Pages.
Doxygen warnings remain at 0.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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>
