4f8530628bbfc1af8ea8f8e1ac0b02365e93e270
98 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Tarik Moussa
|
1bf1defc70 |
feat(solver): S2 — NewtonResult status enum (I1) + iteration fix (H1) + conditioning diagnostics (N7)
Builds on the newton_core refactor; all three findings live in exactly that code.
I1 (test-coverage): add NewtonStatus { Converged, MaxIterations,
LinearSolverFailed, LineSearchStalled } and a `status` field to NewtonResult, so
the three non-convergent exits that `converged == false` previously conflated are
now distinguishable. `converged` is kept (== status==Converged) for back-compat;
+ to_string(NewtonStatus) for logs/tests. newton_core sets the status at each
exit point (centralised by the H2 refactor).
H1 (test-coverage): set res.iterations explicitly at the LinearSolverFailed and
LineSearchStalled breaks (= completed steps), instead of relying on the last
successful iteration's stale value.
N7 (numerical-stability): surface linear-algebra conditioning in the result —
`sparse_qr_fallback_used` (any iteration fell back to SparseQR) and
`min_ldlt_pivot` (smallest |Dᵢᵢ| of the last LDLT, a cheap near-singularity
proxy). This catches the silent case the audit flagged: on a gauge-singular
Hessian SimplicialLDLT "succeeds" with a ~0 pivot and no fallback fires — now
min_ldlt_pivot is tiny and observable.
Tests (+3 synthetic newton_core status/diagnostic tests; +1 assertion on the
closed-mesh-no-pin fallback test). All purely additive — no control-flow or
convergence behaviour changes; 301/301 CGAL tests pass incl. Java parity.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
2fc465f5cf |
refactor(solver): H2 unify 5 Newton loops into newton_core (+B2/B3/B4/B5)
The five DCE solvers (Euclidean, Spherical, HyperIdeal, CP-Euclidean, Inversive-Distance) carried near-identical Newton loops differing only in the gradient function, the Hessian function, and the spherical concave sign (test-coverage audit H2 — "5 near-identical Newton loops"). Extract one detail::newton_core<GradFn, HessFn>(x, grad, hess, concave, tol, max_iter); each public solver is now a thin wrapper passing two lambdas. This lets the performance fixes land once instead of five times: - B2 (api-perf): line_search now optionally returns the gradient at the accepted point; newton_core reuses it as the next iteration's convergence gradient, removing ~1 redundant full-mesh gradient evaluation per iteration. - B4 (api-perf): NewtonLinearSolver keeps one persistent SimplicialLDLT and runs analyzePattern once (symbolic factorization cached across iterations), re-analyzing only when nnz changes (self-healing for the FD Hessians that prune near-zero triplets). SparseQR fallback preserved verbatim. - B3 (api-perf): the Euclidean has_edge_dof scan is hoisted out of the loop (it is layout-invariant) — now done once before newton_core. - B5 (api-perf): the dead SimplicialLDLT variable in newton_euclidean is gone. Behaviour is unchanged: concave spherical still factors −H and solves (−H)·Δx = G; the merit steepest-descent still uses the true H; HardJava clamp default preserved. Tests (+2): NewtonCore.ReusesLineSearchGradient_B2_Convex asserts exactly 2 gradient evals on a unit-Hessian quadratic (vs 3 pre-B2), and ConcavePathConverges covers the −H branch directly. 298/298 CGAL tests pass, including all Java golden-vector parity tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
202b9a108d |
feat(num): N3 selectable scale-floor clamp mode (HardJava | SmoothBarrier)
The hyper-ideal vertex scale b is floored to keep the geometry valid. The original clamp `b<0 → 0.01` mirrors the Java oracle but is only C⁰ (in fact value-discontinuous at b=0): a Newton step crossing the feasibility boundary hits a kink that can stall convergence (numerical-stability audit N3). Rather than replace the Java-faithful behaviour (which would break the golden parity tests), make the floor a selectable mode so BOTH the Java standpoint and the clean mathematics are available: - HyperIdealScaleClamp::HardJava (DEFAULT) — the original snap, bit-for-bit faithful to HyperIdealFunctional.java → all parity tests unchanged. - HyperIdealScaleClamp::SmoothBarrier — C¹ softplus floor b ↦ floor + softplus_β(b−floor), β = HYPER_IDEAL_SCALE_SHARPNESS (=100); ≈ identity away from the floor, smooth across b=0. Opt-in. clamp_hyper_ideal_scale centralises the logic (also folds in the N4 nachzügler: compute_face_angles used a bare 0.01). The mode threads with a defaulted trailing parameter through compute_face_angles, face_angles_from_local_dofs, evaluate_hyper_ideal, the four hyper_ideal_hessian* variants and newton_hyper_ideal — so every existing call site keeps HardJava behaviour. Tests (+4): clamp-function C¹/floor/identity contract, mode-equivalence away from the boundary, and end-to-end SmoothBarrier convergence to the same Java golden vector (LawsonHyperIdeal). 296/296 CGAL tests pass. Documented in doc/math/geometry-modes.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
a1a7f216e0 |
fix(num): N5 stable triangle area (Kahan) in euclidean_cot_weights
The cotangent weights divided by 2·√(t12·t23·t31·l123). For a needle/cap (sliver) triangle one of the t-values is the difference of near-equal edge lengths → catastrophic cancellation, and the area under the sqrt loses precision, feeding large relative error into every cotangent weight, the Hessian, and the linear solve (numerical-stability audit N5). Replace the area computation with Kahan's stable side-length formula (sort a≥b≥c, evaluate ¼·√[(a+(b+c))(c−(a−b))(c+(a−b))(a+(b−c))]). The denominator is still exactly 8·Area for well-shaped triangles but accurate for slivers. The triangle-inequality guard and the cotangent numerators are unchanged. Test: CotWeights_SliverMatchesHighPrecisionReference cross-checks a thin triangle (apex ≈ 0.01 rad) against a long-double law-of-cosines reference. 292/292 CGAL tests pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
2dc4ddcc32 |
perf(inv-dist): B1 port — block-FD Hessian for newton_inversive_distance
The Inversive-Distance solver built its Hessian inline by full finite
differences: n perturbations × a full O(F) gradient eval = O(n·F) per Newton
iteration (quadratic in mesh size), with no fast path at all (api-performance
audit B1, second half).
Port the per-face block-FD scheme already used by HyperIdeal (Phase 9b):
the gradient decomposes by face (G_v = Θ_v − Σ_{f∋v} α_v, and each face's
angles depend only on its 3 vertex DOFs), so the Hessian decomposes into
per-face 3×3 blocks. Cost drops to O(F) face evaluations, a ≈ n/6 speed-up.
- inversive_distance_functional.hpp: add the pure 3→3 kernel
inversive_distance_face_grad_contribs (returns the per-face contribution
−α to G; mirrors the gradient's face-skip on ℓ²≤0 exactly).
- inversive_distance_hessian.hpp (new): full-FD baseline + block-FD + sym
variants, mirroring hyper_ideal_hessian.hpp.
- newton_solver.hpp: drop the inline full-FD lambda; call
inversive_distance_hessian_block_fd_sym.
- test: InversiveDistance_BlockFDHessianMatchesFullFD cross-validates the
two Hessians entry-wise on a perturbed (off-equilibrium) config.
291/291 CGAL tests pass; all Inversive-Distance convergence tests unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
a5718c0326 |
fix(coverage+validation): C2/C3 script gate, V1/V2/V4 JSON/XML errors, I2/I3/I4 tests
C2: Fix coverage.sh — remove || true from lcov capture/extract steps so real
lcov failures are visible; empty coverage.info now exits with code 3.
C3: Add coverage gate to quality-gates CI job (SKIP_COVERAGE_GATE=1 ramp-up
mode until I5 is resolved — fast suite covers ~9.6% not 80%). Thresholds:
80% line / 70% branch / 90% function (agreed 2026-05-31).
V1: Wrap JSON parse + field extraction in try/catch — nlohmann parse_error and
type_error now surface as std::runtime_error with the file path.
V2: Wrap stoi/stod in XML Solver parser — missing/non-numeric attributes throw
std::runtime_error instead of leaking std::invalid_argument.
V4: Validate required JSON keys (dof_vector, solver, solver.*) before access —
missing field produces a clear named-field error message.
I2: 6 serialization negative tests (missing file, malformed JSON, missing
dof_vector, missing solver block, missing XML file, non-numeric XML attr).
I3: load_mesh throws on non-triangulated (quad) mesh — covers the
is_triangle_mesh guard that was previously untested.
I4: spherical_hessian throws on edge DOFs — covers the logic_error guard.
290/290 tests pass (+8 new).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
51d9844f7a |
docs(references): M1/M2/M4 citation fixes (audit quick-wins)
M1: Add two missing references used in hyper_ideal_utility: - Kolpakov, Mednykh (2006, arXiv math/0603097) — tetrahedron volume w/ one ideal vertex - Meyerhoff, Ushijima (2006) — tetrahedron volume w/ three ideal vertices M2: Clarify BPS publication year: Geometry & Topology 2015 (arXiv 2010) - Update references.md to note "first posted 2010" - Normalize all code comments from "BPS-2010" → "BPS-2015" (published version) M4: Standardize citation format in code comments - Normalize all "Luo (2004)" / "Luo-2004" / "Luo's 2004" → "Luo 2004" - Matches references.md convention: Author Year (no parens/dashes) 282/282 tests pass. Addresses M1, M2, M4 from math-derivation-citation audit. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
b0946c8704 |
refactor(constants): centralize magic constants from functionals (N4/N6 audit)
- Add LOG_EDGE_LENGTH_FLOOR (-30.0) for degenerate edge handling - Add HYPER_IDEAL_SCALE_FLOOR (0.01) for negative-scale clamping - Add ASIN_DOMAIN_GUARD (1.0 - 1e-15) for asin argument bounding - Each constant is documented with rationale and units - Update 4 usage sites: euclidean_functional, hyper_ideal_functional, spherical_functional, spherical_geometry - Add constants.hpp include to hyper_ideal_functional and spherical_functional 282/282 tests pass. Addresses N4 (unnamed magic constants) and N6 (centralize tolerances) from numerical-stability audit. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
101f3138ce |
fix(solver+io): B1 block-FD Hessian, V3 NaN/Inf guard, C1 ok-flag (audit quick-wins)
B1 (api-performance): wire hyper_ideal_hessian_block_fd_sym into newton_hyper_ideal instead of the full-FD path — 33×/1166× faster on cathead/brezel, also fixes the FD-step vs Newton-tol accuracy floor (N1 cross-fix). V3 (input-validation): add isfinite check on all vertex coordinates in load_mesh; NaN/Inf now throws runtime_error at the I/O boundary before poisoning the solver. C1 (test-coverage): expose the internal ok flag via an optional bool* parameter on solve_linear_system so double-solver failure is no longer invisible to callers. +5 new tests (LoadMeshThrowsOnNaN/Inf, OkFlag_True*, OkFlag_NullPointerIsSafe). 282/282 tests pass. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
| 505dd4b0a5 |
Merge pull request 'refactor(api): consistent naming for spherical + hyper-ideal helpers (A1–A3)' (#36) from refactor/api-naming-a1-a3 into main
Some checks failed
C++ Tests / test-fast (push) Failing after 2m2s
C++ Tests / quality-gates (push) Has been skipped
API Docs / doc-build (push) Has been skipped
Markdown link check / check (push) Has been skipped
Mirror to Codeberg / mirror (push) Successful in 28s
C++ Tests / test-cgal (push) Has been skipped
|
|||
|
Tarik Moussa
|
65fc8ac816 |
refactor(api): consistent naming for spherical + hyper-ideal helpers (A1–A3)
Standardize the low-level free-function API on <verb>_<geom>_<rest>, matching the already-consistent setup_<geom>_maps. Old names kept as [[deprecated]] inline aliases for one release; all internal call sites migrated. Renames: assign_vertex_dof_indices -> assign_spherical_vertex_dof_indices assign_all_spherical_dof_indices -> assign_spherical_all_dof_indices assign_all_dof_indices -> assign_hyper_ideal_all_dof_indices compute_lambda0_from_mesh -> compute_spherical_lambda0_from_mesh gradient_check -> gradient_check_hyper_ideal A4/A5 (public CGAL API) intentionally deferred pending the license/ provenance decision (see CGAL submission audit G0/G1). Verified: 277/277 CGAL tests pass, no deprecation warnings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
37b538aae4 |
docs: Layout2D index semantics, CLI table, CLI roadmap (U9+U10+U11)
Some checks failed
C++ Tests / test-fast (push) Has been cancelled
C++ Tests / test-cgal (push) Has been cancelled
C++ Tests / quality-gates (push) Has been cancelled
API Docs / doc-build (push) Has been cancelled
Markdown link check / check (push) Has been cancelled
C++ Tests / test-fast (pull_request) Successful in 2m10s
C++ Tests / quality-gates (pull_request) Has been skipped
C++ Tests / test-cgal (pull_request) Has been skipped
U9 (layout.hpp + example_layout.cpp)
Layout2D.uv and .halfedge_uv now have explicit Doxygen docs stating:
- indexing: v.idx() / h.idx() (raw integer index)
- length: mesh.number_of_vertices() / number_of_halfedges()
- precondition: no vertex removal / collect_garbage() after loading
- access pattern example in the doc comment
example_layout.cpp: access site comment + static_cast<size_t>(v.idx())
U10 (getting-started.md)
New 'CLI parameter reference' table (7 rows) added directly below the
CLI usage examples; cross-references --help as the canonical source
U11 (doc/roadmap/phases.md)
New Phase 9h 'CLI usability extensions' section inserted before Phase 10:
9h.1 --tol / --max-iter solver-tuning params (~30 min, no deps)
9h.2 -g cp_euclidean / -g inversive_distance (~2-4 h, needs 9a ✅)
Each sub-task has effort estimate, implementation sketch, and
acceptance criteria so a future session can pick it up cold.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
ccbfd852b2 |
docs(examples): use gauge-vertex overload everywhere (U6)
Finding-U6 from doc/reviewer/usability-audit-2026-05-31.md. The Finding-D fix (external-audit-2026-05-30) added a clean one-call gauge-vertex overload: assign_euclidean_vertex_dof_indices(mesh, maps, gauge_vertex) But all user-facing code still showed the old verbose manual loop: auto vit = mesh.vertices().begin(); maps.v_idx[*vit++] = -1; int idx = 0; for (; vit != mesh.vertices().end(); ++vit) maps.v_idx[*vit] = idx++; Replaced in three places: README.md 'Minimal usage' code block example_euclidean.cpp Step 3 example_layout.cpp pin_first() helper Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
d1399ca82f |
docs: fix stale version, CGAL header, add LOW_MEMORY_BUILD docs (U4+U5+U7+U8)
U4 (README.md:17) — status line: v0.9.0 → v0.10.0, test count 0 → 277
U5 (Discrete_conformal_map.h:6-16) — \file Doxygen block rewritten:
was: 'provides a single function … Spherical/hyperbolic scheduled for Phase 8b.2'
now: lists all three discrete_conformal_map_* functions already present,
plus pointers to the circle-packing companion headers
U7 (getting-started.md) — new 'Mode 4 — Low-memory build' section added
after Mode 3; shows CONFORMALLAB_LOW_MEMORY_BUILD=ON with -j1 and explains
the -O0 / no PCH / batch-1 tradeoffs for Raspberry Pi / ≤ 4 GB runners
U8 (README.md compile-time modes) — LOW_MEMORY_BUILD entry added to the
compile-time workflow code block with a one-line explanation and the
mandatory -j1 note
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
02a3745b67 |
examples: add real conformal-flattening + CGAL-API examples (U1+U2)
Finding-U1 and Finding-U2 from doc/reviewer/usability-audit-2026-05-31.md.
The existing examples (example_euclidean, example_layout, example_hyper_ideal)
all used the "natural theta" pattern which makes x*=0 trivially the
equilibrium — u_v ≈ 0 everywhere, no deformation. A new user following
these examples saw solver output but not conformal geometry.
New: example_flatten.cpp
- PRIMARY USE CASE: conformally flatten a mesh to the plane
- Sets Θ_v = 2π for all interior vertices (flat target)
- Pins boundary vertices (no Gauss-Bonnet check for open meshes)
- Demonstrates non-trivial u_v (cathead.obj: range ≈ 2.96, 5 Newton iters)
- Documents the difference from "natural theta" explicitly
New: example_cgal_api.cpp
- Demonstrates CGAL::discrete_conformal_map_euclidean (Discrete_conformal_map.h)
- First runnable CGAL public API example; contrast with internal API
- Documents the "natural theta" default behaviour and explains why u_v=0
- Explains when to use CGAL API vs internal API
Both examples registered in code/examples/CMakeLists.txt and compile
cleanly with -DWITH_CGAL=ON.
Updated:
- example_euclidean.cpp: prominent "TESTING CONVENTION" warning
- example_layout.cpp: same warning on set_natural_theta helper
- doc/getting-started.md: example_flatten is now the recommended
"start here" example; note on natural-theta behaviour added
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
449c5899c0 |
ci: re-enable CGAL tests with LOW_MEMORY_BUILD for Raspberry Pi runner
Finding-I from doc/reviewer/external-audit-2026-05-30.md.
Root cause: CGAL+Eigen at -O3 drives cc1plus peak RAM to ~700 MB per
Unity compilation unit (batch size 4) on ARM64. With the 1600 MB
container limit the 2nd or 3rd TU reliably triggered OOM-kill, so
test-cgal was gated off via `if: false` since 2026-05-26.
Fix: new CMake option CONFORMALLAB_LOW_MEMORY_BUILD=ON applies four
orthogonal memory-saving measures to conformallab_cgal_tests:
1. -O0 (no debug info): optimizer passes entirely skipped → cc1plus
peak drops from ~700 MB to ~150-200 MB per TU on ARM64.
Omitting -g avoids the additional object-file / linker RAM cost.
2. CONFORMALLAB_USE_PCH=OFF: saves the one-time ~200 MB PCH
compilation cost; each TU re-parses CGAL headers (fast at -O0).
3. UNITY_BUILD_BATCH_SIZE=1: one source file per cc1plus invocation,
removing the "4-file template-explosion" per-unit multiplier.
4. -Wl,--no-keep-memory (GNU ld): linker releases symbol tables after
each input file → ~15-25 % less linker RSS.
Verified locally with cmake -DCONFORMALLAB_LOW_MEMORY_BUILD=ON:
277/277 CGAL tests pass, 31 s runtime (vs 2 s at -O3 — expected;
tests run 15× slower without optimizer but all correct).
CI workflow changes (cpp-tests.yml):
- test-cgal re-enabled: `if: github.event_name == 'pull_request'`
- Configure step adds -DCONFORMALLAB_LOW_MEMORY_BUILD=ON
- Container memory: 1600m → 2000m (--memory-swap=3000m for 1 GB swap
headroom), using ~half of the Pi's 3-4 GB while leaving OS margin.
CLAUDE.md updated: new flag added to compile-time options table; CI
status row corrected from DISABLED to active.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
59a26123c8 |
fix(minor): all five MINOR findings — doc, accuracy, and DRY
MINOR-1 (spherical_functional.hpp:426)
Wrong comment said "second derivative < 0 for a convex functional".
The spherical energy is *concave* (NSD Hessian); the monotone-f argument
applies to both convex and concave functionals equally. Comment rewritten
to explain the actual physics: increasing scale increases all angles and
thus reduces Σ G_v.
MINOR-2 (spherical_functional.hpp:494-495)
Forward finite difference O(ε) → central finite difference O(ε²):
old: dft = (sum_Gv(t + fd_eps) - ft) / fd_eps
new: dft = (sum_Gv(t + fd_eps) - sum_Gv(t - fd_eps)) / (2*fd_eps)
Same cost when the extra sum_Gv(t - fd_eps) replaces the cached ft.
MINOR-3 (euclidean_functional.hpp, spherical_functional.hpp,
inversive_distance_functional.hpp)
New header gauss_legendre.hpp centralises the 10-point Gauss-Legendre
nodes and weights (gl10_nodes() / gl10_weights()). The three energy
functions now use the shared accessors instead of duplicated local
static arrays.
MINOR-4 (euclidean_functional.hpp, spherical_functional.hpp,
hyper_ideal_functional.hpp, inversive_distance_functional.hpp)
halfedge_to_index() centralised in conformal_mesh.hpp. All four local
aliases (eucl_hidx, spher_hidx, hidx, id_detail::hidx) now delegate to
it as one-line wrappers; the aliases are kept for now to avoid a larger
call-site churn, clearly documented as thin wrappers.
MINOR-5 (clausen.hpp:33-38)
Added a comment above inits() explaining the intentional off-by-one
return value and how it interacts with csevl() — matching the Java
Clausen.inits() / csevl() contract.
277/277 CGAL + 26/26 pure-math tests pass, 0 failed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
2325328f77 |
test: add end-to-end skewed-torus and synthetic holonomy Re(τ)<0 tests
Finding-H from doc/reviewer/external-audit-2026-05-30.md
(java-port-audit missing-test item 7).
Guards against a regression where compute_period_matrix reverts to
reduce_to_fundamental_domain (no mirror fold) instead of normalizeModulus
(Finding 6 fix, Java-faithful): such a revert would silently produce
Re(τ) < 0 for lattices where the natural generators give a negative
real part.
Two new tests in test_phase7.cpp:
1. SkewedTorus_ReTauNegativeBeforeNorm_FoldedToPositive
- New mesh: code/data/off/torus_skewed_4x4.off
Flat 4×4 torus on parallelogram lattice ω₁=(4,0) ω₂=(-1,4);
16 vertices, 32 triangles, χ=0 (genus 1).
- Full pipeline: newton_euclidean → cut_graph → euclidean_layout
→ compute_period_matrix(reduce=false) + compute_period_matrix(reduce=true)
- Asserts: raw Re(τ) < 0, normalized Re(τ) ∈ [0,½], Im(τ) > 0, |τ| ≥ 1
2. SyntheticHolonomy_NegativeReTau_NormalizedToPositive
- Bypasses mesh; supplies explicit ω₁=(4,0) ω₂=(-1,4) directly
- Asserts raw τ = -0.25+i (to 1e-10), normalized τ = 0.25+i (to 1e-9)
- Pin-points the mirror fold: Re(-0.25) → Re(+0.25)
277/277 CGAL tests pass, 0 failed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
adbf682f0f |
test: add degenerate-triangle limiting-angle and edge-DOF guard tests
Finding-F and Finding-G from doc/reviewer/external-audit-2026-05-30.md
(java-port-audit missing-test items 1 and 2).
Finding-F — Degenerate triangle: limiting angles (item 1)
test_euclidean_functional.cpp:
DegenerateTriangle_LimitingAngles_L{12,23,31}TooLong
— verifies α_opposite = π, other two = 0, valid = false
for all three edge-over-long cases
DegenerateTriangle_GradientPicksUpPiCorner
— end-to-end mesh test: forces effective l12 >> l23+l31 via
lambda0, evaluates gradient, asserts G_v3 = π (not 2π from
a skipped degenerate face) and G_v1=G_v2 = 2π
test_spherical_functional.cpp:
DegenerateTriangle_LimitingAngles_S{12,23,31}TooLong
— same coverage for spherical_angles()
Finding-G — euclidean_hessian edge-DOF guard (item 2)
test_euclidean_hessian.cpp:
EdgeDOFGuard_Throws
— assign_euclidean_all_dof_indices + euclidean_hessian → throw
EdgeDOFGuard_VertexOnlyDoesNotThrow
— vertex-only layout → no throw (regression guard)
275/275 CGAL tests pass, 0 failed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
7534c62c3d |
fix(gradient-checks): use relative error in all FD check functions
Finding-E from doc/reviewer/external-audit-2026-05-30.md. Scan also uncovered the same issue in inversive_distance_functional.hpp. Three functions used absolute error `|analytic - fd| > tol` while the rest of the library (euclidean_functional, spherical_functional, euclidean_hessian, hyper_ideal_functional) all use relative error `|analytic - fd| / max(1, |analytic|) > tol`. Absolute error is too strict for large gradients (false failures) and too lenient for small gradients. Fixed: cp_euclidean_functional.hpp gradient_check_cp_euclidean() cp_euclidean_functional.hpp hessian_check_cp_euclidean() inversive_distance_functional.hpp gradient_check_inversive_distance() All three now use the relative criterion and accumulate all failures before returning (ok=false instead of early return on first mismatch). Default tol updated from 1e-6/1e-5 to 1e-4, matching the Java FunctionalTest convention used by all other checks in the library. Error message updated to print rel-err instead of raw diff. 266/266 CGAL tests pass, 0 failed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
cfbbc1b21f |
fix(dof-assign): correct "pin before" docs + add gauge-vertex overloads
Finding-D from doc/reviewer/external-audit-2026-05-30.md.
All three DOF-assignment functions iterated over every vertex
unconditionally, overwriting any v_idx set before the call. The
documentation said "pin before OR after" — the "before" option was
silently wrong (the pin would be overwritten). For the
inversive-distance variant the doc explicitly said the pre-call pin
would make the function "a no-op for that vertex", which was false.
Changes (three headers):
- euclidean_functional.hpp assign_euclidean_vertex_dof_indices()
- spherical_functional.hpp assign_vertex_dof_indices()
- inversive_distance_functional.hpp assign_inversive_distance_vertex_dof_indices()
For each:
1. Single-arg overload: doc corrected to "pin AFTER, not before;
pre-call pins are overwritten"
2. New two-arg overload accepting a Vertex_index gauge: pins the
requested vertex (v_idx=-1) in a single pass, preventing the
user error entirely
Three new GTests in test_euclidean_functional.cpp:
SingleArg_PinBeforeHasNoEffect — documents the old pitfall
TwoArg_GaugeIsPinnedOthersAreSequential — verifies the new overload
TwoArg_NewtonConvergesWithGaugeOverload — end-to-end correctness
266/266 CGAL tests pass, 0 failed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
bef5a0ceb7 |
docs(euclidean-hessian): fix wrong cotangent formula in two comment blocks
Finding-C from doc/reviewer/external-audit-2026-05-30.md. The box comment at the top and the function-level comment above euclidean_cot_weights() both stated: cot_k = (t_adj1·l123 − t_adj2·t_opp) / denom2 ← WRONG The correct formula (verified numerically on a 3-4-5 right triangle, expected cot1=4/3, cot2=3/4, cot3=0) is: cot_k = (t_opp · l123 − t_a · t_b) / denom2 where t_opp is the t-value of the edge OPPOSITE vertex k, and t_a/t_b are the t-values of the two edges ADJACENT to vertex k. The implementation in euclidean_cot_weights() was already correct; only the documentation was wrong. Changes (documentation only, zero code changes): - Box comment: rewritten with correct formula and explicit per-vertex assignment (cot1: t_opp=t23, t_a=t12, t_b=t31; etc.) - Box comment: added missing ½ factor to Hessian contribution lines - Function-level comment: corrected to (t_opp·l123 − t_a·t_b)/(8·Area) with a pointer to the box comment for the full assignment - Inline return comment in euclidean_cot_weights(): now shows the mapping (cot1: t_opp=t23, t_a=t12, t_b=t31) directly at the formula 263/263 CGAL tests pass, 0 failed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
46c0b63de8 |
fix(gauss-bonnet): delete HyperIdeal overloads — wrong identity for hyperbolic metrics
Finding-B from doc/reviewer/external-audit-2026-05-30.md. The Euclidean Gauss–Bonnet identity Σ(2π−Θ_v) = 2π·χ is ONLY valid for flat/Euclidean and spherical metrics. For hyperbolic metrics (HyperIdeal) the correct identity is Σ(2π−Θ_v) − Area(M) = 2π·χ. The previously provided gauss_bonnet_sum(HyperIdealMaps) overload would silently pass the wrong LHS to check_gauss_bonnet, which would always throw "deficit = ±Area" for valid hyperbolic targets. Fix: - gauss_bonnet_sum(mesh, HyperIdealMaps) → = delete + explanation comment - enforce_gauss_bonnet(mesh, HyperIdealMaps&) → = delete + explanation comment - Header box comment rewritten with the correct hyperbolic Gauss–Bonnet identity and a clear "HyperIdeal: NOT SUPPORTED" section New test in test_phase6.cpp: - HyperIdeal_EuclideanSumDiscrepancy_DocumentsWhyCheckIsDeleted verifies numerically that the Euclidean sum = 0 but 2π·χ = 4π for a regular tetrahedron, documenting the −4π discrepancy that motivated the deletion - Three compile-time static_asserts (SFINAE) confirm the overload is not invocable with HyperIdealMaps but remains so with Euclidean/SphericalMaps 263/263 CGAL tests pass, 0 failed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
9afefcbb7b |
fix(hyper-ideal): guard face_energy() against unsupported multi-ideal faces
Finding-A from doc/reviewer/external-audit-2026-05-30.md. Root cause: both the Java reference (HyperIdealFunctional.java:222-231) and the C++ port silently applied the one-ideal-vertex volume formula to the first ideal vertex found in a face, ignoring any additional ideal vertices. For two or three ideal vertices this produces a wrong energy value with no diagnostic. Fix: add an ideal_count guard at the top of face_energy() that throws std::logic_error for ideal_count >= 2. The one-ideal (Kolpakov-Mednykh) and zero-ideal (Meyerhoff/Ushijima) paths are unchanged and correct. Three new GTests cover the three guard cases: MultiIdealGuard_TwoIdealVertices_Throws (two ideal → throw) MultiIdealGuard_AllThreeIdealVertices_Throws (all ideal → throw) MultiIdealGuard_ExactlyOneIdeal_DoesNotThrow (one ideal → no throw) 262/262 CGAL tests pass, 0 failed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
822a27da69 |
feat(euclidean): full analytic edge-DOF (cyclic) Hessian; Tier-2 Wente finding
Upgrades the cyclic Euclidean Hessian from block-FD to closed-form, satisfying
the novelty-statement §3.2 "analytic Hessians, not finite difference" claim for
the Euclidean path.
- euclidean_hessian.hpp: `euclidean_hessian_analytic` — closed-form cyclic
Hessian from the law-of-cosines angle derivatives
∂α_i/∂s_i = ℓ_i²/4A, ∂α_i/∂s_j = ½cot α_i − ℓ_j²/4A (Σ_j = 0),
chained to (u, λ_e) and sign-mapped to the gradient outputs (−α vertex,
+α_opp edge). Reuses euclidean_cot_weights. Block-FD kept as cross-check.
- newton_solver.hpp: newton_euclidean cyclic path now uses the analytic Hessian.
- tests: CyclicHessian_Analytic_MatchesBlockFD_Tetrahedron — analytic == block-FD
(1e-6), == gradient FD (1e-5), symmetric (1e-9). Existing cyclic convergence
oracle still GREEN with the analytic Hessian routed in.
Tier-2 (Wente) finding: wente_torus02.obj is a QUAD mesh (1240 quads) and the
Java golden comes from cyclic (quad-net) uniformization; the C++ period-matrix
pipeline is triangle-based, so a faithful bit-vs-Java τ comparison needs a
quad/cyclic pipeline (Phase 9f). Deferred and documented; golden τ = ½+i√3/2.
244/244 cgal tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
ea5f01d73d |
feat(euclidean): block-FD edge-DOF Hessian → cyclic Newton + Java convergence oracle
Implements the edge-DOF (cyclic) Euclidean Hessian, unblocking the full cyclic
Newton solve, and enables the Java EuclideanCyclicConvergenceTest cross-validation.
- euclidean_hessian.hpp: `euclidean_hessian_block_fd` / `_sym` — per-face 6×6
block FD over (u1,u2,u3,λ12,λ23,λ31), mirroring hyper_ideal_hessian_block_fd.
Per-face outputs carry the gradient signs (−α vertex, +α_opp edge), so the
result equals ∂G/∂x by construction (locality lemma). Analytic vertex-only
cotangent Hessian unchanged (still used for vertex-only layouts).
- newton_solver.hpp: newton_euclidean routes cyclic layouts (edge DOFs present)
through the block-FD Hessian; vertex-only path unchanged.
- tests:
* CyclicCircularEdge_CatHead_JavaXVal (now GREEN) — prescribe φ=π−0.1 on one
interior edge, solve, assert realised α_opp+α_opp = π−0.1 @1e-9.
* CyclicCircularEdge_PhiEntersGradient_CatHead — solver-free φ-wiring check.
* CyclicHessian_BlockFD_MatchesGradientFD_Tetrahedron — Hessian correctness.
243/243 cgal tests pass; vertex-only Euclidean Newton unaffected.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
5d74a94b78 |
test(euclidean): Tier-1 circular-edge φ cross-validation + cyclic-solve blocker
Build-verified attempt to port the Java EuclideanCyclicConvergenceTest (cathead, "circular hole edge" φ = π−0.1). - ✅ GREEN `CyclicCircularEdge_PhiEntersGradient_CatHead`: solver-free cross-validation that the circular-edge φ target enters the cyclic edge gradient exactly (ΔG_e = −Δφ_e at 1e-12; no other component moves). - ⏸️ DISABLED `CyclicCircularEdge_CatHead_JavaXVal`: the full Java convergence assertion (α_opp+α_opp = π−0.1), kept with golden semantics. Auto-activates once the edge-DOF Hessian lands. Build-verification finding: `newton_euclidean` -> `euclidean_hessian` throws "edge DOFs are not supported" — the cyclic full solve is blocked by a missing edge-DOF Euclidean Hessian (gradient supports edge DOFs, analytic Hessian does not). Spherical convergence (Tier-1 #2) is already covered by test_newton_solver. Documented in doc/reviewer/java-ignore-crossvalidation.md. All 13 EuclideanFunctional tests pass (1 disabled). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
| adfcb7b931 |
Merge pull request 'feat(geometry): pn_geometry.hpp — Pn projective-metric substrate (jReality port)' (#31) from feat/pn-geometry-substrate into main
Some checks failed
C++ Tests / test-fast (push) Successful in 2m21s
API Docs / doc-build (push) Has been skipped
Markdown link check / check (push) Successful in 54s
Mirror to Codeberg / mirror (push) Successful in 43s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / quality-gates (push) Has been cancelled
|
|||
| 76942418fb |
Merge pull request 'feat(geometry): pn_geometry.hpp — Pn projective-metric substrate (jReality port)' (#30) from feat/lawson-hyperideal-golden into main
Some checks failed
|
|||
|
Tarik Moussa
|
149da15c64 |
feat(geometry): pn_geometry.hpp — Pn projective-metric substrate (jReality port)
Ports the small but pervasive de.jreality.math.Pn surface that the Java
algorithmic core uses across every not-yet-ported geometric phase:
HyperbolicLayout, SphericalLayout, FundamentalPolygon (9c), KoebePolyhedron
(10c'), quasi-isothermic (10e), hyperelliptic theta, CircleDomain (11c).
Porting it once unblocks all downstream consumers instead of re-deriving
the metric ad hoc per phase.
pn_geometry.hpp — header-only, Eigen, ~120 LOC:
PnMetric { EUCLIDEAN=0, ELLIPTIC=+1, HYPERBOLIC=-1 } matching jReality.
pn_inner_product — bilinear form per signature.
pn_norm / pn_dehomogenize / pn_set_to_length / pn_normalize.
pn_distance_between — Euclidean (spatial), elliptic (acos), hyperbolic (acosh).
pn_linear_interpolation — affine (E) and slerp (S/H constant-speed geodesic).
HYPERBOLIC uses the timelike-positive ("upper-sheet") convention, identical to
the already-verified projective_math.hpp::hyperbolicDistance; pn_distance_between
is regression-anchored against it in the tests.
test_pn_geometry.cpp — 6 tests, all GREEN:
InnerProductSignatures, EuclideanDistance, EllipticDistanceIsAngle,
HyperbolicDistanceClosedFormAndAnchor (+ projective_math.hpp anchor),
NormAndScaling, LinearInterpolationGeodesic.
doc/roadmap/java-parity.md — new "Infrastructure / support layers" section:
de.jreality.math.Pn → pn_geometry.hpp (partial, 6 fns covering core usage)
de.jreality.math.Rn → Eigen (no separate port needed)
MatrixBuilder → not yet (only needed for hyperelliptic theta)
conformallab XML types → not planned (GUI persistence, not algorithmic)
246/246 cgal tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
5de95a7a93 |
test(hyperideal): add Lawson branch-points golden-vector cross-validation
Second Lawson variant from HyperIdealConvergenceTest...WithBranchPoints.
- make_lawson_branch_points(): base + STELLAR subdivision (Java StellarLinear)
via CGAL Euler::add_center_vertex — a centre vertex per quad fan-connected to
its 4 corners (6 centres, 24 triangles, 36 edges). The 6 centres are IDEAL
vertices (b=0, v_idx=-1); θ_e=π on the 12 base edges, θ_e=π/2 on the 24 spokes.
- BranchPointsGoldenVector_JavaXVal: newton_hyper_ideal converges to the Java
golden (per symmetry class @1e-4):
original vertices → 1.3169579
base edges → 2.2924317
spoke edges → 0 (the π/2 spokes collapse to ideal)
Key insight: Java's index-based θ split (first 12 edges π, rest π/2) is
geometric — base edges vs stellar spokes — so the symmetry shortcut applies.
createLawsonHyperelliptic() NOT ported: needs a reader for the Java
conformal-data XML (lawson_curve_source.xml) + a port of
HyperIdealHyperellipticUtility, and its golden vector is not class-symmetric.
Documented as a deferred task.
243/243 cgal tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
0c502536b9 |
test(hyperideal): Tier-3 Lawson square-tiled golden-vector Java cross-validation
Ports the Java HyperIdealConvergenceTest (Lawson square-tiled) — the strongest
remaining @Ignore'd oracle (a hard-coded converged solution from a historical
x86 PETSc run).
- make_lawson_square_tiled(): builds the genus-2 base (4 vertices, 12 edges,
6 quads) via the low-level CGAL Surface_mesh half-edge API (add_edge +
set_target/set_next/set_face/set_halfedge), since the multi-edges (≥2 edges
per vertex pair) make add_face / OFF / polygon-soup impossible. Then
triangulate_faces → 12 triangles, 18 edges (12 original + 6 diagonals).
BuildsValidGenus2Mesh: is_valid + V=4/F=12/E=18 + χ=−2.
- ConvergenceGoldenVector_JavaXVal: Θ_v=2π, θ_e=π/2 (12 original edges),
θ_e=π (6 diagonals); newton_hyper_ideal converges (from x0=1.0, unconstrained)
to the Java golden vector:
vertices → 1.1462158341786262
original → 1.7627471737467797
aux → 2.633915794495759
asserted per symmetry class @1e-5 (robust to DOF ordering).
The perfect symmetry of the golden vector means any consistent one-diagonal
triangulation reproduces the three values, so the external jtem Triangulator
choice need not be replicated. Resolves the Tier-3 item from PR #29's analysis.
242/242 cgal tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
ba83974525 |
test: Java golden-value oracles for the five DCE math cores + P1-2/P1-3 fixes
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 1m57s
API Docs / doc-build (pull_request) Successful in 59s
Markdown link check / check (pull_request) Successful in 51s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 2m19s
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> |
||
|
Tarik Moussa
|
a3ee9576d4 |
fix+test: Euclidean holonomy/τ end-to-end + spherical edge-DOF oracle (2026-05-29 audit)
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 1m57s
API Docs / doc-build (pull_request) Successful in 1m3s
Markdown link check / check (pull_request) Successful in 44s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 2m11s
Bundles the 2026-05-29 Java↔C++ math-correctness audit (doc/reviewer/ java-port-audit.md, 11 findings) with two follow-up fixes. Audit code changes: - Finding 3 (spherical_functional): edge-DOF replacement parameterization via spher_eff_lambda; edge gradient α_opp⁺+α_opp⁻−θ_e (drops additive −(S⁺+S⁻)/2) - Finding 4 (spherical_hessian): always-compiled edge-DOF throw guard - Finding 6 (period_matrix): faithful normalizeModulus (0≤Re≤½, Im≥0, |τ|≥1) - Finding 9 (inversive_distance): degenerate-face limiting angles, no skip - Findings 1/2 (euclidean): degenerate gradient limiting angles + Hessian guard Euclidean holonomy/τ fix: develop the cut surface across the dual spanning tree only (cut_graph now exposes is_dual_tree), so genus-1 cut edges yield non-degenerate lattice generators. Previously τ came out 0 / NaN / 1e13 on the bundled tori; now matches the analytic revolution modulus i·√(R²−r²)/r. Re-enabled τ reporting in the Euclidean CLI; rewrote validation.md §3/§4 accordingly. Tests (240 CGAL, 0 skipped): - HolonomyEndToEnd ×3 — tori of revolution (4×4, hex 6×6, 8×8) vs analytic modulus - SphericalFunctional.EdgeGradient_RegularTetClosedForm — independent closed-form π/3 oracle locking the Finding-3 edge formula (the path-integral FD check cannot detect a wrong-but-conservative gradient) Also documents the latent spherical/hyperbolic holonomy-extraction bug (same single-development pattern, dead code today) in research-track.md (Phase 9c/10), and adds favour/normalisations to the codespell ignore list. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
e874f73e29 |
docs+lint: post-merge consistency fixes after PRs #17/#18/#19 landed
Three small cleanups surfaced by running the full gate sweep on the merged main: 1. CGAL conventions (CGAL-2 \\file briefs) doc-only headers `Conformal_map/doxygen_groups.h` and `Conformal_map/doxygen_namespaces.h` were missing the `\\file` brief required by the CGAL conventions check. Added both. 2. codespell — three new triggers `code/tests/cgal/CMakeLists.txt` uses "honour", `doc/reviewer/hub.html` uses `<thead>` (HTML tag, false-positive for "thread"), and `doc/roadmap/research-track.md` uses "optimiser". All three are British-English / HTML usage; added to `.codespellrc` ignore list. 3. Doxygen warning in `doc/architecture/compile-time.md:250` A trailing backtick-quoted CMake flag at end-of-file confused Doxygen's markdown parser into starting a never-closing verbatim block. Rewrote the line to put the prose first and the backtick in the middle, not at end-of-file. All gates green again on the merged main: ✅ 259/259 tests pass ✅ test-count consistency ✅ markdown links 166/166 resolve ✅ CGAL conventions 0/8 violations ✅ license-headers 68/68 carry MIT SPDX ✅ codespell 0 typos ✅ shellcheck 0 findings (18 scripts) ✅ Doxygen 100% coverage, 0 warnings Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
bc40a13e8d |
perf: architecture-touch quick-wins #6 + #10; skip #5 + #7 with honest notes
Evaluated all four mid-tier architecture-touch levers from doc/architecture/compile-time.md. Outcome: ship two opt-in improvements, defer two with explicit rationale. #6 — Eager-include reduction (Dense → Core) ✅ shipped ───────────────────────────────────────────────────── Three headers downgraded from `<Eigen/Dense>` to `<Eigen/Core>`: * projective_math.hpp * hyper_ideal_visualization_utility.hpp * mesh_utils.hpp All three only use Matrix/Vector primitives, no Eigen decompositions. The other five Dense-including headers were inspected and KEPT on `<Eigen/Dense>` because they use `.inverse()`, `.determinant()`, `ColPivHouseholderQR`, or `SelfAdjointEigenSolver`. Measured Apple M1 cold rebuild after this change: 58 / 60 / 63 s across three runs. The prior analysis predicted ~10 % gain; reality landed within the ±5 s natural variance band of repeated builds, so the net build-time effect on the test target is "noise-level". The change is still kept because downstream consumers who include ONLY one of the three downgraded headers see a real per-TU drop (Core preprocesses to ~250 k lines vs Dense's ~350 k). #10 — Fast test-build mode (-O0 -g) ✅ shipped ─────────────────────────────────────────────── New option CONFORMALLAB_FAST_TEST_BUILD (default OFF). When ON, both test targets (`conformallab_tests` and `conformallab_cgal_tests`) compile with `-O0 -g -UNDEBUG`, overriding the inherited Release `-O3 -DNDEBUG`. Measured Apple clang: 51.6 s vs 46.8 s without -O0 → slightly slower. The Backend phase that prior analysis predicted would drop from 9.3 s to ~2 s doesn't dominate on Apple clang the way it does with GCC; the bigger `-g` debug info also lengthens the link step. Kept shipped because: * On Linux + g++ (CI runner) the picture flips — Backend dominates more, `-O0` typically delivers the predicted ~40 % build-time cut. * Cross-platform parity: users on Linux see the same CMake option they see locally. Honest documentation in doc/architecture/compile-time.md notes that the Apple-clang-local benefit is currently 0 %. Tests RUN ~15× slower under `-O0` (1.5 s → 23 s for 236 tests); acceptable for CI "did anything break" loops, NOT acceptable for benchmark workloads. #5 — Move detail:: impls to .inl files ⏸ deferred ─────────────────────────────────────────────────── Pure enabler for #7. Without #7 landing, the .inl extraction would just add an extra hop to header reading. Reconsider once a concrete maintenance reason emerges (e.g. a downstream user wants to override a detail helper). #7 — Pimpl on newton_solver + priority_BFS ⏸ deferred ─────────────────────────────────────────────────────── Honest assessment: Newton_solver is template-on-Functional, so a faithful Pimpl would require either type erasure or a virtual-method interface across the five solver instantiations. Estimated 1-2 weeks of refactor with measurable API-surface risk. PCH already absorbs the SimplicialLDLT + SparseQR template parse cost, so the remaining delta is small. Deferred until a concrete user reports compile-time pain from these specific templates. Documentation ───────────── README.md gains a "Compile-time workflow modes" section with all six opt-in switches (BUILD_TESTING, HEADERS_CHECK, DEV_BUILD, FAST_TEST_BUILD, USE_PCH, USE_CCACHE) as ready-to-paste command lines. doc/architecture/compile-time.md gains: * an "Architecture-touch quick-wins" section with the four-row status table (5 deferred / 6 shipped / 7 deferred / 10 shipped) * the FAST_TEST_BUILD row added to the workflow-modes table * the mode-matrix table updated with Linux-vs-macOS expected values * an honest "variance" note explaining the ±5 s spread between repeated cold builds and why #6's net effect lands in that noise Verified: default build 55 s (within usual variance), 236/236 tests pass under default; FAST_TEST_BUILD=ON build 52 s, 236/236 PASS. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
9ea7d15aa0 |
perf: add 4 workflow modes (BUILD_TESTING / DEV_BUILD / HEADERS_CHECK / ccache)
Four orthogonal opt-in build modes on top of the existing PCH + Unity
defaults. Each addresses a specific iteration scenario; defaults are
unchanged (PCH + Unity stays the canonical fast full-rebuild path).
(A) HEADERS_CHECK target — opt-in via -DCONFORMALLAB_HEADERS_CHECK=ON
Per-public-header smoke-compile sentinels. For each of the six
public CGAL umbrella headers, a stub TU `#include <…>\nint main(){}`
is generated at configure time and compiled in isolation.
* Full headers_check build: ≈ 12 s
* Incremental after touching one header: ≈ 0.1 s
Use case: "did my refactor still parse the public API?" without
waiting 55 s for the full CGAL test build.
(C) DEV_BUILD mode — opt-in via -DCONFORMALLAB_DEV_BUILD=ON
PCH stays on; Unity Build is forced off (both globally AND on the
cgal-tests target which previously overrode the global setting).
Trade-off: full clean rebuild ~75 s (+36 % vs the 55 s default)
but incremental rebuild after editing a single test file drops
from ~46 s (unity batch) to ~16 s (single TU + relink).
Flip on for trial-and-error sessions, flip off before measuring
CI build time or shipping a PR.
(D) ccache integration — default ON, disable with -DCONFORMALLAB_USE_CCACHE=OFF
Detects `ccache` on PATH and prepends it to compile + link
launchers. On Apple clang + PCH + Unity the macOS-local hit
rate is currently 0 % (3 separate friction points documented
in doc/architecture/compile-time.md § "ccache — honesty notes");
stays neutral when it doesn't help. Real payoff on Linux CI
(g++ + traditional PCH) where 80 %+ hit rates are typical.
(BUILD_TESTING=OFF) Standard CMake gate, now respected end-to-end.
Wrapped both `add_subdirectory(tests)` AND the FetchContent of
GoogleTest in `if(BUILD_TESTING)`. Pass `-DBUILD_TESTING=OFF`:
* Configure ≈ 1 s
* Build ≈ 0 s
* 0 object files
* No GTest fetch
Use case: IDE-syntax-check workflow that needs
`compile_commands.json` but does NOT need to download GTest
or build any test binary.
doc/architecture/compile-time.md gains:
* a "Workflow modes — what to choose when" section with a 4-row
switch matrix and a "mode matrix at a glance" comparison table
* a ccache honesty-notes block listing the three macOS friction
points (PCH artefact caching, Unity Build path randomisation,
CMake launcher integration) — Linux CI is where the lever pays
off
Verified: default build 53 s wall, 236/236 tests pass; all opt-in
modes tested end-to-end with their expected workflow numbers
documented in the doc.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
5fbc4bcc7f |
ci+perf: PCH + Unity Build cut CGAL test build wall-time 30% (78s -> 55s)
Two structural compile-time optimisations on the conformallab_cgal_tests
target, both opt-out-able and verified safe (236/236 tests pass under
every configuration).
(1) Precompiled headers — option CONFORMALLAB_USE_PCH (default ON)
target_precompile_headers(conformallab_cgal_tests PRIVATE
<CGAL/Surface_mesh.h>
<CGAL/Simple_cartesian.h>
<CGAL/Kernel_traits.h>
<CGAL/boost/graph/iterator.h>
<CGAL/Polygon_mesh_processing/triangulate_faces.h>
<Eigen/Dense> <Eigen/Sparse> <Eigen/SparseCholesky> <Eigen/SparseQR>
<gtest/gtest.h>
<vector> <string> <cmath> <complex>
)
Absorbs the per-TU CGAL+Eigen template-parse cost (measured at 5.9 s
per minimal "include <CGAL/Discrete_conformal_map.h>" hello-world TU
on Apple M1).
(2) Unity Build — UNITY_BUILD ON with UNITY_BUILD_BATCH_SIZE 4
Concatenates the 22 test TUs into 5 batches of <=4 files each;
CGAL+Eigen headers parsed once per batch instead of once per TU.
Batch size 4 keeps gtest's TEST(...) macros and per-file
`using namespace ...` from colliding across batched files.
Numbers (Apple M1, Ninja, -j8, clean rebuild)
─────────────────────────────────────────────
wall CPU tests
baseline 78 s 676 s 236/236
+ PCH 66 s 474 s 236/236 (-15% wall, -30% CPU)
+ PCH + Unity 55 s 167 s 236/236 (-30% wall, -75% CPU)
Honest deferred items (documented in doc/architecture/compile-time.md):
* `extern template` (lever #2 in the analysis) — subsumed by PCH;
estimated residual gain <5%, would add Eigen-version fragility.
* Header split <CGAL/Discrete_conformal_map_{euclidean,spherical,
hyper_ideal}.h> (lever #3) — downstream-only benefit (our test
build needs all three); kept as a future cleanup once a downstream
user actually requests it.
Opt-outs: `-DCONFORMALLAB_USE_PCH=OFF` and `-DCMAKE_UNITY_BUILD=OFF`.
Detailed measurement methodology, per-TU breakdowns, clang
-ftime-trace template hot-spots, and a "what comes next" lever list
live in doc/architecture/compile-time.md.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
f25174ed69 |
feat: output_uv_map for InversiveDistance, error for CP-Euclidean, reviewer trio
Three reviewer-meeting deliverables in one commit.
(1) output_uv_map for the two remaining DCE entries
─────────────────────────────────────────────────
* Discrete_inversive_distance.h: full implementation. After Newton,
reconstruct effective Euclidean edge lengths from the converged
log-radii via the Bowers-Stephenson identity
`ℓᵢⱼ² = rᵢ² + rⱼ² + 2·Iᵢⱼ·rᵢ·rⱼ`, populate a temporary
EuclideanMaps with `lambda0 = log(ℓᵢⱼ²)`, and reuse the existing
`euclidean_layout(mesh, 0, eucl)` priority-BFS. Per-vertex
Point_2 coordinates written into the user-supplied pmap.
Optional `normalise_layout(true)` applies the canonical PCA
centroid + major-axis rotation, same as the other 3 entries.
* Discrete_circle_packing.h: throws std::runtime_error with a
clear pointer to Phase 9c rather than silently producing
nonsense. CP-Euclidean is face-based; the faithful output is a
per-face circle packing in ℝ², not a per-vertex Point_2 map.
A true layout requires BPS-2010 §6 (~150 lines, on the porting
roadmap as Phase 9c). Failing loudly is the honest default.
Tests: 2 new cases in test_cgal_phase8b_lite.cpp
(OutputUvMap_InversiveDistance_PopulatesPmap;
OutputUvMap_CPEuclidean_ThrowsClearly). Both green.
Suite total now 259 (was 257, +2). CGAL subtotal: 234 → 236.
(2) Reviewer meeting documents
──────────────────────────
New directory doc/reviewer/ with three files:
* briefing.md — one-page orientation for the reviewer.
What the project is, where to look first
(https://tmoussa.codeberg.page/ConformalLabpp/), the headline
evidence (tests/coverage/sanitizers/license), what we want from
them, what's deferred and why, and the 5 questions in a separate
file.
* questions.md — the 5 concrete decisions we want their second
opinion on:
Q1 Phase 9c (port-literal vs re-derive)
Q2 Phase 9b-analytic (worth ~2 weeks for ~6× speedup?)
Q3 CP-Euclidean output_uv_map (build now or defer?)
Q4 CGAL submission strategy (one package or five?)
Q5 geometry-central cross-validation co-authorship
Plus an explicit "what would you say no to?" question at the
bottom — negative feedback is the highest-value information.
* agenda.md — my own internal playbook (NOT to be sent).
60-min flow: 5-min thank-you, 10-min architecture tour,
30-min for Q1-Q5 in the order Q4-Q1-Q2-Q5-Q3, 5-min "no"
question, 5-min wrap-up. Includes post-meeting memo template
to fill out in the 30 min after.
* README.md — index for the directory; says which file goes
to whom and when to send.
(3) locked-vs-flexible.md known-limitations update
─────────────────────────────────────────────
"output_uv_map covers 3 of 5 entries" → "covers 4 of 5".
CP-Euclidean's throws-clearly behaviour documented as a Phase 9c
deliverable rather than a passive gap.
Bonus: extended .codespellrc ignore list (acknowledgement, the
British-English spelling I used in agenda.md).
Verifications on this commit:
259/259 tests pass (0 skipped)
scripts/check-test-counts.sh: OK (23 + 236 = 259)
scripts/quality/license-headers.sh: OK (66/66 SPDX)
python3 scripts/quality/cgal-conventions.py: OK (0/6 violations)
scripts/quality/codespell.sh: OK (0 typos)
scripts/quality/shellcheck.sh: OK (0 findings)
python3 scripts/check-markdown-links.py: OK (143/143)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
32253a8f5e |
ci+licenses: promote 4 trivial gates to required CI + THIRD-PARTY-LICENSES.md
Two reviewer-facing additions consolidated into one commit:
(1) New `quality-gates` job in .gitea/workflows/cpp-tests.yml
──────────────────────────────────────────────────────────
Runs in parallel with test-cgal after test-fast. Installs
`codespell` + `shellcheck` (apt) into the existing ci-cpp container,
then executes four scripts strictly (exit 1 on any finding):
* license-headers.sh — 66/66 files carry SPDX MIT
* cgal-conventions.py — 0 violations across 6 CGAL public headers
* codespell.sh — 0 typos across docs + source + scripts
* shellcheck.sh — 0 findings across 16 shell scripts
Each ran at 0 findings locally before promotion. Total wall-time
on the eulernest runner: ~30 s.
(2) New code/deps/THIRD-PARTY-LICENSES.md
──────────────────────────────────────
Enumerates every vendored dep under code/deps/, plus auto-fetched
GoogleTest, plus system-required Boost, with:
* upstream project + version + SPDX identifier
* compatibility note for MIT distribution
* downstream-packager license matrix (header-only consumer vs
CLI binary) clarifying the LGPL §3 vs §4 distinction
Required for any future Linux-distribution packaging and for the
CGAL submission's compliance check.
Also fixes a `code/.gitignore` gap: the `deps/*` wildcard was
catching the new file; added `!deps/THIRD-PARTY-LICENSES.md` to
the exclusion list so it's actually tracked.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
| 704f42bbfd |
Merge pull request 'ci+quality: structural gates (CI: 3 new; local: 7 new + .clang-tidy)' (#18) from ci/structural-tests into main
Some checks failed
C++ Tests / test-fast (push) Has started running
C++ Tests / test-cgal (push) Has been cancelled
API Docs / doc-build (push) Has been cancelled
Doxygen → Codeberg Pages / publish (push) Has been cancelled
Markdown link check / check (push) Has been cancelled
Mirror to Codeberg / mirror (push) Has been cancelled
|
|||
|
Tarik Moussa
|
1aa3493e7d |
quality: 4 more gates + dependency audit; full --fast sweep 10/10 green
This commit closes the structural-tests work on PR #18. Every gate in `run-all.sh --fast` now passes end-to-end on the canonical dev machine. New gates ───────── 1. shellcheck (scripts/quality/shellcheck.sh) * Scans every `scripts/**/*.sh` at severity=warning+ * 16 scripts inspected; cleanup pass took the tree from 7 findings (SC2164 + SC2034) to 0 findings. 2. cppcheck (scripts/quality/cppcheck.sh) * Complementary static analyser to clang-tidy; different heuristics, fewer false-positives on heavy CGAL/Eigen templates. * Default severity warning+, --strict adds style, --all = everything. * Suppresses 4 noise classes (missingIncludeSystem, etc.) explicitly. 3. .editorconfig * Cross-IDE fallback for editors that don't honour clang-format. * Covers Markdown (preserve trailing whitespace), Python, YAML, JSON, shell, Makefile (tabs) — the file types clang-format doesn't cover. 4. CONFORMALLAB_WARNINGS_AS_ERRORS CMake option * Off by default → regular builds don't break on new GCC warnings. * `-DCONFORMALLAB_WARNINGS_AS_ERRORS=ON` adds `-Werror`, intended for CI promotion-track and sanitizer runs. Dependency audit (doc/architecture/dependencies.md) ──────────────────────────────────────────────────── New single-source-of-truth document listing: * what the library requires (Eigen + CGAL + Boost — all header-only) * what tests require (auto-fetched GTest, no system install) * what each quality tool is for, install command per OS, and behaviour when missing (each gate exits 2 = SKIP, run-all recognises this and continues) * a verification recipe that strips PATH down and shows the library still configures + builds + tests cleanly with zero quality tools installed. run-all.sh enhanced ─────────────────── * Recognises "tool not in PATH" → SKIP (not FAIL). * Summary now reports `passed / skipped / failed` separately. Bug fixes uncovered by the sweep ──────────────────────────────── * sanitizers.sh: gtest_discover_tests ran the ASan-instrumented binary at build time and aborted → added `-DCMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST` to defer discovery to ctest invocation. Now 23/23 sanitizer-instrumented tests pass. * clang-tidy.sh on macOS: brew-installed clang-tidy couldn't find Apple SDK system headers (<cmath>, <complex>, …) → added `--extra-arg=-isysroot $(xcrun --show-sdk-path)` on Darwin. * clang-tidy.sh: needed `-DWITH_CGAL_TESTS=ON` in compile_commands generation so CGAL include paths are part of at least one compile entry. Now resolves CGAL/Surface_mesh.h etc. * clang-tidy.sh: viewer-only headers (`viewer_utils.h`, `mesh_utils.hpp`) excluded — they need `WITH_VIEWER=ON` + system GLFW/libigl that the lint build doesn't drag in. * `.codespellrc`: extended ignore list (recognise, signalled, modelled, travelled, …) for British-English consistency across own writing. Final state — local quality block on this commit, this branch: ✅ License headers (66/66 carry MIT SPDX) ✅ CGAL conventions (0/6 violations on 6 CGAL headers) ✅ clang-format drift (0 drift) ✅ cmake-format/-lint (0 drift, 0 lint findings) ✅ codespell (0 typos in scope) ✅ shellcheck (0 findings across 16 .sh files) ✅ cppcheck (warning+ severity clean) ✅ Markdown links (122/122 resolve) ✅ Sanitizers (ASan+UBSan) (23/23 fast tests pass) ✅ clang-tidy (35 headers inspected, 0 findings) Library standalone-ness verified: env -i PATH=... cmake -S code -B /tmp/build-standalone cmake --build /tmp/build-standalone --target conformallab_tests ctest -E '^cgal\.' → all green Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
d3c08b3bc0 |
quality: 2 new gates (cmake-format, codespell) + SPDX rollout (60 files)
This commit closes the remaining red gates so `run-all.sh --fast` is
green end-to-end on the canonical dev machine.
New gates
─────────
1. cmake-format / cmake-lint
* scripts/quality/cmake-format.sh — dry-run by default,
--strict to fail on drift, --fix to apply
* .cmake-format.yaml — policy (lowercase commands, UPPERCASE
keywords, 100-col loose limit; matches .clang-format choices)
* Uses the pip-installed `cmakelang` package
(`pip3 install --user cmakelang`)
2. codespell
* scripts/quality/codespell.sh — exit 1 on any typo, --fix
interactively
* .codespellrc — extensive ignore-words-list capturing the
project's British-English-leaning style (centre, behaviour,
specialise, normalise, …) plus domain abbreviations (DOF,
iff, fuchsiens), so the gate flags real typos only.
* Validated: 0 typos across docs + code/include + scripts +
code/{src,tests}.
SPDX rollout (license-headers --fix)
────────────────────────────────────
license-headers.sh gained a --fix mode that auto-inserts the
two-line header at the correct place (below `#pragma once` if
present, above the include guard otherwise, plain prepend for
.cpp). Ran it on 60 of 66 files — 100 %-licensed now.
Verified the build is still clean after the textual edits:
cmake -S code -B build-verify -DWITH_CGAL_TESTS=ON
ctest --test-dir build-verify → 257/257 PASS
run-all.sh + README updated to include the two new gates.
End-to-end style/convention block status (on this commit, this branch):
✅ license-headers (66/66 carry MIT SPDX)
✅ cgal-conventions (0/6 violations)
✅ clang-format (0 drift; warn-mode for safety)
✅ cmake-format/-lint (warn-mode for safety)
✅ codespell (0 typos)
✅ markdown-links (122/122 resolve)
The slow correctness/quality block (sanitizers, coverage, clang-tidy,
multi-compiler, cgal-version-matrix, reproducible-build) is left as
follow-up — toolchain is now installed locally, scripts are syntax-
clean, the slow runs themselves are a separate matter of patience.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
62b02f88b9 |
docs(doxygen): 100% public-API coverage (228 → 0 undocumented)
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>
|
||
|
Tarik Moussa
|
e04515c423 |
docs(doxygen): fix critical extraction bug; baseline 24% → 42% on public API
ROOT CAUSE FIX
The Doxyfile EXCLUDE_PATTERNS line contained `*/* 2.hpp` (note the
space — a stray glob from macOS-style "foo 2.hpp" duplicate files).
That pattern was silently matching ALL .hpp / .h files, so Doxygen was
indexing nothing under code/include/. The pre-existing 556 KB of HTML
output was effectively documenting only README.md, CLAUDE.md and a
small stub for std:: — not the C++ API at all.
After fixing the pattern (and properly escaping the space-prefixed
"foo 2.hpp / foo 2.h" macOS-dup patterns), Doxygen now extracts 141
compounds and emits 248 HTML pages from the public headers.
WHAT THIS PR ADDS
1. Doxyfile fix: correct EXCLUDE_PATTERNS; add GENERATE_XML for the
coverage measurement script; add MathJax for `$$...$$` math in
markdown; add the missing CGAL `\cgalParamNBegin/End/Description/
Default/...` aliases so CGAL-style param blocks render correctly.
2. New headers:
- code/include/CGAL/Conformal_map/doxygen_groups.h
defines `PkgConformalMap{,Ref,Concepts,NamedParameters}`,
resolving 17 prior "non-existing group" warnings.
- code/include/CGAL/Conformal_map/doxygen_namespaces.h
gives every namespace under `CGAL::` and `conformallab::` a
brief description.
3. New tool: scripts/doxygen-coverage.sh
Parses the XML output and reports % of public symbols (excluding
the `detail::` implementation namespaces by default) that have a
non-empty brief/detailed description. Supports `--list-undoc`
and `--threshold N` for CI integration.
4. Substantial docstring additions to the public CGAL headers:
`Conformal_map_traits.h`, `Discrete_circle_packing.h`,
`Discrete_inversive_distance.h`, `conformal_mesh.hpp`,
`Discrete_conformal_map.h` (Hyper_ideal_map_result fields).
5. Markdown housekeeping that the strict-warning Doxygen run surfaced:
tests.md (escape literal `#` in table cell),
locked-vs-flexible.md (broken section anchor),
overall_pipeline.md (replace `$$LaTeX$$` with inline-unicode math).
CURRENT NUMBERS
before: ~24% documented (public API; the prior "87%" claim was
based on the broken extraction)
after: 42% documented (165 of 396 public symbols)
warnings: 0 (was 27 spurious + a flood of bogus undocumented
warnings hidden by the buggy EXCLUDE pattern)
NEXT (in a follow-up commit on this branch)
The remaining 231 public symbols (mostly in `layout.hpp`,
`hyper_ideal_functional.hpp`, `spherical_functional.hpp`, the per-mode
functional/Hessian files) can be brought to ~100% with another pass of
short `///` brief descriptions. The coverage script is the gate; CI
can begin enforcing `--threshold 95` once the next pass lands.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
039cc26e36 |
Phase 8b-Lite: pipe-operator chaining for named parameters
Some checks failed
C++ Tests / test-fast (push) Successful in 1m58s
C++ Tests / test-fast (pull_request) Successful in 2m33s
API Docs / doc-build (pull_request) Successful in 51s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / test-cgal (pull_request) Failing after 10m32s
Adds `operator|` in `namespace CGAL` so package-local named parameters
can be combined left-to-right without modifying CGAL upstream:
auto p = CGAL::parameters::gradient_tolerance(1e-12)
| CGAL::parameters::max_iterations(500)
| CGAL::parameters::output_uv_map(uv);
CGAL::discrete_conformal_map_euclidean(mesh, p);
Why not the canonical `.a().b().c()` syntax
───────────────────────────────────────────
CGAL's standard chaining mechanism requires registering each named
parameter as a member function on `Named_function_parameters` via the
`CGAL_add_named_parameter` macro in
`CGAL/STL_Extension/internal/parameters_interface.h` — a vendored
upstream file that conformallab++ deliberately treats as read-only.
Adding member-function chainers for our package-local tags would
require either forking CGAL or modifying the vendored copy. Neither
is acceptable for a library that wants to remain portable across
future CGAL releases.
The pipe-operator achieves the same compositional semantics via a
free function in `namespace CGAL` (so ADL finds it for
`Named_function_parameters` operands). Implementation: rebuild the
right-hand-side `Named_function_parameters` with the left-hand-side
as its `Base`, producing an indistinguishable chain that every entry
function accepts unchanged.
Implementation: `code/include/CGAL/Conformal_map/internal/parameters.h`
lines 158-187. The operator is constrained to right-hand-sides with
`No_property` base (i.e. fresh single-parameter packs from the helper
functions), so it never collides with any future CGAL operator on the
same type.
Tests (2 new, total Phase-8b-Lite suite 15 → 17)
────────────────────────────────────────────────
* CGALPhase8bLite.NamedParamPipe_MultipleParamsTakeEffect
Chain three parameters; verify all three take effect (tight
tolerance respected + UV pmap populated + iteration cap honoured).
* CGALPhase8bLite.NamedParamPipe_TwoParams
Chain two parameters; verify max_iterations(0) blocks the loop
even when combined with another param.
Full CGAL suite: 234/234 PASSED, 0 SKIPPED (was 232).
Total: 257/257 PASSED, 0 SKIPPED (was 255).
scripts/check-test-counts.sh: OK.
Documentation updates
─────────────────────
* doc/tutorials/add-output-uv-map.md §3.4: "Current limitation: no
chaining" → "Chaining: use the pipe operator `|`". Explains why
CGAL's `.member()` syntax isn't available and shows the `|`
workaround with a working code example.
* doc/architecture/locked-vs-flexible.md §8: chaining now flagged as
shipped via pipe; recommended posture says `.member()` chaining
only if a user pushes for the CGAL-canonical syntax.
* doc/roadmap/porting-status.md §5: API limitations table updated.
* doc/api/tests.md: CGALPhase8bLite row 15 → 17, total 232 → 234.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
b7e837815f |
Phase 8b-Lite extension: output_uv_map named parameter for integrated layout
Closes the UX gap identified in the Phase-8b-Lite design discussion:
the four classical-DCE CGAL entries now optionally run their `*_layout()`
step internally if the caller supplies `CGAL::parameters::output_uv_map(pmap)`.
Before this PR, the workflow was:
auto res = CGAL::discrete_conformal_map_euclidean(mesh);
// ... user has to re-set up maps, re-pin vertex, then ...
auto layout = euclidean_layout(mesh, res.x, maps);
// ... and copy coordinates into a property map manually.
After this PR:
auto uv = mesh.add_property_map<Vertex_index, K::Point_2>("uv", ...).first;
CGAL::discrete_conformal_map_euclidean(
mesh, CGAL::parameters::output_uv_map(uv));
// ... uv now populated for every vertex.
Coverage
────────
* `discrete_conformal_map_euclidean` — `Point_2` per vertex.
* `discrete_conformal_map_spherical` — `Point_3` per vertex (on S²).
* `discrete_conformal_map_hyper_ideal` — `Point_2` per vertex (Poincaré disk).
CP-Euclidean and Inversive-Distance entries do not yet support
`output_uv_map` — face-based packing has no per-vertex UV concept, and
inversive-distance needs a dedicated layout routine that uses Luo's
edge-length formula (planned follow-up).
New named parameters (`code/include/CGAL/Conformal_map/internal/parameters.h`)
─────────────────────────────────────────────────────────────────────────────
* `output_uv_map(pmap)` — write coordinates into pmap after layout.
* `normalise_layout(bool)` — apply post-layout canonical normalisation
(PCA centroid for Euclidean, north-pole alignment for Spherical,
Möbius centring for Hyper-ideal).
Both follow the existing Phase-8a-MVP named-parameter convention.
Chained syntax (`.output_uv_map(...).normalise_layout(true)`) is not
yet supported — pass them one at a time.
Tests (5 new in test_cgal_phase8b_lite.cpp)
───────────────────────────────────────────
* `OutputUvMap_Euclidean_PopulatesPmap` — UVs are finite + non-trivial.
* `OutputUvMap_Spherical_PopulatesXyz` — every output on unit S².
* `OutputUvMap_HyperIdeal_PointsInPoincareDisk` — |p|² ≤ 1 if converged.
* `OutputUvMap_Absent_DoesNotRunLayout` — no parameter ⇒ no layout.
* `OutputUvMap_NormaliseLayout_TakesEffect` — both raw + norm calls
return finite UVs (named-parameter chaining limitation documented).
All five pass. Full CGAL suite: 232/232, 0 skipped (was 227).
doc/api/tests.md
────────────────
Updated the per-suite table to list the 7 CGAL test suites that landed
in v0.9.0 (8a MVP + 9a + 9b + 8b-Lite) but had not yet been added to the
canonical table. Total: 227 → 232. This brings the doc back in sync
with `ctest` output and unblocks future `scripts/check-test-counts.sh`
runs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
79f6757646 |
docs: add Doxygen docstrings to high-priority public functions (Phase-9a + setup)
Follow-up to the doc-audit: fills the 30 high-priority docstring gaps
identified across the public-API headers. Code unchanged — comments
only.
Headers updated
───────────────
* code/include/cp_euclidean_functional.hpp (5 docstrings added)
- setup_cp_euclidean_maps — defaults + naming convention
- assign_cp_euclidean_face_dof_indices — gauge-pin semantics
- (overload) — first-face convenience
- cp_euclidean_dimension — DOF counting
(gradient, energy, Hessian, and FD-check were already documented
via the header-block comments.)
* code/include/inversive_distance_functional.hpp (4 docstrings added)
- setup_inversive_distance_maps — defaults + Bowers-Stephenson init note
- assign_inversive_distance_vertex_dof_indices — gauge-pin caveat
- inversive_distance_dimension — DOF counting
- compute_inversive_distance_init_from_mesh — two-phase init + Bowers-Stephenson formula
* code/include/euclidean_functional.hpp (4 docstrings added)
- setup_euclidean_maps — defaults + naming convention
- assign_euclidean_vertex_dof_indices — gauge-pin caveat
- assign_euclidean_all_dof_indices — cyclic-functional usage
- euclidean_dimension — DOF counting
* code/include/spherical_functional.hpp (5 docstrings added)
- setup_spherical_maps — defaults + naming convention
- assign_vertex_dof_indices — gauge-pin
- assign_all_spherical_dof_indices — cyclic-functional usage
- spherical_dimension — DOF counting
- compute_lambda0_from_mesh — unit-sphere precondition
* code/include/hyper_ideal_functional.hpp (3 docstrings added)
- setup_hyper_ideal_maps — defaults + cross-functional naming explanation
- hyper_ideal_dimension — DOF counting
- assign_all_dof_indices — strictly-convex no-gauge usage
* code/include/mesh_utils.hpp (3 docstrings added)
- cgal_to_eigen — libigl-style (V, F) conversion + side-effect note
- simple_visualize_mesh — requires WITH_VIEWER, lifetime
- get_vertex_map — zero-copy + lifetime warning
File header upgraded to a proper Doxygen file-level comment block.
Total: 24 new Doxygen-style docstrings added.
Coverage statistics (per the doc-audit)
───────────────────────────────────────
Before: 110 / 154 public symbols documented (71.4%)
After: 134 / 154 public symbols documented (87.0%)
Remaining gaps (20 entries) cluster in lower-priority utilities
(p2_utility.hpp, period_matrix.hpp internal helpers, mesh_builder
already has block-comments above each factory). These can be filled
in a future PR when the public-API surface for Phase 9c lands.
Verification
────────────
* Build: clean (no new compiler warnings).
* Tests: 250/250 PASSED, 0 SKIPPED.
* scripts/check-test-counts.sh: OK.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
0f78d181e1 |
docs: centralise test counts + add release-policy + remove stale stub references
Two complementary improvements aimed at reducing recurring maintenance
overhead:
1. **Test-count centralisation** — `doc/api/tests.md` is now the
single source of truth for the test counts. All other docs
(README, CLAUDE.md, doc/contributing.md, doc/getting-started.md,
doc/math/validation.md, doc/math/validation-protocol.md,
scripts/try_it.sh) use qualitative phrasing + a link instead of
hardcoded numbers. The previous regime had eight places with
"227 CGAL tests, 23 non-CGAL tests" that drifted apart across
releases (the v0.9.0 release-prep needed to touch nine files).
2. **Versioning policy** — `doc/release-policy.md` (new, ~250 lines)
formalises:
* SemVer rules for the pre-1.0 and post-1.0 phases.
* Phase-milestone → MINOR-bump mapping (v0.10.0 → Phase 9c, …).
* Single-source-of-truth table for moving numbers (test counts,
version, date).
* Step-by-step release process (the recipe that worked for v0.9.0
after the false-start with PR #11/#12).
* Hotfix policy + post-1.0 deprecation policy.
* Known failure modes and how to recover from them.
Plus a small CI gate:
3. **scripts/check-test-counts.sh** — verifies the totals in
doc/api/tests.md match `ctest` output. Re-uses existing build-cgal/
if present. Exit 0 on match, 1 on divergence with recovery hints.
Cheap enough (~30 s) to run on every PR.
Other cleanups
──────────────
* code/tests/cgal/CMakeLists.txt — stale "Test 7 (genus-2 homology)
as GTEST_SKIP stub until Phase 8" comment removed; that test landed
as HomologyGenerators.Genus2_FourCutEdges in Phase 7.
* CLAUDE.md — "test-fast also runs stubs" Known Quirks entry updated
to reflect the v0.9.0 stub cleanup (no GTEST_SKIPs remain).
* CLAUDE.md doc map — new entry for doc/release-policy.md.
Stubs audit
───────────
Zero GTEST_SKIP() calls remain in the codebase as of this commit.
The only references to stubs are in historical documentation
(CHANGELOG.md v0.7.0 entry, doc/roadmap/* "deferred to research-track"
notes) — those are intended.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
540f71a629 |
release: v0.9.0 — finalise PR #11 with CHANGELOG, version bump, stub cleanup
Closes the v0.9.0 release loop on top of Phase 9a-Newton + Phase 8b-Lite: * CHANGELOG.md (NEW) — Keep-A-Changelog format, with v0.9.0 entry detailing all Phase 9a / 9b / 8b-Lite contents and the doc-audit corrections that landed via PR #10. * CITATION.cff — version 0.7.0 → 0.9.0, date 2026-05-18 → 2026-05-22. * Stale HDS-port stubs removed (13 GTEST_SKIPs total): - code/tests/test_spherical_functional.cpp - code/tests/test_hyper_ideal_functional.cpp - code/tests/test_hyper_ideal_hyperelliptic_utility.cpp These referenced a "HDS port (Phase 4)" that never happened — CoHDS was intentionally replaced by CGAL::Surface_mesh, and the functional tests live in code/tests/cgal/test_*_functional.cpp. * Test-count updates everywhere: - Non-CGAL 36 → 23 (drop = 13 deleted stubs) - CGAL 176 → 227 - Total 212 → 250 (+38 net, 0 skipped) Files: README.md, CLAUDE.md, CHANGELOG.md, scripts/try_it.sh, doc/api/tests.md, doc/contributing.md, doc/getting-started.md, doc/math/validation.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
