Commit Graph

27 Commits

Author SHA1 Message Date
Tarik Moussa
adbf682f0f test: add degenerate-triangle limiting-angle and edge-DOF guard tests
Finding-F and Finding-G from doc/reviewer/external-audit-2026-05-30.md
(java-port-audit missing-test items 1 and 2).

Finding-F — Degenerate triangle: limiting angles (item 1)
  test_euclidean_functional.cpp:
    DegenerateTriangle_LimitingAngles_L{12,23,31}TooLong
      — verifies α_opposite = π, other two = 0, valid = false
      for all three edge-over-long cases
    DegenerateTriangle_GradientPicksUpPiCorner
      — end-to-end mesh test: forces effective l12 >> l23+l31 via
        lambda0, evaluates gradient, asserts G_v3 = π (not 2π from
        a skipped degenerate face) and G_v1=G_v2 = 2π

  test_spherical_functional.cpp:
    DegenerateTriangle_LimitingAngles_S{12,23,31}TooLong
      — same coverage for spherical_angles()

Finding-G — euclidean_hessian edge-DOF guard (item 2)
  test_euclidean_hessian.cpp:
    EdgeDOFGuard_Throws
      — assign_euclidean_all_dof_indices + euclidean_hessian → throw
    EdgeDOFGuard_VertexOnlyDoesNotThrow
      — vertex-only layout → no throw (regression guard)

275/275 CGAL tests pass, 0 failed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
7534c62c3d fix(gradient-checks): use relative error in all FD check functions
Finding-E from doc/reviewer/external-audit-2026-05-30.md.
Scan also uncovered the same issue in inversive_distance_functional.hpp.

Three functions used absolute error `|analytic - fd| > tol` while the
rest of the library (euclidean_functional, spherical_functional,
euclidean_hessian, hyper_ideal_functional) all use relative error
`|analytic - fd| / max(1, |analytic|) > tol`.

Absolute error is too strict for large gradients (false failures) and
too lenient for small gradients.

Fixed:
  cp_euclidean_functional.hpp  gradient_check_cp_euclidean()
  cp_euclidean_functional.hpp  hessian_check_cp_euclidean()
  inversive_distance_functional.hpp  gradient_check_inversive_distance()

All three now use the relative criterion and accumulate all failures
before returning (ok=false instead of early return on first mismatch).
Default tol updated from 1e-6/1e-5 to 1e-4, matching the Java
FunctionalTest convention used by all other checks in the library.
Error message updated to print rel-err instead of raw diff.

266/266 CGAL tests pass, 0 failed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
cfbbc1b21f fix(dof-assign): correct "pin before" docs + add gauge-vertex overloads
Finding-D from doc/reviewer/external-audit-2026-05-30.md.

All three DOF-assignment functions iterated over every vertex
unconditionally, overwriting any v_idx set before the call.  The
documentation said "pin before OR after" — the "before" option was
silently wrong (the pin would be overwritten).  For the
inversive-distance variant the doc explicitly said the pre-call pin
would make the function "a no-op for that vertex", which was false.

Changes (three headers):
- euclidean_functional.hpp  assign_euclidean_vertex_dof_indices()
- spherical_functional.hpp  assign_vertex_dof_indices()
- inversive_distance_functional.hpp  assign_inversive_distance_vertex_dof_indices()

For each:
  1. Single-arg overload: doc corrected to "pin AFTER, not before;
     pre-call pins are overwritten"
  2. New two-arg overload accepting a Vertex_index gauge: pins the
     requested vertex (v_idx=-1) in a single pass, preventing the
     user error entirely

Three new GTests in test_euclidean_functional.cpp:
  SingleArg_PinBeforeHasNoEffect        — documents the old pitfall
  TwoArg_GaugeIsPinnedOthersAreSequential — verifies the new overload
  TwoArg_NewtonConvergesWithGaugeOverload — end-to-end correctness

266/266 CGAL tests pass, 0 failed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
bef5a0ceb7 docs(euclidean-hessian): fix wrong cotangent formula in two comment blocks
Finding-C from doc/reviewer/external-audit-2026-05-30.md.

The box comment at the top and the function-level comment above
euclidean_cot_weights() both stated:

  cot_k = (t_adj1·l123 − t_adj2·t_opp) / denom2   ← WRONG

The correct formula (verified numerically on a 3-4-5 right triangle,
expected cot1=4/3, cot2=3/4, cot3=0) is:

  cot_k = (t_opp · l123 − t_a · t_b) / denom2

where t_opp is the t-value of the edge OPPOSITE vertex k, and t_a/t_b
are the t-values of the two edges ADJACENT to vertex k.

The implementation in euclidean_cot_weights() was already correct;
only the documentation was wrong.

Changes (documentation only, zero code changes):
- Box comment: rewritten with correct formula and explicit per-vertex
  assignment (cot1: t_opp=t23, t_a=t12, t_b=t31; etc.)
- Box comment: added missing ½ factor to Hessian contribution lines
- Function-level comment: corrected to (t_opp·l123 − t_a·t_b)/(8·Area)
  with a pointer to the box comment for the full assignment
- Inline return comment in euclidean_cot_weights(): now shows the
  mapping (cot1: t_opp=t23, t_a=t12, t_b=t31) directly at the formula

263/263 CGAL tests pass, 0 failed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
46c0b63de8 fix(gauss-bonnet): delete HyperIdeal overloads — wrong identity for hyperbolic metrics
Finding-B from doc/reviewer/external-audit-2026-05-30.md.

The Euclidean Gauss–Bonnet identity Σ(2π−Θ_v) = 2π·χ is ONLY valid for
flat/Euclidean and spherical metrics.  For hyperbolic metrics (HyperIdeal)
the correct identity is Σ(2π−Θ_v) − Area(M) = 2π·χ.  The previously
provided gauss_bonnet_sum(HyperIdealMaps) overload would silently pass the
wrong LHS to check_gauss_bonnet, which would always throw "deficit = ±Area"
for valid hyperbolic targets.

Fix:
- gauss_bonnet_sum(mesh, HyperIdealMaps)        → = delete + explanation comment
- enforce_gauss_bonnet(mesh, HyperIdealMaps&)   → = delete + explanation comment
- Header box comment rewritten with the correct hyperbolic Gauss–Bonnet
  identity and a clear "HyperIdeal: NOT SUPPORTED" section

New test in test_phase6.cpp:
- HyperIdeal_EuclideanSumDiscrepancy_DocumentsWhyCheckIsDeleted
  verifies numerically that the Euclidean sum = 0 but 2π·χ = 4π for a
  regular tetrahedron, documenting the −4π discrepancy that motivated
  the deletion
- Three compile-time static_asserts (SFINAE) confirm the overload is not
  invocable with HyperIdealMaps but remains so with Euclidean/SphericalMaps

263/263 CGAL tests pass, 0 failed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
faf96ee28c doc(roadmap): add research item for 2/3-ideal hyper-ideal volume formulas
Follow-up to the Finding-A fix (face_energy guard).  The throw is the
correct safe behaviour for now; the mathematically complete solution
requires formulas for semi-ideal and fully-ideal tetrahedra that are
absent from the Java reference.

Adds a structured research entry to research-track.md (Phase 9b+):
- primary references: Kolpakov-Mednykh arXiv:math/0603097, Milnor 1982,
  Vinberg 1985
- acceptance criteria: two new volume functions + gradient-check tests +
  limiting-behaviour continuity witness
- explicit note that the throw in face_energy() must not be removed
  without implementing and testing the replacement formulas

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
9afefcbb7b fix(hyper-ideal): guard face_energy() against unsupported multi-ideal faces
Finding-A from doc/reviewer/external-audit-2026-05-30.md.

Root cause: both the Java reference (HyperIdealFunctional.java:222-231)
and the C++ port silently applied the one-ideal-vertex volume formula
to the first ideal vertex found in a face, ignoring any additional ideal
vertices.  For two or three ideal vertices this produces a wrong energy
value with no diagnostic.

Fix: add an ideal_count guard at the top of face_energy() that throws
std::logic_error for ideal_count >= 2.  The one-ideal (Kolpakov-Mednykh)
and zero-ideal (Meyerhoff/Ushijima) paths are unchanged and correct.

Three new GTests cover the three guard cases:
  MultiIdealGuard_TwoIdealVertices_Throws        (two ideal  → throw)
  MultiIdealGuard_AllThreeIdealVertices_Throws   (all ideal  → throw)
  MultiIdealGuard_ExactlyOneIdeal_DoesNotThrow   (one ideal  → no throw)

262/262 CGAL tests pass, 0 failed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
7f1a077269 doc(reviewer): add external audit 2026-05-30
Full external code review of v0.10.0 against all math-critical headers
(direct source read, not automated scan). Documents 5 open bugs/API errors,
3 test gaps inherited from java-port-audit.md, 1 architectural CI risk,
and 5 minor findings. Each finding is self-contained with file+line
references, a concrete fix proposal, and acceptance criteria so a new
session can pick up any single finding without prior context.

Key findings:
- FINDING-A (critical): face_energy() wrong for mixed ideal/hyper-ideal configs
- FINDING-B (medium):   Gauss–Bonnet API conceptually wrong for HyperIdeal
- FINDING-C (medium):   cotangent formula in euclidean_hessian.hpp header is wrong
- FINDING-D (medium):   DOF-assignment doc falsely claims "pin before" works
- FINDING-E (medium):   cp_euclidean gradient_check uses absolute not relative error
- FINDING-F/G/H:        three open test gaps from java-port-audit.md
- FINDING-I (arch):     246/272 CGAL tests not gated in CI

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-31 01:17:27 +02:00
Tarik Moussa
8619043b79 docs(crossvalidation): fix stale test count 243→259 after PRs #29-31 merged
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m17s
API Docs / doc-build (pull_request) Successful in 1m1s
Markdown link check / check (pull_request) Successful in 43s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 1m52s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:36:51 +02:00
Tarik Moussa
c472748e46 docs(reviewer): refresh §4 to mark Tier-1/3 done (stale TODO removed)
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m1s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 58s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m14s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:32:02 +02:00
Tarik Moussa
082649ef40 docs(reviewer): mark Tier-3 done (PR #30); fix duplicated tier table
- Tier-3 (Lawson HyperIdeal) plain + branch-points marked DONE (PR #30,
  test_lawson_hyperideal.cpp); status, §3 HIGH/MED rows, §3b table and §4
  recommended-order updated accordingly.
- Hyperelliptic variant documented as deferred (option c): needs an XML-format
  reader for lawson_curve_source.xml + a port of HyperIdealHyperellipticUtility
  (jReality geometry θ); golden vector is non-symmetric.
- Removed a pre-existing duplicated/stale copy of the tier-table rows.
- Added a status summary (Tier 1  PR #29 · Tier 2 → Phase 9f/13 · Tier 3  PR #30).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:32:02 +02:00
Tarik Moussa
267ae965ab docs(reviewer): Tier-2 exhausted (genus≥2 → Phase 13); Tier-3 Lawson scoped as mini-project
- regular_uniformization.xml / LetterB01_canonical_group.xml are genus≥2
  hyperbolic Fuchsian-group uniformizations (12-edge fundamental polygon), not
  genus-1 → Phase 13, not Tier 2.
- Tier-2 is therefore exhausted (only Wente, deferred to Phase 9f quad/cyclic).
- Tier-3 Lawson HyperIdeal golden vectors require a low-level halfedge genus-2
  multi-edge generator (4 verts/12 edges) + jtem Triangulator replication;
  scoped as a dedicated follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:32:02 +02:00
Tarik Moussa
822a27da69 feat(euclidean): full analytic edge-DOF (cyclic) Hessian; Tier-2 Wente finding
Upgrades the cyclic Euclidean Hessian from block-FD to closed-form, satisfying
the novelty-statement §3.2 "analytic Hessians, not finite difference" claim for
the Euclidean path.

- euclidean_hessian.hpp: `euclidean_hessian_analytic` — closed-form cyclic
  Hessian from the law-of-cosines angle derivatives
    ∂α_i/∂s_i = ℓ_i²/4A,  ∂α_i/∂s_j = ½cot α_i − ℓ_j²/4A   (Σ_j = 0),
  chained to (u, λ_e) and sign-mapped to the gradient outputs (−α vertex,
  +α_opp edge). Reuses euclidean_cot_weights. Block-FD kept as cross-check.
- newton_solver.hpp: newton_euclidean cyclic path now uses the analytic Hessian.
- tests: CyclicHessian_Analytic_MatchesBlockFD_Tetrahedron — analytic == block-FD
  (1e-6), == gradient FD (1e-5), symmetric (1e-9). Existing cyclic convergence
  oracle still GREEN with the analytic Hessian routed in.

Tier-2 (Wente) finding: wente_torus02.obj is a QUAD mesh (1240 quads) and the
Java golden comes from cyclic (quad-net) uniformization; the C++ period-matrix
pipeline is triangle-based, so a faithful bit-vs-Java τ comparison needs a
quad/cyclic pipeline (Phase 9f). Deferred and documented; golden τ = ½+i√3/2.

244/244 cgal tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:32:02 +02:00
Tarik Moussa
ea5f01d73d feat(euclidean): block-FD edge-DOF Hessian → cyclic Newton + Java convergence oracle
Implements the edge-DOF (cyclic) Euclidean Hessian, unblocking the full cyclic
Newton solve, and enables the Java EuclideanCyclicConvergenceTest cross-validation.

- euclidean_hessian.hpp: `euclidean_hessian_block_fd` / `_sym` — per-face 6×6
  block FD over (u1,u2,u3,λ12,λ23,λ31), mirroring hyper_ideal_hessian_block_fd.
  Per-face outputs carry the gradient signs (−α vertex, +α_opp edge), so the
  result equals ∂G/∂x by construction (locality lemma). Analytic vertex-only
  cotangent Hessian unchanged (still used for vertex-only layouts).
- newton_solver.hpp: newton_euclidean routes cyclic layouts (edge DOFs present)
  through the block-FD Hessian; vertex-only path unchanged.
- tests:
  * CyclicCircularEdge_CatHead_JavaXVal (now GREEN) — prescribe φ=π−0.1 on one
    interior edge, solve, assert realised α_opp+α_opp = π−0.1 @1e-9.
  * CyclicCircularEdge_PhiEntersGradient_CatHead — solver-free φ-wiring check.
  * CyclicHessian_BlockFD_MatchesGradientFD_Tetrahedron — Hessian correctness.

243/243 cgal tests pass; vertex-only Euclidean Newton unaffected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:32:02 +02:00
Tarik Moussa
5d74a94b78 test(euclidean): Tier-1 circular-edge φ cross-validation + cyclic-solve blocker
Build-verified attempt to port the Java EuclideanCyclicConvergenceTest
(cathead, "circular hole edge" φ = π−0.1).

-  GREEN `CyclicCircularEdge_PhiEntersGradient_CatHead`: solver-free
  cross-validation that the circular-edge φ target enters the cyclic edge
  gradient exactly (ΔG_e = −Δφ_e at 1e-12; no other component moves).
- ⏸️ DISABLED `CyclicCircularEdge_CatHead_JavaXVal`: the full Java convergence
  assertion (α_opp+α_opp = π−0.1), kept with golden semantics. Auto-activates
  once the edge-DOF Hessian lands.

Build-verification finding: `newton_euclidean` -> `euclidean_hessian` throws
"edge DOFs are not supported" — the cyclic full solve is blocked by a missing
edge-DOF Euclidean Hessian (gradient supports edge DOFs, analytic Hessian does
not). Spherical convergence (Tier-1 #2) is already covered by test_newton_solver.
Documented in doc/reviewer/java-ignore-crossvalidation.md.

All 13 EuclideanFunctional tests pass (1 disabled).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:32:02 +02:00
Tarik Moussa
41ad4a84d2 docs(reviewer): cross-validation analysis of Java @Ignore tests
Classifies the 22 Java @Ignore'd test files by root cause (ARM64 PETSc
native lib vs logic/known-issue) and by cross-validation value for the
C++ port.

- Notes what PR #27 already locks (math cores + functional-eval oracles)
  to avoid duplication.
- Priority ranking: HIGH (HyperIdeal Lawson convergence golden vector —
  records the exact u*), MEDIUM (genus-1 Wente uniformization, branch-point
  variant), LATER (genus-2/hyperelliptic/Mobius/quasi-isothermic/Schottky),
  NON-ORACLE (Java gaps: testHessian, testDoLayout; ARM64-flaky known issues).
- Documents why the Lawson mesh needs a low-level half-edge generator
  (4 vertices / 12 edges => multi-edges; CGAL add_face cannot build it).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 17:28:54 +02:00
a993a101e9 Merge pull request 'docs: citation audit (8 mis-citations fixed) + Phases 12/13' (#28) from docs/citation-audit-phases-12-13 into main
Some checks failed
C++ Tests / test-fast (push) Successful in 2m15s
API Docs / doc-build (push) Has been skipped
Markdown link check / check (push) Successful in 47s
Mirror to Codeberg / mirror (push) Successful in 27s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / quality-gates (push) Failing after 1m51s
Reviewed-on: #28
2026-05-30 08:06:33 +00:00
Tarik Moussa
26f4f0637d docs: citation audit + correct 8 mis-citations; add Phases 12/13
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 1m55s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 50s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 1m56s
External reviewer pass over the literature references. Verified entries
against arXiv/DOI/publisher and corrected misattributions that had
propagated across the docs.

Corrected citations (consistent across all docs):
- Bowers-Bowers-Lutz 2026: title was the 2017 paper's
  -> "Rigidity of Koebe Polyhedra and Inversive Distance Circle Packings"
- Liouville theorem: "Springborn 2019" -> Pinkall & Springborn,
  Geom. Dedicata 214 (2021)
- Bobenko-Pinkall-Springborn: "G&T 14 (2010)" -> G&T 19(4) (2015), 2155-2215
- Optimal Cone Singularities: "Crane, Soliman, Ben-Chen, Schroeder"
  -> Soliman, Slepcev, Crane, ACM TOG 37(4)
- Schlaefli formula: "Rivin, Springborn 1999" -> Rivin, Schlenker
- Quasiconformal distortion: "Springborn, Veselov" -> Born, Buecking,
  Springborn (arXiv:1505.01341)
- Period matrices: "Bobenko, Buecking 2009" (was Bobenko-Mercat-Schmies'
  title) -> Bobenko-Mercat-Schmies 2011 + genuine Bobenko-Buecking 2021
- Fabricated entry: "Alexa 2020, DOI 10.1145/3414685.3417840" pointed to
  an unrelated paper (Pixelor) -> Bunge, Herholz, Kazhdan, Botsch 2020
- Stripe Patterns: "Bonneel et al. 2015" -> Knoeppel, Crane, Pinkall,
  Schroeder 2015

Equation-number corrections (verified against the PDFs):
- Glickenstein 2011 "eq. 4.6" -> "§5.2" (no such equation label exists)
- Springborn 2020 "eq. 4.6" -> "§4 variational gradient"
- inversive-distance attribution softened to classical inversive distance

Other:
- DBFEnergy bibliography (separate repo) and convergence half-sentence in
  novelty-statement.md §3.3 (Bobenko-Buecking 2021)
- Status legend (implemented vs planned) at top of references.md
- New Phase 12 (decorated DCE & geometric transition, Chain A, near-term)
  and Phase 13 (canonical tessellations & polyhedral realisation, Chain B
  capstone) in phases.md + research-track.md; 10c scope-boundary note
  clarifying infrastructure vs Lutz-specific algorithms

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 1m57s
API Docs / doc-build (pull_request) Successful in 59s
Markdown link check / check (pull_request) Successful in 51s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 2m19s
Add bit-for-bit (1e-12) golden-value oracle tests pinning the C++ pure-math
and functional cores against the compiled upstream Java library (openjdk 17):

- HyperIdealGoldenJava: Clausen/Л/ImLi2, ζ13/14/15/ζ, both tetrahedron-volume
  formulas (real de.varylab…Clausen / HyperIdealUtility).
- EuclideanGoldenJava / SphericalGoldenJava: angle formulas + β relations + Л
  energy terms, plus FULL-MESH oracles driving the real EuclideanCyclicFunctional
  / SphericalFunctional on a shared tetrahedron — per-vertex gradient (Θ−Σα) and
  ΔE = E(x)−E(0) (C++ Gauss-Legendre path integral vs Java closed form).
- SphericalGoldenJava.FullMeshEdgeDofGradient: edge-DOF gradient (vertex + edge
  components, α_opp⁺+α_opp⁻−θ_e) vs raw conformalEnergyAndGradient — locks
  Finding 3 at the solution level (audit items 4 & 5).
- PeriodMatrix.NormalizeModulus_GoldenJava: τ-reduction fold convention vs the
  real DiscreteEllipticUtility.normalizeModulus (audit items 7 & 8).

Subtlety documented: the spherical oracles call Java's raw
conformalEnergyAndGradient, not evaluate() (which pre-runs a Brent gauge
maximization that C++ factors into the Newton solver's spherical_gauge_shift).

Also:
- P1-2 (layout.hpp): Euclidean holonomy now uses a per-cut-edge rigid-motion fit
  g(z)=a·z+b, exposing residual_rotation = |arg(a)| as a diagnostic; non-
  regressive (flat case a=1 reduces to the old midpoint formula).
- P1-3 (period_matrix.hpp): is_in_fundamental_domain fixed to the correct
  half-open SL(2,ℤ) domain (−½ ≤ Re < ½). Updated the now-exposed
  ComputePeriodMatrix_ReducedTau_InFD to assert the normalizeModulus domain
  (closed +½ edge) instead.

Test counts (single source of truth = doc/api/tests.md): 272/272 pass, 0
skipped (26 non-CGAL + 246 CGAL).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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)
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 1m57s
API Docs / doc-build (pull_request) Successful in 1m3s
Markdown link check / check (pull_request) Successful in 44s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 2m11s
Bundles the 2026-05-29 Java↔C++ math-correctness audit (doc/reviewer/
java-port-audit.md, 11 findings) with two follow-up fixes.

Audit code changes:
- Finding 3 (spherical_functional): edge-DOF replacement parameterization via
  spher_eff_lambda; edge gradient α_opp⁺+α_opp⁻−θ_e (drops additive −(S⁺+S⁻)/2)
- Finding 4 (spherical_hessian): always-compiled edge-DOF throw guard
- Finding 6 (period_matrix): faithful normalizeModulus (0≤Re≤½, Im≥0, |τ|≥1)
- Finding 9 (inversive_distance): degenerate-face limiting angles, no skip
- Findings 1/2 (euclidean): degenerate gradient limiting angles + Hessian guard

Euclidean holonomy/τ fix: develop the cut surface across the dual spanning tree
only (cut_graph now exposes is_dual_tree), so genus-1 cut edges yield
non-degenerate lattice generators. Previously τ came out 0 / NaN / 1e13 on the
bundled tori; now matches the analytic revolution modulus i·√(R²−r²)/r. Re-enabled
τ reporting in the Euclidean CLI; rewrote validation.md §3/§4 accordingly.

Tests (240 CGAL, 0 skipped):
- HolonomyEndToEnd ×3 — tori of revolution (4×4, hex 6×6, 8×8) vs analytic modulus
- SphericalFunctional.EdgeGradient_RegularTetClosedForm — independent closed-form
  π/3 oracle locking the Finding-3 edge formula (the path-integral FD check cannot
  detect a wrong-but-conservative gradient)

Also documents the latent spherical/hyperbolic holonomy-extraction bug (same
single-development pattern, dead code today) in research-track.md (Phase 9c/10),
and adds favour/normalisations to the codespell ignore list.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-29 12:50:16 +02:00
Tarik Moussa
11d660af49 fix(hub): correct double-branch/branch/main URL prefix + v0.10.0 badge
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m20s
API Docs / doc-build (pull_request) Successful in 49s
C++ Tests / test-cgal (pull_request) Failing after 8m18s
C++ Tests / quality-gates (pull_request) Successful in 1m52s
Two bugs in the reviewer hub HTML:

1. The earlier sed-rewrite that lifted the hub from
   `preview/reviewer-snapshot-v6` into `branch/main` accidentally
   produced `branch/branch/main` — sed pattern matched the
   `preview/reviewer-snapshot-v6` slug but the surrounding URL
   already had `/src/branch/` prefix.  All 25 in-hub links to the
   repo were broken with 404 on codeberg.org.

   Fix: `s|/src/branch/branch/main/|/src/branch/main/|g`.

2. The version pill in the badge strip still read v0.9.0 (stale
   from the original v0.9.0-era hub template).  Updated to v0.10.0.

The fix is in this in-repo source-of-truth file so any future manual
republication of the pages branch picks up the corrected hub.  The
just-pushed pages branch already has the fix applied; codeberg's
`tmoussa.codeberg.page` frontend cache (max-age=600 s) will refresh
over the next 10 minutes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 11:50:59 +02:00
Tarik Moussa
3f508adf18 ci+hub: durable reviewer hub via in-repo HTML + perf-CI matrix on Linux
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m16s
API Docs / doc-build (pull_request) Successful in 51s
Markdown link check / check (pull_request) Successful in 45s
C++ Tests / test-cgal (pull_request) Failing after 7m40s
C++ Tests / quality-gates (pull_request) Failing after 2m1s
Two additions that close out the reviewer-prep work cleanly:

1. doc/reviewer/hub.html  +  publish-workflow integration
   ──────────────────────────────────────────────────────
   Move the hand-curated reviewer hub from the codeberg `pages`
   branch (where it lived as an opaque snapshot) into the repo as
   `doc/reviewer/hub.html`.  `.gitea/workflows/doxygen-pages.yml`
   gains a conditional `if [ -f doc/reviewer/hub.html ]; then …`
   step that installs it as the publish `index.html` and demotes
   the auto-generated Doxygen index to `/doxygen.html`.

   Effect: merging any of the open PRs into main will trigger the
   workflow, which republishes BOTH the Doxygen + the reviewer hub
   together.  The reviewer URL stays live across merges with zero
   manual intervention.

   Source-controlled benefits:
     * hub edits go through normal PRs, not orphan-branch
       force-pushes
     * old hub versions live in git history
     * the in-repo links now target `branch/main/…` instead of the
       transient `preview/reviewer-snapshot-vN/…` paths

2. .gitea/workflows/perf-compile-time.yml — Linux CI bench
   ────────────────────────────────────────────────────────
   New workflow runs on every push to main that touches the build
   system or public headers.  Five-step matrix measures and reports:
     Run 1   cold baseline (no PCH, no Unity, no ccache)
     Run 2   + PCH only
     Run 3   + PCH + Unity (current default)
     Run 4   + FAST_TEST_BUILD=ON  (-O0 -g — Linux's expected ~40 % win)
     Run 5   + ccache warm rerun   (expected ≥ 90 % cache hit)

   Validates the Apple-M1 predictions in doc/architecture/compile-time.md
   against the Linux + g++ runner where Backend dominates more and
   the Apple-clang+PCH friction that defeats ccache locally does not
   apply.  Job is data-collection only; never blocks a merge.

doc updates:
  * doc/architecture/compile-time.md — new "Cross-platform perf bench"
    section linking to the workflow + the table of macOS-vs-Linux
    expected deltas.
  * doc/reviewer/README.md — new "Hub-Page durability" subsection
    explaining how the hub survives merges.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
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