59a26123c87f4c5d12506eef71676af6aee7cd97
85 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
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
|
faf96ee28c |
doc(roadmap): add research item for 2/3-ideal hyper-ideal volume formulas
Follow-up to the Finding-A fix (face_energy guard). The throw is the correct safe behaviour for now; the mathematically complete solution requires formulas for semi-ideal and fully-ideal tetrahedra that are absent from the Java reference. Adds a structured research entry to research-track.md (Phase 9b+): - primary references: Kolpakov-Mednykh arXiv:math/0603097, Milnor 1982, Vinberg 1985 - acceptance criteria: two new volume functions + gradient-check tests + limiting-behaviour continuity witness - explicit note that the throw in face_energy() must not be removed without implementing and testing the replacement formulas 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
|
7f1a077269 |
doc(reviewer): add external audit 2026-05-30
Full external code review of v0.10.0 against all math-critical headers (direct source read, not automated scan). Documents 5 open bugs/API errors, 3 test gaps inherited from java-port-audit.md, 1 architectural CI risk, and 5 minor findings. Each finding is self-contained with file+line references, a concrete fix proposal, and acceptance criteria so a new session can pick up any single finding without prior context. Key findings: - FINDING-A (critical): face_energy() wrong for mixed ideal/hyper-ideal configs - FINDING-B (medium): Gauss–Bonnet API conceptually wrong for HyperIdeal - FINDING-C (medium): cotangent formula in euclidean_hessian.hpp header is wrong - FINDING-D (medium): DOF-assignment doc falsely claims "pin before" works - FINDING-E (medium): cp_euclidean gradient_check uses absolute not relative error - FINDING-F/G/H: three open test gaps from java-port-audit.md - FINDING-I (arch): 246/272 CGAL tests not gated in CI Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
8619043b79 |
docs(crossvalidation): fix stale test count 243→259 after PRs #29-31 merged
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m17s
API Docs / doc-build (pull_request) Successful in 1m1s
Markdown link check / check (pull_request) Successful in 43s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 1m52s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
c472748e46 |
docs(reviewer): refresh §4 to mark Tier-1/3 done (stale TODO removed)
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m1s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 58s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m14s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
082649ef40 |
docs(reviewer): mark Tier-3 done (PR #30); fix duplicated tier table
- Tier-3 (Lawson HyperIdeal) plain + branch-points marked DONE (PR #30, test_lawson_hyperideal.cpp); status, §3 HIGH/MED rows, §3b table and §4 recommended-order updated accordingly. - Hyperelliptic variant documented as deferred (option c): needs an XML-format reader for lawson_curve_source.xml + a port of HyperIdealHyperellipticUtility (jReality geometry θ); golden vector is non-symmetric. - Removed a pre-existing duplicated/stale copy of the tier-table rows. - Added a status summary (Tier 1 ✅ PR #29 · Tier 2 → Phase 9f/13 · Tier 3 ✅ PR #30). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
267ae965ab |
docs(reviewer): Tier-2 exhausted (genus≥2 → Phase 13); Tier-3 Lawson scoped as mini-project
- regular_uniformization.xml / LetterB01_canonical_group.xml are genus≥2 hyperbolic Fuchsian-group uniformizations (12-edge fundamental polygon), not genus-1 → Phase 13, not Tier 2. - Tier-2 is therefore exhausted (only Wente, deferred to Phase 9f quad/cyclic). - Tier-3 Lawson HyperIdeal golden vectors require a low-level halfedge genus-2 multi-edge generator (4 verts/12 edges) + jtem Triangulator replication; scoped as a dedicated follow-up. Co-Authored-By: Claude Opus 4.8 <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> |
||
|
Tarik Moussa
|
41ad4a84d2 |
docs(reviewer): cross-validation analysis of Java @Ignore tests
Classifies the 22 Java @Ignore'd test files by root cause (ARM64 PETSc native lib vs logic/known-issue) and by cross-validation value for the C++ port. - Notes what PR #27 already locks (math cores + functional-eval oracles) to avoid duplication. - Priority ranking: HIGH (HyperIdeal Lawson convergence golden vector — records the exact u*), MEDIUM (genus-1 Wente uniformization, branch-point variant), LATER (genus-2/hyperelliptic/Mobius/quasi-isothermic/Schottky), NON-ORACLE (Java gaps: testHessian, testDoLayout; ARM64-flaky known issues). - Documents why the Lawson mesh needs a low-level half-edge generator (4 vertices / 12 edges => multi-edges; CGAL add_face cannot build it). 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
|
|||
|
Tarik Moussa
|
330515ea90 |
docs(java-parity): P2/Matrix jReality notes + Phase 9c dependency warning
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 2m20s
API Docs / doc-build (pull_request) Successful in 52s
Markdown link check / check (pull_request) Successful in 1m1s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 2m24s
- Infrastructure table: add Matrix (→ Eigen inline, done) and P2 rows. P2 marked "port inline with Phase 9c" — almost exclusively consumed by FundamentalPolygon/CanonicalForm/SurfaceCurve (all Phase 9c), so building p2_geometry.hpp as a standalone ahead of 9c would be dead weight. - Phase 9c rows in the utility table: ⚠️ annotation listing the exact P2.* methods needed (makeDirectIsometryFromFrames, projectP3ToP2, imbedMatrixP2InP3) plus the P2Big/cpp_dec_float_50 high-precision prerequisite for the group-relation product ∏gᵢ = Id. Ensures a future Phase 9c session starts with full context and does not discover the jReality/precision dependencies mid-port. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
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>
|
||
| a993a101e9 |
Merge pull request 'docs: citation audit (8 mis-citations fixed) + Phases 12/13' (#28) from docs/citation-audit-phases-12-13 into main
Some checks failed
C++ Tests / test-fast (push) Successful in 2m15s
API Docs / doc-build (push) Has been skipped
Markdown link check / check (push) Successful in 47s
Mirror to Codeberg / mirror (push) Successful in 27s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / quality-gates (push) Failing after 1m51s
Reviewed-on: #28 |
|||
|
Tarik Moussa
|
26f4f0637d |
docs: citation audit + correct 8 mis-citations; add Phases 12/13
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 1m55s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 50s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 1m56s
External reviewer pass over the literature references. Verified entries against arXiv/DOI/publisher and corrected misattributions that had propagated across the docs. Corrected citations (consistent across all docs): - Bowers-Bowers-Lutz 2026: title was the 2017 paper's -> "Rigidity of Koebe Polyhedra and Inversive Distance Circle Packings" - Liouville theorem: "Springborn 2019" -> Pinkall & Springborn, Geom. Dedicata 214 (2021) - Bobenko-Pinkall-Springborn: "G&T 14 (2010)" -> G&T 19(4) (2015), 2155-2215 - Optimal Cone Singularities: "Crane, Soliman, Ben-Chen, Schroeder" -> Soliman, Slepcev, Crane, ACM TOG 37(4) - Schlaefli formula: "Rivin, Springborn 1999" -> Rivin, Schlenker - Quasiconformal distortion: "Springborn, Veselov" -> Born, Buecking, Springborn (arXiv:1505.01341) - Period matrices: "Bobenko, Buecking 2009" (was Bobenko-Mercat-Schmies' title) -> Bobenko-Mercat-Schmies 2011 + genuine Bobenko-Buecking 2021 - Fabricated entry: "Alexa 2020, DOI 10.1145/3414685.3417840" pointed to an unrelated paper (Pixelor) -> Bunge, Herholz, Kazhdan, Botsch 2020 - Stripe Patterns: "Bonneel et al. 2015" -> Knoeppel, Crane, Pinkall, Schroeder 2015 Equation-number corrections (verified against the PDFs): - Glickenstein 2011 "eq. 4.6" -> "§5.2" (no such equation label exists) - Springborn 2020 "eq. 4.6" -> "§4 variational gradient" - inversive-distance attribution softened to classical inversive distance Other: - DBFEnergy bibliography (separate repo) and convergence half-sentence in novelty-statement.md §3.3 (Bobenko-Buecking 2021) - Status legend (implemented vs planned) at top of references.md - New Phase 12 (decorated DCE & geometric transition, Chain A, near-term) and Phase 13 (canonical tessellations & polyhedral realisation, Chain B capstone) in phases.md + research-track.md; 10c scope-boundary note clarifying infrastructure vs Lutz-specific algorithms 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
|
ca936b7652 |
docs: note high-precision requirement for Phase 9c/10 uniformization
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m0s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 54s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m14s
The Java uniformization classes (FundamentalPolygonUtility, CanonicalFormUtility) rely on the *Big arbitrary-precision geometry (MathContext(50)) because products of hyperbolic isometry generators grow exponentially and double fails to verify the group relation ∏gᵢ = Id. Record this planning-relevant prerequisite and resolve the contradiction in java-parity.md, which previously listed *Big as permanently out of scope. - CLAUDE.md: † note on the Phase-9 not-yet-ported table - java-parity.md: *Big exception (localized high-precision substrate for 9c/10) - phases.md: precision prerequisite as 9c sub-task + effort estimate - design-decisions.md: new "Scalar type: double, with one localized exception" Core flattening (Newton/energy/Eigen solver) stays double; the substrate (cpp_dec_float_50 / mpreal) is localized to the uniformization module only. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
1ff5382c8b |
docs: record 2026-05-28 full-library scan findings in roadmap
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 1m55s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 1m1s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m3s
Cross-referenced all 232 Java classes against the roadmap. New plan entries for genuinely-useful, previously-unplanned items: - 9g.1 conformal quality measures (Isothermicity, ConformalEquivalence, FlippedTriangles, LengthCrossRatio + ConvergenceUtility metrics) - 9g.2 optional period-matrix convergence experiment (method only; Java harness depends on Mathematica/JLink + jReality, not ported) - DEC operator layer (heds/dec/) noted as a 10a prerequisite - HomotopyUtility -> 10a (explicit generator cycles; not covered by cut_graph.hpp, which yields only the 2g cut edges) - SurfaceCurveUtility -> 9c; MercatorTextureProjection -> 9d.3 companion Documented as deliberately out-of-scope: SpanningTreeUtility (subsumed by cut_graph.hpp), convergence/* harness, datasource/* (jReality viewer decoration), *Big arbitrary-precision geometry, jReality GUI, and the MTJ/Tao/PETSc solver bindings. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
569a03dc08 |
docs+tooling: doc-freshness gate, documentation-pass policy, token-hygiene
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 2m2s
API Docs / doc-build (pull_request) Successful in 1m8s
Markdown link check / check (pull_request) Successful in 52s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 1m59s
Refresh CLAUDE.md for v0.10.0 (3 CI jobs incl. disabled test-cgal,
compile-time option matrix, reviewer/pages docs, agentic + token-hygiene
workflow patterns) and condense the historical Phase-8/audit logs to
pointers.
Add the documentation-pass process so the single-source-of-truth rules
stay enforced:
* scripts/quality/check-doc-freshness.sh — string-only drift gate
(version/date across CITATION/CHANGELOG/CLAUDE, doc-map count), <1 s,
registered in run-all.sh + quality README.
* doc/release-policy.md — "Documentation passes" subsection (triggers +
docs:sync rule); fix stale Phase-milestone mapping (v0.10.0 was
reviewer-ready, 9c→v0.11.0) and the test-cgal CI mention.
Add shared Claude config (un-ignore the two files only):
* .claude/settings.json — permission allowlist for safe repo commands.
* .claude/token-hygiene.md — Tier-3 cache-discipline user guide that
CLAUDE.md instructs Claude to remind the user about.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
11d660af49 |
fix(hub): correct double-branch/branch/main URL prefix + v0.10.0 badge
Two bugs in the reviewer hub HTML: 1. The earlier sed-rewrite that lifted the hub from `preview/reviewer-snapshot-v6` into `branch/main` accidentally produced `branch/branch/main` — sed pattern matched the `preview/reviewer-snapshot-v6` slug but the surrounding URL already had `/src/branch/` prefix. All 25 in-hub links to the repo were broken with 404 on codeberg.org. Fix: `s|/src/branch/branch/main/|/src/branch/main/|g`. 2. The version pill in the badge strip still read v0.9.0 (stale from the original v0.9.0-era hub template). Updated to v0.10.0. The fix is in this in-repo source-of-truth file so any future manual republication of the pages branch picks up the corrected hub. The just-pushed pages branch already has the fix applied; codeberg's `tmoussa.codeberg.page` frontend cache (max-age=600 s) will refresh over the next 10 minutes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
09a68a4569 |
release: v0.10.0 — reviewer-ready release
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m16s
API Docs / doc-build (pull_request) Successful in 49s
Markdown link check / check (pull_request) Successful in 51s
C++ Tests / test-cgal (pull_request) Failing after 7m34s
C++ Tests / quality-gates (pull_request) Successful in 2m20s
Post-merge consistency commit:
* CITATION.cff version 0.9.0 → 0.10.0, date 2026-05-26
* CHANGELOG.md — new "[0.10.0]" section listing all 13 commits
that landed across PRs #17 / #18 / #19
* Post-merge gate fixes:
- doxygen_groups.h + doxygen_namespaces.h gain \\file briefs
- .codespellrc extended (honour, thead, optimiser)
- compile-time.md: unbalanced backtick on line 102 fixed
(was confusing Doxygen's verbatim-block detector)
Final gate state on the merged main:
✅ 259/259 tests pass
✅ test-count consistency
✅ markdown links 166/166 resolve (43 .md files)
✅ CGAL conventions 0/8 violations
✅ license-headers 68/68 carry MIT SPDX
✅ codespell 0 typos
✅ shellcheck 0 findings (18 scripts)
✅ Doxygen 396/396 symbols, 0 warnings
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
|
3f508adf18 |
ci+hub: durable reviewer hub via in-repo HTML + perf-CI matrix on Linux
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m16s
API Docs / doc-build (pull_request) Successful in 51s
Markdown link check / check (pull_request) Successful in 45s
C++ Tests / test-cgal (pull_request) Failing after 7m40s
C++ Tests / quality-gates (pull_request) Failing after 2m1s
Two additions that close out the reviewer-prep work cleanly:
1. doc/reviewer/hub.html + publish-workflow integration
──────────────────────────────────────────────────────
Move the hand-curated reviewer hub from the codeberg `pages`
branch (where it lived as an opaque snapshot) into the repo as
`doc/reviewer/hub.html`. `.gitea/workflows/doxygen-pages.yml`
gains a conditional `if [ -f doc/reviewer/hub.html ]; then …`
step that installs it as the publish `index.html` and demotes
the auto-generated Doxygen index to `/doxygen.html`.
Effect: merging any of the open PRs into main will trigger the
workflow, which republishes BOTH the Doxygen + the reviewer hub
together. The reviewer URL stays live across merges with zero
manual intervention.
Source-controlled benefits:
* hub edits go through normal PRs, not orphan-branch
force-pushes
* old hub versions live in git history
* the in-repo links now target `branch/main/…` instead of the
transient `preview/reviewer-snapshot-vN/…` paths
2. .gitea/workflows/perf-compile-time.yml — Linux CI bench
────────────────────────────────────────────────────────
New workflow runs on every push to main that touches the build
system or public headers. Five-step matrix measures and reports:
Run 1 cold baseline (no PCH, no Unity, no ccache)
Run 2 + PCH only
Run 3 + PCH + Unity (current default)
Run 4 + FAST_TEST_BUILD=ON (-O0 -g — Linux's expected ~40 % win)
Run 5 + ccache warm rerun (expected ≥ 90 % cache hit)
Validates the Apple-M1 predictions in doc/architecture/compile-time.md
against the Linux + g++ runner where Backend dominates more and
the Apple-clang+PCH friction that defeats ccache locally does not
apply. Job is data-collection only; never blocks a merge.
doc updates:
* doc/architecture/compile-time.md — new "Cross-platform perf bench"
section linking to the workflow + the table of macOS-vs-Linux
expected deltas.
* doc/reviewer/README.md — new "Hub-Page durability" subsection
explaining how the hub survives merges.
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
|
0c520046fb |
docs(reviewer): baustein D — close Java-scan + lit-integration gaps
Earlier baustein B (`07c653c`) added a 6-row Research-Alignments table + a "what's new" banner, but only surfaced ~75 % of what the four Java-scan + literature-integration commits (`f854f0e`, `979f30c`, `e8a118f`, `8daee1b`) had introduced. This commit closes the gaps identified in the lückenprüfung: Research-Alignments table grows from 6 → 10 rows ───────────────────────────────────────────────── * +quasi-isothermic maps (Phase 10e, Java port — 6 classes incl. discrete Beltrami-field solver, Lawson correspondence ~800 lines) * +higher-genus + hyperelliptic surfaces (Phase 10b — `HyperellipticUtility` + Bobenko–Bücking 2009) * +Möbius centring as variational problem (Phase 9d.4 — replaces the iterative Fréchet-mean fallback in `normalise_hyperbolic()`) * +Boundary-First / interactive flattening row (Crane 2017 BFF; Stripe Patterns 2015) — listed for comparison even though it is not on the porting roadmap, so the reader sees we know about it * table caption clarifies that some rows are RESEARCH-only (no Java parent) and some are planned ports "What's new" banner ─────────────────── * citation count corrected from "+9" to "+13" — the four Tier-2 papers added in commit `e8a118f` (Springborn 2019, Springborn–Veselov 2015, Crane 2017 BFF, Bonneel et al. 2015 Stripe Patterns) are now named * phase count of "+6 phases" kept, but +Phase 9d.4 (Möbius centring) and +Phase 10e (quasi-isothermic) are now called out explicitly so the reader knows what is in the count * cross-link to `java-parity.md` for the reverse table (every Java class → C++ destination or *do-not-port* rationale) questions.md / Q1 ───────────────── * expand the table from 3 to 6 candidate phases — adding 10e (quasi- isothermic), 10b (hyperelliptic), and 9d.4 (Möbius centring) as options alongside the existing 9d.2 / 9f / 10c+10c′ * track column distinguishes RESEARCH-only from planned-port * +Question C — "is there a seventh line we are missing?" — invites the reader to flag a research thread we have not scoped yet Pages hub will be refreshed to v5 in a follow-up step (separate from the in-repo commit, lives only on the codeberg `pages` branch). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
9be11eca4e |
docs(reviewer): refresh hub link list — add roadmap, research-track, references
Updates the "Quick links the reviewer should bookmark" section of
doc/reviewer/README.md so it matches the Pages-hub v4 layout:
* the hub itself now carries status badges, a "what's new" banner,
and the research-alignment table — call this out so the reader
knows what to expect when they click through;
* adds direct links to the three documents that the new Q1/Q2/Q3
questions actually depend on (references.md, phases.md,
research-track.md) — previously only the Schläfli-derivation note
and the locked-vs-flexible architecture page were linked;
* re-points the Schläfli derivation link from "Q2" (old numbering)
to "Q3" (new numbering after baustein B inserted research
questions at Q1/Q2).
Companion change to the Pages-hub v4 already pushed to the codeberg
`pages` branch; this commit keeps the in-repo guidance in sync.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
36596c7c79 |
docs(reviewer): research alignments + 2 new Q1/Q2 + reordered agenda
Adds the two research-track questions to the front of the queue, where
they belong for a reader whose publication line maps directly onto our
research-track roadmap entries.
briefing.md gains two new sections:
* Research alignments — a 6-row table mapping the reader's research
threads (decorated DCE, canonical tessellations, hyperideal
rigidity, optimal cone placement, polygon Laplacian, Schläfli
machinery) onto concrete phases of the roadmap, with the closest
published line cited generically (year + venue only).
* What's new on this snapshot — the 6 new porting phases + 9 new
citations + Phase 9f (RESEARCH, no Java parent) + output_uv_map
extension to Inversive-Distance.
questions.md restructures the question set from 5 to 7:
* Q1 (NEW) — research-track alignment: which of 9d.2 / 9f / 10c /
10c′ would unblock concrete experiments?
* Q2 (NEW) — decorated-DCE API surface: A/B/C named parameter vs
new solver vs property-map auto-detect?
* Q3 — Phase 9b-analytic (was Q2)
* Q4 — Phase 9c port-literal vs re-derive (was Q1)
* Q5 — GC-1 cross-validation co-authorship (was Q5)
* Q6 — CGAL submission packaging (was Q4)
* Q7 — The "no" question (was the trailing section)
Also drops Q3 from the previous list (CP-Euclidean output_uv_map),
since that question is now answered (Phase 9c, runtime error today,
on the deferred list — no reviewer input needed).
Adds a final "After the meeting — would you collaborate?" block so
the post-meeting collaboration options (acknowledgement / co-author /
cadence / PRs) do not surprise the reader on the day.
agenda.md reorders §2 to match the new question order; the timing
shifts Q1/Q2/Q3 (research) to the front and Q4/Q6 (project
management) to the back. Memo template at the bottom now has 7
named answer slots instead of 5 numbered ones.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
72503a3518 |
docs(reviewer): anonymise reviewer references; profile-based framing
Replaces the "Springborn / Bobenko alumnus" placeholder in the reviewer materials (briefing, questions, agenda, README) and in locked-vs-flexible.md with a research-profile description: active researcher in the decorated-DCE / Penner-coordinates / canonical-tessellations / hyperideal-polyhedra line, treated as a peer most likely to USE conformallab++ as numerical infrastructure for their own future experiments — not merely to evaluate it. Citations to the published literature (Springborn 2020 paper, etc.) remain untouched. Only personal references to the prospective reviewer were anonymised. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
f93292e815 |
docs: fix cherry-pick duplicate 9d/9e sections — merge into unified structure
Auto-merge from cherry-pick concatenated both branch versions of Phase 9d
and 9e. This commit resolves the duplication:
- 9d now has 4 sub-items (9d.1–9d.4) combining both branches:
9d.1 ConesUtility (detailed: BFS, auto-placement, quantization)
+ Troyanov/Springborn refs (from literature analysis)
9d.2 Non-Euclidean cone extensions (RESEARCH)
+ Bobenko-Lutz 2025 + Crane 2018 (from literature analysis)
9d.3 StereographicUnwrapper + SphereUtility
9d.4 MobiusCenteringFunctional
- 9e keeps the detailed reviewer/meeting-prep version
+ adds mathematical references (Bobenko-Hoffmann-Springborn 2006)
- 9f (Polygon Laplacian, Alexa 2011/2020) retained as standalone section
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
ab07f90653 |
docs: add 4 remaining Tier-2 papers (Springborn 2019, Springborn-Veselov 2015, Crane 2017 BFF, Stripe Patterns 2015)
phases.md: - 10b: Springborn 2019 discrete Liouville theorem (uniqueness of Ω) - 10c: Springborn-Veselov 2015 quasiconformal distortion (error bounds) - 10a: Knöppel-Crane-Pinkall-Schröder 2015 Stripe Patterns (cross-validation ref) references.md (Phase 10 section, 4 new rows): - Springborn 2019 arXiv:1911.00966 → Phase 10b uniqueness - Springborn-Veselov 2015 Int. Math. Res. Not. → Phase 10c error analysis - Knöppel-Crane-Pinkall-Schröder 2015 SIGGRAPH → Phase 10a cross-validation - Sawhney-Crane 2017 BFF ACM TOG → complementary method to Phase 9d Completes the literature integration started in the previous commit: all Tier-2 papers from the Alexa/Bobenko/Springborn/Crane/Lutz analysis are now documented in the roadmap. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
068df474b1 |
docs: integrate publication analysis — Alexa, Bobenko, Springborn, Crane, Lutz
Add phases 9d / 9e / 9f and literature citations derived from a systematic
review of the five authors' publication lists (Tier 1 / 2 / 3 analysis).
phases.md:
- Phase 9d: ConesUtility port (9d.1) + non-Euclidean cone extensions
(9d.2, RESEARCH) + StereographicUnwrapper (9d.3)
- Phase 9e: CirclePatternLayout + CirclePatternUtility (Java port)
- Phase 9f: Polygon Laplacian on non-triangular meshes (Alexa 2011/2020,
RESEARCH — no Java equivalent)
- Phase 9b-analytic: add Rivin-Springborn 1999 as Schläfli source
- Phase 10b: add Bobenko-Bücking 2009 + Bobenko-Lutz 2024 IMRN
- Phase 10c: add Lutz 2023 (canonical tessellations) + Bobenko-Lutz 2024
- Phase 10c' KoebePolyhedron: add Bowers-Bowers-Lutz 2026 rigidity result
references.md:
- Crane et al. 2018 Optimal Cone Singularities (Phase 9d.2)
- Bobenko-Lutz 2025 Discrete & Comput. Geom. (Phase 9d.2)
- Bobenko-Lutz 2024 IMRN (Phase 10b/c)
- Lutz 2023 Geom. Dedicata (Phase 10c)
- Lutz PhD thesis TU Berlin 2024 (Phases 9d.2, 10b, 10c)
- Bowers-Bowers-Lutz 2026 (Phase 9b-analytic + 10c')
- Alexa-Wardetzky 2011 + Alexa 2020 (Phase 9f)
- Bobenko-Bücking 2009 (Phase 10b)
- Rivin-Springborn 1999 (Phase 9b-analytic)
research-track.md:
- New entry: Phase 9d.2 non-Euclidean cone extensions (Bobenko-Lutz 2025
+ Crane 2018), with acceptance criteria
- New entry: Phase 9f polygon Laplacian (Alexa-Wardetzky 2011 / Alexa 2020),
with acceptance criteria
java-parity.md:
- Split cone-metrics row into Euclidean (9d.1 port) and non-Euclidean
(9d.2 research) with literature references
- Add ConesUtility to "utility classes not yet ported" table
Co-Authored-By: Claude Sonnet 4.6 <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>
|
||
| 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
|
8e9ec9eccf |
docs: full Java library scan — new phases 9d/9e/10d–10g + parity table
Complete scan of all de.varylab.discreteconformal packages (functional/, unwrapper/, unwrapper/circlepattern/, unwrapper/koebe/, unwrapper/quasiisothermic/, uniformization/, util/) against the current roadmap. New items added to java-parity.md: - ConesUtility: cone detection, BFS cut, auto-placement, quantization (9d) - MobiusCenteringFunctional: variational Lösung über Lorentz-Geometrie (9d) - ElectrostaticSphereFunctional: Initialisierungsheuristik auf S² (9d) - StereographicUnwrapper + SphereUtility: S²→ℂ atlas für genus-0 (9d) - CirclePatternLayout + CirclePatternUtility + CPEuclideanRotation (9e) - CutAndGlueUtility, StitchingUtility, PathUtility (9c additions) - DualityUtility: Hodge-Stern + dual cycles — prerequisite 10a - HyperellipticUtility + HyperIdealHyperellipticUtility (10b) - CircleDomainUnwrapper: Koebe-Andreev-Thurston (10d) - quasiisothermic/ package: QI maps + DBF + sin-condition (10e) - KoebePolyhedron (10f) - EuclideanCyclicFunctional + HyperbolicCyclicFunctional (10g) - "Do not port" table: ColtIterationReporter, PETSc wrappers, etc. New phases added to phases.md: - Phase 9d: ConesUtility + StereographicUnwrapper + MobiusCenteringFunctional - Phase 9e: CirclePatternLayout (complement to already-ported 9a.1) - Phase 10d: CircleDomainUnwrapper (Koebe-Andreev-Thurston) - Phase 10e: quasi-isothermic maps - Phase 10f: Koebe polyhedra - Phase 10g: cyclic-symmetry functionals Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
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
|
f1d77aa293 |
quality: add code-style + CGAL-convention checkers (local-only)
Closes the gap "no code-quality / convention gate" from the structural
review. Three new artefacts, all local-only (CI promotion deferred
until the existing tree is 100 % clean under each):
1. .clang-format — project's existing style mechanically captured
(4-space indent, opening brace on new line for class/struct/function,
left-aligned pointer/reference modifiers, aligned `using = ...` blocks,
100-col loose limit, no include re-ordering — matches code/include/
today).
2. scripts/quality/clang-format.sh — drift detector. Dry-run mode by
default (always exits 0); --strict to fail on drift; --fix to apply
suggested changes in place. Skips code/deps/ and macOS-duplicate
files.
3. scripts/quality/cgal-conventions.py — checker for the CGAL idioms
that clang-format/clang-tidy cannot express:
CGAL-1 include-guard format `CGAL_<DIRS>_<FILE>_H`
CGAL-2 every public header has a `\\file` Doxygen brief
CGAL-3 no nested namespaces beyond the allowed set
(CGAL::parameters, CGAL::Conformal_map, internal_np, IO)
CGAL-4 named-parameter tag types end in `_t`; value object does not
CGAL-5 no `using namespace ...` at file scope (header leakage)
CGAL-6 no #define beyond CGAL_* / include-guard
Result on the current tree: 6 CGAL public headers, 0 violations.
The checker therefore doubles as documentation of the conventions
we already follow.
Both are wired into scripts/quality/run-all.sh's fast subset (~5 s
combined wall time). README.md updated to split the gates into a
"style/convention" group (cheap, run-on-every-commit material) and a
"correctness/quality" group (slow, run-before-tag material).
The reviewer-facing locked-vs-flexible.md gains another "✅ Closed"
row documenting both gates and the 0-violation baseline.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
a2eee9c279 |
ci+quality: structural gates (CI: 3 new; local: 7 new + .clang-tidy)
CI gates (active on every PR via .gitea/workflows/)
───────────────────────────────────────────────────
1. test-count consistency
cpp-tests.yml gains a step after test-cgal that runs
`scripts/check-test-counts.sh` against the just-built ./build dir
(reuse via new BUILD_DIR env var, ~5 s overhead). Drift between
`doc/api/tests.md` and ctest reality now fails the PR.
2. End-to-end smoke
`scripts/try_it.sh` (the documented user quick-start) is now part of
the CGAL job, so README quick-start regressions fail the PR rather
than silently breaking when users land.
3. Internal markdown link checker
New `.gitea/workflows/markdown-links.yml` + `scripts/check-markdown
-links.py`. PRs that touch any *.md file run the check; main pushes
trigger it too; a weekly cron catches external link rot. Pure
Python, no third-party action. Validated against the current tree:
122 internal links across 37 *.md files, 0 broken.
Local quality scripts (`scripts/quality/`, not in CI)
─────────────────────────────────────────────────────
* `license-headers.sh` — `SPDX-License-Identifier: MIT` audit over
code/{include,src,tests}/. Currently
reports 60/66 files missing it — that's
a follow-up; the script captures the
structural gap.
* `sanitizers.sh` — ASan + UBSan over the fast test suite.
* `coverage.sh` — gcov/lcov line + branch coverage of
code/include/, HTML report under
build-coverage/lcov-html/.
* `clang-tidy.sh` — runs the curated `.clang-tidy` policy over
every public header.
* `multi-compiler.sh` — sequential build + test against every
detected g++/clang++ (auto-discovery or
explicit list).
* `cgal-version-matrix.sh`— sequential build + CGAL test suite against
every CGAL tree under `~/cgal/<ver>/` (or
via `CGAL_ROOTS=...` env var).
* `reproducible-build.sh`— two `Release -j1` builds, fail if any test
executable byte-differs.
* `run-all.sh` — driver: `--fast` for the ~5-min subset,
no arg for the ~25–40 min full sweep;
captures per-gate logs to
build-quality-logs/.
+ `.clang-tidy` — curated, deliberately-small policy (only
checks that fire on OUR code, never on
transitive CGAL/Eigen/Boost headers).
+ `scripts/quality/README.md` — explains the structure, lists each
gate's wall-time + prereqs, and codifies
the promotion path: a gate moves into CI
only when it's green on the dev machine
AND has a recovery-instructions paragraph
in `doc/release-policy.md`.
Doc updates
───────────
`doc/architecture/locked-vs-flexible.md` (reviewer-facing) gains 4
"closed" rows in the limitations table — the 3 CI gates above and the
local quality-script suite.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
f6722d7e84 |
docs: auto-generate doc/api/headers.md from Doxygen XML
Replaces the hand-maintained `doc/api/headers.md` with a generated one
sourced from each header's `\file` brief and the public symbols
extracted by Doxygen into XML. The CI workflow regenerates it on every
push to main that touches the public headers.
New files
─────────
* scripts/gen-headers-md.py — parses doc/doxygen/xml/*.xml, groups
headers by directory (CGAL public / CGAL internals / Core), and
writes a markdown table with header path, first-sentence brief, and
the public symbols declared at file scope. Skips `detail::`
namespaces and template-specialisation duplicates.
* scripts/regen-docs.sh — convenience wrapper:
doxygen → gen-headers-md.py → coverage report.
Workflow changes
────────────────
.gitea/workflows/doxygen-pages.yml now:
1. Runs `bash scripts/doxygen-coverage.sh` as an informational step
(no fail threshold yet — the script supports `--threshold N` for
when we're ready).
2. Re-runs `python3 scripts/gen-headers-md.py` and warns if the
file drifted from what's in main (operator should run
`regen-docs.sh` locally before pushing).
Doxyfile hygiene
────────────────
`HTML_TIMESTAMP` was removed in Doxygen 1.10 → replaced with the new
`TIMESTAMP = NO` to silence the obsolete-tag warning.
Effect on the reviewer-facing landing pages
───────────────────────────────────────────
Every improvement to a `\file` brief at the top of a public header now
flows automatically into both:
* the Doxygen HTML at https://tmoussa.codeberg.page/ConformalLabpp/
* the markdown landing at doc/api/headers.md (rendered by Codeberg
in the repo view)
…so writers have a single source of truth (the C++ source) and
readers see the same words in both surfaces.
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>
|
