ConformalLabpp/doc/architecture/geometry-central-comparison.md

# conformallab++ vs. geometry-central — Detailed Comparison

> **Purpose of this document.**  
> conformallab++ and geometry-central (CMU, Keenan Crane's group) both implement
> discrete conformal equivalence of triangulated surfaces.  They share the same
> mathematical core but diverge in algorithmic strategy, scope, and target audience.
> This document maps the overlap precisely, identifies what cannot and should not be
> adopted, and explains where a side-by-side study creates scientific added value.

---

## 1 — Shared mathematical foundation

Both libraries implement the following chain:

```
Input mesh M  →  edge lengths ℓᵢⱼ  →  solve for u ∈ ℝᵛ
  such that  ℓ̃ᵢⱼ = e^{(uᵢ+uⱼ)/2} · ℓᵢⱼ  satisfies  Σα_v(u) = Θᵥ  ∀v
```

The variational framework that makes this a well-posed optimisation problem goes
back to **Bobenko & Springborn (2004)**.  The hyperbolic (HyperIdeal) geometry is
from **Springborn (2020)**.  The geometry-central implementation (Gillespie,
Springborn & Crane, SIGGRAPH 2021) is an explicit extension of Springborn 2020
to intrinsic triangulations.

**Key consequence:** the *mathematical problem* is identical.  Any difference in
output is either a normalization convention or a bug in one of the two libraries —
making cross-validation directly meaningful.

---

## 2 — Algorithmic comparison

| Dimension | conformallab++ | geometry-central (Gillespie 2021) |
|---|---|---|
| **Solver** | Newton–Raphson, analytical Hessian | Newton or Yamabe gradient flow (user choice) |
| **Convergence** | Quadratic (8–20 iterations on typical meshes) | Newton: quadratic; Yamabe: linear (~hundreds of steps) |
| **Triangulation** | Fixed throughout — operates on original `Surface_mesh` | Ptolemaic flips applied before/during solve to reach intrinsic Delaunay |
| **Hessian** | SimplicialLDLT + SparseQR fallback; analytical for Euclidean/Spherical, FD for HyperIdeal | Assembled on the current (possibly flipped) triangulation |
| **Mesh backend** | CGAL `Surface_mesh<Point_3>` | geometry-central `ManifoldSurfaceMesh` |
| **Geometry modes** | Euclidean ✓ · Spherical ✓ · HyperIdeal ✓ | Euclidean ✓ · Hyperbolic ✓ · Spherical ✗ |
| **Open meshes** | ✓ (boundary DOFs pinned) | ✓ |

### Why Newton on a fixed triangulation works well

The Euclidean and HyperIdeal energies are strictly convex after gauge-fixing.
Newton therefore converges from u=0 in 8–20 iterations for any reasonable mesh.
The Hessian is the cotangent Laplacian (Euclidean) or its hyperbolic analog —
well-conditioned on Delaunay meshes, but can degrade on strongly non-Delaunay inputs.

### What Ptolemaic flips add

A Ptolemaic flip replaces diagonal AC with BD in a quadrilateral under the constraint
that the Ptolemy relation

```
AC · BD = AB · CD + AD · BC
```

holds.  This is *conformal-class-preserving* — the new λ₀ values represent the same
discrete conformal structure.  The gain: the flipped triangulation is intrinsic
Delaunay, which bounds the off-diagonal Hessian entries and prevents ill-conditioning
on pathological inputs.

**This is the only genuine algorithmic advantage geometry-central has for the shared
sub-problem.** It costs nothing mathematically and buys robustness on bad meshes.

---

## 3 — Feature matrix: what exists where

| Feature | conformallab++ | geometry-central | Notes |
|---|---|---|---|
| Discrete conformal equivalence (Euclidean) | ✓ | ✓ | Shared core |
| Discrete conformal equivalence (Hyperbolic/HyperIdeal) | ✓ (Springborn 2020 formulation) | ✓ (Gillespie 2021 extension) | Mathematically equivalent |
| Discrete conformal equivalence (Spherical) | ✓ | ✗ | Unique to conformallab++ |
| Analytical Hessian (Euclidean & Spherical) | ✓ | ✓ | |
| Analytical Hessian (HyperIdeal) | FD (Phase 9b: analytical planned) | ✓ | gc has analytical version |
| Gauss–Bonnet check & enforce | ✓ | implicit in solver | |
| Tree-cotree cut graph (2g seam edges) | ✓ | ✗ | Required for period matrix |
| Priority-BFS layout in ℝ²/S²/Poincaré disk | ✓ | partial (conformal param only) | |
| Möbius holonomy SU(1,1) | ✓ | ✗ | Unique to conformallab++ |
| Period matrix τ ∈ ℍ + SL(2,ℤ) reduction | ✓ | ✗ | Unique to conformallab++ |
| Fundamental domain + tiling | ✓ | ✗ | Unique to conformallab++ |
| Intrinsic Delaunay triangulation | ✗ | ✓ | gc has via SignpostIntrinsicTriangulation |
| Ptolemaic flips | ✗ | ✓ | gc's robustness mechanism |
| Heat method (geodesic distances) | ✗ | ✓ | Auxiliary tool in gc |
| YAML/declarative pipeline | ✓ (Phase 8e spec) | ✗ | |
| CGAL-package submission | ✓ (Phase 8 target) | ✗ | |
| JSON/XML serialisation | ✓ | ✗ | |
| CLI app | ✓ | ✗ | |
| Inversive distance functional (Luo 2004) | ✗ (Phase 9a) | ✗ | Neither has it yet |
| Siegel period matrix Ω (genus g≥2) | ✗ (Phase 10b) | ✗ | |

---

## 4 — What should be adopted — and what should not

### Adopt: Ptolemaic pre-conditioning (GC-2, after Phase 8)

**What:** a single preprocessing pass that Delaunay-izes the input triangulation
via Ptolemaic flips, updates λ₀ accordingly, then hands off to the existing
Newton pipeline unchanged.

**Why it fits:**
- Preserves the conformal class — mathematically sound
- Drop-in before `compute_euclidean_lambda0_from_mesh()`, no interface change
- Does not touch cut graph, holonomy, period matrix
- ~200 lines of code, one new test suite

**Interface sketch:**
```cpp
// include/preprocessing_delaunay.hpp  (Phase GC-2)
void ptolemy_delaunay(ConformalMesh& mesh, EuclideanMaps& maps);
// Flips edges until all faces satisfy the Delaunay condition.
// Updates maps.lambda0[e] via the Ptolemy relation after each flip.
// Prerequisite: compute_euclidean_lambda0_from_mesh() already called.
// Postcondition: mesh is an intrinsic Delaunay triangulation of the same surface.
```

### Adopt partially: analytical HyperIdeal Hessian

geometry-central has a closed-form Hessian for the hyperbolic energy.
conformallab++ currently uses finite differences (Phase 9b plans analytical).
The geometry-central implementation can serve as a reference for Phase 9b —
not a code copy, but a mathematical cross-check.

### Do not adopt: full intrinsic triangulations as architecture

**SignpostIntrinsicTriangulation** is geometry-central's core data structure.
It tracks vertex positions as (face, barycentric coordinates) rather than 3D points.
Replacing `CGAL::Surface_mesh` with this would require:

1. Rewriting the cut graph algorithm (which works on halfedges of the *original* mesh
   and must survive across flips — non-trivial bookkeeping)
2. Tracking seam edges through flip events for holonomy computation
3. Abandoning the CGAL package target (Phase 8) — CGAL's mesh concepts are extrinsic
4. Losing the 3D layout output (Poincaré disk, sphere) which clients depend on

**Verdict:** the architecture incompatibility is fundamental, not incidental.
The period matrix pipeline requires a stable topological cut that does not survive
arbitrary flip sequences. This is not a solvable engineering problem within the
current project scope — it would be a different project.

### Do not adopt: Yamabe flow

Newton converges in 8–20 iterations; Yamabe flow needs hundreds.
The only reason to use Yamabe flow is when the Hessian is indefinite (which happens
in the Spherical case — and conformallab++ already handles this with the correct
sign flip in the energy). There is no mesh type where Yamabe flow beats Newton
on metrics that conformallab++ targets.

---

## 5 — Where cross-comparison creates scientific added value

### 5.1 — Independent cross-validation of the shared core

The discrete conformal equivalence problem for Euclidean and HyperIdeal geometry
is implemented independently in two codebases, by different groups, with different
algorithms.  Agreement on:

- the u-vector (after normalization)
- UV coordinates (up to Möbius transformation)
- the residual ‖G(u*)‖ at convergence

would constitute **mutual validation without ground truth**.  This is the same
methodology used in numerical PDE literature to validate independent solvers.

**Concrete protocol:**
```
For each test mesh (cathead.obj, brezel.obj, torus_4x4.off, torus_hex_6x6.off):
  1. Load into both libraries with identical vertex ordering
  2. Run conformallab++ Newton solver  →  u_clab, UV_clab
  3. Run geometry-central solver        →  u_gc,   UV_gc
  4. Normalize both (subtract mean, divide by scale)
  5. Report  max|u_clab[v] - u_gc[v]|  and  mean conformal distortion difference
```

Expected: agreement to ≤ 1e-8 on well-conditioned meshes.  Discrepancy would
indicate a bug or a normalization mismatch worth investigating.

### 5.2 — Convergence study: Newton with vs. without Ptolemaic pre-conditioning

Hypothesis: on non-Delaunay meshes (e.g. a torus refined by subdivision without
re-meshing), Ptolemaic Delaunay pre-conditioning reduces Newton iteration count.

**Measurable quantities:**
- Newton iterations to ‖G‖ < 1e-8
- Hessian condition number κ(H) at u = 0
- Wall-clock time

This comparison requires only GC-2 to be implemented in conformallab++ and would
answer the question: *how bad does a mesh have to be before Ptolemaic pre-conditioning
pays off?*

**Publication potential:** a short note or conference contribution comparing the
two approaches on a systematic mesh quality benchmark would be self-contained and
novel — neither library has published this comparison.

### 5.3 — Period matrix and holonomy as differentiating contribution

geometry-central deliberately stops at the conformal parameterization.  The period
matrix τ and Möbius holonomy computation in conformallab++ extend the pipeline into
Teichmüller theory territory that geometry-central does not address.

This is the strongest scientific differentiator: conformallab++ can compute

```
τ = ω_b / ω_a  ∈ ℍ,  SL(2,ℤ)-reduced
```

for any closed genus-1 surface, and (in Phase 10) the Siegel matrix Ω for genus g≥2.
No other open-source C++ library does this.  Cross-comparison with geometry-central
makes this gap explicit and positions conformallab++ as the more complete tool for
Teichmüller-theoretic applications.

### 5.4 — Spherical geometry as unique contribution

The Spherical geometry mode (angle sums → 4π on a sphere, NSD Hessian with sign
flip) has no counterpart in geometry-central.  A mathematician interested in
conformal maps on surfaces of positive curvature (constant curvature +1) has no
alternative in open-source C++.

### 5.5 — Validation of Springborn 2020 in two independent implementations

Springborn 2020 ("Ideal Hyperbolic Polyhedra and Discrete Uniformization") is the
shared theoretical reference for both the HyperIdeal geometry mode in conformallab++
(Phase 2/3) and the hyperbolic component of Gillespie 2021 in geometry-central.
Cross-checking the ζ-function values (ζ₁₃, ζ₁₄, ζ₁₅) and the resulting angle sums
on the same meshes would validate both implementations of the paper — a service to
the discrete geometry community.

---

## 6 — Demarcation: where the comparison ends

| Topic | conformallab++ | geometry-central | Comparable? |
|---|---|---|---|
| u-vector at convergence | ✓ | ✓ | ✓ after normalization |
| UV parameterization | ✓ | ✓ | ✓ up to Möbius |
| Convergence speed (iterations) | ✓ | ✓ (Newton mode) | ✓ direct |
| HyperIdeal angle sums | ✓ | ✓ | ✓ |
| Spherical angle sums | ✓ | ✗ | ✗ |
| Period matrix τ | ✓ | ✗ | ✗ |
| Holonomy T_a, T_b | ✓ | ✗ | ✗ |
| Fundamental domain | ✓ | ✗ | ✗ |
| Intrinsic Delaunay quality | not tracked | ✓ | — |
| Mesh topology handling | CGAL halfedge | gc manifold mesh | not comparable |
| Scalability (large meshes) | not benchmarked yet | benchmarked in paper | comparable if same mesh |

The comparison is meaningful and complete for the **shared conformal core**.
It ends where conformallab++ continues into Teichmüller theory (holonomy, τ,
fundamental domain) — that region has no counterpart in geometry-central and
must be validated by analytic invariants alone (→ `doc/math/validation.md`).

---

## 7 — Practical roadmap for the comparison

| Step | When | What | Effort |
|---|---|---|---|
| **GC-1a** | Now | Manual UV comparison on cathead.obj — run both, diff u-vectors | 1 day |
| **GC-1b** | Now | Add normalization utility to conformallab++ (`normalize_u_vector()`) | 2h |
| **GC-1c** | After Phase 8 | Automated comparison script (Python or small C++ binary) | 2 days |
| **GC-2** | After Phase 8 | `ptolemy_delaunay()` preprocessing pass | 1 week |
| **GC-bench** | After GC-2 | Convergence study: Newton ± Ptolemaic pre-conditioning on 10 meshes | 1 week |
| **GC-paper** | Phase 10 | Short note on the comparison — period matrix as differentiator | — |

---

## 8 — References

| Reference | Role in this comparison |
|---|---|
| **Bobenko, Springborn** — *Variational Principles for Circle Patterns*, Trans. AMS (2004) | Shared variational foundation for all three geometry modes |
| **Springborn** — *Ideal Hyperbolic Polyhedra and Discrete Uniformization*, DCG (2020) | Mathematical basis for HyperIdeal in conformallab++ AND for Gillespie 2021 |
| **Gillespie, Springborn, Crane** — *Discrete Conformal Equivalence of Polyhedral Surfaces*, SIGGRAPH (2021) | geometry-central implementation; introduces Ptolemaic flips |
| **Sharp, Soliman, Crane** — *Navigating Intrinsic Triangulations*, SIGGRAPH (2019) | geometry-central `SignpostIntrinsicTriangulation` — basis for GC-2 |
| **Sechelmann** — doctoral thesis, TU Berlin (2016) | conformallab++ primary source; covers period matrix, holonomy, all three modes |