ConformalLabpp/doc/reviewer/briefing.md

Reviewer briefing — conformallab++

Audience. Active researcher in discrete differential geometry — specifically the research line around decorated discrete conformal equivalence, Penner coordinates on hyperbolic surfaces, canonical Delaunay tessellations of decorated surfaces, and hyperideal polyhedra. Treats the reader as a peer who is more likely to use conformallab++ as numerical infrastructure for their own future experiments than to merely evaluate it as a software artefact.

Purpose. One page to read before the meeting: what is shipping, which of the reader's research questions it could already support, and where the gaps are that we would close together.

In one paragraph

conformallab++ is a C++17 header-only re-implementation of the Java library ConformalLab (Sechelmann 2016, TU Berlin), built around CGAL's Surface_mesh and Eigen. v0.9.0 ships five Discrete Conformal Equivalence (DCE) solvers — Euclidean, Spherical, HyperIdeal, Circle-Packing Euclidean (BPS 2010, face-based), Inversive-Distance (Luo 2004, vertex-based) — plus the Newton infrastructure, layout (priority-BFS trilateration in ℝ², S², Poincaré disk), Möbius holonomy, period matrix, cut graph, and JSON/XML serialisation. Long-term goal: a CGAL package.

Where to start (one URL, 5 minutes)

👉 https://tmoussa.codeberg.page/ConformalLabpp/

The landing page is a hand-curated reviewer hub, not an auto-generated index. It links to the Doxygen API, the key markdown documents, and shows static quality-gate status.

Research alignments — where this library could be infrastructure for your work

The current snapshot already contains, or has roadmap entries for, the following. Most rows match an active publication line in discrete differential geometry; a few (marked no Java parent) are research-only phases the reader can shape at design stage.

Your research thread	What this snapshot has	Phase
Decorated DCE in non-Euclidean geometries (Bobenko–Lutz 2025, DCG)	five DCE solvers + traits scaffolding; non-Euclidean cone extension scoped in research-track with acceptance criteria	9d.2 RESEARCH (planned)
Canonical Delaunay tessellations of decorated hyperbolic surfaces (Lutz 2023, Geom. Dedicata; Lutz 2024 PhD thesis)	cut-graph + period matrix + hyperbolic-disk layout as scaffolding; canonical-tessellation algorithm itself outlined	10c planned
Hyperideal polyhedra rigidity (Bowers–Bowers–Lutz 2026)	HyperIdeal functional + analytic Hessian derivation (805-line LaTeX note)	9b-analytic derived; 10c′ KAT planned
Optimal cone placement / non-Euclidean cone metrics (Crane et al. 2018)	Cone-singularity port via ConesUtility scoped; the non-Euclidean extension is the research delta	9d.1 port + 9d.2 RESEARCH
Polygon Laplacian on general meshes (Alexa–Wardetzky 2011; Alexa 2020)	no Java parent — first phase a reviewer can shape at design stage	9f RESEARCH (planned)
Quasi-isothermic maps (generalising conformality where exact conformality is impossible — Lawson-correspondence parameterisation)	scoped as a 6-class port (~800 lines) from the Java original: QuasiisothermicLayout, DBFSolution (discrete Beltrami field), SinConditionApplication, QuasiisothermicDelaunay, QuasiisothermicUtility, ConformalStructureUtility	10e planned
Higher-genus + hyperelliptic surfaces (Bobenko–Bücking 2009 on polyhedral surfaces; period matrices with block-diagonal Z₂ structure)	port of HyperellipticUtility + HyperIdealHyperellipticUtility scoped; existing period-matrix code as scaffolding	10b planned
Möbius centring for Poincaré-disk layouts as a variational problem (Lorentz geometry: E = Σ log(−⟨x,p⟩/√(−⟨x,x⟩)))	currently we use iterative Fréchet mean in normalise_hyperbolic(); the principled variational alternative is scoped via the Java MobiusCenteringFunctional port (full gradient + Hessian)	9d.4 planned
Boundary-First / interactive flattening (Crane et al. 2017 BFF; Bonneel et al. 2015 Stripe Patterns on Surfaces)	not on the roadmap as ports; documented in references.md as comparison points / inspiration for future API design	—
Schläfli-based variational machinery (Rivin–Springborn 1999)	derivation done, implementation gated on your view of whether the ~6× speedup over our block-FD path matters at your mesh sizes	9b-analytic ready to implement

See doc/roadmap/phases.md for the per-phase porting plan, doc/roadmap/research-track.md for the items beyond Java parity with explicit acceptance criteria, and doc/roadmap/java-parity.md for the reverse table (every Java class → C++ destination or do-not-port rationale).

What's new on this snapshot (since the previous publish)

• +6 new porting-roadmap phases (9d cones + 9d.4 Möbius centring / 9e circle-pattern layout / 10d Koebe circle-domain / 10e quasi-isothermic / 10f Koebe polyhedra / 10g cyclic-symmetry quotients) derived from a full Java-library scan. See phases.md for the per-phase plan and java-parity.md for the reverse table.
• +13 literature citations integrated into the roadmap, all Tier-1/2. Decorated-DCE / canonical-tessellation / hyperideal line: Bobenko–Lutz 2024 IMRN; Bobenko–Lutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD; Bowers–Bowers–Lutz 2026. Cones, polyhedra, period matrices: Crane et al. 2018; Springborn 2019 (hyperbolic polyhedra); Bobenko–Bücking 2009; Rivin–Springborn 1999. Polygon Laplacians: Alexa–Wardetzky 2011; Alexa 2020. Integrable + practical-flattening context: Springborn–Veselov 2015 (cluster dynamics); Crane et al. 2017 (BFF); Bonneel et al. 2015 (Stripe Patterns).
• Phase 9f (polygon Laplacian on non-triangular meshes) added as RESEARCH-only — no Java parent — so you can influence its design before it exists.
• Phase 10e (quasi-isothermic maps) and Phase 9d.4 (variational Möbius centring) newly scoped from the Java scan; both touch research lines adjacent to decorated DCE.
• output_uv_map now covers 4 of 5 DCE solvers (Inversive-Distance added; CP-Euclidean deferred to Phase 9c with a clear runtime error rather than silent failure).

What's true about this snapshot

Claim	Concrete evidence
Library is header-only and standalone	Verification recipe in doc/architecture/dependencies.md: env -i PATH=… cmake … && ctest passes with zero quality tools installed.
Tests: 259 pass, 0 skipped	bash scripts/check-test-counts.sh enforces this against doc/api/tests.md; CI fails on drift.
Doxygen: 100 % public-API coverage, 0 warnings	bash scripts/doxygen-coverage.sh --threshold 100 is in CI.
License hygiene: 66/66 files carry MIT SPDX	bash scripts/quality/license-headers.sh is in CI (strict).
Build reproducibility: byte-identical between runs	bash scripts/quality/reproducible-build.sh (local, ~6 min).
Sanitizers (ASan + UBSan) clean on fast suite	bash scripts/quality/sanitizers.sh (local, ~3 min).
CGAL conventions: 6 rules, 0 violations	python3 scripts/quality/cgal-conventions.py (CI required).

What we want from you

Seven concrete questions are in doc/reviewer/questions.md — please skim them beforehand. They are deliberately scoped: each can be answered with "go this way" / "no, go that way" / "either is fine".

Ordered by reviewer-value (the first two are the ones your research profile makes you best-positioned to answer):

1. Q1 — Research-track alignment — of the three RESEARCH-track phases (9d.2 non-Euclidean cones, 9f polygon Laplacian, 10c canonical tessellations + 10c′ Koebe polyhedra), which would unblock concrete experiments you have wanted to run?
2. Q2 — Decorated-DCE API surface — what's the minimum public API for Penner-coordinate / decorated-DCE work? Named parameter on the existing Euclidean entry, separate decorated_* solvers, or per-edge decoration weights via property maps?
3. Q3 — Phase 9b-analytic — is the ~6× speedup over the current block-FD Hessian worth ~2 weeks of implementation, at the mesh sizes you typically work with?
4. Q4 — Phase 9c (4g-polygon) — port the Java implementation literally, or re-derive from Springborn 2020 §5?
5. Q5 — geometry-central cross-validation (GC-1) — would you be interested in co-authoring a Newton-vs-Ptolemy-flips comparison?
6. Q6 — CGAL submission strategy — one package or several?
7. Q7 — The "no" question — looking at our 12 architecture decisions, is there one you would push back on?

What's deliberately deferred (so we can discuss with you first)

Item	Why deferred
Phase 9b-analytic (Schläfli-based HyperIdeal Hessian)	derivation done (805-line LaTeX doc), implementation depends on your opinion of payoff
Phase 9c (fundamental-polygon utility, 4g-polygon canonical form)	algorithm choice up to you
Cross-validation against geometry-central (GC-1)	potential paper, scope depends on your interest
CP-Euclidean output_uv_map (per-face circle packing)	needs the BPS-2010 §6 layout algorithm, ~3 days
.a().b().c() member-style named-parameter chaining	requires patching CGAL upstream; pipe-operator (`a

These are all flagged in doc/architecture/locked-vs-flexible.md §"Known limitations".

Architectural decisions you might want to challenge

12 decisions classified 🔴 load-bearing / 🟡 semi-fixed / 🟢 opportunistic in doc/architecture/locked-vs-flexible.md. The ones most worth your time:

• #1 Surface_mesh as default — 🔴 ~3 weeks to change. Are you OK with this default, or should we wire Polyhedron_3 / OpenMesh now?
• #6 Eigen as linear-algebra back-end — 🔴 ~2 weeks to change. Are the Eigen sparse solvers (SparseCholesky + SparseQR fallback) sufficient for the mesh sizes you've seen, or should we look at CHOLMOD / PETSc?
• #7 Strategy C (one Default trait per functional, not a unified trait) — 🟡 ~1 week to refactor. CGAL convention agrees; do you?

How to actually run something

git clone https://codeberg.org/TMoussa/ConformalLabpp && cd ConformalLabpp
cmake -S code -B build && cmake --build build --target conformallab_tests
ctest --test-dir build              # ~2 s, 23 pure-math tests
# CGAL tests (adds Boost as a system dep):
cmake -S code -B build -DWITH_CGAL_TESTS=ON
cmake --build build --target conformallab_cgal_tests -j
ctest --test-dir build              # ~3 min, 236 CGAL tests

A more end-to-end recipe lives in scripts/try_it.sh (also run in CI).

Meeting logistics

• Format: video call (you suggested), ~60 min
• Materials needed on your side: just a browser to follow the reviewer-hub URL.
• Materials I'll have ready: a screen-share-able terminal with the repo open, my own agenda in doc/reviewer/agenda.md, and the questions doc above.

Looking forward.