# 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. **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) |
| 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).
