dd87b8007b1bbb2d123065604e676bfefd046a2f
11 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Tarik Moussa
|
8c01a133d8 |
Phase 9a: dual circle-packing functionals (CP-Euclidean + Inversive Distance)
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m48s
C++ Tests / test-fast (push) Successful in 2m50s
API Docs / doc-build (pull_request) Successful in 34s
C++ Tests / test-cgal (pull_request) Failing after 10m52s
C++ Tests / test-cgal (push) Has been skipped
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>
|
||
|
Tarik Moussa
|
4f0a3035e4 |
docs: full audit — fix 4 wrong port/research labels + consolidated research-track
Some checks failed
C++ Tests / test-fast (push) Successful in 2m50s
C++ Tests / test-fast (pull_request) Successful in 2m36s
API Docs / doc-build (pull_request) Successful in 1m10s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / test-cgal (pull_request) Failing after 10m25s
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>
|
||
|
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>
|
||
|
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>
|
||
|
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> |
||
|
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> |
||
|
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>
|
||
|
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> |
||
|
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> |
||
|
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> |
||
|
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> |