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>
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>
Unified the codebase language to English throughout. German text appeared
in code comments, test file headers, CI step names, and several markdown
documents. All natural-language text is now English; proper nouns
(Institut für Mathematik, Technische Universität Berlin) are unchanged.
Files changed:
- .gitea/workflows/cpp-tests.yml — CI step names and job comments
- code/include/mesh_utils.hpp — inline comment
- code/tests/cgal/CMakeLists.txt — section comment block
- code/tests/cgal/test_geometry_utils.cpp — full file header + all test comments
- doc/math/references.md — geometry-central section
- doc/math/validation.md — Section 9 (geometry-central cross-validation)
- doc/roadmap/phases.md — Optional geometry-central track (GC-1/2/3)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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>
doc/concepts/declarative-pipeline.md — vollständige Design-Spezifikation:
1. Kernidee: Processing Units mit expliziten require/provide-Contracts
2. Token-Vokabular: 30 Tokens in 7 Kategorien
input, setup, Gauss-Bonnet, solver, topology, layout, period/domain/output
3. YAML-Schema: Vollständige Syntax inkl. Parameterdefaults aller Units
4. Validierungsalgorithmus: monoton wachsendes provided-Set, Pre-Execution-Check
5. 5 vollständige Beispiele:
A — Euklidische Uniformisierung Torus (τ-Ausgabe)
B — Sphärische Uniformisierung (cathead.obj)
C — Hyperbolische Uniformisierung Torus (Poincaré-Disk)
D — Volle Pipeline mit Periodenmatrix + 5×5-Kachelung
E — Absichtlich fehlerhaftes Beispiel mit Validator-Fehlermeldungen
6. C++-Mapping: alle YAML-Unit-Namen → C++-Funktionen + Header
7. Implementierungsplan (Phase 8e): pipeline.hpp + CLI-App + YAML-Abhängigkeit
8. Design-Entscheidungen: YAML vs. JSON/TOML, explizit vs. auto-inference,
linear vs. DAG, eine Geometrie pro Datei
doc/api/cgal-package.md: Link zum Konzeptdokument ergänzt.
README.md: Link in Dokumentationstabelle ergänzt.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Ziel: einem interessierten Mathematiker ermöglichen, die bisherige Arbeit
unabhängig zu validieren und eigene Forschung beizutragen.
Neu:
doc/math/discrete-conformal-theory.md
Kompakte mathematische Einführung (DCE, Variationsprinzip, drei
Geometriemodi, Holonomie, Periodenmatrix) für Riemann-Flächen-Kenner.
doc/math/validation.md
Analytisch bekannte Sollwerte + wie man sie mit dem Code prüft:
Gauss–Bonnet (χ), τ ∈ Fundamentaldomäne (3 Invarianten), Symmetrie-
Argumente für τ=i (4-fach) und τ=e^{iπ/3} (6-fach), Newton-Konvergenz,
Gradienten-Check (FD), Holonomie-Kommutator. Reviewer-Checkliste.
CONTRIBUTING.md (Root)
Gitea/GitHub-Standard: CONTRIBUTING.md im Root-Verzeichnis als
Kurzreferenz mit Links zu doc/contributing.md und den Math-Docs.
code/data/off/torus_4x4.off — 16 Vertices, 32 Flächen, Genus 1
code/data/off/torus_8x8.off — 64 Vertices, 128 Flächen, Genus 1
code/data/off/torus_hex_6x6.off — 36 Vertices, 72 Flächen, 6-fach Sym.
Aktualisiert:
README.md — 158 → 170 Tests, zwei neue Math-Links in Tabelle
doc/api/tests.md — 28 Suiten, 170 Tests, 1 Skip (korrigiert)
doc/contributing.md — Testzähler 158+2 → 170+1
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
doc/api/headers.md — all 24 public headers with descriptions
doc/api/tests.md — 26 test suites, individual counts, run instructions
doc/architecture/design-decisions.md — 5 key design choices with rationale
doc/architecture/project-structure.md — full directory tree + build targets
README + overall_pipeline.md link tables updated.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
README.md: reduced from 703 to ~75 lines — what/why, status, quick
start, minimal usage example, navigation table to doc/ files.
doc/architecture/overall_pipeline.md: trimmed — roadmap, extension
points, declarative pipeline YAML, and references sections removed
(each now has its own dedicated file). Replaced with a link table.
New files:
doc/getting-started.md — build modes, single-test invocation, CLI
doc/api/pipeline.md — full pipeline API with code for all 3 geometries
doc/api/extending.md — new functionals, geometry modes, Java porting guide
doc/api/contracts.md — processing unit preconditions/provides table
doc/api/cgal-package.md — Phase 8 CGAL package design + YAML pipeline (TODO)
doc/math/geometry-modes.md — Euclidean/Spherical/HyperIdeal comparison
doc/math/references.md — all papers by module
doc/roadmap/phases.md — Phases 1–10 with porting/research boundary
doc/roadmap/java-parity.md — Java vs C++ feature parity table
doc/contributing.md — language policy, test standards, release flow
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Structured the development roadmap into four blocks with an explicit
boundary marker separating direct Java ports (Phase 1–7) from
infrastructure (Phase 8), remaining porting (Phase 9), and new
research territory (Phase 10+).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
README:
- Neuer Einstieg mit vollständiger Dissertation-Referenz (Titel, TU Berlin 2016,
DOI 10.14279/depositonce-5415, CC BY-SA 4.0)
- Links zu Original-Java-Repo, sechel.de und linkedin.com/in/sechel
- Neuer Abschnitt "Ursprung & Danksagung" vor der Lizenz
doc/architecture/overall_pipeline.md:
- Neuer "Origin"-Abschnitt ganz oben mit vollständiger Quellenangabe
- Literaturabschnitt erweitert: Dissertation als "Primary source" hervorgehoben,
Java-Original-Repo als direkter Port-Bezug dokumentiert
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Ersetzt den generischen Geometry-Framework-Entwurf durch eine präzise
Beschreibung der tatsächlichen konformen Geometrie-Pipeline:
- Klare Positionierung: spezialisiertes Werkzeug für diskrete konforme
Abbildungen, kein generisches Mesh-Processing-Framework
- Korrigiertes Mermaid-Diagramm: alle 3 Phasen mit realen Komponenten
(load_mesh → setup_maps → GB-check → Newton → CutGraph → Layout →
halfedge_uv → Holonomie → Periodenmatrix → Fundamentalbereich → Export)
- Preconditions/Capabilities-Tabelle für alle Processing-Units
- Drei Geometrie-Modi (Euklidisch/Sphärisch/Hyper-ideal) im Vergleich
- MobiusMap, halfedge_uv, Priority-BFS, SL(2,ℤ)-Reduktion dokumentiert
- Realistischer YAML-Pipeline-Entwurf als Phase-8-Ziel (Tokens statt Prosa)
- Erweiterungspunkte: neues Funktional, neue Geometrie, neues Unit
- Alle Literaturverweise direkt auf Implementierungsstellen gemappt
- "Nice To Have but maybe too much" komplett entfernt
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
