26 Commits

Author	SHA1	Message	Date
Tarik Moussa	fc77afc55f	docs(roadmap): add phase orchestration system mirroring the reviewer audit workflow ... Brings doc/roadmap/ to the same operational level as doc/reviewer/ by adding the two missing structural files and updating existing docs to close the gap identified in the system review. New files: - doc/roadmap/phase-orchestration.md — master phase table (model assignments, session IDs, status, review-gate checklist); mirrors finding-orchestration.md - doc/roadmap/session-prompts.md — copy-paste-ready prompts for P1–P4 (Haiku/Sonnet/Opus) + universal Opus review gate; mirrors reviewer/session-prompts.md Updated files: - CLAUDE.md: roadmap section now lists porting-status.md, phase-orchestration.md, session-prompts.md; reviewer section adds finding-orchestration.md and session-prompts.md; agentic-workflow section has direct "S3 is next / P1 is next" entry points so agents don't need to derive the next action from scratch - doc/roadmap/phases.md: Current-focus table at the top (7 tracks, next session per track, gating); cross-links to geometry-central-comparison.md, software-landscape.md, complexity.md added in GC and 9b-analytic sections - doc/roadmap/porting-status.md: snapshot date updated to 2026-05-31 (post S1+S2); test count replaced by reference to doc/api/tests.md; §4 gains four new solver rows (newton_core refactor, NewtonStatus enum, diagnostics, selectable clamp mode); §7 gains four new research-extension rows from S1/S2 - doc/roadmap/research-track.md: header companion-docs section links to novelty-statement.md, software-landscape.md, and phase-orchestration.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-01 00:52:02 +02:00
Tarik Moussa	d4ea5fdd2e	ci: remove /ci-all — Pi cannot sustain parallel Docker containers ... The Pi runner (3-4 GB RAM, swap heavily loaded) OOMs when /ci-all triggers test-cgal + quality-gates + doc-build + links simultaneously: four Docker containers start at once after test-fast completes, each consuming 150-400 MB, exhausting available RAM. Fix: /ci-all removed from all three workflow files. Each keyword now triggers exactly one job — no parallel container competition. Safe workflow: one keyword per commit. Typical sequence: git commit -m 'fix: ... /test-cgal' → CGAL tests (~5 min) git commit -m 'chore: /quality-gates' → style checks (~30 s) CLAUDE.md: CI table updated with Pi-runner warning note. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-31 02:00:39 +02:00
Tarik Moussa	7df47c0435	ci: switch to commit-message triggers (replace issue_comment) ... issue_comment triggers had two problems: Gitea did not reliably fire them, and the refs/pull/N/head checkout was fragile. Commit-message keywords are simpler and guaranteed to work on any push event. Trigger keywords (add anywhere in the commit message): /test-cgal → CGAL test suite (277 tests, LOW_MEMORY_BUILD) /quality-gates → license/codespell/shellcheck/cgal-conventions /docs → Doxygen build + warning summary /links → Markdown internal link check test-fast still runs on every push (no keyword needed). All `issue_comment` event handlers and `refs/pull/N/head` checkouts removed from all three workflow files. review/** added to push branch filters so this PR branch triggers normally. CLAUDE.md CI table updated. /test-cgal /quality-gates	2026-05-31 01:17:27 +02:00
Tarik Moussa	018484a94d	ci: switch all non-fast jobs to comment triggers ... Every CI job except test-fast and mirror-to-codeberg now runs only when explicitly requested via a PR comment, instead of on every push or PR sync. This keeps the Pi runner idle during WIP commits and lets the author decide when to pay each job's cost. Trigger commands: /test-cgal → CGAL test suite (277 tests, ~5 min build + 31 s run) /quality-gates → license/codespell/shellcheck/cgal-conventions (~30 s) /docs → Doxygen build + warning summary (~2 min) /links → Markdown internal link check (~10 s) All comment-triggered jobs check: event is issue_comment AND comment is on a PR (issue.pull_request != null) AND comment body contains the trigger word AND checkout uses refs/pull/N/head (not the default branch) Jobs that stay automatic: test-fast — runs on every push (26 pure-math tests, < 5 s) mirror-to-codeberg — unchanged Jobs that keep additional triggers: markdown-links — weekly cron (Mon 05:00 UTC) + workflow_dispatch doc-build — workflow_dispatch (for manual runs outside a PR) quality-gates drops `needs: test-fast` — it now runs independently when comment-triggered (caller decides whether test-fast passed first). CLAUDE.md CI pipeline table updated with all five jobs and their new trigger descriptions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-31 01:17:27 +02:00
Tarik Moussa	2b456abc78	ci(test-cgal): switch to manual comment trigger (/test-cgal on PR) ... Instead of triggering on every pull_request push, test-cgal now fires only when a PR comment contains "/test-cgal". This prevents the Pi runner (3-4 GB RAM, swap constantly loaded) from queuing CGAL builds faster than it can drain them on every WIP commit. Workflow changes: - Add `issue_comment: types: [created]` to the top-level `on:` block - test-cgal `if:` condition: event is issue_comment AND comment is on a PR (issue.pull_request != null) AND comment body contains "/test-cgal" - Checkout uses `refs/pull/N/head` so the PR branch is checked out correctly (issue_comment sets GITHUB_REF to the default branch, not the PR branch) Usage: write "/test-cgal" as a PR comment to trigger the 277-test CGAL suite. The build uses CONFORMALLAB_LOW_MEMORY_BUILD=ON (-O0, no PCH, unity batch 1) and runs in a 2000 MB container. CLAUDE.md: CI table + status paragraph updated accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-31 01:17:27 +02:00
Tarik Moussa	449c5899c0	ci: re-enable CGAL tests with LOW_MEMORY_BUILD for Raspberry Pi runner ... Finding-I from doc/reviewer/external-audit-2026-05-30.md. Root cause: CGAL+Eigen at -O3 drives cc1plus peak RAM to ~700 MB per Unity compilation unit (batch size 4) on ARM64. With the 1600 MB container limit the 2nd or 3rd TU reliably triggered OOM-kill, so test-cgal was gated off via `if: false` since 2026-05-26. Fix: new CMake option CONFORMALLAB_LOW_MEMORY_BUILD=ON applies four orthogonal memory-saving measures to conformallab_cgal_tests: 1. -O0 (no debug info): optimizer passes entirely skipped → cc1plus peak drops from ~700 MB to ~150-200 MB per TU on ARM64. Omitting -g avoids the additional object-file / linker RAM cost. 2. CONFORMALLAB_USE_PCH=OFF: saves the one-time ~200 MB PCH compilation cost; each TU re-parses CGAL headers (fast at -O0). 3. UNITY_BUILD_BATCH_SIZE=1: one source file per cc1plus invocation, removing the "4-file template-explosion" per-unit multiplier. 4. -Wl,--no-keep-memory (GNU ld): linker releases symbol tables after each input file → ~15-25 % less linker RSS. Verified locally with cmake -DCONFORMALLAB_LOW_MEMORY_BUILD=ON: 277/277 CGAL tests pass, 31 s runtime (vs 2 s at -O3 — expected; tests run 15× slower without optimizer but all correct). CI workflow changes (cpp-tests.yml): - test-cgal re-enabled: `if: github.event_name == 'pull_request'` - Configure step adds -DCONFORMALLAB_LOW_MEMORY_BUILD=ON - Container memory: 1600m → 2000m (--memory-swap=3000m for 1 GB swap headroom), using ~half of the Pi's 3-4 GB while leaving OS margin. CLAUDE.md updated: new flag added to compile-time options table; CI status row corrected from DISABLED to active. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-31 01:17:27 +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	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	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	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	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
Tarik Moussa	7edf699ac2	test/docs: Scalability Smoke Tests + Komplexitätsdokumentation ... test_scalability_smoke.cpp (3 neue Tests → 176 CGAL-Tests gesamt): SmokeEuclidean.CatHead_SmallOpen — V=131, Newton 3 iter, <1ms SmokeEuclidean.Brezel_LargeGenus2 — V=6910, Newton 3 iter, 69ms (Apple M) SmokeEuclidean.Brezel2_Genus2_CutGraph — V=2622, Cut Graph 10ms, 4 Nähte - Korrektheit-Assertions (iter<30, ||G||<1e-8), kein Timing-Assert (CI-stabil) - Informative Ausgabe: iter, Residuum, Laufzeit als stdout-Print - Korrektur: brezel.obj ist Genus-2 (χ=−2), nicht Genus-1 (Namensgebung aus Java-Original übernommen, nicht topologisch) - Perturbation x0=−0.05 damit Newton tatsächlich iteriert doc/math/complexity.md (neu): - O()-Analyse aller Pipeline-Schritte tabellarisch - Gemessene Timings auf echten Meshes (Apple M, Release, Single-Thread) - HyperIdeal-FD-Hessian als bekannter Bottleneck dokumentiert - Skalierungsprojektion bis V=100K - Speicherverbrauch-Tabelle - Reproduzierbare Messanleitung README.md + CLAUDE.md: Testzähler 173→176, complexity.md verlinkt Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-18 23:05:22 +02:00
Tarik Moussa	e79c8a5707	docs: CLAUDE.md — vollständige Dokumentations-Karte (23 Dokumente, v0.7.0) ... Abschnitt "Key documentation" → "Documentation map": - 6 Zeilen → 23 Dokumente in 6 kategorisierten Tabellen (Mathematik, Architektur, API, Konzepte, Roadmap, Tutorials) - Jede Tabelle als Frage→Dokument-Format für schnellen Lookup - geometry-central-Kontext auf eigene Sektion verschoben + GC-Roadmap-Link Neuer Abschnitt "Release state": - v0.7.0 Tag dokumentiert - CITATION.cff, CONTRIBUTING.md, scripts/try_it.sh, cmake --install erwähnt Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-18 20:59:18 +02:00
Tarik Moussa	c8e77e715c	docs: CLAUDE.md aktualisiert — Testzähler, Doku-Karte, geometry-central ... - Testzähler korrigiert: 158 CGAL / 2 skips → 173 CGAL / 1 skip - Neue Sektion "Key documentation for mathematical context": Tabelle der wichtigsten Nachschlagewerke für mathematische Aufgaben (discrete-conformal- theory.md, geometry-modes.md, geometry-central-comparison.md, etc.) - Kompakter geometry-central Absatz: was es ist, was es nicht hat, warum Kreuz-Validierung sinnvoll ist — Scope-Information für neue Sessions - Finder-Duplicates-Quirk entfernt (längst behoben) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-18 02:15:48 +02:00
Tarik Moussa	279f964b96	docs(claude): rewrite CLAUDE.md with full project context ... Incorporates README, architecture doc, and Java ConformalLab source structure. Adds: - Long-term CGAL package goal made explicit - Language policy: all code/comments/docs in English - Java-to-C++ porting table (what is done, what is Phase 9, what is Phase 10) - Java class names as reference anchors for future porting work - "Natural theta" and gradient-check test patterns - Halfedge traversal conventions - CI job table with expected pass/skip counts - Both remotes (origin + Codeberg) sync requirement - Known quirks (Finder duplicates, protected main, Boost header-only) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-17 20:58:52 +02:00
Tarik Moussa	26405be149	docs: add CLAUDE.md — context file for Claude Code ... Covers build commands (all three modes), single-test invocation, header-only architecture, the three geometry modes, Newton solver sign conventions, layout BFS design, test patterns, CI structure, and known quirks (Finder ` 2.hpp` duplicates, CGAL compile flags). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-17 20:47:01 +02:00