ConformalLabpp/doc/math/geometry-modes.md

The Three Geometry Modes

conformallab++ implements discrete conformal geometry in three model spaces. All three share the same algorithmic structure — only the angle formula, the trilateration geometry, and the Hessian sign differ.

---

Comparison

                  Euclidean            Spherical            Hyper-ideal
                  ─────────────────────────────────────────────────────
Space             ℝ²                   S²                   H² (Poincaré disk)
Curvature         K = 0                K = +1               K = −1
Typical genus     any (cone metrics)   0                    ≥ 1
Angle sum         Σαᵥ = Θᵥ             Σαᵥ = Θᵥ             Σβᵥ = Θᵥ
Gradient sign     G_v = actual − Θᵥ    G_v = Θᵥ − actual    G_v = actual − Θᵥ
Hessian           PSD (cotangent-Lap.) NSD (sign-flip)       PSD (FD, strict conv.)
Newton solve      SimplicialLDLT(H)    SimplicialLDLT(−H)    SimplicialLDLT(H)
Holonomy          translations ωᵢ      rotations (2-D)       Möbius maps Tᵢ ∈ SU(1,1)
Period            τ = ω₂/ω₁ ∈ ℍ        —                     axis of Tᵢ
Normalise         PCA centring         Rodrigues to N pole   weighted Möbius centring
Layout            Layout2D (ℝ²)        Layout3D (unit sphere) Layout2D (Poincaré disk)

---

Euclidean (ℝ²)

Energy: the cotangent-weighted angle defect energy (Pinkall & Polthier 1993).

Effective log-length:

Λ̃ᵢⱼ = λ°ᵢⱼ + uᵢ + uⱼ

Gradient: G_v = Σ_{faces adj. v} α_v(face) − Θᵥ — the actual angle sum minus the target.

Hessian: cotangent Laplacian, assembled in euclidean_hessian.hpp. PSD with one zero eigenvalue (constant function) for closed meshes — handled by pinning one vertex or SparseQR.

Normalisation: centroid → origin, major axis → x-axis via PCA (normalise_euclidean).

Holonomy: lattice translations ω₁, ω₂ ∈ ℂ for closed surfaces. Period ratio τ = ω₂/ω₁ ∈ ℍ is the conformal modulus of the torus.

---

Spherical (S²)

Typical use: genus-0 (sphere-like) surfaces.

Gradient: G_v = Θᵥ − Σ α_v(face) — note the sign reversal vs. Euclidean.

Hessian: NSD (the spherical energy is concave). Newton solves (−H)·Δx = G, i.e. SimplicialLDLT is called on −H. This is handled transparently in newton_spherical().

Gauge fix: for a closed spherical surface, one additional DOF must be pinned to remove the rotational gauge mode. SphericalMaps has a dedicated gauge_vertex field.

Normalisation: normalise_spherical() rotates the layout so the area centroid maps to the north pole (Rodrigues rotation formula).

---

Hyper-ideal (H²)

Typical use: genus-g surfaces (g ≥ 1), hyperbolic cone metrics.

DOFs: both vertex variables bᵢ (hyper-ideal radius) and edge variables aₑ (intersection angle). assign_all_dof_indices(mesh, maps) assigns both automatically. No vertex needs to be pinned — the functional is strictly convex.

Geometry functions (in hyper_ideal_geometry.hpp):

ζ₁₃(b, a)  ζ₁₄(b, a)  ζ₁₅(b, a)   — the three fundamental Springborn functions
lᵢⱼ(ζ)                             — edge length from ζ value
αᵢⱼ(l₁, l₂, l₃)                   — interior angle
βᵢ(l₁, l₂, l₃)                    — vertex angle sum contribution

Hessian: currently a symmetric finite-difference approximation (see hyper_ideal_hessian.hpp). The analytic Hessian through the (bᵢ, aₑ) → lᵢⱼ → ζ → αᵢⱼ/βᵢ chain is Phase 9b.

Holonomy: Möbius isometries Tᵢ ∈ SU(1,1) (orientation-preserving isometries of the Poincaré disk). MobiusMap in layout.hpp: T(z) = (az+b)/(cz+d).

Normalisation: normalise_hyperbolic() performs iterative face-area-weighted Möbius centring (Fréchet mean, 30 iterations) to map the weighted centroid to the disk origin.

---

Gauss–Bonnet constraint

Before calling any Newton solver, the target angles must satisfy the Gauss–Bonnet equation:

Σᵥ (2π − Θᵥ)  =  2π · χ(M)    (Euclidean / flat)
Σᵥ (2π − Θᵥ)  >  0             (spherical, χ > 0)
Σᵥ (2π − Θᵥ)  <  0             (hyperbolic, χ < 0)

If this is violated, no conformal factor can realise the target angles and Newton will fail to converge without a visible error.

check_gauss_bonnet(mesh, maps);      // throws if violated
enforce_gauss_bonnet(mesh, maps);    // redistributes residual uniformly across all vertices

This is the most common source of silent non-convergence. Always call one of these before solving.