conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
eb393537f301c0cef9cec73c2be9c01b304bcde6
ConformalLabpp/doc/roadmap/porting-status.md
Tarik Moussa eb393537f3 docs: 5-document meeting prep — tutorials + research note + status + architecture 
External-reviewer-visit prep package (Springborn-Bobenko PhD alumnus,
2026-05-26).  All five documents target the same audience: a
mathematician who wants to evaluate, extend, or contribute to
conformallab++.  Goal: make the project maximally hackable BEFORE the
meeting.  Code unchanged in this commit — pure documentation.

Files added
───────────

1. **doc/tutorials/block-fd-hessian.md** (460 lines)
   Step-by-step tutorial on the per-face block-FD Hessian pattern
   shipped in Phase 9b (96× speed-up).  Matches the style of
   add-inversive-distance.md.  Covers:
   * The per-face locality lemma (mathematical justification).
   * Cost analysis (full-FD vs block-FD vs analytic).
   * Implementation walkthrough through face_angles_from_local_dofs +
     hyper_ideal_hessian_block_fd.
   * Porting checklist for applying the same pattern to a new
     functional.
   * The four cross-validation criteria.
   * When NOT to use block-FD + upgrade path to Phase 9b-analytic.

2. **doc/tutorials/add-output-uv-map.md** (477 lines)
   Tutorial for the `output_uv_map` named-parameter pattern shipped in
   PR #14.  Covers:
   * The UX problem (two-step pipeline → one-call wrapper).
   * The CGAL named-parameter mechanism + how the entry functions
     wire it (get_parameter + constexpr if).
   * Step-by-step recipe for adding a new named parameter (worked
     example: hypothetical `output_holonomy_map`).
   * The five test patterns for verification.
   * Why CP-Euclidean (face-DOF) and Inversive-Distance (Luo-edge-length)
     do not yet support output_uv_map — what is needed to add them.

3. **doc/math/hyperideal-hessian-derivation.md** (805 lines)
   Research-quality LaTeX-formatted derivation of the analytic
   HyperIdeal Hessian via the Schläfli identity (Phase 9b-analytic
   preparation).  Covers:
   * Schläfli identity (1858/60) — gradient and second-order form.
   * Derivatives of ζ, ζ₁₃, ζ₁₄, ζ₁₅ (all hyper-ideal-to-fully-ideal cases).
   * Chain rule for ∂β_i/∂(b,a) and ∂α_ij/∂(b,a) — case-split on the
     four α_ij branches.
   * Per-face 6×6 block formulas.
   * Acceptance criteria for the future implementation.
   * Implementation outline (Conformal_map header sketch).
   * Appendix A: sign / argument-order pitfalls reading the code.
   * References: Schläfli 1858, Milnor 1982, Vinberg 1993, Cho-Kim 1999,
     Rivin, Glickenstein 2011, Springborn 2020, BPS 2015.

4. **doc/roadmap/porting-status.md** (~250 lines)
   Operational snapshot of "where is each piece of Java math today"
   at v0.9.0.  Sections:
   * 25 000 lines of Java in one table (ported / worth porting /
     intentionally skipped breakdown).
   * Five DCE models — full status matrix with Java port status,
     Hessian type, Newton support, CGAL entry, UV-output capability.
   * Topology + solver infrastructure status.
   * CGAL public API map + known limitations (no chaining, Surface_mesh
     only, submission-readiness gaps).
   * Reverse cross-reference: Java class → C++ port location (or
     "skipped: replaced by …" / "in roadmap: phase X").
   * Things in C++ that the Java original does NOT have (research
     extensions track).
   * "How to use the library today" quickstart.

5. **doc/architecture/locked-vs-flexible.md** (~270 lines)
   12-item architecture-decision review with tier classification
   (🔴 load-bearing / 🟡 semi-fixed / 🟢 opportunistic).  Each item
   includes: locked-since date, cost to change, when to revisit,
   recommended posture for new contributors.  Key insight stated up
   front: "the load-bearing decisions are all good in 2026".  Closes
   with five open questions for the external reviewer — items where
   a second opinion would genuinely help (Phase 9c algorithm choice,
   Phase 10a priorities, analytic-Hessian payoff justification,
   CGAL upstream vs independent distribution, geometry-central
   cross-validation).

Total: ~2 250 lines across five new docs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-22 13:38:53 +02:00

248 lines
15 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-22 (commit graph at v0.9.0 + 2 open PRs).
>
> **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: 250+ tests covering all five models, 0 skipped. Per-suite
breakdown: [`doc/api/tests.md`](../api/tests.md).
### 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 |
| 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. **No chaining yet.** `.gradient_tolerance(eps).max_iterations(n)` does
not work — pass one named parameter per call. Fix is mechanical
(~2 days, generate CGAL-style chaining helpers via macros).
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) |
| Analytic HyperIdeal Hessian via Schläfli | 🔲 derivation written (`hyperideal-hessian-derivation.md`); implementation Phase 9b-analytic |
| Output UV map integrated into wrappers | ✅ shipped (PR #14) for 3 of 5 models |
| 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