conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
b57528d92fad2aee8346d293f443082bfa5e9c9c
ConformalLabpp/doc/roadmap/porting-status.md
Tarik Moussa b57528d92f docs(roadmap): add phase orchestration system mirroring the reviewer audit workflow 
Brings doc/roadmap/ to the same operational level as doc/reviewer/ by adding
the two missing structural files and updating existing docs to close the gap
identified in the system review.

New files:
- doc/roadmap/phase-orchestration.md  — master phase table (model assignments,
  session IDs, status, review-gate checklist); mirrors finding-orchestration.md
- doc/roadmap/session-prompts.md      — copy-paste-ready prompts for P1–P4
  (Haiku/Sonnet/Opus) + universal Opus review gate; mirrors reviewer/session-prompts.md

Updated files:
- CLAUDE.md: roadmap section now lists porting-status.md, phase-orchestration.md,
  session-prompts.md; reviewer section adds finding-orchestration.md and
  session-prompts.md; agentic-workflow section has direct "S3 is next / P1 is next"
  entry points so agents don't need to derive the next action from scratch
- doc/roadmap/phases.md: Current-focus table at the top (7 tracks, next session
  per track, gating); cross-links to geometry-central-comparison.md,
  software-landscape.md, complexity.md added in GC and 9b-analytic sections
- doc/roadmap/porting-status.md: snapshot date updated to 2026-05-31 (post S1+S2);
  test count replaced by reference to doc/api/tests.md; §4 gains four new solver
  rows (newton_core refactor, NewtonStatus enum, diagnostics, selectable clamp mode);
  §7 gains four new research-extension rows from S1/S2
- doc/roadmap/research-track.md: header companion-docs section links to
  novelty-statement.md, software-landscape.md, and phase-orchestration.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-01 08:58:46 +02:00

261 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Porting status overview
> **Snapshot date:** 2026-05-31 (post audit-sessions S1 + S2 on branch
> `fix/b1-v3-c1-quick-wins`; 9 commits; 301/301 CGAL tests green).
> For the authoritative live count see [`doc/api/tests.md`](../api/tests.md).
>
> **Audience.** External collaborators evaluating whether to use, extend,
> or contribute to conformallab++. This document is the **operational
> truth** of which Java mathematics is reachable from C++ today, with
> what API, and with which caveats. For the longer plan see
> [`phases.md`](phases.md), for the formal port-vs-research classification
> see [`research-track.md`](research-track.md), for the cross-reference
> with the Java original see [`java-parity.md`](java-parity.md).
---
## 1. The 25 000 lines of Java in one table
```
de.varylab.discreteconformal
├── functional/ ~3 000 LoC ████████████░░░░ Phase 3 + 9a ✅
├── unwrapper/ ~3 500 LoC ████████░░░░░░░░ Phase 5/6/7 (basic 3 modes) ✅
│ residual: Stereographic, CircleDomain, Koebe, CirclePattern
├── util/ ~5 000 LoC ████░░░░░░░░░░░░ partial — main utilities ported
│ residual: Homology, Holomorphic / Harmonic forms,
│ FundamentalPolygon, Surgery, Cutting
├── heds/ (Co* data struct) ~3 000 LoC ░░░░░░░░░░░░░░░░ REPLACED by CGAL::Surface_mesh ❌ intentional
├── plugin/ ~7 000 LoC ░░░░░░░░░░░░░░░░ SKIP (Swing UI, GLSL viewer) ❌ intentional
├── numerics/ (PETSc glue) ~1 500 LoC ░░░░░░░░░░░░░░░░ REPLACED by Eigen ❌ intentional
├── math/, logging/, ... ~2 000 LoC ░░░░░░░░░░░░░░░░ REPLACED by std::* / Eigen ❌ intentional
└── total ~25 000 LoC
```
**Coverage of the mathematics:** about **4 500 of the 11 000 LoC** of
genuinely mathematical Java code is portrayed in C++ — **~41% of the
maths, ~75% of the "core math we actually want"** (Phase 1–7 + 9a + 9b
together cover the algorithmically central mass).
The remaining ~6 500 LoC of port-worthy maths is catalogued in
[`java-parity.md`](java-parity.md) and broken into Phases 9c / 10a /
10b / 10b' / 11.
---
## 2. Five DCE models — operational status matrix
The library supports **five** discrete-conformal-equivalence models on
the same `CGAL::Surface_mesh<P>`. All can be used from both the
legacy API (`code/include/*.hpp`) and the CGAL public API
(`<CGAL/Discrete_*.h>`).
| Model | Native space | DOF location | Java port? | Hessian | Newton | CGAL entry | UV out |
|------------------------|---------------|--------------|-----------|------------------|-----------|---------------------------------------------|----------|
| **Euclidean** | ℝ² | vertex | EuclideanCyclic 530 LoC | analytic (cot-Laplace) | ✅ | `discrete_conformal_map_euclidean` | ✅ Point_2 |
| **Spherical** | S² | vertex | Spherical 458 LoC | analytic | ✅ | `discrete_conformal_map_spherical` | ✅ Point_3 |
| **Hyper-ideal** | H² (Poincaré) | vertex + edge | HyperIdeal 311 LoC (no Hess) | block-FD (Phase 9b, 96× speed-up); analytic planned | ✅ | `discrete_conformal_map_hyper_ideal` | ✅ Point_2 |
| **CP-Euclidean** (BPS) | face circles | **face** | CPEuclidean 260 LoC | analytic 2×2-per-edge | ✅ | `discrete_circle_packing_euclidean` | ⛔ N/A |
| **Inversive Distance** | vertex circles| vertex | ❌ no Java (Luo 2004 + Glickenstein 2011 from literature) | FD (analytic planned) | ✅ | `discrete_inversive_distance_map` | ⛔ pending |
Total test count: see [`doc/api/tests.md`](../api/tests.md) — single source
of truth (counts change as sessions land; do not hardcode them here).
### What "UV out" means
The `output_uv_map(pmap)` named parameter, when supplied, runs the
relevant `*_layout()` step internally and writes per-vertex coordinates
into `pmap` — no separate user code needed. See
[`doc/tutorials/add-output-uv-map.md`](../tutorials/add-output-uv-map.md).
* **Euclidean / Spherical / HyperIdeal**: shipped.
* **CP-Euclidean**: conceptually not applicable (face-based packing
produces face-circles, not per-vertex UV — needs a separate
`output_circle_map` design).
* **Inversive Distance**: requires `inversive_distance_layout()` using
Luo's edge-length formula `ℓ² = r_i² + r_j² + 2 I_ij r_i r_j`.
~3 days work, on the wishlist.
---
## 3. Topology infrastructure
| Feature | Status | Notes |
|------------------------------------------------|:-----:|-------|
| Mesh I/O (OFF / OBJ / PLY) | ✅ | `mesh_io.hpp` via CGAL::IO |
| Gauss–Bonnet check & enforce | ✅ | `gauss_bonnet.hpp` |
| Cut graph (tree-cotree, Erickson–Whittlesey) | ✅ | `cut_graph.hpp`, produces 2g seam edges |
| Layout / embedding (priority-BFS trilateration) | ✅ | ℝ² / S² / Poincaré disk |
| Halfedge UV (seam-aware texture atlas) | ✅ | `layout.hpp` |
| Möbius holonomy SU(1,1) | ✅ | for hyperbolic mode, genus 1 |
| Period matrix τ ∈ ℍ + SL(2,ℤ) reduction | ✅ | genus 1 only |
| Fundamental domain (parallelogram) | ✅ | genus 1 only |
| Fundamental domain (4g-polygon) | 🔲 | Phase 9c — biggest remaining Java-port item |
| Real mesh cuts (CuttingUtility ops) | 🔲 | Phase 9c prerequisite |
---
## 4. Solver infrastructure
| Feature | Status | Notes |
|-------------------------------------------------|:-----:|-------|
| Newton with line search | ✅ | `newton_solver.hpp`, all five solvers |
| SimplicialLDLT + SparseQR fallback | ✅ | gauge-singular meshes handled automatically |
| Block-FD Hessian framework | ✅ | shipped for HyperIdeal (Phase 9b); 96× speed-up |
| `newton_core` refactor — single exit path | ✅ | shipped S1 (2026-05-31); prerequisite for clean diagnostic propagation |
| `NewtonStatus` enum (`Converged` / `MaxIterations` / `LinearSolverFailed` / `LineSearchStalled`) | ✅ | shipped S2 (2026-05-31); propagated into all three CGAL result types via `CGAL::Newton_status` alias |
| Solver diagnostics: `sparse_qr_fallback_used`, `min_ldlt_pivot` | ✅ | shipped S2 (2026-05-31); available on all public CGAL result types |
| Selectable Newton clamp mode (`HardJava` \| `SmoothBarrier`) | ✅ | shipped S1 (2026-05-31); `HardJava` is the default (Java-parity) |
| Analytic Hessian via Schläfli | 🔲 | Phase 9b-analytic; derivation in [`hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) |
---
## 5. CGAL public API (`<CGAL/Discrete_*.h>`)
After Phase 8a MVP + 8b-Lite (both shipped in v0.9.0):
| Public header | Provides |
|--------------------------------------------------------------|----------|
| `<CGAL/Discrete_conformal_map.h>` | `discrete_conformal_map_euclidean / _spherical / _hyper_ideal` + `Conformal_map_result<FT>` |
| `<CGAL/Discrete_circle_packing.h>` | `Default_cp_euclidean_traits` + `discrete_circle_packing_euclidean` + `Circle_packing_result<FT>` |
| `<CGAL/Discrete_inversive_distance.h>` | `Default_inversive_distance_traits` + `discrete_inversive_distance_map` |
| `<CGAL/Conformal_layout.h>` | Thin re-exports of layout functions in the `CGAL::` namespace |
| `<CGAL/Conformal_map_traits.h>` | `ConformalMapTraits` concept + `Default_conformal_map_traits` |
| `<CGAL/Conformal_map/internal/parameters.h>` (private) | Named-parameter tags |
Named parameters available:
| Parameter | Effect |
|------------------------------------|--------|
| `vertex_curvature_map(pmap)` | Per-vertex Θ targets; if omitted, "natural-theta" makes x = 0 the equilibrium |
| `fixed_vertex_map(pmap)` | Gauge pin; if omitted, first vertex is pinned |
| `gradient_tolerance(eps)` | Newton stop threshold (default 1e-10) |
| `max_iterations(n)` | Newton iteration cap (default 200) |
| `output_uv_map(pmap)` | Run layout + write per-vertex coordinates |
| `normalise_layout(flag)` | Canonical post-layout normalisation (PCA / north-pole / Möbius) |
**Known limitations** (documented for the meeting):
1. **Chaining via pipe operator.** CGAL-style `.a().b().c()` is not yet
implemented for package-local tags (would require modifying CGAL
upstream). conformallab++ provides `operator|` instead — see
`code/include/CGAL/Conformal_map/internal/parameters.h` and the test
`CGALPhase8bLite.NamedParamPipe_MultipleParamsTakeEffect`. Example:
`gradient_tolerance(1e-12) | max_iterations(500) | output_uv_map(uv)`.
2. **Generic FaceGraph not yet supported.** All Default traits
specialise on `CGAL::Surface_mesh<P>` only. Adding `Polyhedron_3`,
`OpenMesh-adapter`, `pmp::SurfaceMesh` is Phase 8a.2 — speculative,
waiting on a concrete user request.
3. **CGAL submission-readiness incomplete.** User_manual /
PackageDescription.txt / CGAL-format tests are not yet written
(Phase 8c / 8d). Required for upstream submission, not for current
users.
---
## 6. What's reachable from the Java original today
Cross-reference between Java classes and their C++ port status. For
the full list see [`java-parity.md`](java-parity.md); the table below
gives the operational summary for a Java user wondering "where is X?".
### Direct ports
| Java | C++ |
|----------------------------------------------|-------------------------------------------------------------|
| `EuclideanCyclicFunctional` | `euclidean_functional.hpp` |
| `SphericalFunctional` | `spherical_functional.hpp` |
| `HyperIdealFunctional` | `hyper_ideal_functional.hpp` |
| `HyperIdealUtility`, `…Geometry` | `hyper_ideal_utility.hpp`, `hyper_ideal_geometry.hpp` |
| `HyperIdealHyperellipticUtility` | `hyper_ideal_visualization_utility.hpp` |
| `CPEuclideanFunctional` | `cp_euclidean_functional.hpp` |
| `Clausen` | `clausen.hpp` |
| `MeshIO` (jReality JRS) | `mesh_io.hpp` (CGAL::IO, OFF/OBJ/PLY) |
| `CuttingUtility::point_in_triangle_2d` | `geometry_utils.hpp` partial port |
| `ConvergenceUtility::circumradius` | `geometry_utils.hpp` |
| `HomologyUtility::compute_generators` | `cut_graph.hpp` (different algorithm: tree-cotree) |
| `PeriodMatrixUtility` (genus 1) | `period_matrix.hpp` |
| `UnwrapperUtility::EuclideanUnwrapper` | `newton_euclidean()` + `euclidean_layout()` |
| `UnwrapperUtility::SphericalUnwrapper` | `newton_spherical()` + `spherical_layout()` |
| `UnwrapperUtility::HyperbolicUnwrapper` | `newton_hyper_ideal()` + `hyper_ideal_layout()` |
### Not-yet-ported, in roadmap
| Java | Suggested phase | Lines | Notes |
|---------------------------------------------------|:----:|:----:|-------|
| `FundamentalPolygonUtility` + `CanonicalFormUtility` | 9c | 698+532 | genus > 1 fundamental domain |
| `CuttingUtility` + `SurgeryUtility` (full ops) | 9c | 584+217 | real mesh-cut operations |
| `DiscreteHarmonicFormUtility` | 10a | 657 | harmonic 1-forms |
| `DiscreteHolomorphicFormUtility` | 10a | 285 | holomorphic differentials |
| `CanonicalBasisUtility` | 10a | 337 | symplectic homology basis |
| `DualityUtility`, `HomologyUtility` (full) | 10a | 308+122 | primal/dual cohomology |
| `DiscreteRiemannUtility` | 10b | 186 | period matrix for genus > 1 |
| `HyperbolicCyclicFunctional` | 10b–c | 530 | hyperbolic energy (different from hyper-ideal) |
| `QuasiisothermicUtility` + `SinConditionApplication` | 10b | ~1200 | Lawson correspondence |
| `StereographicUnwrapper` | 10b' | 266 | S² → ℂ atlas |
| `KoebePolyhedron` | 10c | 321 | KAT circle packing |
| `MobiusCenteringFunctional` | 10c | 289 | sphere pre-processing |
| `CircleDomainUnwrapper` | 11c | 570 | multiply-connected planar regions |
### Intentionally not ported
* **`CoHDS` (half-edge data structure)** — replaced by `CGAL::Surface_mesh`. ~3 000 Java LoC saved.
* **`plugin/*` Swing UI** — out of scope; C++ project is a library, not an application.
* **`unwrapper/numerics/*` PETSc/Tao wrappers** — replaced by Eigen, which is header-only and bundled.
* **`math/CP1`, `math/Cn`, …** — redundant with `std::complex`, `Eigen::Matrix`.
---
## 7. Things in C++ that the Java original does NOT have
These are conformallab++ contributions beyond porting — the
"research extensions" track ([`research-track.md`](research-track.md)).
| Item | Status |
|----------------------------------------------|:-----:|
| Block-FD HyperIdeal Hessian (96× speed-up) | ✅ shipped (Phase 9b) |
| HyperIdeal Hessian (any kind) | ✅ shipped — Java has `hasHessian()==false` |
| Inversive-Distance functional (Luo 2004) | ✅ shipped — implemented from paper, not from Java |
| `<CGAL/Discrete_*.h>` public-API surface | ✅ shipped (Phase 8a + 8b-Lite) |
| Cross-validation framework (4 acceptance criteria) | ✅ documented in `add-inversive-distance.md` |
| Genus-2 test mesh + brezel2.obj scalability | ✅ shipped |
| Memory-safe layout via `halfedge_uv` storage | ✅ shipped |
| `doc/release-policy.md` formal release policy | ✅ shipped (PR #13) |
| Output UV map integrated into wrappers | ✅ shipped (PR #14) for 3 of 5 models |
| `[[deprecated]]` aliases for pre-S1 API names (A1–A3 rename → `<verb>_<geom>_<rest>`) | ✅ shipped S1 (2026-05-31) |
| Named numeric constants in `constants.hpp` (all thresholds / FD steps / guard values) | ✅ shipped S1 (2026-05-31) |
| Kahan-compensated triangle area in `enforce_gauss_bonnet` | ✅ shipped S1 (2026-05-31) |
| `NewtonStatus` enum + solver diagnostics on all public CGAL result types | ✅ shipped S2 (2026-05-31) |
| Analytic HyperIdeal Hessian via Schläfli | 🔲 derivation written (`hyperideal-hessian-derivation.md`); implementation Phase 9b-analytic (P4) |
| Full uniformisation for genus g ≥ 2 | 🔲 Phase 10c — fully new research |
---
## 8. How to "use the library today"
The fastest path for a mathematician evaluating the library:
```bash
# Build + run the full test suite
git clone <repo> && cd ConformalLabpp
cmake -S code -B build -DWITH_CGAL_TESTS=ON
cmake --build build --target conformallab_cgal_tests -j$(nproc)
ctest --test-dir build -R "^cgal\." --output-on-failure
# Try the CGAL API on a mesh
./build/examples/example_layout my_mesh.off
```
To experiment with a new functional, follow
[`doc/tutorials/add-inversive-distance.md`](../tutorials/add-inversive-distance.md).
To extend the CGAL API with new named parameters, follow
[`doc/tutorials/add-output-uv-map.md`](../tutorials/add-output-uv-map.md).
To optimise an FD Hessian, follow
[`doc/tutorials/block-fd-hessian.md`](../tutorials/block-fd-hessian.md).
For the architectural commitments that constrain future contributions,
see [`doc/architecture/locked-vs-flexible.md`](../architecture/locked-vs-flexible.md).
Reference in New Issue View Git Blame Copy Permalink