chore/docs: Onboarding-Sprint für externe Mathematiker
- 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:
143
doc/math/novelty-statement.md
Normal file
143
doc/math/novelty-statement.md
Normal 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 (Erickson–Whittlesey)
|
||||
|
||||
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 (Bobenko–Springborn 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:
|
||||
- Gauss–Bonnet: Σ(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.
|
||||
Reference in New Issue
Block a user