67 Commits

Author	SHA1	Message	Date
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	330515ea90	docs(java-parity): P2/Matrix jReality notes + Phase 9c dependency warning ... - 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>	2026-05-30 17:20:35 +02: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
user2595	a993a101e9	Merge pull request 'docs: citation audit (8 mis-citations fixed) + Phases 12/13' (#28) from docs/citation-audit-phases-12-13 into main ... Reviewed-on: #28	2026-05-30 08:06:33 +00:00
Tarik Moussa	26f4f0637d	docs: citation audit + correct 8 mis-citations; add Phases 12/13 ... 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>	2026-05-29 19:17:17 +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	ca936b7652	docs: note high-precision requirement for Phase 9c/10 uniformization ... 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>	2026-05-28 07:41:23 +02:00
Tarik Moussa	1ff5382c8b	docs: record 2026-05-28 full-library scan findings in roadmap ... 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>	2026-05-28 06:53:09 +02:00
Tarik Moussa	569a03dc08	docs+tooling: doc-freshness gate, documentation-pass policy, token-hygiene ... 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>	2026-05-28 06:15:14 +02:00
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>	2026-05-26 11:50:59 +02:00
Tarik Moussa	09a68a4569	release: v0.10.0 — reviewer-ready release ... 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>	2026-05-26 11:24: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	3f508adf18	ci+hub: durable reviewer hub via in-repo HTML + perf-CI matrix on Linux ... 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>	2026-05-26 11:15:09 +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	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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	2026-05-26 11:15:09 +02:00
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>	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	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>	2026-05-25 23:17:48 +02:00
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>	2026-05-24 09:56:40 +02:00
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>	2026-05-24 08:37:12 +02:00
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>	2026-05-24 08:25:09 +02:00
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>	2026-05-23 23:47:29 +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	b0c67af922	ci: auto-publish Doxygen HTML to Codeberg Pages on main ... New .gitea/workflows/doxygen-pages.yml runs on every push to main that touches the public headers, Doxyfile, the markdown-link filter, any doc/**/*.md, README.md, or the workflow itself. It reuses the existing ci-cpp container image and the existing CODEBERG_TOKEN secret already used by mirror-to-codeberg.yml — no new secret setup needed. The job force-pushes an orphan commit to the `pages` branch on codeberg.org/TMoussa/ConformalLabpp, which Codeberg Pages serves from https://tmoussa.codeberg.page/ConformalLabpp/ (verified live). README.md gains a Doxygen badge and a Documentation table row pointing at the Pages URL. locked-vs-flexible.md (the reviewer-facing doc) is updated to mention the Pages URL next to the Doxygen-coverage gap. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-23 23:30:54 +02:00
Tarik Moussa	ba5c9303a3	docs: clean Doxygen warning log (0 warnings) + flag honest gaps to reviewer ... Doxygen now builds with **0 warnings** (was 27). Root cause: `[label](doc/api/tests.md)`-style relative markdown links in README.md and CLAUDE.md were being interpreted by Doxygen as \ref commands and failed to resolve (Doxygen indexes .md files by basename, not by repo-relative path). Fix: add a per-file `FILTER_PATTERNS` to Doxyfile that rewrites `[label](path/to/file.md)` into `<a href="path/to/file.md">label</a>` just for Doxygen. HTML anchors bypass \ref resolution entirely; the generated Doxygen HTML still hyperlinks correctly. The on-disk markdown is untouched, so GitHub rendering is unaffected. New file: scripts/doxygen-md-filter.sh (24 lines, documented). Also: append a "Known limitations (state at the time of the reviewer meeting)" table to doc/architecture/locked-vs-flexible.md so the external reviewer sees the 7 deliberate gaps (output_uv_map covers 3 of 5 entries; pipe-only chaining; Phase 9b-analytic derived but not implemented; Doxygen WARN_IF_UNDOCUMENTED policy; CI test-count gate; research-track utilities) with effort estimates next to each. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-23 23:19:37 +02:00
Tarik Moussa	0b1bf07232	docs: fix 2 broken internal links ... - doc/release-policy.md:85 corrected `doc/api/tests.md` link to relative `api/tests.md` (was resolving to nonexistent doc/doc/api/tests.md). - doc/tutorials/block-fd-hessian.md:40 redirected stale reference `../math/hyper-ideal.md` to the actual file `../math/geometry-modes.md`. Found by a sweep of all doc/*.md before the reviewer meeting. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-23 23:09:40 +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	eb393537f3	docs: 5-document meeting prep — tutorials + research note + status + architecture ... External-reviewer-visit prep package (Springborn-Bobenko PhD alumnus, 2026-05-26). All five documents target the same audience: a mathematician who wants to evaluate, extend, or contribute to conformallab++. Goal: make the project maximally hackable BEFORE the meeting. Code unchanged in this commit — pure documentation. Files added ─────────── 1. **doc/tutorials/block-fd-hessian.md** (460 lines) Step-by-step tutorial on the per-face block-FD Hessian pattern shipped in Phase 9b (96× speed-up). Matches the style of add-inversive-distance.md. Covers: * The per-face locality lemma (mathematical justification). * Cost analysis (full-FD vs block-FD vs analytic). * Implementation walkthrough through face_angles_from_local_dofs + hyper_ideal_hessian_block_fd. * Porting checklist for applying the same pattern to a new functional. * The four cross-validation criteria. * When NOT to use block-FD + upgrade path to Phase 9b-analytic. 2. **doc/tutorials/add-output-uv-map.md** (477 lines) Tutorial for the `output_uv_map` named-parameter pattern shipped in PR #14. Covers: * The UX problem (two-step pipeline → one-call wrapper). * The CGAL named-parameter mechanism + how the entry functions wire it (get_parameter + constexpr if). * Step-by-step recipe for adding a new named parameter (worked example: hypothetical `output_holonomy_map`). * The five test patterns for verification. * Why CP-Euclidean (face-DOF) and Inversive-Distance (Luo-edge-length) do not yet support output_uv_map — what is needed to add them. 3. **doc/math/hyperideal-hessian-derivation.md** (805 lines) Research-quality LaTeX-formatted derivation of the analytic HyperIdeal Hessian via the Schläfli identity (Phase 9b-analytic preparation). Covers: * Schläfli identity (1858/60) — gradient and second-order form. * Derivatives of ζ, ζ₁₃, ζ₁₄, ζ₁₅ (all hyper-ideal-to-fully-ideal cases). * Chain rule for ∂β_i/∂(b,a) and ∂α_ij/∂(b,a) — case-split on the four α_ij branches. * Per-face 6×6 block formulas. * Acceptance criteria for the future implementation. * Implementation outline (Conformal_map header sketch). * Appendix A: sign / argument-order pitfalls reading the code. * References: Schläfli 1858, Milnor 1982, Vinberg 1993, Cho-Kim 1999, Rivin, Glickenstein 2011, Springborn 2020, BPS 2015. 4. **doc/roadmap/porting-status.md** (~250 lines) Operational snapshot of "where is each piece of Java math today" at v0.9.0. Sections: * 25 000 lines of Java in one table (ported / worth porting / intentionally skipped breakdown). * Five DCE models — full status matrix with Java port status, Hessian type, Newton support, CGAL entry, UV-output capability. * Topology + solver infrastructure status. * CGAL public API map + known limitations (no chaining, Surface_mesh only, submission-readiness gaps). * Reverse cross-reference: Java class → C++ port location (or "skipped: replaced by …" / "in roadmap: phase X"). * Things in C++ that the Java original does NOT have (research extensions track). * "How to use the library today" quickstart. 5. **doc/architecture/locked-vs-flexible.md** (~270 lines) 12-item architecture-decision review with tier classification (🔴 load-bearing / 🟡 semi-fixed / 🟢 opportunistic). Each item includes: locked-since date, cost to change, when to revisit, recommended posture for new contributors. Key insight stated up front: "the load-bearing decisions are all good in 2026". Closes with five open questions for the external reviewer — items where a second opinion would genuinely help (Phase 9c algorithm choice, Phase 10a priorities, analytic-Hessian payoff justification, CGAL upstream vs independent distribution, geometry-central cross-validation). Total: ~2 250 lines across five new docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-22 13:38:53 +02:00
Tarik Moussa	ff9c9ec11b	docs: add StereographicUnwrapper + CircleDomainUnwrapper to roadmap ... Audit found that 2 of the 4 Java-port candidates from the conformal- mapping discussion were missing from the documentation: * StereographicUnwrapper (266 Java LoC) — projects spherical layout S² → ℂ via stereographic projection + Möbius centring. Closes the visualisation gap from discrete_conformal_map_spherical() which currently returns Point_3 on S²; downstream uses typically want a 2-D atlas. Suggested phase: 10b' (alternative methods, parallel to Hyperbolic / Quasi-isothermic). Effort: small (~3 days). * CircleDomainUnwrapper (570 Java LoC) — conformal map of a multiply-connected planar region onto a disk-with-holes (Koebe's general uniformization theorem 1909). A use-case class conformallab++ does not currently cover (annulus, slit torus, fluid flow around obstacles, electrostatics with multiple conductors). Suggested phase: 11c. Effort: large (~2 weeks). Added to all three roadmap documents: * doc/roadmap/java-parity.md — worth-porting table extended * doc/roadmap/research-track.md — Java-backlog summary extended * doc/roadmap/phases.md — Phase 10b' bullet + new Phase 11c block with full math context (Koebe 1909 reference, classical complex-analysis use cases). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-22 13:24:37 +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	84258921df	docs: audit-driven fixes — stale claims, missing v0.9.0 entries ... Follow-up to the test-count centralisation + release-policy commit: applies the findings of the parallel doc-audit. Stale claims fixed ────────────────── * CLAUDE.md line 14-17 (phase block summary): expanded from "Phase 1-7 done, 8-9 planned, 10+ research" to reflect that Phase 8a MVP + 8b-Lite + 9a + 9b are now done (v0.9.0), with Phase 9b-analytic + 9c as the next planned milestones. * CLAUDE.md line 251-252 (release state): "v0.7.0 ... Phase 7 next" → "v0.9.0 ... Phase 9c + 9b-analytic next". * CLAUDE.md "Three geometry modes" → "Five DCE models" table. Adds CP-Euclidean and Inversive-Distance rows with their CGAL public entries. DOF-assignment pattern subsection rewritten to cover vertex-only / vertex+edge / face-based assignments. * CLAUDE.md "Newton solver" section: gradient sign and Hessian convention for all five solvers (was: three). Replaces the "Hessian is FD" claim for HyperIdeal with the block-FD note (Phase 9b shipped). * CLAUDE.md "Known quirks": stale GTEST_SKIP entry removed (v0.9.0 cleaned up the HDS-port stubs). * README.md line 86: "all 24 headers with descriptions" → "all public headers with descriptions" (was undercounting). Missing entries added — `doc/api/headers.md` ───────────────────────────────────────────── * New section **"Circle-packing functionals (Phase 9a)"** with `cp_euclidean_functional.hpp` and `inversive_distance_functional.hpp`. * New section **"Math utilities"** documenting four previously- undocumented public helpers: `matrix_utility.hpp`, `projective_math.hpp`, `p2_utility.hpp`, `discrete_elliptic_utility.hpp`. * New section **"CGAL public API (Phase 8b-Lite)"** documenting all six new public headers under `include/CGAL/`. * `newton_solver.hpp` row expanded to list all five Newton functions. Header count summary (before vs after): * Before: 24 headers in 8 sections (missing 6 of the 30 actually present). * After: 30 headers in 11 sections (complete coverage). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-22 13:24:37 +02:00
Tarik Moussa	0f78d181e1	docs: centralise test counts + add release-policy + remove stale stub references ... Two complementary improvements aimed at reducing recurring maintenance overhead: 1. **Test-count centralisation** — `doc/api/tests.md` is now the single source of truth for the test counts. All other docs (README, CLAUDE.md, doc/contributing.md, doc/getting-started.md, doc/math/validation.md, doc/math/validation-protocol.md, scripts/try_it.sh) use qualitative phrasing + a link instead of hardcoded numbers. The previous regime had eight places with "227 CGAL tests, 23 non-CGAL tests" that drifted apart across releases (the v0.9.0 release-prep needed to touch nine files). 2. **Versioning policy** — `doc/release-policy.md` (new, ~250 lines) formalises: * SemVer rules for the pre-1.0 and post-1.0 phases. * Phase-milestone → MINOR-bump mapping (v0.10.0 → Phase 9c, …). * Single-source-of-truth table for moving numbers (test counts, version, date). * Step-by-step release process (the recipe that worked for v0.9.0 after the false-start with PR #11/#12). * Hotfix policy + post-1.0 deprecation policy. * Known failure modes and how to recover from them. Plus a small CI gate: 3. **scripts/check-test-counts.sh** — verifies the totals in doc/api/tests.md match `ctest` output. Re-uses existing build-cgal/ if present. Exit 0 on match, 1 on divergence with recovery hints. Cheap enough (~30 s) to run on every PR. Other cleanups ────────────── * code/tests/cgal/CMakeLists.txt — stale "Test 7 (genus-2 homology) as GTEST_SKIP stub until Phase 8" comment removed; that test landed as HomologyGenerators.Genus2_FourCutEdges in Phase 7. * CLAUDE.md — "test-fast also runs stubs" Known Quirks entry updated to reflect the v0.9.0 stub cleanup (no GTEST_SKIPs remain). * CLAUDE.md doc map — new entry for doc/release-policy.md. Stubs audit ─────────── Zero GTEST_SKIP() calls remain in the codebase as of this commit. The only references to stubs are in historical documentation (CHANGELOG.md v0.7.0 entry, doc/roadmap/* "deferred to research-track" notes) — those are intended. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-22 13:24:37 +02:00
Tarik Moussa	540f71a629	release: v0.9.0 — finalise PR #11 with CHANGELOG, version bump, stub cleanup ... Closes the v0.9.0 release loop on top of Phase 9a-Newton + Phase 8b-Lite: * CHANGELOG.md (NEW) — Keep-A-Changelog format, with v0.9.0 entry detailing all Phase 9a / 9b / 8b-Lite contents and the doc-audit corrections that landed via PR #10. * CITATION.cff — version 0.7.0 → 0.9.0, date 2026-05-18 → 2026-05-22. * Stale HDS-port stubs removed (13 GTEST_SKIPs total): - code/tests/test_spherical_functional.cpp - code/tests/test_hyper_ideal_functional.cpp - code/tests/test_hyper_ideal_hyperelliptic_utility.cpp These referenced a "HDS port (Phase 4)" that never happened — CoHDS was intentionally replaced by CGAL::Surface_mesh, and the functional tests live in code/tests/cgal/test_*_functional.cpp. * Test-count updates everywhere: - Non-CGAL 36 → 23 (drop = 13 deleted stubs) - CGAL 176 → 227 - Total 212 → 250 (+38 net, 0 skipped) Files: README.md, CLAUDE.md, CHANGELOG.md, scripts/try_it.sh, doc/api/tests.md, doc/contributing.md, doc/getting-started.md, doc/math/validation.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-22 04:27:24 +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	4f0a3035e4	docs: full audit — fix 4 wrong port/research labels + consolidated research-track ... A full audit of `doc/` plus root-level markdown files (27 files) against the actual ground truth in the C++ code and the local Java repository at `/Users/tarikmoussa/Desktop/conformallab/` revealed four pre-existing mis-labels and a stale test count. All are corrected here. Audit findings — corrected ───────────────────────── 1. **`InversiveDistanceFunctional` mis-labelled as Java port** (4 doc sites) Empirical verification: find /Users/tarikmoussa/Desktop/conformallab -iname "*nversive*" (zero matches) The class does NOT exist in `de.varylab.discreteconformal`. The C++ implementation is built from Luo 2004 + Glickenstein 2011 + Bowers- Stephenson 2004 — new research, not a port. Fixed in: java-parity.md, references.md, add-inversive-distance.md. 2. **HyperIdeal Hessian mis-labelled as "Java has analytic Hessian"** Empirical verification: `HyperIdealFunctional.java:295-298`: public boolean hasHessian() { return false; } Java has NO Hessian at all. Both the FD (Phase 4a) and the block-FD (Phase 9b) Hessians in C++ are research beyond the Java port. The chain rule (b,a) → ℓ → ζ → α/β is the *mathematical formulation* from Springborn 2020, not something Java implements. Fixed in: java-parity.md. 3. **Stale test count** README:87 said "28 suites, 170 tests" — current actual is 35 suites, 176 CGAL + 36 non-CGAL. Fixed. 4. **Tutorial framing** — `add-inversive-distance.md` was framed as "porting an InversiveDistanceFunctional.java" that does not exist. Rewritten as "Implementing the Inversive-Distance functional from Luo 2004" with prominent verification block at top. New document: `doc/roadmap/research-track.md` ───────────────────────────────────────────── Consolidates everything in conformallab++ that goes beyond a Java port: * Items already on `main`: HyperIdeal FD Hessian, period matrix τ partial-research components, Möbius holonomy storage. * Items on open PRs: CP-Euclidean (PR #8, port), Inversive-Distance (PR #8, research), block-FD Hessian (PR #9, research). * Planned research with full citations: - **Phase 9b-analytic** — full analytic HyperIdeal Hessian via Schläfli identity (Schläfli 1858/60) and chain rule through ζ₁₃/ζ₁₄/ζ₁₅, citing Springborn 2020 §4, Cho-Kim 1999, Glickenstein 2011 §4. Includes acceptance-criteria checklist (per-case derivative cross-checks, gauge null space, PSD, measured ≥ 3× speed-up, LaTeX correctness note). - **Phase 9a.2-analytic** — analytic inversive-distance Hessian via Glickenstein 2011 eq. (4.6). - **Phase 10c** — full uniformization for genus g ≥ 2 (Fuchsian group representation) — fully new research, no Java reference. - **geometry-central** GC-1/2/3 exploratory track. * Java backlog summary: 11 worth-porting Java classes identified by the parallel survey (FundamentalPolygonUtility, DiscreteHarmonicForm- Utility, DiscreteHolomorphicFormUtility, CanonicalBasisUtility, HyperbolicCyclicFunctional, QuasiisothermicUtility, KoebePolyhedron, …). ~6 500 Java lines, ~5 months of porting work, organised by phase. Updated documents ───────────────── * CLAUDE.md - New "Port-vs-research maintenance rule" with empirical verification command and the four corrected mis-labels. - Doc map: 23 → 24 documents (research-track.md added). * README.md - Test count corrected (170 → 176+36). * doc/math/references.md - Luo 2004 entry corrected ("new research" instead of "not yet ported"). - New entries for Bowers-Stephenson 2004, Glickenstein 2011, Bobenko-Pinkall-Springborn 2010, Schläfli 1858/60. * doc/roadmap/phases.md - Phase 9 reorganised: 9a split into 9a.1 (port) / 9a.2 (research), 9b clarified as research (Java has no Hessian), 9c expanded with Java line counts and effort estimates. - Phase 10 reorganised: 10a/10b/10c with their Java prerequisites explicitly listed; 10c flagged as "fully new research". - Phase 10b' added: parallel research track (hyperbolic functional, quasi-isothermic, Möbius centering). - Phase 10c' added: optional Java-port additions (Koebe, circle patterns, electrostatic sphere). * doc/roadmap/java-parity.md - Inversive-distance row: ❌ Java, ❌ C++ (Phase 9a.2) — new research. - CP-Euclidean row added: ✅ Java, ❌ C++ (Phase 9a.1) — port. - HyperIdeal Hessian row: ❌ Java, ⚠️ FD + block-FD in C++. - Worth-porting table replaced with the survey results (12 classes, Java line counts, suggested phases). - "HyperIdeal Hessian: FD vs analytic" section rewritten with the correction notice. * doc/tutorials/add-inversive-distance.md - Rewritten end-to-end with prominent verification block at top. - Now correctly framed as "Implementing the Inversive-Distance functional from Luo 2004" — research, not port. - Includes the four required cross-validations: limit cases, Bowers-Stephenson round-trip, FD-vs-analytic, cross-validation against euclidean_functional at u=0. - New "How to know if it's a port or research" closing section with the empirical verification command. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-21 20:48:16 +02:00
Tarik Moussa	4971f0254d	docs: refine Phase 8 strategy to Hybrid MVP — MVP first, port second ... Re-evaluated cost/benefit of Phase 8 vs Phase 9 after distinguishing three concurrent goals: • Goal A (Port): ~90% done, ~3 weeks remaining • Goal B (CGAL): speculative, 12+ months, uncertain submission • Goal C (Tool): research utility with novel features Phase 8 full (3–4 weeks) would mostly serve Goal C plus optional Goal B. Phase 9 (3 weeks) finishes Goal A unconditionally. Building Phase 8 in full before Phase 9 risks 3-4 weeks of speculative architecture for a hypothetical CGAL submission. New strategy: Hybrid MVP. Phase 8 MVP (3–5 days): Conformal_map_traits.h concept + Default<Surface_mesh,K> Discrete_conformal_map.h ONE entry: _euclidean() 4 named parameters Theta-map, max_iter, tol, pin Concept-check header + Doxygen Phase 9a (3–5 days): Inversive-Distance vs MVP API = acceptance test Phase 9b + 9c (~2 weeks): Port truly complete Phase 8 extensions: Only on concrete trigger 8a.2 generic FaceGraph trigger: Polyhedron_3 user 8c full doc trigger: submission planned 8d CGAL-format tests trigger: submission planned 8e YAML pipeline orthogonal, any time Net committed budget: ~4 weeks for "port complete + CGAL MVP", not 6–8 weeks for full Phase 8 + Phase 9. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-19 20:04:54 +02:00
Tarik Moussa	02fb80ee3e	Phase 7.5: Doxygen infrastructure + Phase 8 design freeze ... Adds the Doxygen documentation pipeline as the bridge from Phase 7 (porting complete) to Phase 8 (CGAL package). Also captures the strategic Phase 8 decisions taken on 2026-05-19. Infrastructure ────────────── * Doxyfile — CGAL-style minimal configuration, HTML-only, INPUT=code/include + doc/, excludes deps/ and macOS Finder duplicates * code/CMakeLists — `doc` target via find_package(Doxygen QUIET); silently disabled if Doxygen is not installed * README — `cmake --build build --target doc` instructions * .gitignore — exclude doc/doxygen/ output Phase 8 strategic decisions (recorded in doc/api/cgal-package.md) ──────────────────────────────────────────────────────────────── * Submission to CGAL: pre-submission-ready, 12+ months horizon, MIT preserved * Mesh-type flexibility: generic FaceGraph + HalfedgeGraph * Parameter style: CGAL Named Parameters * Default kernel: Simple_cartesian<double> (status quo) * Architecture: 3-layer wrapper, no algorithm duplication * Acceptance test: Phase 9a (Inversive-Distance) as first new client CLAUDE.md updated with a compact Phase 8 decision table. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-19 19:56:22 +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	52f61cec36	Update all doc test counts to 176 CGAL tests, 0 skipped ... Propagates the new baseline (176 passed, 0 skipped) established by the GradientCheck_Hessian implementation across all documentation files that previously referenced the stale counts (174/173/170 + 1-2 skips). Files updated: CLAUDE.md, doc/api/tests.md, doc/contributing.md, doc/getting-started.md, doc/math/novelty-statement.md, doc/math/validation.md, doc/math/validation-protocol.md, scripts/try_it.sh Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-18 23:33:31 +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