65 Commits

Author	SHA1	Message	Date
Tarik Moussa	d3fc4ae056	fix(s3-followup): enforce V5 rule 4 + mark H3/H4/H5/V5/V6 done ... serialization.hpp: `found_dofvector` was set but never checked after the parse loop, leaving rule 4 of the strict-subset (§doc line 285) unenforced. Add the missing post-loop throw so a ConformalResult XML that omits the <DOFVector> element is rejected with a clear error instead of silently returning an empty x. Update the docstring to remove the misleading "silently returns" note. finding-orchestration.md: mark H3/H4/H5/V5/V6 ✅ and record the S3 session as complete. Implementation landed in commit 135bcf0 (P1 merge bd613a6); PR #45 code commits were redundant — the only net-new change in this follow-up is the V5 enforcement fix + tracker update. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-01 16:32:41 +02:00
Tarik Moussa	135bcf0bba	feat(p1): CLI extensions + quality measures + stereographic layout ... Implement Phase-Session P1 quick wins (4 independent additions): 9h.1: Add --tol and --max-iter CLI options to conformallab_core - Newton solver tolerance [default 1e-8] - Newton iteration limit [default 200] - Thread both through run_euclidean / run_spherical / run_hyper_ideal - Update CLI parameter table in documentation 9h.2: Add -g cp_euclidean and -g inversive_distance geometry routes - run_cp_euclidean() & run_inversive_distance() pipelines (~60 lines each) - Face-based DOF assignment for CP-Euclidean - Vertex-based DOF assignment for Inversive-Distance - Both integrated into CLI geometry validator (IsMember) 9g.1: Create conformal_quality.hpp with validation measures - IsothermicityMeasure: metric anisotropy (conformality deviation) - DiscreteConformalEquivalenceMeasure: length-cross-ratio residuals - FlippedTriangles: detects inverted/degenerate triangles - LengthCrossRatio: discrete conformal invariant computation - ConvergenceUtility: aggregated convergence statistics (max/mean/sum) - Ported from Java: plugin/visualizer + convergence utilities - Includes sanity tests validating finite outputs on valid layouts 9d.3: Create stereographic_layout.hpp for S² → ℂ projection - Stereographic projection from north pole: S² → ℂ ∪ {∞} - Inverse projection: ℂ → S² for round-trip validation - Möbius centring: centres the 2-D point cloud at origin - stereographic_layout(Layout3D) -> Layout2D conversion - Round-trip tests: south pole, equator, random sphere points - Tests: projection/inverse consistency, north pole handling Test results: 336/336 CGAL tests pass (272 pre-existing + 64 new from all phases) - conformal_quality.cpp: 13 new tests (measures, isothermic, dce, convergence) - stereographic_layout.cpp: 10 new tests (projection, inverse, round-trip, layout) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>	2026-06-01 08:58:46 +02:00
Tarik Moussa	56f13d7c4f	feat(cgal): propagate Newton status + conditioning diagnostics into CGAL results ... Follow-up to S2: surface the new NewtonResult diagnostics through the public CGAL result types so callers of the high-level API see them too. - Add `CGAL::Newton_status` (alias of conformallab::NewtonStatus) and three fields — `status`, `sparse_qr_fallback_used`, `min_ldlt_pivot` — to Conformal_map_result, Hyper_ideal_map_result and Circle_packing_result. (sparse_qr_fallback_used already existed on Conformal_map_result but was never populated; it is now wired through.) - Map them from NewtonResult at all five entry points (euclidean / spherical / hyper_ideal / inversive_distance / cp_euclidean). - Test: SingleTriangleConverges now asserts status == Converged and the diagnostics propagate. Additive only — existing `converged`/`iterations`/`gradient_norm` semantics unchanged. 301/301 CGAL tests pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-05-31 19:44:50 +02:00
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>	2026-05-31 19:44:50 +02:00
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>	2026-05-31 19:44:50 +02:00
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>	2026-05-31 19:44:50 +02:00
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>	2026-05-31 19:44:50 +02:00
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>	2026-05-31 19:44:50 +02:00
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>	2026-05-31 19:44:39 +02:00
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>	2026-05-31 19:44:39 +02:00
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>	2026-05-31 19:44:39 +02:00
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>	2026-05-31 19:44:39 +02:00
user2595	505dd4b0a5	Merge pull request 'refactor(api): consistent naming for spherical + hyper-ideal helpers (A1–A3)' (#36) from refactor/api-naming-a1-a3 into main	2026-05-31 17:43:42 +00:00
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>	2026-05-31 10:37:06 +02:00
Tarik Moussa	37b538aae4	docs: Layout2D index semantics, CLI table, CLI roadmap (U9+U10+U11) ... 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>	2026-05-31 01:51:04 +02:00
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>	2026-05-31 01:46:08 +02:00
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>	2026-05-31 01:17:27 +02:00
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>	2026-05-31 01:17:27 +02:00
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>	2026-05-31 01:17:27 +02:00
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>	2026-05-31 01:17:27 +02:00
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>	2026-05-31 01:17:27 +02:00
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>	2026-05-31 01:17:27 +02:00
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>	2026-05-30 17:32:02 +02:00
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>	2026-05-30 17:32:02 +02:00
user2595	adfcb7b931	Merge pull request 'feat(geometry): pn_geometry.hpp — Pn projective-metric substrate (jReality port)' (#31) from feat/pn-geometry-substrate into main	2026-05-30 15:26:23 +00:00
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>	2026-05-30 17:20:35 +02:00
Tarik Moussa	ba83974525	test: Java golden-value oracles for the five DCE math cores + P1-2/P1-3 fixes ... 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>	2026-05-29 19:08:37 +02:00
Tarik Moussa	a3ee9576d4	fix+test: Euclidean holonomy/τ end-to-end + spherical edge-DOF oracle (2026-05-29 audit) ... 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>	2026-05-29 12:50:16 +02:00
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>	2026-05-26 11:19:55 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
user2595	704f42bbfd	Merge pull request 'ci+quality: structural gates (CI: 3 new; local: 7 new + .clang-tidy)' (#18) from ci/structural-tests into main	2026-05-26 09:14:45 +00:00
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>	2026-05-24 09:15:34 +02:00
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>	2026-05-24 04:22:49 +02:00
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>	2026-05-23 23:44:54 +02:00
Tarik Moussa	039cc26e36	Phase 8b-Lite: pipe-operator chaining for named parameters ... 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>	2026-05-22 13:43:52 +02:00
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>	2026-05-22 13:24:37 +02:00
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>	2026-05-22 13:24:37 +02:00
Tarik Moussa	7d10500811	Phase 8b-Lite: CGAL entries for all 5 DCE models + layout wrapper ... Completes the CGAL public API surface so all five discrete-conformal functionals are reachable from <CGAL/Discrete_*.h>, not only Euclidean. CGAL test count: 219 → 227 (+8). Zero skips. New public headers ────────────────── * CGAL/Discrete_conformal_map.h extended Adds discrete_conformal_map_spherical() and discrete_conformal_map_hyper_ideal() plus the Hyper_ideal_map_result<FT> struct that carries both vertex DOFs (b_v) and edge DOFs (a_e). * CGAL/Discrete_circle_packing.h new (180 lines) Face-based BPS-2010 circle packing. Provides Default_cp_euclidean_traits<Mesh, K> Circle_packing_result<FT> discrete_circle_packing_euclidean() * CGAL/Discrete_inversive_distance.h new (180 lines) Vertex-based Luo-2004 packing. Provides Default_inversive_distance_traits<Mesh, K> discrete_inversive_distance_map() reusing the existing Conformal_map_result<FT> for the u-vector. * CGAL/Conformal_layout.h new (110 lines) Thin re-export of euclidean_layout / spherical_layout / hyper_ideal_layout into the CGAL:: namespace. Architecture choice ─────────────────── Per Phase 8b architecture audit: Strategy C (functional-specific default traits, one entry per functional, no fat shared trait). Documented in each header's docblock. This avoids speculative design of a unified trait that would need to fit all 5 DOF layouts (vertex, vertex+edge, face). Conformal_map_traits.h is kept as the Euclidean-specific trait it already is; new functionals have their own Default_*_traits classes right next to their entry functions. Test count after this merge ─────────────────────────── CGAL suite: 219 → 227 (8 new in test_cgal_phase8b_lite.cpp covering all four new entries + the Euclidean+layout round-trip). After-the-merge user contract ───────────────────────────── A user can now write any of these and get a valid Newton-converged result: #include <CGAL/Discrete_conformal_map.h> auto r = CGAL::discrete_conformal_map_euclidean(mesh); auto r = CGAL::discrete_conformal_map_spherical(mesh); auto r = CGAL::discrete_conformal_map_hyper_ideal(mesh); #include <CGAL/Discrete_circle_packing.h> auto r = CGAL::discrete_circle_packing_euclidean(mesh); #include <CGAL/Discrete_inversive_distance.h> auto r = CGAL::discrete_inversive_distance_map(mesh); #include <CGAL/Conformal_layout.h> auto layout = CGAL::euclidean_layout(mesh, r.x, maps); Not in this PR (intentionally deferred) ─────────────────────────────────────── * 8a.2 — Generic FaceGraph specialisation (still Surface_mesh-only). * 8c — User_manual + PackageDescription.txt (CGAL-submission prep). * 8d — CGAL-format test directory (CGAL-submission prep). * 8e — YAML pipeline + CLI flag (orthogonal). * Named-parameter chaining (`a.b().c()`) — current parameter helpers return Named_function_parameters without member-function chainers; pass parameters one at a time for now. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-21 21:24:26 +02:00
Tarik Moussa	dd87b8007b	Phase 9a-Newton: newton_cp_euclidean + newton_inversive_distance ... Wires the two Phase-9a functionals into the Newton-solver layer so they are operational end-to-end. CGAL test count: 212 → 219 (+7). Solvers ─────── * newton_cp_euclidean(mesh, x0, m, tol, max_iter) - Uses cp_euclidean_hessian — analytic 2×2-per-edge BPS-2010 formula h_jk = sin θ / (cosh Δρ − cos θ). - SparseQR fallback handles the gauge-singular case when no face is pinned (caller error, but we recover gracefully). - Strictly-convex energy ⇒ quadratic convergence near optimum. * newton_inversive_distance(mesh, x0, m, tol, max_iter, hess_eps) - Uses an inline FD Hessian (n × gradient evaluations per step) — mirrors the Phase 4a HyperIdeal solver in spirit. - Analytic alternative via Glickenstein 2011 eq. (4.6) is tracked in doc/roadmap/research-track.md as Phase 9a.2-analytic. - Sensitive to initial point; the test suite always starts from a natural-theta setup (u = 0 is the equilibrium when compute_inversive_distance_init_from_mesh was called). Tests (test_newton_phase9a.cpp, 7 cases) ──────────────────────────────────────── * CPEuclidean_NaturalPhi_ClosedTetrahedron_ConvergesInZeroIterations * CPEuclidean_PerturbedStart_ConvergesBackToEquilibrium * CPEuclidean_OpenTetrahedron_NaturalPhi_Converges * InversiveDistance_NaturalTheta_Triangle_ConvergesInZero * InversiveDistance_PerturbedQuadStrip_Converges * InversiveDistance_PerturbedTetrahedron_Converges * CPEuclidean_UsesAnalyticHessian Regression guard: 3-DOF problem converges in ≤ 10 iterations even with strong perturbation, confirming the analytic Hessian path is actually used. All seven tests pass. Full CGAL suite: 219/219 PASSED, 0 SKIPPED. Roadmap additions (`doc/roadmap/phases.md`) ─────────────────────────────────────────── New Phase 11+ section flags two Java sub-packages as optional/deferred ports, recorded for project memory but not roadmap commitments: * 11a — Schottky uniformisation (Java plugin/schottky/*, ~3000 LoC) Hyperbolic loxodromic group acting on S²; complement of the Phase 10c Fuchsian-group representation in H². Requires Phase 10b period matrix + Möbius-group machinery from Phase 7. Effort: very large (4-6 weeks). * 11b — Riemann maps (Java plugin/riemannmap/*, ~1500 LoC) Discrete Riemann mapping theorem; texture mapping of bounded planar regions, classical conformal mapping for engineering. Requires Phase 10b' quasi-isothermic or Phase 9a.1 CP-Euclidean. Effort: large (3-4 weeks). Both are explicitly NOT roadmap commitments — they live in the doc so they aren't re-discovered. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-21 21:10:00 +02:00
Tarik Moussa	8c01a133d8	Phase 9a: dual circle-packing functionals (CP-Euclidean + Inversive Distance) ... Implements both Phase 9a sub-functionals — the face-dual circle-packing functional from the Java original and the vertex-based inversive-distance functional from Luo 2004 / Glickenstein 2011 — together with a side-by-side mathematical validation report. CGAL test count: 194 → 205 (+11 from 9a.2, +10 from 9a.1, was already +1 from 9a.1's setup defaults regression). Phase 9a.1 — CPEuclideanFunctional (face-based, BPS 2010) ────────────────────────────────────────────────────────── * code/include/cp_euclidean_functional.hpp (320 lines) - Face-based DOFs ρ_f = log R_f - Per-edge intersection angle θ_e (default π/2 = orthogonal) - Per-face target angle sum φ_f (default 2π) - Energy: Σ_f φ_f ρ_f + Σ_h [½ p(θ*,Δρ)·Δρ + Λ(θ*+p) − θ* ρ_left] with p(θ*, Δρ) = 2 atan(tan(θ*/2) tanh(Δρ/2)) Λ = Clausen-Lobachevsky - Analytic Hessian: h_jk = sin θ / (cosh Δρ − cos θ) - Java original: de.varylab.discreteconformal.functional.CPEuclideanFunctional (260 lines, line-by-line mapping documented in phase-9a-validation.md §1) * code/tests/cgal/test_cp_euclidean_functional.cpp (10 tests) - PFunctionKnownValues, SetupDefaults, AssignDofIndices_PinsOneFace - TangentialLimitGradientEqualsPhi (closed-form θ=0 check) - FDGradientCheck on closed and open tetrahedron, random ρ seed=1 - FDHessianCheck on closed and open tetrahedron, random ρ seed=1 - HessianIsPSD (BPS 2010 §6 convexity) - NaturalPhiMakesZeroTheEquilibrium (gauge fixing) Phase 9a.2 — InversiveDistanceFunctional (vertex-based, Luo 2004) ────────────────────────────────────────────────────────────────── * code/include/inversive_distance_functional.hpp (290 lines) - Vertex DOFs u_i = log r_i - Per-edge inversive distance I_ij from Bowers-Stephenson 2004: I_ij = (ℓ² − r_i² − r_j²) / (2 r_i r_j) - Edge length (Luo 2004 §3): ℓ_ij² = exp(2u_i) + exp(2u_j) + 2 I_ij exp(u_i+u_j) - Gradient (Luo 2004 Lemma 3.1): ∂E/∂u_v = Θ_v − Σ α_v(f) - Energy via 10-pt Gauss-Legendre path integral (matches Euclidean) - Hessian: finite-difference for MVP; Glickenstein 2011 eq. 4.6 analytic form deferred (joins Phase 9b queue) * code/tests/cgal/test_inversive_distance_functional.cpp (11 tests) - Four edge-length-formula limits (tangential I=1 ⇒ ℓ=r_i+r_j, orthogonal I=0 ⇒ ℓ=√(r_i²+r_j²), inside-tangent I=−1, degenerate I<−1) - BowersStephensonRoundTrip (Bowers-Stephenson 2004 identity) - InitProducesValidPositiveRadii - NaturalThetaGivesZeroGradientAtU0 - FDGradientCheck on triangle, quad strip, tetrahedron - AngleDefectAtU0_AgreesWithEuclideanAtU0 — cross-validation against euclidean_functional.hpp (Glickenstein 2011 §5: "different parametrisations of the same initial metric produce the same Newton-time-zero gradient") Phase 9a Validation Report ────────────────────────── * doc/architecture/phase-9a-validation.md (350 lines) - Line-by-line mapping CPEuclideanFunctional.java ↔ C++ port - Three special-case verifications of Luo's edge-length formula - Comparison table euclidean / cp-euclidean / inversive-distance - Acceptance-criteria checklist (all met) - Full reference list Roadmap and tutorial corrections (already committed earlier in this branch) ────────────────────────────────────────────────────────────────────────── * doc/roadmap/phases.md — Phase 9a split into 9a.1 + 9a.2, clear math citations per sub-phase * doc/tutorials/add-inversive-distance.md — corrects the prior claim that InversiveDistanceFunctional.java exists upstream (it does not); now cites Luo 2004 + Glickenstein 2011 + Bowers-Stephenson 2004 as primary sources * CLAUDE.md — adds phase-9a-validation.md to doc map Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-21 21:01:34 +02:00
Tarik Moussa	f50ef4a305	Phase 9b: Hyper-ideal Hessian — block-FD optimisation (96× speed-up) ... Replaces the O(n·F) full-FD Hessian with an O(F·36) block-local variant that exploits the per-face locality of the hyper-ideal functional. Both variants are kept (full-FD as correctness reference, block-FD as default) and proven to match to FD rounding tolerance on all test configurations. Java parity note ──────────────── HyperIdealFunctional.java line 295-298 declares: public boolean hasHessian() { return false; } i.e. the upstream Java functional has NO Hessian implementation, analytic or numerical. Both Hessian variants in this file are conformallab++ extensions beyond the Java port. Analytic Hessian via Schläfli-type differentiation through (b_i, a_e) → l_ij → ζ_13/ζ_14/ζ_15 → α_ij/β_i is deferred to a future PR. Implementation ────────────── * code/include/hyper_ideal_functional.hpp - New pure-math helper face_angles_from_local_dofs() takes 6 input DOFs (b1, b2, b3, a12, a23, a31) + variability flags and returns the 6 output angles (β1, β2, β3, α12, α23, α31). - Used by block-FD Hessian as the inner loop; identical semantics to the existing compute_face_angles(). * code/include/hyper_ideal_hessian.hpp - hyper_ideal_hessian_block_fd() — new, default production path - hyper_ideal_hessian_block_fd_sym() — symmetrised variant - hyper_ideal_hessian() — full-FD baseline, kept for cross-validation - hyper_ideal_hessian_sym() — symmetrised baseline - Header docblock documents speed-up curve: ~33× at cathead.obj scale, ~1166× at brezel.obj scale. Tests (7 new in test_hyper_ideal_hessian.cpp) ───────────────────────────────────────────── * PureHelperMatchesMeshHelper — refactor sanity * BlockFD_MatchesFullFD_ClosedTetrahedron * BlockFD_MatchesFullFD_Open3FaceMesh (boundary edge path) * BlockFD_MatchesFullFD_PinnedDOFs (partial-DOF path) * BlockFD_IsPSD (Springborn 2020 convexity) * BlockFD_SparsityMatchesFaceAdjacency (structural correctness) * BlockFD_FasterThanFullFD (performance assertion: ≥ 3×) Measured speed-up on the 200-face tet strip (603 DOFs): full-FD: 226 591 µs block-FD: 2 347 µs ratio: 96.5× The assertion uses ≥ 3× to leave wide CI-hardware tolerance. Test count ────────── CGAL suite: 184 → 191 (+7). Zero skips. Why not full analytic now ───────────────────────── Full analytic Hessian via the chain rule (b_i, a_e) → l_ij → ζ_{13,14,15} → α_ij / β_i requires Schläfli-type differentiation with multiple cases for the ideal / hyper-ideal vertex mix. It would add another ~6× over block-FD but at significantly higher implementation and verification cost. Block-FD already removes the practical bottleneck for meshes up to ~10k faces; analytic optimisation can land later when justified by a concrete profiling result. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-21 20:58:33 +02:00
Tarik Moussa	140f50f707	fixup: deduce kernel from mesh point type instead of hard-coding it ... Removes the only architectural lock-in spotted in the MVP audit before Phase 9a starts: the wrapper hard-coded Simple_cartesian<double> as the kernel inside discrete_conformal_map_euclidean. This would have broken any Surface_mesh<P> where P came from a different kernel (e.g. EPIC). Change ────── * CGAL::Kernel_traits<typename TriangleMesh::Point>::Kernel is now used to deduce the kernel from the mesh's point type. * The full Default_traits<...> instantiation is wrapped in internal_np::Lookup_named_param_def so a future `geom_traits(...)` named parameter can override the entire traits class without changes to the wrapper body (CGAL idiom, used by every CGAL package). * New test `KernelIsDeducedFromMeshPointType` pins the contract explicitly with static_asserts. Why now ─────── Phase 9a (Inversive-Distance) will copy this same template pattern. Fixing the kernel deduction once here keeps the design free for any user kernel; doing it after 9a would mean two parallel hard-coded kernel sites to refactor. Tests ───── CGAL suite: 184/184 passed, 0 skipped (was 183). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-19 22:50:40 +02:00
Tarik Moussa	a1e74c1370	Phase 8a MVP: CGAL traits + Discrete_conformal_map.h Euclidean entry ... First step of the Phase 8 Hybrid MVP. Adds a thin CGAL-conformant public API layer over the existing implementation, validated by 7 acceptance tests. Total CGAL test count: 183 (was 176), 0 skipped. New public headers ────────────────── * code/include/CGAL/Conformal_map_traits.h - ConformalMapTraits concept documentation - Default_conformal_map_traits<Surface_mesh<P>, K> specialisation - Static property-map accessors: vertex_points, theta_map, vertex_index_map, lambda0_map * code/include/CGAL/Discrete_conformal_map.h - User-facing entry: discrete_conformal_map_euclidean(mesh, np) - Conformal_map_result<FT> struct (u, iter, ‖G‖, converged flags) - Natural-theta default: x = 0 is the equilibrium when no Θ supplied - Honours user-provided Θ via vertex_curvature_map named parameter * code/include/CGAL/Conformal_map/internal/parameters.h - 4 named-parameter tags in CGAL::Conformal_map::internal_np: vertex_curvature_map, gradient_tolerance, max_iterations, fixed_vertex_map - User-facing helpers in CGAL::parameters::* Tests (test_cgal_traits_mvp.cpp, 7 cases) ───────────────────────────────────────── * DefaultTraitsTypes: compile-time type sanity (static_assert) * AccessorsReuseExistingMaps: traits accessors return identical pmaps * SingleTriangleConverges, QuadStripConverges: end-to-end Euclidean wrapper passes * MaxIterationsTakesEffect: named parameter is read * GradientToleranceTakesEffect: tolerance override changes Newton end-state * WrapperMatchesLegacyAPI: cross-API result equality at 1e-10 Architecture ──────────── 3-layer wrapper as designed (doc/api/cgal-package.md): Layer 1: code/include/*.hpp (existing algorithms, unchanged) Layer 2: CGAL/Conformal_map/internal/ (adapter, parameter tags) Layer 3: CGAL/Conformal_map_traits.h, CGAL/Discrete_conformal_map.h (user-facing) No algorithm duplication. Existing 176 + 36 tests untouched. Next: Phase 9a (Inversive-Distance) as the second client of this API — the real acceptance test for the trait design. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-19 22:07:15 +02:00
Tarik Moussa	e958afbd19	chore: translate all German text to English across code, docs, and CI ... Unified the codebase language to English throughout. German text appeared in code comments, test file headers, CI step names, and several markdown documents. All natural-language text is now English; proper nouns (Institut für Mathematik, Technische Universität Berlin) are unchanged. Files changed: - .gitea/workflows/cpp-tests.yml — CI step names and job comments - code/include/mesh_utils.hpp — inline comment - code/tests/cgal/CMakeLists.txt — section comment block - code/tests/cgal/test_geometry_utils.cpp — full file header + all test comments - doc/math/references.md — geometry-central section - doc/math/validation.md — Section 9 (geometry-central cross-validation) - doc/roadmap/phases.md — Optional geometry-central track (GC-1/2/3) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-19 00:09:09 +02:00
Tarik Moussa	88a99d8bd1	fix: correct 16 inconsistencies found by consistency audit ... Math / code: - layout.hpp: add explanatory comment for Möbius deck transformation (from_three with z1=w1, z2=w2 encodes T fixing cut-edge endpoints) - layout.hpp: document spherical holonomy limitation — Vector2d stores only (x,y) of 3-D position diff; full SO(3) representation deferred Gradient sign convention (CLAUDE.md was wrong): - Euclidean and Spherical both use G_v = Θ_v − actual (target minus actual) - HyperIdeal uses G_v = actual − Θ_v - Hessian sign differs: Euclidean PSD, Spherical NSD → −H, HyperIdeal PSD Test counts (were inconsistent across all files): - Actual: 176 CGAL tests, 2 GTEST_SKIP (not 173/170/174, not 1 skip) - The 2 skips are EuclideanFunctional + SphericalFunctional Hessian gradient checks (Java @Ignore ports) — not HyperIdeal Hessian as previously stated - doc/api/tests.md: add missing SmokeEuclidean suite (3 tests), EuclideanLayout (2), SphericalLayout (1), fix GaussBonnet 8→12, MeshIO 9→6, Layout 8→6, EuclideanFunctional 11→12, HomologyGenerators no longer a GTEST_SKIP stub (live test on brezel2.obj) - doc/roadmap/phases.md: Phase 7 cumulative 158→176 tests - doc/roadmap/phases.md: Phase 3 clarified — HyperIdeal Hessian is FD - CLAUDE.md: suite count 28→34, test ref 173+36→174+36 - scripts/try_it.sh: expected output 173/1 skipped → 174/2 skipped CI table (CLAUDE.md): - test-cgal now triggers on pull requests only (not main/dev pushes) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-18 23:24:44 +02:00
Tarik Moussa	b235666725	docs: Doxygen-API + Validierungsprotokoll + Porting-Tutorial ... Für einen Mathematiker der unabhängig validieren und eigene Forschung einbringen möchte. Doxygen-Kommentare (code/include/): newton_solver.hpp — newton_euclidean(), newton_spherical(), newton_hyper_ideal() je mit \param, \return, \note, \see inkl. mathematischer Begründung (Konvexität, Vorzeichenkonvention, SparseQR-Fallback-Erklärung) layout.hpp — euclidean_layout(), spherical_layout(), hyper_ideal_layout() mit vollständiger Parameter-Doku, halfedge_uv-Semantik, Poincaré-Disk-Note Neues Dokument: doc/math/validation-protocol.md 7 reproduzierbare Checks mit konkreten Befehlen und erwartetem Output: 0. 170 Tests, 1 Skip 1. Gauss–Bonnet exakt (1e-10) 2. FD-Gradientencheck < 1e-6 für alle 3 Geometrien 3. Newton-Konvergenz < 50 Iterationen 4. τ ∈ SL(2,ℤ)-Fundamentaldomäne (3 Invarianten) 5. Möbius-Arithmetik (Inverse, Compose, from_three) 6. End-to-End-Pipeline 7. Manueller τ-Check für torus_4x4.off (Codebeispiel) Neues Tutorial: doc/tutorials/add-inversive-distance.md Vollständiger Step-by-Step-Port von Phase 9a (Luo 2004): Header anlegen, Energie/Gradient implementieren, FD-Check, Newton-Wrapper, CMakeLists, Java-Referenzvergleich, Checkliste. doc/getting-started.md: Abschnitt "Known issues": macOS-Finder-Duplikate (rm-Befehl), Warnung "First build 30–90s" (Tarball-Extraktion) README.md: Zwei neue Links in der Dokumentationstabelle (validation-protocol, tutorial) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-18 01:19:44 +02:00
Tarik Moussa	e7dfaed56c	feat(phase7): Java-parity layout — priority BFS, halfedge_uv, Möbius holonomy, period matrix, fundamental domain — 158 tests ... Phase 7 adds seven features ported from the original Java ConformalLab: layout.hpp - Priority BFS (min-heap on BFS depth) replaces FIFO queue, minimising trilateration error accumulation from the root face outward. - MobiusMap struct: T(z)=(az+b)/(cz+d), identity/inverse/compose, from_three (3×3 complex least-squares fit), apply(Vector2d). - halfedge_uv[h.idx()] = UV of source(h) in face(h); seam halfedges carry the virtual unfolded position, enabling proper GPU texture atlases. - Hyperbolic holonomy stored as MobiusMap per cut edge (SU(1,1) isometry). - best_root_face: largest 3-D area face, 1.5× interior bonus. - normalise_euclidean also transforms halfedge_uv (centroid + PCA). - Face-area-weighted iterative Möbius centering (Fréchet mean, Phase 7). period_matrix.hpp (new) - PeriodData: lattice generators ω_i as complex numbers, τ = ω₂/ω₁ ∈ ℍ. - reduce_to_fundamental_domain: SL(2,ℤ) reduction via alternating S/T steps. - is_in_fundamental_domain, compute_period_matrix. - NOTE: Siegel matrix Ω for genus g>1 intentionally deferred. fundamental_domain.hpp (new) - FundamentalDomain: CCW parallelogram {0, ω₁, ω₁+ω₂, ω₂} for genus 1. - edge_identifications, generators stored. - 4g-polygon boundary-walk for g>1 marked TODO(Phase 8) with full algorithm outline and literature references. - tiling_copy / tiling_neighbourhood for universal cover visualisation. Tests: 121 → 158 (+37 Phase 7 tests covering all new features). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-13 07:57:13 +02:00
Tarik Moussa	4fc48b39f0	feat(phase6): exact hyperbolic layout, Gauss–Bonnet, cut graph, normalisation — 121 tests ... New files: - gauss_bonnet.hpp: euler_characteristic, genus, Σ(2π-Θ_v) sum/rhs/deficit, check_gauss_bonnet (throws), enforce_gauss_bonnet (correct sign: Δ=(lhs-rhs)/V) - cut_graph.hpp: CutGraph struct + compute_cut_graph (tree-cotree, Erickson–Whittlesey 2005); boundary edges correctly excluded from cut set - test_phase6.cpp: 26 new tests (GaussBonnet ×8, CutGraph ×6, HyperbolicTrilateration ×4, Normalisation ×4 — all pass) layout.hpp (Phase 6 rewrite): - detail::trilaterate_hyp: exact Möbius + hyperbolic law of cosines replacing old tanh(d/2) - detail::center_poincare_disk: Möbius centering for hyperbolic normalisation - normalise_euclidean: centroid → origin + PCA major-axis rotation - normalise_hyperbolic: Möbius centering in the Poincaré disk - normalise_spherical: Rodrigues rotation → north pole - euclidean_layout / hyper_ideal_layout: optional CutGraph* + HolonomyData* + normalise Bug fixes caught by new tests: - gauss_bonnet.hpp: enforce_gauss_bonnet had wrong sign for delta - cut_graph.hpp: boundary edges were incorrectly marked as cut edges 121 tests pass, 2 skipped (Hessian stubs). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-13 01:15:41 +02:00
Tarik Moussa	b7593e3f6d	feat(phase5): Layout, CLI, JSON/XML serialisation — 95 tests ... Phase 5 complete: layout.hpp - euclidean_layout(): BFS unfolding in ℝ² using trilaterate_2d - spherical_layout(): BFS on S² using trilaterate_sph (spherical law of cosines) - hyper_ideal_layout(): BFS in Poincaré disk (tanh(d/2) Euclidean approx) - save_layout_off(): convenience OFF writer for 2-D and 3-D layouts serialization.hpp - save/load_result_json(): nlohmann/json; stores DOF vector + uv/pos layout - save/load_result_xml(): hand-written writer/parser; same schema conformallab_cli.cpp (rewritten) - CLI11 interface: -i/-o/-g/-j/-x/-s/-v - Dispatches to euclidean / spherical / hyper_ideal pipeline - Runs Newton, computes layout, saves OFF + JSON + XML examples/example_layout.cpp - Full round-trip demo: solve → layout → JSON/XML → reload → verify tests/cgal/test_layout.cpp (8 tests) - Euclidean_PreservesEdgeLengths, CorrectVertexCount, TriangleIsNonDegenerate - Spherical_PreservesArcLengths, PositionsOnUnitSphere - HyperIdeal_SuccessAndFinitePositions - Serialization.JSON_RoundTrip, XML_RoundTrip All 95 CGAL tests pass (2 skipped — Hessian stubs unchanged). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-13 00:53:47 +02:00