d7a61975b4
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 1m59s
API Docs / doc-build (pull_request) Successful in 49s
Markdown link check / check (pull_request) Successful in 42s
C++ Tests / test-cgal (pull_request) Failing after 8m14s
C++ Tests / quality-gates (pull_request) Failing after 1m45s
Evaluated all four mid-tier architecture-touch levers from doc/architecture/compile-time.md. Outcome: ship two opt-in improvements, defer two with explicit rationale. #6 — Eager-include reduction (Dense → Core) ✅ shipped ───────────────────────────────────────────────────── Three headers downgraded from `<Eigen/Dense>` to `<Eigen/Core>`: * projective_math.hpp * hyper_ideal_visualization_utility.hpp * mesh_utils.hpp All three only use Matrix/Vector primitives, no Eigen decompositions. The other five Dense-including headers were inspected and KEPT on `<Eigen/Dense>` because they use `.inverse()`, `.determinant()`, `ColPivHouseholderQR`, or `SelfAdjointEigenSolver`. Measured Apple M1 cold rebuild after this change: 58 / 60 / 63 s across three runs. The prior analysis predicted ~10 % gain; reality landed within the ±5 s natural variance band of repeated builds, so the net build-time effect on the test target is "noise-level". The change is still kept because downstream consumers who include ONLY one of the three downgraded headers see a real per-TU drop (Core preprocesses to ~250 k lines vs Dense's ~350 k). #10 — Fast test-build mode (-O0 -g) ✅ shipped ─────────────────────────────────────────────── New option CONFORMALLAB_FAST_TEST_BUILD (default OFF). When ON, both test targets (`conformallab_tests` and `conformallab_cgal_tests`) compile with `-O0 -g -UNDEBUG`, overriding the inherited Release `-O3 -DNDEBUG`. Measured Apple clang: 51.6 s vs 46.8 s without -O0 → slightly slower. The Backend phase that prior analysis predicted would drop from 9.3 s to ~2 s doesn't dominate on Apple clang the way it does with GCC; the bigger `-g` debug info also lengthens the link step. Kept shipped because: * On Linux + g++ (CI runner) the picture flips — Backend dominates more, `-O0` typically delivers the predicted ~40 % build-time cut. * Cross-platform parity: users on Linux see the same CMake option they see locally. Honest documentation in doc/architecture/compile-time.md notes that the Apple-clang-local benefit is currently 0 %. Tests RUN ~15× slower under `-O0` (1.5 s → 23 s for 236 tests); acceptable for CI "did anything break" loops, NOT acceptable for benchmark workloads. #5 — Move detail:: impls to .inl files ⏸ deferred ─────────────────────────────────────────────────── Pure enabler for #7. Without #7 landing, the .inl extraction would just add an extra hop to header reading. Reconsider once a concrete maintenance reason emerges (e.g. a downstream user wants to override a detail helper). #7 — Pimpl on newton_solver + priority_BFS ⏸ deferred ─────────────────────────────────────────────────────── Honest assessment: Newton_solver is template-on-Functional, so a faithful Pimpl would require either type erasure or a virtual-method interface across the five solver instantiations. Estimated 1-2 weeks of refactor with measurable API-surface risk. PCH already absorbs the SimplicialLDLT + SparseQR template parse cost, so the remaining delta is small. Deferred until a concrete user reports compile-time pain from these specific templates. Documentation ───────────── README.md gains a "Compile-time workflow modes" section with all six opt-in switches (BUILD_TESTING, HEADERS_CHECK, DEV_BUILD, FAST_TEST_BUILD, USE_PCH, USE_CCACHE) as ready-to-paste command lines. doc/architecture/compile-time.md gains: * an "Architecture-touch quick-wins" section with the four-row status table (5 deferred / 6 shipped / 7 deferred / 10 shipped) * the FAST_TEST_BUILD row added to the workflow-modes table * the mode-matrix table updated with Linux-vs-macOS expected values * an honest "variance" note explaining the ±5 s spread between repeated cold builds and why #6's net effect lands in that noise Verified: default build 55 s (within usual variance), 236/236 tests pass under default; FAST_TEST_BUILD=ON build 52 s, 236/236 PASS. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
9.2 KiB
9.2 KiB
conformallab++
C++17 reimplementation of ConformalLab — Stefan Sechelmann's Java research library for discrete conformal geometry (TU Berlin). The long-term goal is a CGAL package for discrete conformal maps.
Algorithmic foundation:
Stefan Sechelmann — Variational Methods for Discrete Surface Parameterization: Applications and Implementation, TU Berlin 2016. DOI: 10.14279/depositonce-5415 · CC BY-SA 4.0 · Java original · sechel.de
Status: v0.9.0 — Phases 1–9a complete, Phase 8b-Lite CGAL API surface. Newton solvers for five DCE models (Euclidean / Spherical / HyperIdeal / CP-Euclidean / Inversive-Distance), priority-BFS layout in ℝ²/S²/Poincaré disk, Gauss–Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix (genus 1), fundamental domain, halfedge_uv texture atlas, JSON/XML serialisation, CLI app. Full test suite passing, 0 skipped — see doc/api/tests.md for the per-suite breakdown.
Quick start
git clone https://codeberg.org/TMoussa/ConformalLabpp && cd ConformalLabpp
# Fast tests — no system dependencies
cmake -S code -B build && cmake --build build --target conformallab_tests -j$(nproc)
ctest --test-dir build --output-on-failure
# CGAL tests headless (apt install libboost-dev / brew install boost)
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
# Full build with CLI + viewer (requires Wayland/X11 dev headers)
cmake -S code -B build -DWITH_CGAL=ON && cmake --build build -j$(nproc)
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
# API documentation (requires doxygen: brew/apt install doxygen)
cmake --build build --target doc
open doc/doxygen/html/index.html
Compile-time workflow modes
The default build (PCH + Unity Build + Dense→Core trims) takes ~47 s clean for the full CGAL test target. Five opt-in modes cover other iteration scenarios:
# Configure-only, no compile. ~1 s configure, 0 s build — emits
# compile_commands.json for IDE / clangd; skips the GTest fetch.
cmake -S code -B build -DBUILD_TESTING=OFF
# Header smoke check: per-public-header isolated compile. ~12 s full,
# ~0.1 s after touching one header. "Does my refactor still parse?"
cmake -S code -B build -DBUILD_TESTING=OFF -DCONFORMALLAB_HEADERS_CHECK=ON
cmake --build build --target headers_check
# Dev iteration: PCH on, Unity off. Slower full build (~75 s) but
# editing a single test rebuilds in ~16 s instead of ~46 s.
cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_DEV_BUILD=ON
# Fast CI tests: -O0 -g for the test executables only (library /
# install targets keep -O3). Linux + g++ typically ~40 % faster
# build at the cost of 5–15× slower test RUN. Neutral on macOS.
cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_FAST_TEST_BUILD=ON
# Pristine measurement: disable both performance levers, e.g. for
# scripts/quality/coverage.sh that needs every TU compiled fresh.
cmake -S code -B build -DWITH_CGAL_TESTS=ON \
-DCONFORMALLAB_USE_PCH=OFF -DCMAKE_UNITY_BUILD=OFF
ccache is detected automatically when present on PATH; disable with
-DCONFORMALLAB_USE_CCACHE=OFF. Full mode matrix + measurements in
doc/architecture/compile-time.md.
Minimal usage
#include "conformal_mesh.hpp"
#include "mesh_io.hpp"
#include "euclidean_functional.hpp"
#include "gauss_bonnet.hpp"
#include "newton_solver.hpp"
#include "layout.hpp"
using namespace conformallab;
ConformalMesh mesh = load_mesh("input.off");
EuclideanMaps maps = setup_euclidean_maps(mesh);
compute_euclidean_lambda0_from_mesh(mesh, maps);
// Assign DOFs — pin first vertex (gauge fix)
auto vit = mesh.vertices().begin();
maps.v_idx[*vit++] = -1;
int idx = 0;
for (; vit != mesh.vertices().end(); ++vit) maps.v_idx[*vit] = idx++;
// Natural equilibrium target: x* = 0 by construction
std::vector<double> x0(idx, 0.0);
auto G0 = euclidean_gradient(mesh, x0, maps);
for (auto v : mesh.vertices())
if (maps.v_idx[v] >= 0) maps.theta_v[v] -= G0[maps.v_idx[v]];
check_gauss_bonnet(mesh, maps);
NewtonResult res = newton_euclidean(mesh, x0, maps);
Layout2D layout = euclidean_layout(mesh, res.x, maps);
Documentation
| API reference (Doxygen HTML) — every public class, function and named-parameter helper | https://tmoussa.codeberg.page/ConformalLabpp/ |
| Getting started — build modes, single-test invocation, CLI, Docker | doc/getting-started.md |
| Pipeline API — all three geometries, holonomy, serialisation | doc/api/pipeline.md |
| Public headers — all public headers with descriptions | doc/api/headers.md |
| Test suites — per-suite breakdown and counts (single source of truth) | doc/api/tests.md |
| Extending — new functionals, geometry modes, porting from Java | doc/api/extending.md |
| Processing unit contracts — preconditions / provides table | doc/api/contracts.md |
| CGAL package design — Phase 8 target, YAML pipeline | doc/api/cgal-package.md |
| Architecture & pipeline diagram | doc/architecture/overall_pipeline.md |
| geometry-central comparison — shared core, demarcation, adoption candidates, scientific added value | doc/architecture/geometry-central-comparison.md |
| Design decisions — key architectural choices + rationale | doc/architecture/design-decisions.md |
| Project structure — directory tree + build targets | doc/architecture/project-structure.md |
| Discrete conformal theory — mathematical background for collaborators | doc/math/discrete-conformal-theory.md |
| Validation — known analytic results + how to verify them | doc/math/validation.md |
| Validation protocol — concrete commands with expected outputs | doc/math/validation-protocol.md |
| Tutorial: add a new functional — step-by-step Inversive-Distance port | doc/tutorials/add-inversive-distance.md |
| Declarative YAML pipeline — concept, token vocabulary, 5 examples | doc/concepts/declarative-pipeline.md |
| Geometry modes — Euclidean / Spherical / HyperIdeal comparison | doc/math/geometry-modes.md |
| References — all papers by module | doc/math/references.md |
| Software landscape — how conformallab++ relates to libigl, CGAL, geometry-central | doc/math/software-landscape.md |
| Novelty statement — unique features, target audience, what this is not | doc/math/novelty-statement.md |
| Complexity & scalability — O() analysis, measured timings on real meshes, HyperIdeal bottleneck | doc/math/complexity.md |
| Roadmap — Phases 1–10 | doc/roadmap/phases.md |
| Java parity table — what is ported, what is planned | doc/roadmap/java-parity.md |
| Contributing — language policy, test standards, release flow | doc/contributing.md |
| Claude Code context | CLAUDE.md |
Citing
If you use conformallab++ in your research, please cite it using the metadata
in CITATION.cff. GitHub and Codeberg show a "Cite this repository"
button that generates BibTeX and APA automatically.
The primary algorithmic source is:
Stefan Sechelmann — Variational Methods for Discrete Surface Parameterization: Applications and Implementation, TU Berlin 2016. DOI: 10.14279/depositonce-5415
Bugs & questions
- Bug reports / feature requests: Gitea Issues
- Code mirror (read-only): Codeberg
- Contact: Tarik Moussa · Tarik.moussa95@gmail.com
License
conformallab++ is released under the MIT License (see LICENSE).
Copyright © 2024–2026 Tarik Moussa.
The dissertation (Sechelmann 2016) is CC BY-SA 4.0.