docs: Mathematiker-Onboarding — Theorie, Validierung, Beispiel-Meshes, 170 Tests

Ziel: einem interessierten Mathematiker ermöglichen, die bisherige Arbeit
      unabhängig zu validieren und eigene Forschung beizutragen.

Neu:
  doc/math/discrete-conformal-theory.md
      Kompakte mathematische Einführung (DCE, Variationsprinzip, drei
      Geometriemodi, Holonomie, Periodenmatrix) für Riemann-Flächen-Kenner.

  doc/math/validation.md
      Analytisch bekannte Sollwerte + wie man sie mit dem Code prüft:
      Gauss–Bonnet (χ), τ ∈ Fundamentaldomäne (3 Invarianten), Symmetrie-
      Argumente für τ=i (4-fach) und τ=e^{iπ/3} (6-fach), Newton-Konvergenz,
      Gradienten-Check (FD), Holonomie-Kommutator. Reviewer-Checkliste.

  CONTRIBUTING.md (Root)
      Gitea/GitHub-Standard: CONTRIBUTING.md im Root-Verzeichnis als
      Kurzreferenz mit Links zu doc/contributing.md und den Math-Docs.

  code/data/off/torus_4x4.off   — 16 Vertices, 32 Flächen, Genus 1
  code/data/off/torus_8x8.off   — 64 Vertices, 128 Flächen, Genus 1
  code/data/off/torus_hex_6x6.off — 36 Vertices, 72 Flächen, 6-fach Sym.

Aktualisiert:
  README.md              — 158 → 170 Tests, zwei neue Math-Links in Tabelle
  doc/api/tests.md       — 28 Suiten, 170 Tests, 1 Skip (korrigiert)
  doc/contributing.md    — Testzähler 158+2 → 170+1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

doc/math/discrete-conformal-theory.md

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