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>
This commit is contained in:
Tarik Moussa
27
CLAUDE.md
27
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<double>`** (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)
|
||||
|
||||
@@ -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<Surface_mesh,K> │
|
||||
│ • 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<Surface_mesh, K>` | ✅ | — | 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<Surface_mesh, K>`
|
||||
- [ ] 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<Surface_mesh, K>`
|
||||
- [ ] `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)
|
||||
|
||||
Reference in New Issue
Block a user