b235666725
Für einen Mathematiker der unabhängig validieren und eigene Forschung
einbringen möchte.
Doxygen-Kommentare (code/include/):
newton_solver.hpp — newton_euclidean(), newton_spherical(), newton_hyper_ideal()
je mit \param, \return, \note, \see inkl. mathematischer Begründung
(Konvexität, Vorzeichenkonvention, SparseQR-Fallback-Erklärung)
layout.hpp — euclidean_layout(), spherical_layout(), hyper_ideal_layout()
mit vollständiger Parameter-Doku, halfedge_uv-Semantik, Poincaré-Disk-Note
Neues Dokument:
doc/math/validation-protocol.md
7 reproduzierbare Checks mit konkreten Befehlen und erwartetem Output:
0. 170 Tests, 1 Skip
1. Gauss–Bonnet exakt (1e-10)
2. FD-Gradientencheck < 1e-6 für alle 3 Geometrien
3. Newton-Konvergenz < 50 Iterationen
4. τ ∈ SL(2,ℤ)-Fundamentaldomäne (3 Invarianten)
5. Möbius-Arithmetik (Inverse, Compose, from_three)
6. End-to-End-Pipeline
7. Manueller τ-Check für torus_4x4.off (Codebeispiel)
Neues Tutorial:
doc/tutorials/add-inversive-distance.md
Vollständiger Step-by-Step-Port von Phase 9a (Luo 2004):
Header anlegen, Energie/Gradient implementieren, FD-Check,
Newton-Wrapper, CMakeLists, Java-Referenzvergleich, Checkliste.
doc/getting-started.md:
Abschnitt "Known issues": macOS-Finder-Duplikate (rm-Befehl),
Warnung "First build 30–90s" (Tarball-Extraktion)
README.md:
Zwei neue Links in der Dokumentationstabelle (validation-protocol,
tutorial)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
167 lines
4.3 KiB
Markdown
167 lines
4.3 KiB
Markdown
# Getting Started
|
||
|
||
## Prerequisites
|
||
|
||
| Tool | Minimum | Notes |
|
||
|---|---|---|
|
||
| C++ compiler (GCC or Clang) | C++17 | GCC 11+ or Clang 14+ recommended |
|
||
| CMake | 3.20 | |
|
||
| Boost headers | 1.70 | Only for `-DWITH_CGAL_TESTS=ON` or `-DWITH_CGAL=ON` |
|
||
| Wayland/X11 dev headers | — | Only for `-DWITH_CGAL=ON` (viewer) |
|
||
|
||
All other dependencies (Eigen 3.4, CGAL 6.1.1, libigl 2.6, GLFW 3.4, GTest 1.14)
|
||
are bundled as tarballs in `code/deps/tarballs/` and extracted automatically at CMake
|
||
configure time. No internet access is required at build time (except GTest, fetched via
|
||
`FetchContent` from GitHub).
|
||
|
||
Install Boost on your system:
|
||
```bash
|
||
# Ubuntu / Debian
|
||
apt install libboost-dev
|
||
|
||
# macOS
|
||
brew install boost
|
||
```
|
||
|
||
---
|
||
|
||
## Clone
|
||
|
||
```bash
|
||
git clone https://codeberg.org/TMoussa/ConformalLabpp
|
||
cd ConformalLabpp
|
||
```
|
||
|
||
---
|
||
|
||
## Build modes
|
||
|
||
Three modes with increasing dependencies:
|
||
|
||
### Mode 1 — Fast tests (default, no system dependencies)
|
||
|
||
Pure-math tests: Clausen functions, hyper-ideal geometry, matrix utilities.
|
||
|
||
```bash
|
||
cmake -S code -B build
|
||
cmake --build build --target conformallab_tests -j$(nproc)
|
||
ctest --test-dir build --output-on-failure
|
||
```
|
||
|
||
Expected: **36 tests pass**.
|
||
|
||
### Mode 2 — CGAL tests, headless (recommended for CI and development)
|
||
|
||
Full CGAL test suite. Requires Boost headers only — no display, no Wayland, no GLFW.
|
||
|
||
```bash
|
||
cmake -S code -B build -DWITH_CGAL_TESTS=ON
|
||
cmake --build build --target conformallab_cgal_tests -j$(nproc)
|
||
ctest --test-dir build -R "^cgal\." --output-on-failure
|
||
```
|
||
|
||
Expected: **158 tests pass, 2 skipped** (intentional stubs for Phase 9 items).
|
||
|
||
### Mode 3 — Full local build (CLI app + interactive viewer)
|
||
|
||
Requires Wayland or X11 development packages (`wayland-scanner`, `libx11-dev`, etc.).
|
||
Automatically enables the viewer library (GLFW + libigl).
|
||
|
||
```bash
|
||
cmake -S code -B build -DWITH_CGAL=ON
|
||
cmake --build build -j$(nproc)
|
||
```
|
||
|
||
> **Note:** `-DWITH_CGAL=ON` implies `-DWITH_VIEWER=ON`. Do not use this in headless
|
||
> environments — it will fail with `Failed to find wayland-scanner`.
|
||
|
||
---
|
||
|
||
## Running a single test
|
||
|
||
```bash
|
||
# By GTest filter (fastest, full output)
|
||
./build/conformallab_cgal_tests --gtest_filter="NewtonSolver*"
|
||
./build/conformallab_tests --gtest_filter="Clausen*"
|
||
|
||
# By CTest regex
|
||
ctest --test-dir build -R "cgal.NewtonSolver" --output-on-failure
|
||
```
|
||
|
||
All CGAL tests have the prefix `cgal.` in CTest (set in `tests/cgal/CMakeLists.txt`
|
||
via `TEST_PREFIX "cgal."`).
|
||
|
||
---
|
||
|
||
## First run — CLI app
|
||
|
||
After a full build (`-DWITH_CGAL=ON`):
|
||
|
||
```bash
|
||
# Euclidean conformal layout
|
||
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
|
||
|
||
# Spherical layout
|
||
./bin/conformallab_core -i input.off -g spherical -o sphere.off
|
||
|
||
# Hyperbolic layout (HyperIdeal)
|
||
./bin/conformallab_core -i input.off -g hyper_ideal -o hyperbolic.off
|
||
|
||
# Show input mesh in interactive viewer
|
||
./bin/conformallab_core -i input.off -s
|
||
|
||
# All options
|
||
./bin/conformallab_core --help
|
||
```
|
||
|
||
## Example programs
|
||
|
||
```bash
|
||
./build/examples/example_layout [input.off] [layout.off] [result.json]
|
||
./build/examples/example_euclidean [input.off] [output.off]
|
||
./build/examples/example_hyper_ideal [input.off] [output.off]
|
||
./build/examples/example_viewer [input.off] # interactive, requires WITH_VIEWER
|
||
```
|
||
|
||
`example_layout.cpp` is the best starting point — it shows the complete pipeline in ~120 lines.
|
||
|
||
---
|
||
|
||
## Known issues
|
||
|
||
### macOS Finder duplicates
|
||
|
||
macOS Finder sometimes creates duplicate files named `foo 2.hpp` when copying
|
||
the repository. These cause confusing compile errors ("redefinition of …").
|
||
|
||
**Fix (run once from the repo root):**
|
||
```bash
|
||
find code/include -name "* 2.*" -delete
|
||
find code/include -name "*\ 2.*" -delete
|
||
```
|
||
|
||
Files without a ` 2` suffix are always canonical — the duplicates are safe to delete.
|
||
|
||
### First build is slow
|
||
|
||
The first CMake configure extracts four tarballs (Eigen 3.4, CGAL 6.1.1,
|
||
libigl 2.6, GLFW 3.4) and downloads GTest via `FetchContent`.
|
||
Allow **30–90 seconds** for the first configure. Subsequent builds are fast
|
||
(< 10 s incremental).
|
||
|
||
---
|
||
|
||
## Rebuilding the CI Docker image
|
||
|
||
The CI runner is a self-hosted Raspberry Pi (ARM64). After changes to
|
||
`.gitea/docker/Dockerfile.ci-cpp`:
|
||
|
||
```bash
|
||
docker buildx build \
|
||
--platform linux/arm64 \
|
||
-f .gitea/docker/Dockerfile.ci-cpp \
|
||
-t git.eulernest.eu/conformallab/ci-cpp:latest \
|
||
--push \
|
||
.gitea/docker/
|
||
```
|