chore/docs: Onboarding-Sprint für externe Mathematiker
Some checks failed
C++ Tests / test-fast (push) Successful in 2m16s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / test-fast (pull_request) Successful in 2m27s
C++ Tests / test-cgal (pull_request) Failing after 2m11s

- LICENSE: Copyright Tarik Moussa <Tarik.moussa95@gmail.com> (war user2595)
- CITATION.cff: maschinenlesbares Zitat mit 3 Primärreferenzen (Sechelmann 2016,
  Springborn 2020, Bobenko–Springborn 2004)
- scripts/try_it.sh: Clone→Build→Test→Beispiel in einem Skript
- doc/math/software-landscape.md: Landkarte aller relevanten Tools,
  Problem-A vs. Problem-B Abgrenzung, vollständige Feature-Matrix
- doc/math/novelty-statement.md: formales Alleinstellungsmerkmal,
  Zielgruppen, was dieses Projekt nicht ist
- code/CMakeLists.txt: cmake --install Target für Header-only-Library
- doc/getting-started.md: Testzähler 158→173, Beispiel-Output, try_it.sh
- README.md: CI/License/DOI-Badges, Cite-Abschnitt, Issue-Tracker-Link,
  Copyright, neue Doku-Einträge software-landscape + novelty-statement

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-18 20:35:46 +02:00
parent c8e77e715c
commit c5efc3d3cc
8 changed files with 483 additions and 2 deletions

View File

@@ -0,0 +1,143 @@
# Scientific Novelty Statement
> **Purpose.** This document explicitly states what conformallab++ contributes
> that no other open-source C++ library provides, and for which research problems
> it is the right tool. It is intended as a reference for paper introductions,
> grant applications, and collaborator onboarding.
---
## 1 — The one-sentence statement
conformallab++ is the **only open-source C++ library** that implements discrete
conformal equivalence in all three geometric settings (Euclidean, Spherical,
Hyper-ideal), with a complete downstream Teichmüller pipeline — period matrix
τ ∈ , Möbius holonomy, and fundamental domain construction — in a single
cohesive codebase targeting the CGAL ecosystem.
---
## 2 — Unique features (no equivalent elsewhere in C++)
### 2.1 — Three geometry modes in one library
| Mode | Space | Energy | Application |
|---|---|---|---|
| Euclidean | ℝ² | Σ log(ℓᵢⱼ/ℓ̃ᵢⱼ)² | Flat torus uniformization, texture atlasing |
| Spherical | S² | NSD variant | Constant positive curvature, Koebe's theorem |
| HyperIdeal | H² (Poincaré disk) | Springborn 2020 ζ-functions | Hyperbolic surfaces, genus g ≥ 2 |
No other open-source C++ library implements all three. geometry-central
(CMU) has Euclidean and partial HyperIdeal but lacks the Spherical mode entirely.
### 2.2 — Period matrix τ with SL(2,) reduction
For a closed genus-1 surface, conformallab++ computes the complex modulus
τ = ω_b/ω_a ∈ from the holonomy of the uniformizing flat metric, then reduces
τ to the standard fundamental domain
```
F = { τ ∈ : |τ| ≥ 1, |Re(τ)| ≤ 1/2 }
```
via the SL(2,) action. This identifies the conformal class of the surface in
Teichmüller space T₁ ≅ /SL(2,).
**No other open-source C++ library computes τ.** The Java ConformalLab does,
but requires the JVM and is not integrated with any modern mesh processing framework.
### 2.3 — Möbius holonomy in SU(1,1)
The holonomy representation ρ: π₁(Σ) → SU(1,1) is computed for closed surfaces
of any genus. For the torus this gives the lattice generators ω_a, ω_b ∈ .
For hyperbolic surfaces this gives deck transformations as Möbius maps acting on
the Poincaré disk.
### 2.4 — Tree-cotree cut graph (EricksonWhittlesey)
For a closed surface of genus g, the cut graph produces exactly 2g seam edges
that cut the surface to a disk. This is required for layout, holonomy computation,
and fundamental domain construction. The cut graph is not present in any other
C++ conformal geometry library.
### 2.5 — Fundamental domain and tiling
From the holonomy generators, conformallab++ constructs the fundamental domain
parallelogram and its lattice tiling for genus-1 surfaces. This is the discrete
analog of the classical construction of a torus as /Λ.
---
## 3 — What makes this a research tool, not just an implementation
### 3.1 — Variational framework, not heuristic
The energy functionals are derived from first principles (BobenkoSpringborn 2004).
The Newton solver guarantees quadratic convergence to the *global* optimum for
Euclidean and HyperIdeal modes (strict convexity). The solution is mathematically
unique (up to Möbius normalisation) — not an approximation.
### 3.2 — Analytic Hessians
For Euclidean and Spherical modes, the Hessian is computed analytically from the
cotangent Laplacian and its spherical analog. This gives exact derivatives, not
finite-difference approximations, which is required for reproducible research.
### 3.3 — Discrete-to-smooth correspondence
The discrete period matrix τ_discrete is a computable invariant of the triangulated
surface. Its convergence to the smooth Riemannian τ_smooth under mesh refinement
is an open research question that this library is designed to investigate.
### 3.4 — Full test coverage of analytic invariants
173 CGAL tests verify mathematically provable properties:
- GaussBonnet: Σ(2πΘᵥ) = 2π·χ(M) to machine precision
- τ ∈ fundamental domain: three inequalities
- Holonomy closure: [T_a, T_b] = Id (abelian for genus 1)
- Gradient consistency: FD check at ε = 1e-5 for all three functionals
These are not regression tests — they verify mathematical correctness independently
of the input mesh.
---
## 4 — Target audience
| Audience | Primary use |
|---|---|
| Discrete differential geometers | Computing τ, holonomy, uniformization for theoretical examples |
| Computational mathematicians | Benchmarking discrete-to-smooth convergence of τ |
| CGAL developers | Extending the CGAL parameterization package (Phase 8) |
| Computer graphics researchers | Conformal texture atlasing with exact angle preservation |
| Algebraic geometers | Numerical experiments on moduli spaces of tori |
---
## 5 — Relationship to the Java original
conformallab++ is a port of Stefan Sechelmann's Java ConformalLab (TU Berlin,
~850 commits, v1.0.0 2018, LGPL). The port:
- Replaces the custom Java halfedge structure (`CoHDS`) with `CGAL::Surface_mesh`
- Replaces JUnit tests with GTest + CGAL test format (173 tests)
- Adds Doxygen API documentation, CMake build, and CLI
- Is MIT licensed (the Java original is LGPL)
- Targets submission to the CGAL library as package `Discrete_conformal_map`
The mathematics is identical to the Java original. The C++ implementation is
independently validated by the test suite and by agreement with Java outputs on
shared test meshes (cathead, brezel, torus family).
---
## 6 — What conformallab++ is not
- **Not a mesh processing library.** It operates on existing triangulated surfaces.
Remeshing, smoothing, and simplification are outside its scope.
- **Not a real-time renderer.** The Newton solver is accurate but not optimised
for interactive frame rates (though it converges in < 1 second for typical meshes).
- **Not a distortion-minimisation tool.** It computes the unique conformally
equivalent metric, not a least-distortion UV map. Use libigl for the latter.
- **Not complete for genus g 2.** The Siegel period matrix Ω and full
uniformization for higher genus are Phase 10 research targets, not yet implemented.