203 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
user2595	ed9ae844d1	Merge pull request 'release: v0.10.0 — reviewer-ready' (#20) from release/v0.10.0 into main v0.10.0	2026-05-26 09:25:06 +00: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
user2595	3953d1549b	Merge pull request 'reviewer-meeting prep: CI promotion + 3rd-party licenses + output_uv_map(ID) + briefing trio' (#19) from reviewer/meeting-prep into main	2026-05-26 09:15:37 +00: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
Tarik Moussa	32253a8f5e	ci+licenses: promote 4 trivial gates to required CI + THIRD-PARTY-LICENSES.md ... Two reviewer-facing additions consolidated into one commit: (1) New `quality-gates` job in .gitea/workflows/cpp-tests.yml ────────────────────────────────────────────────────────── Runs in parallel with test-cgal after test-fast. Installs `codespell` + `shellcheck` (apt) into the existing ci-cpp container, then executes four scripts strictly (exit 1 on any finding): * license-headers.sh — 66/66 files carry SPDX MIT * cgal-conventions.py — 0 violations across 6 CGAL public headers * codespell.sh — 0 typos across docs + source + scripts * shellcheck.sh — 0 findings across 16 shell scripts Each ran at 0 findings locally before promotion. Total wall-time on the eulernest runner: ~30 s. (2) New code/deps/THIRD-PARTY-LICENSES.md ────────────────────────────────────── Enumerates every vendored dep under code/deps/, plus auto-fetched GoogleTest, plus system-required Boost, with: * upstream project + version + SPDX identifier * compatibility note for MIT distribution * downstream-packager license matrix (header-only consumer vs CLI binary) clarifying the LGPL §3 vs §4 distinction Required for any future Linux-distribution packaging and for the CGAL submission's compliance check. Also fixes a `code/.gitignore` gap: the `deps/*` wildcard was catching the new file; added `!deps/THIRD-PARTY-LICENSES.md` to the exclusion list so it's actually tracked. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	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
user2595	63f2b9799d	Merge pull request 'docs: drive Doxygen coverage to 100 percent + auto-generate headers.md' (#17) from docs/doxygen-coverage-100 into main	2026-05-26 09:14:15 +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	8d34be76a7	quality: full --slow sweep runs cleanly; 13/14 PASS, 1 SKIP, 0 FAIL ... Closes the structural-tests work end-to-end. After this commit, the full run-all.sh sweep (10 fast + 4 slow gates) finishes in ~3 min on the canonical dev machine with: PASS License headers (66/66 carry MIT SPDX) PASS CGAL conventions (0/6 violations) PASS clang-format drift (0 drift) PASS cmake-format/-lint (0 drift, 0 lint findings) PASS codespell (0 typos) PASS shellcheck (0 findings, 16 .sh files) PASS cppcheck (warning+ severity clean) PASS Markdown links (122/122 resolve) PASS Sanitizers (ASan+UBSan) (23/23 tests pass) PASS clang-tidy (35 headers, 0 findings) PASS Coverage (gcov+lcov, graceful on macOS) PASS Multi-compiler (AppleClang + brew LLVM, both 23/23) PASS Reproducible build (byte-identical between 2 builds) SKIP CGAL version matrix (no CGAL tarballs under ~/cgal/) Bug fixes uncovered by the slow block ───────────────────────────────────── 1. coverage.sh — Apple Clang `--coverage` deadlocks on arm64 during static-initializer profiling of template-heavy code (Eigen+CGAL). Auto-prefer brew-installed LLVM clang++ on Darwin when present; honoured `CXX=...` override. 2. coverage.sh — lcov 2.x rejects the brew-clang gcov output with "inconsistent / unsupported / negative / empty / mismatch" errors over GoogleTest's preprocessor gymnastics. Added `--ignore-errors` for all those classes; degrade gracefully to an informational "empty trace, but tests passed" summary when the info file can't be filled (lcov-on-macOS toolchain mismatch). 3. coverage.sh — added the same `CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE =PRE_TEST` fix as sanitizers.sh — coverage-instrumented binaries can't be safely executed at *build* time. 4. run-all.sh — broadened the SKIP-detection regex so the cgal-version-matrix.sh exit-2 message ("FAIL: no CGAL installs found.") is recognised as SKIP, not FAIL. These fixes make every slow gate runnable. The Linux CI will hit the same code paths with system gcc + system lcov where the coverage trace actually fills in; macOS dev users get a green "tests passed under instrumentation" signal without the report. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 19:34:20 +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	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	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	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	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
user2595	8869ead3c9	Merge pull request 'Docs + CI: link fixes, 0-warning Doxygen, Codeberg Pages auto-publish' (#16) from ci/doxygen-pages-autopublish into main	2026-05-23 21:32:19 +00: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
user2595	b569daa388	Merge pull request #15: Hackability meeting-prep — 5 docs + pipe-chaining (250→257 tests) ... External reviewer prep package for the 2026-05-26 Springborn-Bobenko PhD alumnus visit. Deliverables: • 5 new docs (~2250 lines): block-FD Hessian tutorial, output_uv_map tutorial, Schläfli-derivation LaTeX note, porting-status snapshot, locked-vs-flexible architecture review. • Pipe-operator chaining for named parameters (`a | b | c`). • Bundled all PR #13 + #14 work (test-count centralisation, release-policy.md, 24 docstrings, output_uv_map for 3 of 5 models, Stereo/CircleDomain roadmap). Tests: 257/257 PASSED, 0 SKIPPED. check-test-counts.sh: OK.	2026-05-22 11:47:56 +00: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	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	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
user2595	e67ccd6b9d	Merge pull request #12: release v0.9.0 finalisation v0.9.0	2026-05-22 02:29:19 +00: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
user2595	b26368924b	Merge pull request 'Phase 9a-Newton + Phase 8b-Lite: complete the CGAL API surface for all 5 DCE models' (#11) from feature/phase-9a-newton into main ... Reviewed-on: #11	2026-05-21 20:15:48 +00: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
user2595	c5917754d8	Merge pull request #8: Phase 9a — CP-Euclidean (port) + Inversive-Distance (research) ... Adds two new circle-packing functionals: • 9a.1 CP-Euclidean (face-based, BPS 2010) — direct port of CPEuclideanFunctional.java (260 lines + test) • 9a.2 Inversive-Distance (vertex-based) — new research from Luo 2004 + Glickenstein 2011 + Bowers-Stephenson 2004 (no Java original) Validated by 21 new tests including line-by-line Java parity for 9a.1, three special-case verifications of Luo edge-length formula for 9a.2, and Glickenstein §5 cross-correspondence I_ij = cos θ_e at u=0. Combined with PR #9: CGAL test count is now 212.	2026-05-21 19:03:04 +00: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
user2595	1a6e731ad2	Merge pull request #9: Phase 9b — block-FD HyperIdeal Hessian (96× speed-up) ... Replaces O(n·F) full-FD Hessian with O(F·36) block-local variant. Measured 96.5× speed-up on 200-face tet strip (V=202, 603 DOFs). 7 new tests verify block-FD ≡ full-FD on closed/open/pinned configurations, PSD property, and sparsity pattern. Java parity note: HyperIdealFunctional.java:295-298 declares hasHessian()==false. Both Hessian variants in conformallab++ are new research beyond Java parity. Analytic Schläfli-based variant deferred to research-track.md.	2026-05-21 19:01:20 +00: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
user2595	fb8b36226c	Merge pull request 'docs: full audit — fix 4 port/research mis-labels + consolidated research-track' (#10) from feature/doc-audit-and-research-roadmap into main ... Reviewed-on: #10	2026-05-21 18:53:28 +00:00