# Discrete Conformal Geometry — Mathematical Background

This document is written for a mathematician who knows Riemannian surfaces and
complex analysis but is new to the *discrete* setting.  It covers exactly the
theory implemented in conformallab++.

---

## 1 — The continuous picture (in one paragraph)

A **Riemann surface** (M, g) carries a conformal structure: the class of all
metrics related to g by a smooth positive factor.  On a compact surface of genus
g, the Uniformization Theorem gives a unique constant-curvature representative
(flat for g = 1, hyperbolic for g ≥ 2, spherical for g = 0).  The conformal
modulus of a genus-1 surface is a point τ ∈ ℍ (upper half-plane), well-defined
up to SL(2, ℤ).

---

## 2 — Discrete conformal equivalence (DCE)

A **triangulated surface** is a pair (K, ℓ) where K is a simplicial complex
homeomorphic to a surface and ℓ: E → ℝ₊ assigns an edge length.  Two
length assignments ℓ and ℓ̃ are **discretely conformally equivalent** if there
exist vertex weights u: V → ℝ such that

```
ℓ̃ᵢⱼ = e^{(uᵢ + uⱼ)/2} · ℓᵢⱼ    for every edge {i, j}.
```

This is the discrete analogue of a conformal rescaling g̃ = e^{2φ} g.
The weights u ∈ ℝ^V are the *conformal factors* (log-scale factors on vertices).

**Key fact** (Springborn 2020): within each DCE class there exists a unique
length assignment realising a prescribed angle structure, and it can be found
by Newton's method on a convex energy.

---

## 3 — The variational energy

For each target corner angle **Θ_v** at vertex v, define the **angle-defect energy**:

```
E(u) = Σ_{corners} φ(αᵥ(u))   −   Σᵥ Θᵥ · uᵥ   +   boundary terms
```

where αᵥ(u) is the corner angle at v in the triangulation with edge lengths
ℓ̃(u) and φ is an appropriate primitive (Clausen / Lobachevsky / ImLi₂ depending
on geometry).

The **gradient** is simply the angle-sum residual:

```
∂E/∂uᵥ = Σ_{faces containing v} αᵥ(face)  −  Θᵥ
```

Setting G = 0 finds the unique u realising the prescribed angle sums.

### Three geometry modes

| Mode | Space | φ | Hessian | Newton step |
|---|---|---|---|---|
| Euclidean | ℝ² | Clausen Cl₂ | cotangent Laplacian, PSD | SimplicialLDLT(H) |
| Spherical | S² | ImLi₂ | NSD (concave E) | SimplicialLDLT(−H) |
| Hyper-ideal | H² | Lobachevsky | PSD (strictly convex) | SimplicialLDLT(H) |

---

## 4 — Gauss–Bonnet constraint

The target angles **must** satisfy the discrete Gauss–Bonnet equation

```
Σᵥ (2π − Θᵥ) = 2π · χ(M)
```

before any solver is called.  If this fails, no conformal factor can realise Θ
and Newton will not converge.  conformallab++ provides:

```cpp
check_gauss_bonnet(mesh, maps);     // throws if violated
enforce_gauss_bonnet(mesh, maps);   // redistributes residual uniformly
```

---

## 5 — From angles to geometry: trilateration

After Newton converges, edge lengths ℓ̃ are known.  The layout
(embedding into ℝ², S², or H²) is built by a **priority BFS**:

1. Place an initial face arbitrarily.
2. For each adjacent face, place its third vertex by *trilateration* —
   solving the system of three distance equations.
3. Priority is depth in the spanning tree (shallowest first).

For Euclidean geometry this is the standard cosine rule.
For hyperbolic geometry (Poincaré disk model) it uses the Möbius-isometric
placement formula implemented in `layout.hpp`.

---

## 6 — Cut graph and holonomy

For genus g ≥ 1 the layout does not close up: a handle introduces a
**holonomy**  — a non-trivial monodromy around each generator of π₁.

The **tree-cotree algorithm** (Erickson–Whittlesey 2005) computes a minimal
cut graph with exactly 2g seam edges.  After cutting, the surface is disk-like
and the BFS layout is well-defined.  The holonomies along the 2g cut edges are:

- **Euclidean:** lattice translations ω₁, ω₂ ∈ ℂ
- **Hyperbolic:** Möbius isometries T₁, T₂ ∈ SU(1,1)

---

## 7 — Period matrix (genus 1)

For a torus the **conformal modulus** is

```
τ = ω₂ / ω₁ ∈ ℍ
```

After Euclidean uniformization, ω₁ and ω₂ are the holonomies computed from
the seam edge displacements.  The SL(2, ℤ)-reduction to the fundamental
domain {|τ| ≥ 1, |Re(τ)| ≤ 1/2, Im(τ) > 0} is performed automatically by
`compute_period_matrix()`.

For genus g ≥ 2, the Siegel period matrix Ω ∈ H_g (g×g complex symmetric with
positive definite imaginary part) requires integrating holomorphic 1-forms — this
is Phase 10b.

---

## 8 — Fundamental domain

The fundamental domain of a torus is the parallelogram with vertices
{0, ω₁, ω₁+ω₂, ω₂} in ℂ.  conformallab++ computes this and provides tiling
utilities (`tiling_copy`, `tiling_neighbourhood`).

For genus g ≥ 2, the fundamental domain is the standard 4g-gon (Phase 9c).

---

## 9 — Where the code lives

```
Energy / gradient      code/include/*_functional.hpp
Hessian                code/include/*_hessian.hpp
Newton solver          code/include/newton_solver.hpp
Trilateration / BFS    code/include/layout.hpp
Cut graph              code/include/cut_graph.hpp
Holonomy               code/include/layout.hpp  (HolonomyData)
Period matrix          code/include/period_matrix.hpp
Fundamental domain     code/include/fundamental_domain.hpp
Möbius maps            code/include/layout.hpp  (MobiusMap)
```

All implementations are header-only (C++17), no compiled library.

---

## 10 — Primary references

| Reference | Covers |
|---|---|
| Springborn, *Discrete Uniformization of Polyhedral Surfaces*, 2020 | Complete mathematical foundation of all three modes |
| Sechelmann, *Variational Methods for Discrete Surface Parameterization*, TU Berlin 2016 | Original Java implementation — the direct source for this library |
| Pinkall & Polthier, 1993 | Cotangent Laplacian |
| Erickson & Whittlesey, SODA 2005 | Tree-cotree cut graph |
| Bobenko & Springborn, Trans. AMS 2004 | Variational circle-pattern framework |

Full reference list: [doc/math/references.md](references.md)