chore: .gitignore + vergessene Doc-Dateien nachgetragen
.gitignore: build-Verzeichnisse, .DS_Store, .claude/, CMake-Artefakte Doc-Dateien die beim Restructure-Commit fehlten: doc/api/headers.md — alle 24 Public-Header mit Beschreibung doc/api/tests.md — 26 Suiten, 158 Tests, Einzelzahlen doc/architecture/design-decisions.md — Architekturentscheidungen + Begründung doc/architecture/project-structure.md — Verzeichnisbaum + Build-Targets README.md: Links zu den vier neuen Doc-Dateien ergänzt Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
74
doc/api/headers.md
Normal file
74
doc/api/headers.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Public Headers (`code/include/`)
|
||||
|
||||
All algorithms are header-only. Include the headers you need directly —
|
||||
there is no compiled library to link against (only GTest for tests and
|
||||
CGAL/Eigen for the CGAL-dependent headers).
|
||||
|
||||
## Core mesh type
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `conformal_mesh.hpp` | `ConformalMesh` = `CGAL::Surface_mesh<Point3>`. Property-map naming convention. Index type aliases. `GeometryType` enum. |
|
||||
| `constants.hpp` | `conformallab::PI`, `TWO_PI` |
|
||||
| `mesh_builder.hpp` | `make_triangle()` / `make_tetrahedron()` / `make_quad_strip()` / `make_fan()` / `make_open_cylinder()` — test mesh factories |
|
||||
| `mesh_io.hpp` | `load_mesh()` / `save_mesh()` via `CGAL::IO` (OFF / OBJ / PLY) |
|
||||
| `mesh_utils.hpp` | `cgal_to_eigen()` — convert `ConformalMesh` vertex positions to `Eigen::MatrixXd` |
|
||||
|
||||
## Special functions
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `clausen.hpp` | `clausen_cl2(θ)` (Clausen Cl₂), `lobachevsky(θ)` (Л), `im_li2(θ)` (ImLi₂ = imaginary part of dilogarithm) |
|
||||
|
||||
## HyperIdeal geometry (H²)
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `hyper_ideal_geometry.hpp` | `ζ₁₃`, `ζ₁₄`, `ζ₁₅` (Springborn 2020), `l_from_zeta()`, `alpha_ij()`, `beta_i()`, `sigma_i()`, `sigma_ij()` |
|
||||
| `hyper_ideal_utility.hpp` | Tetrahedron volumes (Meyerhoff formula, Kolpakov–Mednykh) |
|
||||
| `hyper_ideal_visualization_utility.hpp` | Poincaré disk projection, circumcircle helpers, Lorentz boost |
|
||||
| `hyper_ideal_functional.hpp` | `HyperIdealMaps`, `setup_hyper_ideal_maps()`, `compute_hyper_ideal_lambda0_from_mesh()`, `assign_all_dof_indices()`, `hyper_ideal_gradient()`, `hyper_ideal_energy()` |
|
||||
| `hyper_ideal_hessian.hpp` | `hyper_ideal_hessian()` — symmetric FD Hessian (Phase 9b: analytic) |
|
||||
|
||||
## Spherical geometry (S²)
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `spherical_geometry.hpp` | Spherical arc-length, half-angle formula, spherical law of cosines |
|
||||
| `spherical_functional.hpp` | `SphericalMaps`, `setup_spherical_maps()`, `compute_spherical_lambda0_from_mesh()`, `spherical_gradient()`, `spherical_energy()` |
|
||||
| `spherical_hessian.hpp` | `spherical_hessian()` — analytic Hessian via ∂α/∂u from law of cosines |
|
||||
|
||||
## Euclidean geometry (ℝ²)
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `euclidean_geometry.hpp` | Euclidean corner angle (t-value / atan2), edge lengths from DOF vector |
|
||||
| `euclidean_functional.hpp` | `EuclideanMaps`, `setup_euclidean_maps()`, `compute_euclidean_lambda0_from_mesh()`, `euclidean_gradient()`, `euclidean_energy()` |
|
||||
| `euclidean_hessian.hpp` | `euclidean_hessian()` — cotangent Laplacian (Pinkall–Polthier 1993) |
|
||||
|
||||
## Solver
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `newton_solver.hpp` | `newton_euclidean()`, `newton_spherical()`, `newton_hyper_ideal()`, `solve_linear_system()` (SimplicialLDLT + SparseQR fallback), `NewtonResult` struct |
|
||||
|
||||
## Preprocessing
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `gauss_bonnet.hpp` | `euler_characteristic()`, `genus()`, `gauss_bonnet_sum()`, `gauss_bonnet_rhs()`, `gauss_bonnet_deficit()`, `check_gauss_bonnet()`, `enforce_gauss_bonnet()` |
|
||||
|
||||
## Layout and holonomy
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `cut_graph.hpp` | `CutGraph` struct, `compute_cut_graph()` — tree-cotree algorithm (Erickson–Whittlesey 2005), produces 2g seam edges |
|
||||
| `layout.hpp` | `euclidean_layout()`, `spherical_layout()`, `hyper_ideal_layout()`, `normalise_{euclidean,hyperbolic,spherical}()`. Structs: `Layout2D`, `Layout3D`, `HolonomyData`. `MobiusMap` (T(z)=(az+b)/(cz+d), `from_three`, `compose`, `inverse`, `apply`). Priority-BFS, `halfedge_uv`. |
|
||||
|
||||
## Post-processing
|
||||
|
||||
| Header | Description |
|
||||
|---|---|
|
||||
| `period_matrix.hpp` | `PeriodData`, `compute_period_matrix()`, `reduce_to_fundamental_domain()`, `is_in_fundamental_domain()` — period ratio τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ) reduction |
|
||||
| `fundamental_domain.hpp` | `FundamentalDomain`, `compute_fundamental_domain()` (genus 1: CCW parallelogram; genus > 1: empty, TODO Phase 9c), `tiling_copy()`, `tiling_neighbourhood()` |
|
||||
| `serialization.hpp` | `save_result_json()`, `load_result_json()`, `save_result_xml()`, `load_result_xml()`, `save_layout_off()` |
|
||||
80
doc/api/tests.md
Normal file
80
doc/api/tests.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Test Suites
|
||||
|
||||
## `conformallab_tests` — always built (no CGAL)
|
||||
|
||||
Pure-math tests, only Eigen required. Covers Java utilities ported in Phase 1–2.
|
||||
|
||||
| File | What it tests |
|
||||
|---|---|
|
||||
| `test_clausen.cpp` | Clausen Cl₂, Lobachevsky Л, ImLi₂ — values at known points |
|
||||
| `test_hyper_ideal_utility.cpp` | Tetrahedron volumes (Meyerhoff / Kolpakov–Mednykh) |
|
||||
| `test_matrix_utility.cpp` | Matrix helpers |
|
||||
| `test_surface_curve_utility.cpp` | Surface curve utilities |
|
||||
| `test_discrete_elliptic_utility.cpp` | Discrete elliptic functions |
|
||||
| `test_p2_utility.cpp` | P2 projective utilities |
|
||||
| `test_hyper_ideal_visualization_utility.cpp` | Poincaré disk projection, circumcircle |
|
||||
|
||||
**Total: 36 tests, 0 skipped.**
|
||||
|
||||
---
|
||||
|
||||
## `conformallab_cgal_tests` — built with `-DWITH_CGAL_TESTS=ON` or `-DWITH_CGAL=ON`
|
||||
|
||||
All tests have CTest prefix `cgal.` (set via `TEST_PREFIX "cgal."` in CMakeLists).
|
||||
|
||||
| Suite | File | Tests | What is verified |
|
||||
|---|---|---:|---|
|
||||
| `ConformalMeshTopology` | `test_conformal_mesh.cpp` | 4 | Euler characteristic, vertex/edge/face counts |
|
||||
| `ConformalMeshTraversal` | `test_conformal_mesh.cpp` | 4 | Halfedge iteration, valence, opposite |
|
||||
| `ConformalMeshProperties` | `test_conformal_mesh.cpp` | 5 | Property maps (λ, θ, idx, α, geometry type) |
|
||||
| `ConformalMeshValidity` | `test_conformal_mesh.cpp` | 1 | CGAL validity for all factory meshes |
|
||||
| `HyperIdealFunctional` | `test_hyper_ideal_functional.cpp` | 7 | FD gradient checks + Hessian symmetry |
|
||||
| `SphericalFunctional` | `test_spherical_functional.cpp` | 12 | Angle formula + gradient + gauge-fix *(1 skipped)* |
|
||||
| `EuclideanFunctional` | `test_euclidean_functional.cpp` | 11 | Angle formula + gradient *(1 skipped)* |
|
||||
| `EuclideanHessian` | `test_euclidean_hessian.cpp` | 9 | Cotangent Laplacian structure, FD agreement, PSD, null space |
|
||||
| `SphericalHessian` | `test_spherical_hessian.cpp` | 8 | Derivative correctness, NSD at equilibrium |
|
||||
| `NewtonSolver` | `test_newton_solver.cpp` | 11 | Convergence: Euclidean ×3, Spherical ×4, HyperIdeal ×4 |
|
||||
| `SparseQRFallback` | `test_newton_solver.cpp` | 3 | Full-rank LDLT · singular matrix → QR · closed mesh gauge mode |
|
||||
| `MeshIO` | `test_mesh_io.cpp` | 9 | OFF/OBJ round-trips, error handling |
|
||||
| `Pipeline` | `test_pipeline.cpp` | 5 | End-to-end: build → setup → solve → export → reload |
|
||||
| `Layout` | `test_layout.cpp` | 8 | Edge-length preservation (Eucl./Spher.), Poincaré disk layout |
|
||||
| `Serialization` | `test_layout.cpp` | 2 | JSON and XML round-trips (DOF vector + layout UVs) |
|
||||
| `GaussBonnet` | `test_phase6.cpp` | 8 | χ, genus, sum/RHS, deficit, check, enforce |
|
||||
| `CutGraph` | `test_phase6.cpp` | 6 | Tree-cotree, open/closed meshes, flag–index consistency |
|
||||
| `HyperbolicTrilateration` | `test_phase6.cpp` | 4 | Möbius + law of cosines: exact distances, disk interior, off-origin |
|
||||
| `Normalisation` | `test_phase6.cpp` | 4 | Euclidean centroid, length ratios, Möbius centring |
|
||||
| `MobiusMap` | `test_phase7.cpp` | 8 | Identity, inverse, compose, `from_three`, `apply(Vector2d)` |
|
||||
| `BestRootFace` | `test_phase7.cpp` | 2 | Valid root face selection, interior bonus |
|
||||
| `HalfedgeUV` | `test_phase7.cpp` | 4 | Size = #halfedges, seam consistency, boundary halfedges = 0 |
|
||||
| `PriorityBFS` | `test_phase7.cpp` | 3 | Success, no seam on open meshes, all vertices placed |
|
||||
| `NormaliseEuclidean` | `test_phase7.cpp` | 2 | UV centroid = 0, halfedge_uv centroid = 0 |
|
||||
| `PeriodMatrix` | `test_phase7.cpp` | 7 | τ ∈ ℍ, SL(2,ℤ) reduction, exception outside ℍ |
|
||||
| `FundamentalDomain` | `test_phase7.cpp` | 7 | Genus-1 parallelogram CCW, generators, g > 1 empty |
|
||||
| `TilingCopy/Neighbourhood` | `test_phase7.cpp` | 4 | Translation correct, tile count |
|
||||
| `GeometryUtils` | `test_geometry_utils.cpp` | 6 | Java CuttingUtility, UnwrapUtility, ConvergenceUtility, HomologyTest ports (Tests 1–6); Test 7 GTEST_SKIP stub |
|
||||
|
||||
**Total: 158 tests, 2 intentional skips.**
|
||||
|
||||
The 2 skips are:
|
||||
- `SphericalFunctional` — analytic gauge-fix stub (Phase 9b)
|
||||
- `GeometryUtils` Test 7 — genus-2 homology (Phase 9c)
|
||||
|
||||
Both correspond to Java `@Ignore`-annotated tests in the original library.
|
||||
|
||||
---
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
# All CGAL tests
|
||||
ctest --test-dir build -R "^cgal\." --output-on-failure
|
||||
|
||||
# One suite
|
||||
./build/conformallab_cgal_tests --gtest_filter="PeriodMatrix*"
|
||||
|
||||
# One specific test
|
||||
./build/conformallab_cgal_tests --gtest_filter="PeriodMatrix.TauInUpperHalfPlane"
|
||||
|
||||
# Verbose output with timing
|
||||
./build/conformallab_cgal_tests --gtest_filter="NewtonSolver*" --gtest_print_time=1
|
||||
```
|
||||
Reference in New Issue
Block a user