ConformalLabpp/README.md

conformallab++

conformallab++ is a modern C++ reimplementation of the ConformalLab software by Stefan Sechelmann for experiments in discrete conformal geometry and related mesh transformations.

The long-term goal is a CGAL package that brings discrete conformal maps (hyper-ideal, spherical, Euclidean) to the CGAL ecosystem using CGAL::Surface_mesh as the underlying half-edge data structure.

Status: Phase 5 vollständig abgeschlossen. Alle drei Geometrien lösbar via Newton-Solver (SimplicialLDLT + SparseQR-Fallback). BFS-Layout in ℝ²/S²/Poincaré-Disk, JSON/XML-Serialisierung, vollständige CLI-App. 95 Tests, 2 skipped.

---

Features

Area	Status
Clausen / Lobachevsky / ImLi₂ functions	✅ Phase 1
Hyper-ideal geometry (ζ, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ)	✅ Phase 2
CGAL Surface_mesh infrastructure + mesh builders	✅ Phase 3a
Hyper-ideal functional (energy + gradient)	✅ Phase 3b
Spherical functional (energy + gradient + gauge-fix)	✅ Phase 3c/3e
Euclidean functional (energy + gradient)	✅ Phase 3d
Euclidean Hessian (cotangent-Laplace, Pinkall–Polthier)	✅ Phase 3f
Spherical Hessian (∂α/∂u from law of cosines)	✅ Phase 3f
Hyper-ideal Hessian (numerical FD, symmetrised)	✅ Phase 4a
Newton solver — all three geometries	✅ Phase 4a
SparseQR fallback for rank-deficient H (gauge modes)	✅ Phase 4a
Mesh I/O (CGAL::IO — OFF / OBJ / PLY)	✅ Phase 4b
End-to-end pipeline tests	✅ Phase 4c
Example programs (headless + interactive viewer)	✅ Phase 4d
BFS Layout (ℝ², S², Poincaré disk)	✅ Phase 5
CLI app (conformallab_core)	✅ Phase 5
JSON + XML serialisation	✅ Phase 5

---

Quick start — CLI app

cmake -S code -B build -DWITH_CGAL=ON
cmake --build build -j4

# Run the conformal map CLI on any OFF/OBJ/PLY mesh
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json -x result.xml

# Available geometries: euclidean | spherical | hyper_ideal
./bin/conformallab_core -i input.off -g spherical -o sphere.off

# Show input mesh in interactive viewer (built-in)
./bin/conformallab_core -i input.off -s

Example programs

# Layout + JSON/XML round-trip demo
./build/examples/example_layout  [input.off]  [layout.off]  [result.json]  [result.xml]

# Headless pipelines
./build/examples/example_euclidean   [input.off]  [output.off]
./build/examples/example_hyper_ideal [input.off]  [output.off]

# Interactive viewer (requires -DWITH_CGAL=ON, viewer is built automatically)
./build/examples/example_viewer  [input.off]

If no input file is given each example uses a built-in quad-strip mesh.

---

Library usage — minimal Euclidean pipeline

#include "conformal_mesh.hpp"
#include "mesh_builder.hpp"
#include "mesh_io.hpp"
#include "euclidean_functional.hpp"
#include "newton_solver.hpp"

using namespace conformallab;

int main() {
    // 1. Load mesh
    ConformalMesh mesh = load_mesh("input.off");

    // 2. Set up functional maps
    auto maps = setup_euclidean_maps(mesh);
    compute_euclidean_lambda0_from_mesh(mesh, maps);

    // 3. Assign DOFs — pin first vertex (gauge fix)
    auto vit = mesh.vertices().begin();
    maps.v_idx[*vit++] = -1;   // pinned: u[v0] = 0
    int idx = 0;
    for (; vit != mesh.vertices().end(); ++vit)
        maps.v_idx[*vit] = idx++;
    const int n = idx;

    // 4. Set target angles (natural equilibrium: x* = 0)
    std::vector<double> x0(n, 0.0);
    auto G0 = euclidean_gradient(mesh, x0, maps);
    for (auto v : mesh.vertices()) {
        int iv = maps.v_idx[v];
        if (iv >= 0) maps.theta_v[v] -= G0[iv];
    }

    // 5. Solve
    auto result = newton_euclidean(mesh, std::vector<double>(n, -0.1), maps);

    // 6. Save result
    if (result.converged)
        save_mesh("output.off", mesh);

    return result.converged ? 0 : 1;
}

For HyperIdeal geometry:

auto maps = setup_hyper_ideal_maps(mesh);
int n = assign_all_dof_indices(mesh, maps);
// … set theta_v / theta_e targets …
auto result = newton_hyper_ideal(mesh, x0, maps);

Layout (embedding into target space)

After solving, convert scale factors into actual vertex coordinates:

#include "layout.hpp"
#include "serialization.hpp"

// Euclidean: flat 2-D positions in ℝ²
Layout2D layout = euclidean_layout(mesh, result.x, maps);
// layout.uv[v.idx()] = Eigen::Vector2d

// Spherical: unit vectors on S² ⊂ ℝ³
Layout3D slayout = spherical_layout(mesh, result.x, smaps);
// slayout.pos[v.idx()] = Eigen::Vector3d

// HyperIdeal: Poincaré disk coordinates in ℝ²
Layout2D hlayout = hyper_ideal_layout(mesh, result.x, hmaps);

// Save layout as OFF
save_layout_off("layout.off", mesh, layout);

// Serialise to JSON / XML
save_result_json("result.json", result, "euclidean",
    mesh.number_of_vertices(), mesh.number_of_faces(), &layout);
save_result_xml("result.xml", result, "euclidean",
    mesh.number_of_vertices(), mesh.number_of_faces(), &layout);

// Load back
NewtonResult res2; std::string geom; Layout2D uv2;
auto x = load_result_json("result.json", &res2, &geom, &uv2);

Using solve_linear_system directly (with fallback detection):

#include "newton_solver.hpp"

bool used_fallback = false;
auto dx = conformallab::solve_linear_system(H, rhs, &used_fallback);
if (used_fallback)
    std::cout << "SparseQR was used (H is rank-deficient)\n";

---

Build modes

Mode	CMake flags	What gets built	CI
Tests only (default)	(none)	conformallab_tests — Eigen + GTest only	✅ automatic
CGAL tests + examples	-DWITH_CGAL=ON	conformallab_cgal_tests, example_euclidean, example_hyper_ideal, example_layout, conformallab_core (CLI)	local only
Interactive viewer	-DWITH_CGAL=ON (implied)	above + example_viewer + viewer linked into CLI	local only

External dependencies are bundled as tarballs in code/deps/tarballs/ and extracted lazily at CMake configure time (GTest is fetched via FetchContent).

Boost is required only with -DWITH_CGAL=ON (header-only use by CGAL 6.x).

---

Prerequisites

Tool	Minimum
C++ compiler (GCC or Clang)	C++17
CMake	3.20
Boost headers	1.70 (only with -DWITH_CGAL=ON)

---

Getting started

git clone https://codeberg.org/TMoussa/ConformalLabpp
cd ConformalLabpp

Tests only (CI default — no system deps)

cmake -S code -B build
cmake --build build --target conformallab_tests -j$(nproc)
ctest --test-dir build --output-on-failure

CGAL tests + headless examples (needs system Boost)

cmake -S code -B build -DWITH_CGAL=ON
cmake --build build -j$(nproc)
ctest --test-dir build -R "^cgal\." --output-on-failure
./build/examples/example_euclidean
./build/examples/example_hyper_ideal
./build/examples/example_layout
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json

Expected: 95 tests pass, 2 skipped (the two @Ignore Hessian stubs).

Interactive viewer

# WITH_CGAL=ON already implies viewer; example_viewer is built automatically
cmake -S code -B build -DWITH_CGAL=ON && cmake --build build -t example_viewer -j$(nproc)
./build/examples/example_viewer data/off/example.off

---

Public headers (code/include/)

Header	Description
clausen.hpp	Clausen Cl₂, Lobachevsky Л, ImLi₂
hyper_ideal_geometry.hpp	ζ functions, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ
hyper_ideal_utility.hpp	Tetrahedron volume (Meyerhoff / Kolpakov–Mednykh)
hyper_ideal_functional.hpp	HyperIdeal energy + gradient on ConformalMesh
hyper_ideal_hessian.hpp	HyperIdeal Hessian (numerical FD, symmetrised)
hyper_ideal_visualization_utility.hpp	Poincaré disk projection, circumcircle helpers
spherical_geometry.hpp	Spherical arc length, half-angle formula
spherical_functional.hpp	Spherical energy + gradient + gauge-fix
spherical_hessian.hpp	Spherical Hessian (∂α/∂u, law of cosines)
euclidean_geometry.hpp	Euclidean corner-angle (t-value / atan2)
euclidean_functional.hpp	Euclidean energy + gradient
euclidean_hessian.hpp	Cotangent-Laplace Hessian (Pinkall–Polthier)
newton_solver.hpp	newton_euclidean / newton_spherical / newton_hyper_ideal + public solve_linear_system
mesh_io.hpp	read_mesh / write_mesh / load_mesh / save_mesh
conformal_mesh.hpp	ConformalMesh = CGAL::Surface_mesh<Point3> + property-map helpers
mesh_builder.hpp	make_triangle / make_tetrahedron / make_quad_strip / make_fan / make_spherical_tetrahedron
layout.hpp	euclidean_layout / spherical_layout / hyper_ideal_layout → Layout2D/3D; BFS unfolding
serialization.hpp	save/load_result_json + save/load_result_xml
mesh_utils.hpp	CGAL → Eigen conversion (cgal_to_eigen)
constants.hpp	conformallab::PI, TWO_PI

---

Project structure

code/
├── include/                         # All public headers (header-only library)
│   ├── conformal_mesh.hpp
│   ├── mesh_builder.hpp
│   ├── mesh_io.hpp
│   ├── mesh_utils.hpp
│   ├── newton_solver.hpp            # ← public solve_linear_system + 3 Newton solvers
│   ├── layout.hpp                   # ← BFS layout (euclidean/spherical/hyper_ideal)
│   ├── serialization.hpp            # ← JSON + XML save/load
│   ├── hyper_ideal_{functional,hessian,geometry,utility,visualization_utility}.hpp
│   ├── spherical_{functional,hessian,geometry}.hpp
│   ├── euclidean_{functional,hessian,geometry}.hpp
│   ├── clausen.hpp
│   └── constants.hpp
├── examples/                        # Standalone example programs
│   ├── CMakeLists.txt
│   ├── example_euclidean.cpp        # Headless Euclidean pipeline
│   ├── example_hyper_ideal.cpp      # Headless HyperIdeal pipeline
│   ├── example_layout.cpp           # Solve → layout → OFF/JSON/XML round-trip
│   └── example_viewer.cpp           # Interactive libigl viewer (WITH_VIEWER)
├── src/
│   ├── apps/v0/conformallab_cli.cpp # Full CLI app (Phase 5)
│   └── viewer/simple_viewer.cpp
├── tests/
│   ├── CMakeLists.txt
│   ├── *.cpp                        # conformallab_tests (no CGAL)
│   └── cgal/
│       ├── CMakeLists.txt
│       ├── test_conformal_mesh.cpp          # 14 tests
│       ├── test_hyper_ideal_functional.cpp  #  7 tests (1 skipped)
│       ├── test_spherical_functional.cpp    # 11 tests (1 skipped)
│       ├── test_euclidean_functional.cpp    # 11 tests
│       ├── test_euclidean_hessian.cpp       #  8 tests
│       ├── test_spherical_hessian.cpp       #  8 tests
│       ├── test_newton_solver.cpp           # 14 tests (incl. 3 SparseQR tests)
│       ├── test_mesh_io.cpp                 #  6 tests
│       ├── test_pipeline.cpp               #  5 tests
│       └── test_layout.cpp                 #  8 tests (layout + JSON/XML)
└── deps/
    ├── eigen-3.4.0/        # always extracted
    ├── CGAL-6.1.1/         # extracted with WITH_CGAL
    ├── libigl-2.6.0/       # extracted with WITH_VIEWER
    ├── glfw-3.4/           # extracted with WITH_VIEWER
    ├── libigl-glad/
    └── single_includes/    # CLI11, json.hpp

---

Test suites

conformallab_tests (CI — always built)

Pure-math tests requiring only Eigen: Clausen / Lobachevsky / ImLi₂, hyper-ideal geometry, tetrahedron volumes.

conformallab_cgal_tests (local — -DWITH_CGAL=ON)

Suite	Tests	What it checks
ConformalMeshTopology	4	Euler characteristic, vertex/edge/face counts
ConformalMeshTraversal	4	Halfedge iteration, valence, opposite
ConformalMeshProperties	5	Property maps (λ, θ, idx, α, geometry type)
ConformalMeshValidity	1	CGAL validity for all factory meshes
HyperIdealFunctional	7	FD gradient checks + Hessian symmetry
SphericalFunctional	11	Angle formula + gradient + gauge-fix
EuclideanFunctional	11	Angle formula + gradient
EuclideanHessian	8	Cotangent-Laplace structure, FD agreement, PSD, null space
SphericalHessian	8	Derivative correctness, NSD at equilibrium
NewtonSolver	11	Convergence (Euclidean ×3, Spherical ×4, HyperIdeal ×4)
SparseQRFallback	3	Full-rank LDLT path · singular matrix triggers QR · closed-mesh gauge-mode
MeshIO	6	OFF/OBJ round-trips, error handling
Pipeline	5	End-to-end: build → setup → solve → export → reload, all three geometries
Layout	6	Edge-length preservation (Euclidean/Spherical), arc-lengths on S², Poincaré disk
Serialization	2	JSON and XML round-trips (DOF + layout)
Total	95	2 skipped (Hessian stubs)

---

Newton solver & SparseQR fallback

newton_solver.hpp exposes three solvers with a unified interface:

NewtonResult newton_euclidean (mesh, x0, maps [, tol, max_iter])
NewtonResult newton_spherical (mesh, x0, maps [, tol, max_iter])
NewtonResult newton_hyper_ideal(mesh, x0, maps [, tol, max_iter, hess_eps])

Each iteration:

1. Evaluate gradient G
2. Evaluate Hessian H (analytical for Euclidean / Spherical; numerical FD for HyperIdeal)
3. Solve H·Δx = −G — try Eigen::SimplicialLDLT, fall back to Eigen::SparseQR on failure
4. Backtracking line search (up to 20 halvings)

Gradient sign conventions:

Geometry	G	H sign
Euclidean	Θ_v − Σα_v	PSD → LDLT on H
Spherical	Θ_v − Σα_v	NSD → LDLT on −H
HyperIdeal	Σβ_v − Θ_v	PSD → LDLT on H

SparseQR fallback (solve_linear_system):
When SimplicialLDLT fails (singular/rank-deficient H, e.g. gauge modes on closed meshes without a pinned vertex), SparseQR finds the minimum-norm Newton step orthogonal to the null space. Because the gradient always lies in the row space of H, the solver converges correctly without requiring the caller to pin a vertex.

The fallback is a public API:

bool used_fallback = false;
auto dx = conformallab::solve_linear_system(H, rhs, &used_fallback);

---

Mathematical scope — C++ vs. Java original

The three core functionals are fully equivalent to the Java original at the level of energy, gradient, and Hessian formulas. The table below shows where parity holds, where there is a numerical difference, and what is not yet ported.

Mathematical layer	Java ConformalLab	conformallab++
Euclidean functional — energy, gradient	✅	✅
Spherical functional — energy, gradient, gauge-fix	✅	✅
HyperIdeal functional — energy, gradient	✅	✅
Inversive-distance functional (Luo 2004, Bowers–Stephenson)	✅	❌ not ported
Euclidean Hessian — cotangent-Laplace (Pinkall–Polthier 1993)	✅ analytical	✅ analytical
Spherical Hessian — ∂α/∂u from law of cosines	✅ analytical	✅ analytical
HyperIdeal Hessian — through ζ → lᵢⱼ → β/α chain	✅ analytical	⚠️ symmetric FD
Newton solver	✅	✅
SparseQR fallback for gauge-mode null spaces	?	✅
Cone metrics — prescribed Θ_v ≠ 2π	✅ full pipeline	⚠️ data structure only
Boundary conditions — Dirichlet u=f, Neumann, free boundary	✅	⚠️ pin-only
Layout / embedding — DOF vector → vertex coordinates in ℝ² / H² / S²	✅	✅ BFS unfolding (all three geometries)
Gauss–Bonnet consistency check on target angles	✅	❌
Global uniformization for genus g ≥ 1	✅	❌
Period matrices — Teichmüller parameters for g ≥ 2	✅	❌
Holonomy / monodromy	✅	❌
HyperIdeal generator — constructing geometrically valid meshes	✅	❌ only test meshes
Clausen / Lobachevsky / ImLi₂ special functions	✅	✅
Discrete elliptic utility (modular normalisation of τ)	✅	✅ (not yet wired up)
Poincaré disk / Lorentz boost visualisation helpers	✅	✅
Mesh I/O + serialisation	✅ XML/CoHDS	✅ OFF/OBJ/PLY + JSON/XML
Interactive viewer	✅ jReality	✅ libigl/GLFW

Key numerical difference — HyperIdeal Hessian

The analytical Hessian of the HyperIdeal functional requires differentiating through the chain

(b_i, a_e) → l_ij  →  ζ₁₃/ζ₁₄/ζ₁₅  →  α_ij / β_i

which is feasible but involves many nested cases (four vertex-type combinations per edge). Until Phase 6 delivers the analytical version, conformallab++ uses a symmetric finite-difference Hessian:

H[i,j] = ( G(x + ε·eⱼ)[i] − G(x − ε·eⱼ)[i] ) / (2ε)

This is O(ε²) accurate (≈ 10⁻¹⁰ relative error at ε = 10⁻⁵), positive semi-definite by strict convexity of the HyperIdeal energy (Springborn 2020), and costs n extra gradient evaluations per Newton step instead of O(n). For meshes with fewer than ~500 DOFs the difference in wall time is negligible.

What "cone metrics" still requires

Cone metrics — the property map theta_v is already subtracted in the gradient (G_v = Σα_v − Θ_v), so prescribing a cone angle is a one-liner: maps.theta_v[v] = desired_angle. What is missing is the application layer: checking Gauss–Bonnet consistency (Σ (2π − Θ_v) = 2π·χ), distributing angle defects sensibly, and special handling at boundary vertices.

Layout (Phase 5 ✅) — layout.hpp implements BFS unfolding for all three geometries via euclidean_layout, spherical_layout, and hyper_ideal_layout. For open meshes the embedding is globally consistent; for closed meshes the first BFS visit wins and has_seam = true is set. To get a proper parameterisation of a closed mesh, cut it to a disk first (not yet implemented).

Next steps — global uniformization (cutting closed meshes, period matrices, holonomy), Gauss–Bonnet checking, analytical HyperIdeal Hessian.

---

For mathematicians — extending the library

This section explains how to add new functionals, test conjectures numerically, and hook into the existing solver infrastructure, with no assumed prior knowledge of the codebase.

Mental model

The library is built around one central idea: a discrete conformal functional E(x) whose critical points are the conformally equivalent metrics. Everything else is infrastructure for evaluating E, its gradient G = ∂E/∂x, and its Hessian H = ∂²E/∂x².

ConformalMesh           — half-edge mesh (CGAL::Surface_mesh)
    + property maps     — per-vertex / per-edge data (λ, θ, α, DOF index, …)

Maps struct             — collects all property maps for one functional
    theta_v[v]          — target angle at vertex v  (your input)
    v_idx[v]            — DOF index, or −1 if pinned
    e_idx[e]            — DOF index for edge DOFs (HyperIdeal only)

x ∈ ℝⁿ                 — the DOF vector the solver optimises

evaluate_*(mesh, x, maps)  → { energy, gradient, … }
newton_*(mesh, x0, maps)   → { x*, iterations, converged, … }

The mesh geometry (vertex positions) is only used to initialise the log edge-lengths λ°. From then on the solver works entirely in the x-space.

Adding a new functional — step-by-step

Copy euclidean_functional.hpp as a template (it is the simplest of the three). You need to provide:

1. A Maps struct that holds the property maps your functional needs:

// my_functional.hpp
#pragma once
#include "conformal_mesh.hpp"

namespace conformallab {

struct MyMaps {
    // property maps attached to the mesh
    ConformalMesh::Property_map<Vertex_index, double> lambda;   // log edge-lengths
    ConformalMesh::Property_map<Vertex_index, double> theta_v;  // target angles
    ConformalMesh::Property_map<Vertex_index, int>    v_idx;    // DOF indices

    // any extra parameters your functional needs
    double my_parameter = 1.0;
};

inline MyMaps setup_my_maps(ConformalMesh& mesh) { … }

2. An energy + gradient function:

struct MyResult {
    double              energy;
    std::vector<double> gradient;
};

inline MyResult evaluate_my_functional(
    ConformalMesh&             mesh,
    const std::vector<double>& x,
    const MyMaps&              m,
    bool                       compute_energy = true)
{
    MyResult res;
    res.gradient.assign(x.size(), 0.0);

    for (auto f : mesh.faces()) {
        // iterate halfedges around face
        // compute your per-face contribution to E and G
        // accumulate: res.gradient[m.v_idx[v]] += …
    }

    // subtract target-angle term
    for (auto v : mesh.vertices()) {
        int iv = m.v_idx[v];
        if (iv < 0) continue;
        res.gradient[iv] -= m.theta_v[v];   // G_v = actual - target
    }

    return res;
}

3. A gradient check — before trusting your formula, verify it numerically. There is a ready-made helper in hyper_ideal_functional.hpp you can call directly, or write your own:

// Finite-difference gradient check for any functional
bool my_gradient_check(ConformalMesh& mesh,
                       const std::vector<double>& x,
                       const MyMaps& m,
                       double eps = 1e-6, double tol = 1e-5)
{
    auto r0 = evaluate_my_functional(mesh, x, m, false);
    const int n = static_cast<int>(x.size());
    for (int i = 0; i < n; ++i) {
        auto xp = x; xp[i] += eps;
        auto xm = x; xm[i] -= eps;
        double fd = (evaluate_my_functional(mesh, xp, m).energy
                   - evaluate_my_functional(mesh, xm, m).energy) / (2*eps);
        if (std::abs(fd - r0.gradient[i]) > tol * (1 + std::abs(fd)))
            return false;
    }
    return true;
}

Add a TEST(MyFunctional, GradientCheck_Triangle) in tests/cgal/ and it will be picked up automatically by CTest.

4. Hook into the Newton solver. Once your gradient and Hessian are correct, plug in solve_linear_system or write a thin wrapper in the style of newton_euclidean:

// Use a numerical Hessian first (safe starting point)
#include "newton_solver.hpp"
#include <Eigen/Sparse>

// Build H by FD of your gradient, then:
bool ok = false;
auto dx = detail::solve_with_fallback(H, -G, ok);

Or supply an analytical Hessian as a sparse matrix and pass it directly.

Where the key mathematical objects live

Object	File	What to look for
Corner angle formula (Euclidean)	euclidean_geometry.hpp	euclidean_corner_angle() — inputs are log half-edge lengths
Spherical angle formula	spherical_geometry.hpp	spherical_corner_angle() — uses spherical law of cosines
HyperIdeal angle (ζ₁₃/ζ₁₄/ζ₁₅)	hyper_ideal_geometry.hpp	zeta13/14/15(), alpha_ij() — the four vertex-type cases
Per-face energy term	*_functional.hpp	the inner loop over mesh.faces()
Gradient accumulation	*_functional.hpp	grad[v_idx[v]] += … after the face loop
Cotangent-Laplace structure	euclidean_hessian.hpp	euclidean_hessian() — shows the sparse-triplet pattern
Spherical Hessian derivation	spherical_hessian.hpp	comments give the ∂α/∂u formula step by step
Special functions	clausen.hpp	Cl2(), lobachevsky(), imLi2() — all take a double angle

How to navigate the half-edge mesh

for (auto f : mesh.faces()) {
    // The three halfedges of face f:
    auto h0 = mesh.halfedge(f);
    auto h1 = mesh.next(h0);
    auto h2 = mesh.next(h1);

    // Vertices opposite to each halfedge (the vertex NOT on h):
    Vertex_index v0 = mesh.target(h2);  // opposite to edge h0-h1
    Vertex_index v1 = mesh.target(h0);  // opposite to edge h1-h2
    Vertex_index v2 = mesh.target(h1);  // opposite to edge h0-h2 (= h2 target)

    // Access DOF index (−1 = pinned):
    int i0 = maps.v_idx[v0];

    // The opposite halfedge (for the adjacent face, if not on boundary):
    auto h_opp = mesh.opposite(h0);
    bool is_boundary = mesh.is_border(h_opp);
}

Attaching new data to a mesh

// Add a per-vertex curvature field (survives mesh copy):
auto [curv, created] = mesh.add_property_map<Vertex_index, double>("v:my_curv", 0.0);

// Write and read:
curv[v] = 1.234;
double k = curv[v];

// Pass it through your Maps struct so functions can access it.

Property maps are reference-counted and cheap to copy. Give them unique string names to avoid collision.

Quick-start experiment checklist

1. Read examples/example_layout.cpp — it shows the full pipeline (load → setup → solve → layout → JSON/XML save → reload) in ~120 lines with comments at every step.
2. Build with cmake -S code -B build -DWITH_CGAL=ON && cmake --build build --target example_layout and run ./build/examples/example_layout.
3. Add a gradient check test in tests/cgal/ — copy any TEST(…, GradientCheck_…) block and swap out the functional. Run with ctest -R your_test_name.
4. Try different target angles — set maps.theta_v[v] = M_PI / 3 for all interior vertices and see how the solver responds. The constraint Σ(2π − Θ_v) = 2π·χ(M) (Gauss–Bonnet) must hold for a solution to exist.
5. Inspect convergence — NewtonResult carries iterations, grad_inf_norm, and the full x at termination. Plot ||G(xₖ)|| per iteration to verify quadratic convergence near the solution.

Recommended reading

Paper	Relevance to this codebase
Springborn, Schröder, Pinkall — Conformal Equivalence of Triangle Meshes (2008)	Euclidean & spherical functionals; the Schläfli formula at the core of spherical_functional.hpp
Springborn — Ideal Hyperbolic Polyhedra and Discrete Uniformization (2020)	HyperIdeal functional; the ζ₁₃/ζ₁₄/ζ₁₅ functions in hyper_ideal_geometry.hpp
Pinkall, Polthier — Computing Discrete Minimal Surfaces (1993)	Cotangent-Laplace Hessian in euclidean_hessian.hpp
Luo — Combinatorial Yamabe Flow on Surfaces (2004)	Inversive-distance functional (not yet ported — good first contribution)
Bobenko, Springborn — Variational Principles for Circle Patterns (2004)	Background for the angle-sum variational framework used throughout

---

Key design decisions

CGAL as CoHDS replacement. CGAL::Surface_mesh<Point3> replaces the Java CoHDS half-edge data structure. Vertex/edge/face/halfedge descriptors are typed integers — no raw handles, no RTTI.

Property maps. mesh.add_property_map<Vertex_index, double>("v:lambda", 0.0) replaces the Java adapter/decorator pattern. Multiple maps attach to one mesh without subclassing.

DOF vector convention. All functionals use x indexed by v_idx[v] / e_idx[e] (−1 = pinned). This matches the Java FunctionalTest gradient-check convention and is uniform across all three geometries.

HyperIdeal Hessian via FD. The analytical Hessian through ζ13/14/15 → lij → β/α is deferred to Phase 6. A symmetric FD Hessian H[i,j] = (G(x+ε·eⱼ)[i] − G(x−ε·eⱼ)[i]) / (2ε) is O(ε²) accurate, PSD by strict convexity, and sufficient for Newton on < 500 DOFs.

Spherical Hessian sign. The spherical energy is concave (not convex) — the Hessian H is NSD at equilibrium. Newton solves (−H)·Δx = G, so the sign flip is handled transparently inside newton_spherical.

Natural theta trick. Tests set theta_v = Σα_v(x=x_base) to make x_base the known equilibrium, avoiding any need to manufacture reference solutions. For HyperIdeal x_base = (b=1.0, a=0.5) is used (x=0 is degenerate in log-space).

---

CI

Tests run automatically on push to main, dev, and claude/** branches via a self-hosted Gitea Actions runner (eulernest, ARM64). The CI image contains cmake, g++, git, and Node.js. Only conformallab_tests runs in CI (no Boost/CGAL dependency there).

# Rebuild and push the CI image when the Dockerfile changes
docker buildx build \
  --platform linux/arm64 \
  -f .gitea/docker/Dockerfile.ci-cpp \
  -t git.eulernest.eu/conformallab/ci-cpp:latest \
  --push \
  .gitea/docker/

---

Roadmap

Phase 1   Clausen / Lobachevsky / ImLi₂                ✅ abgeschlossen

Phase 2   Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ)    ✅ abgeschlossen

Phase 3a  CGAL Surface_mesh Infrastruktur              ✅ abgeschlossen
Phase 3b  HyperIdealFunctional                         ✅ abgeschlossen
Phase 3c  SphericalFunctional                          ✅ abgeschlossen
Phase 3d  EuclideanCyclicFunctional                    ✅ abgeschlossen
Phase 3e  Gauge-Fix für SphericalFunctional            ✅ abgeschlossen
Phase 3f  Analytische Hessians (Eucl. + Sphär.)        ✅ abgeschlossen
Phase 3g  PI-Konstante konsolidieren                   ✅ abgeschlossen

Phase 4a  Newton-Solver (alle drei Geometrien)         ✅ abgeschlossen
          → newton_euclidean / newton_spherical / newton_hyper_ideal
          → detail::solve_with_fallback → public solve_linear_system
          → Backtracking-Line-Search
          → hyper_ideal_hessian.hpp (numerischer FD-Hessian)

Phase 4b  CGAL::IO Mesh-Import/Export                  ✅ abgeschlossen
          → mesh_io.hpp: read/write/load/save
          → Format-Erkennung aus Dateiendung (OFF, OBJ, PLY)

Phase 4c  End-to-End-Pipeline Tests                    ✅ abgeschlossen
          → test_pipeline.cpp: 5 Tests (alle 3 Geometrien, I/O, full loop)

Phase 4d  SparseQR-Fallback + Beispiel-Programme       ✅ abgeschlossen
          → solve_linear_system als öffentliche API mit fallback_used-Flag
          → 3 dedizierte SparseQR-Tests (full-rank, singular, closed mesh)
          → examples/example_euclidean.cpp   (headless)
          → examples/example_hyper_ideal.cpp (headless)
          → examples/example_viewer.cpp      (interaktiver Viewer, WITH_VIEWER)

Phase 5   Layout + CLI + Serialisierung                ✅ abgeschlossen
          → layout.hpp: BFS-Einbettung in ℝ² (Euclidean/HyperIdeal) und S² (Spherical)
          → serialization.hpp: JSON (nlohmann/json) + XML (hand-written) save/load
          → conformallab_core CLI: -i/-o/-g/-j/-x/-s/-v Flags, alle drei Geometrien
          → example_layout.cpp: Solve → Layout → OFF/JSON/XML + Round-Trip-Check
          → test_layout.cpp: 8 Tests (Eucl./Sphär./HyperIdeal + JSON/XML)
          → 95 Tests gesamt (2 skipped)

Phase 6   (geplant)
          → Analytischer HyperIdeal-Hessian (direkte Ableitung durch ζ-Kette)
          → Gauss–Bonnet Konsistenzprüfung für Kegelmetriken
          → Mesh-Cut für geschlossene Flächen → globale Parameterisierung
          → Inversive-Distance-Funktional (Luo 2004)

---

License

conformallab++ is released under the MIT License (see LICENSE).