diff --git a/CLAUDE.md b/CLAUDE.md index 53a6bb6..b2a2a6b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -253,19 +253,34 @@ Phase 7 is complete. Phase 7.5 (Doxygen) and Phase 8 (CGAL package) are next. ## Phase 8 strategic decisions (2026-05-19) -The CGAL-package architecture was frozen on 2026-05-19 after the end-of-Phase-7 -docstring audit. Full design: [`doc/api/cgal-package.md`](doc/api/cgal-package.md). -Key decisions: +The CGAL-package architecture was frozen on 2026-05-19. Full design: +[`doc/api/cgal-package.md`](doc/api/cgal-package.md). Key decisions: | Decision | Choice | |---|---| | Submission to upstream CGAL | **Pre-submission-ready, not bound.** 12+ months horizon. | | License | **MIT preserved** (no LGPL switch). | -| Mesh-type flexibility | **Generic `FaceGraph + HalfedgeGraph`** — Surface_mesh, Polyhedron_3, OpenMesh-adapter, pmp. | +| Mesh-type flexibility | **Generic `FaceGraph + HalfedgeGraph`** in target design; MVP starts Surface_mesh-only. | | Parameter style | **Named Parameters** (`CGAL::parameters::...`). | | Default kernel | **`Simple_cartesian`** (status quo). | -| Backward compatibility | **Dual-layer wrapper** — `code/include/*.hpp` stays as implementation, `include/CGAL/*.h` is thin wrapper. No algorithm duplication. | -| Phase-8a acceptance test | **Phase 9a (Inversive-Distance)** as the first new client of the new traits API. | +| Backward compatibility | **Dual-layer wrapper** — `code/include/*.hpp` stays as implementation, `include/CGAL/*.h` is thin wrapper. No algorithm duplication. | +| Implementation strategy | **Hybrid MVP** — minimum Phase 8 (traits + one wrapper) first, then Phase 9 in full, then Phase 8 extensions only on concrete demand. | +| Phase-8 MVP acceptance test | **Phase 9a (Inversive-Distance)** as the first new client of the new traits API. | + +### Implementation sequence (committed) + +``` +1. Phase 7.5 Doxygen + cleanup done ✅ +2. Phase 8 MVP — traits + one euclidean wrapper 3–5 days +3. Phase 9a — Inversive-Distance against new traits 3–5 days +4. Phase 9b — analytic HyperIdeal Hessian 1 week +5. Phase 9c — 4g-polygon for genus g > 1 1 week + → port really complete, v0.9.0 release +``` + +Phase 8 extensions (8a.2 generic FaceGraph, 8c full Doxygen manuals, 8d +CGAL-format tests, 8e YAML pipeline) are deferred to on-demand status — +no speculative architecture for an uncertain submission. Root-level files added at v0.7.0: - `CITATION.cff` — machine-readable citation (Sechelmann 2016, Springborn 2020, Bobenko–Springborn 2004) diff --git a/doc/api/cgal-package.md b/doc/api/cgal-package.md index 2e3bc4d..38f158c 100644 --- a/doc/api/cgal-package.md +++ b/doc/api/cgal-package.md @@ -290,36 +290,114 @@ If any of these fail, the design is iterated before continuing. --- -## Implementation order +## Implementation strategy — "Hybrid MVP" (decided 2026-05-19) + +After cost/benefit re-evaluation, the plan is **not** to build Phase 8 in full +before resuming the port. Instead: ``` -1. Phase 7.5 Doxygen infrastructure + duplicate cleanup (½–1 day) -2. Phase 8a.1 ConformalMapTraits concept + Default_traits (2–3 days) -3. Phase 8a.2 Generic FaceGraph specialisation (2 days) -4. Phase 8b.1 Discrete_conformal_map.h entry point (2 days) -5. Phase 8b.2 Layout + cut graph wrappers (2 days) -6. Phase 9a Inversive-Distance against new traits = API test (3–5 days) -7. Phase 8c PackageDescription.txt + User_manual.md (2 days) -8. Phase 8d CGAL-format test directory (1–2 days) -9. Phase 8e YAML pipeline + CLI flag (3 days) +┌────────────────────────────────────────────────────────────────────┐ +│ PHASE 8 MVP (3–5 days) │ +│ ───────────────────── │ +│ Just enough CGAL-style architecture for Phase 9a to validate it. │ +│ │ +│ • Conformal_map_traits.h concept + Default │ +│ • Discrete_conformal_map.h ONE entry: _euclidean() │ +│ • 4 named parameters Θ-map, max_iter, tol, pin │ +│ • Concept-check header │ +│ • Doxygen on these 3 headers │ +└────────────────────────────────────────────────────────────────────┘ + ▼ +┌────────────────────────────────────────────────────────────────────┐ +│ PHASE 9a — Inversive-Distance (3–5 days) │ +│ ────────────────────────────────── │ +│ Built directly against the new traits API. This is the │ +│ acceptance test for the MVP. │ +│ │ +│ If painless → MVP design is sound, continue with Phase 9b/9c │ +│ If painful → iterate the traits design before going further │ +└────────────────────────────────────────────────────────────────────┘ + ▼ +┌────────────────────────────────────────────────────────────────────┐ +│ PHASE 9b — Analytic HyperIdeal Hessian (1 week) │ +│ PHASE 9c — 4g-polygon fundamental domain (1 week) │ +│ ──────────────────────────────────────── │ +│ Port really finished. v0.9.0 release possible. │ +└────────────────────────────────────────────────────────────────────┘ + ▼ +┌────────────────────────────────────────────────────────────────────┐ +│ PHASE 8 EXTENSIONS — only on demand │ +│ ───────────────────────────────── │ +│ • 8a.2 generic FaceGraph specialisation when Polyhedron_3 user │ +│ • 8b extend to spherical + hyperbolic when 9a pattern proven │ +│ • 8c full User_manual + Reference_manual when submission planned│ +│ • 8d CGAL-format test directory when submission planned│ +│ • 8e YAML pipeline + CLI flag orthogonal, any time │ +│ │ +│ Each extension only when there is a concrete trigger. No │ +│ speculative architecture for a hypothetical CGAL submission. │ +└────────────────────────────────────────────────────────────────────┘ ``` -**Total budget: 3–4 weeks net work, 6–8 weeks calendar.** +**Why this order?** + +- Port-completion (Phase 9) is the higher-confidence value: well-defined, + ~3 weeks of work, finishes Goal A. +- Full Phase 8 (3–4 weeks) speculative — only pays off if CGAL submission + actually happens, which is uncertain. +- Phase 8 MVP captures the architectural insight (traits + named params) + without the long tail. If the rest of Phase 8 is ever wanted, it's + additive — nothing built in the MVP needs to be thrown away. + +**Total committed budget: 2 weeks (MVP + 9a) + 2 weeks (9b + 9c) = ~4 weeks +net work, 6–8 weeks calendar.** After that, the port is finished. + +## Phase 8 MVP scope — what is and isn't in the first cut + +| Item | MVP | Later | Reason | +|---|:---:|:---:|---| +| `Conformal_map_traits.h` concept | ✅ | — | Core abstraction | +| `Default_conformal_map_traits` | ✅ | — | Status-quo wrapper | +| Generic `FaceGraph` specialisation | — | ✅ 8a.2 | Speculative until asked | +| `Discrete_conformal_map.h` — `_euclidean()` | ✅ | — | First entry function | +| `Discrete_conformal_map.h` — `_spherical()`, `_hyperbolic()` | — | ✅ 8b.2 | Pattern-replicates once 9a works | +| Named parameters: `vertex_curvature_map`, `max_iterations`, `gradient_tolerance`, `fixed_vertex_pmap` | ✅ | — | Essential 4 | +| Named parameters: rest (`output_uv_map`, `cut_graph`, …) | — | ✅ 8b.2 | Additive | +| Doxygen on MVP headers | ✅ | — | Same time anyway | +| Doxygen on legacy `code/include/*` | partial | ✅ 8c | Bulk later | +| `PackageDescription.txt` | — | ✅ 8c | Only if submitting | +| User_manual.md | — | ✅ 8c | Only if submitting | +| `test/Conformal_map/` CGAL-style | — | ✅ 8d | Only if submitting | +| YAML pipeline + CLI flag | — | ✅ 8e | Orthogonal, any time | --- ## TODO checklist -- [ ] Phase 7.5: Doxyfile + CMake doc target + duplicate cleanup -- [ ] 8a.1: `ConformalMapTraits` concept header -- [ ] 8a.1: `Default_conformal_map_traits` -- [ ] 8a.2: Generic `FaceGraph` specialisation -- [ ] 8a.2: `Conformal_map_concept_checks.h` -- [ ] 8b.1: `Discrete_conformal_map.h` (3 entry functions) -- [ ] 8b.1: Named-parameter vocabulary header +### MVP track (committed work, ~4 weeks) +- [x] Phase 7.5: Doxyfile + CMake doc target + duplicate cleanup +- [ ] **Phase 8 MVP — Traits + one wrapper** + - [ ] `Conformal_map_traits.h` — concept documentation + - [ ] `Default_conformal_map_traits` + - [ ] `Conformal_map_concept_checks.h` + - [ ] `Discrete_conformal_map.h` with `_euclidean()` only + - [ ] 4 named parameters: Θ-map, max_iter, tol, pin + - [ ] Test: `cgal.ConformalTraits.Surface_mesh_default_works` +- [ ] **Phase 9a — Inversive-Distance (acceptance test for MVP)** + - [ ] `inversive_distance_functional.hpp` against new traits + - [ ] Gradient check + Newton convergence tests + - [ ] Doxygen on new headers +- [ ] **Phase 9b — Analytic HyperIdeal Hessian** + - [ ] Replace FD in `hyper_ideal_hessian.hpp` + - [ ] Symmetry + PSD checks unchanged +- [ ] **Phase 9c — 4g-polygon for genus g > 1** + - [ ] Extend `compute_fundamental_domain()` beyond genus 1 + +### On-demand track (only with concrete trigger) +- [ ] 8a.2: Generic `FaceGraph` specialisation (trigger: Polyhedron_3 user) +- [ ] 8b.2: `_spherical()` + `_hyperbolic()` entry functions (trigger: pattern proven) - [ ] 8b.2: `Conformal_layout.h`, `Conformal_cut_graph.h` wrappers -- [ ] 9a: `inversive_distance_functional.hpp` written against new traits -- [ ] 8c: `doc/Conformal_map/PackageDescription.txt` -- [ ] 8c: User_manual + Reference_manual -- [ ] 8d: `test/Conformal_map/` CGAL-style tests -- [ ] 8e: YAML validator + CLI `--pipeline` flag +- [ ] 8c: `doc/Conformal_map/PackageDescription.txt` (trigger: submission planned) +- [ ] 8c: User_manual + Reference_manual (trigger: submission planned) +- [ ] 8d: `test/Conformal_map/` CGAL-style tests (trigger: submission planned) +- [ ] 8e: YAML validator + CLI `--pipeline` flag (orthogonal, any time)