conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: 5-document meeting prep — tutorials + research note + status + architecture

Browse Source 
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>
This commit is contained in:
Tarik Moussa
2026-05-22 13:38:53 +02:00
parent ff9c9ec11b
commit eb393537f3
5 changed files with 2270 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
doc/roadmap/porting-status.md Normal file
View File

@@ -0,0 +1,247 @@
# 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).