4 Commits

Author	SHA1	Message	Date
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	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	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	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