eb393537f3
External-reviewer-visit prep package (Springborn-Bobenko PhD alumnus,
2026-05-26). All five documents target the same audience: a
mathematician who wants to evaluate, extend, or contribute to
conformallab++. Goal: make the project maximally hackable BEFORE the
meeting. Code unchanged in this commit — pure documentation.
Files added
───────────
1. **doc/tutorials/block-fd-hessian.md** (460 lines)
Step-by-step tutorial on the per-face block-FD Hessian pattern
shipped in Phase 9b (96× speed-up). Matches the style of
add-inversive-distance.md. Covers:
* The per-face locality lemma (mathematical justification).
* Cost analysis (full-FD vs block-FD vs analytic).
* Implementation walkthrough through face_angles_from_local_dofs +
hyper_ideal_hessian_block_fd.
* Porting checklist for applying the same pattern to a new
functional.
* The four cross-validation criteria.
* When NOT to use block-FD + upgrade path to Phase 9b-analytic.
2. **doc/tutorials/add-output-uv-map.md** (477 lines)
Tutorial for the `output_uv_map` named-parameter pattern shipped in
PR #14. Covers:
* The UX problem (two-step pipeline → one-call wrapper).
* The CGAL named-parameter mechanism + how the entry functions
wire it (get_parameter + constexpr if).
* Step-by-step recipe for adding a new named parameter (worked
example: hypothetical `output_holonomy_map`).
* The five test patterns for verification.
* Why CP-Euclidean (face-DOF) and Inversive-Distance (Luo-edge-length)
do not yet support output_uv_map — what is needed to add them.
3. **doc/math/hyperideal-hessian-derivation.md** (805 lines)
Research-quality LaTeX-formatted derivation of the analytic
HyperIdeal Hessian via the Schläfli identity (Phase 9b-analytic
preparation). Covers:
* Schläfli identity (1858/60) — gradient and second-order form.
* Derivatives of ζ, ζ₁₃, ζ₁₄, ζ₁₅ (all hyper-ideal-to-fully-ideal cases).
* Chain rule for ∂β_i/∂(b,a) and ∂α_ij/∂(b,a) — case-split on the
four α_ij branches.
* Per-face 6×6 block formulas.
* Acceptance criteria for the future implementation.
* Implementation outline (Conformal_map header sketch).
* Appendix A: sign / argument-order pitfalls reading the code.
* References: Schläfli 1858, Milnor 1982, Vinberg 1993, Cho-Kim 1999,
Rivin, Glickenstein 2011, Springborn 2020, BPS 2015.
4. **doc/roadmap/porting-status.md** (~250 lines)
Operational snapshot of "where is each piece of Java math today"
at v0.9.0. Sections:
* 25 000 lines of Java in one table (ported / worth porting /
intentionally skipped breakdown).
* Five DCE models — full status matrix with Java port status,
Hessian type, Newton support, CGAL entry, UV-output capability.
* Topology + solver infrastructure status.
* CGAL public API map + known limitations (no chaining, Surface_mesh
only, submission-readiness gaps).
* Reverse cross-reference: Java class → C++ port location (or
"skipped: replaced by …" / "in roadmap: phase X").
* Things in C++ that the Java original does NOT have (research
extensions track).
* "How to use the library today" quickstart.
5. **doc/architecture/locked-vs-flexible.md** (~270 lines)
12-item architecture-decision review with tier classification
(🔴 load-bearing / 🟡 semi-fixed / 🟢 opportunistic). Each item
includes: locked-since date, cost to change, when to revisit,
recommended posture for new contributors. Key insight stated up
front: "the load-bearing decisions are all good in 2026". Closes
with five open questions for the external reviewer — items where
a second opinion would genuinely help (Phase 9c algorithm choice,
Phase 10a priorities, analytic-Hessian payoff justification,
CGAL upstream vs independent distribution, geometry-central
cross-validation).
Total: ~2 250 lines across five new docs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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
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
| 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.