26f4f0637d
External reviewer pass over the literature references. Verified entries against arXiv/DOI/publisher and corrected misattributions that had propagated across the docs. Corrected citations (consistent across all docs): - Bowers-Bowers-Lutz 2026: title was the 2017 paper's -> "Rigidity of Koebe Polyhedra and Inversive Distance Circle Packings" - Liouville theorem: "Springborn 2019" -> Pinkall & Springborn, Geom. Dedicata 214 (2021) - Bobenko-Pinkall-Springborn: "G&T 14 (2010)" -> G&T 19(4) (2015), 2155-2215 - Optimal Cone Singularities: "Crane, Soliman, Ben-Chen, Schroeder" -> Soliman, Slepcev, Crane, ACM TOG 37(4) - Schlaefli formula: "Rivin, Springborn 1999" -> Rivin, Schlenker - Quasiconformal distortion: "Springborn, Veselov" -> Born, Buecking, Springborn (arXiv:1505.01341) - Period matrices: "Bobenko, Buecking 2009" (was Bobenko-Mercat-Schmies' title) -> Bobenko-Mercat-Schmies 2011 + genuine Bobenko-Buecking 2021 - Fabricated entry: "Alexa 2020, DOI 10.1145/3414685.3417840" pointed to an unrelated paper (Pixelor) -> Bunge, Herholz, Kazhdan, Botsch 2020 - Stripe Patterns: "Bonneel et al. 2015" -> Knoeppel, Crane, Pinkall, Schroeder 2015 Equation-number corrections (verified against the PDFs): - Glickenstein 2011 "eq. 4.6" -> "§5.2" (no such equation label exists) - Springborn 2020 "eq. 4.6" -> "§4 variational gradient" - inversive-distance attribution softened to classical inversive distance Other: - DBFEnergy bibliography (separate repo) and convergence half-sentence in novelty-statement.md §3.3 (Bobenko-Buecking 2021) - Status legend (implemented vs planned) at top of references.md - New Phase 12 (decorated DCE & geometric transition, Chain A, near-term) and Phase 13 (canonical tessellations & polyhedral realisation, Chain B capstone) in phases.md + research-track.md; 10c scope-boundary note clarifying infrastructure vs Lutz-specific algorithms Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
11 KiB
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; Bunge et al. 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–Mercat–Schmies 2011 / Bobenko–Bücking 2021 on polyhedral period matrices; 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 (Sawhney–Crane 2017 BFF; Knöppel–Crane–Pinkall–Schröder 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–Schlenker 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.mdfor the per-phase plan andjava-parity.mdfor 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: Soliman–Slepčev–Crane 2018; Pinkall–Springborn 2021 (discrete Liouville); Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021; Rivin–Schlenker 1999. Polygon Laplacians: Alexa–Wardetzky 2011; Bunge et al. 2020. Integrable + practical-flattening context: Born–Bücking–Springborn 2015 (quasiconformal distortion); Sawhney–Crane 2017 (BFF); Knöppel 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_mapnow 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):
- 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?
- 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? - 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?
- Q4 — Phase 9c (4g-polygon) — port the Java implementation literally, or re-derive from Springborn 2020 §5?
- Q5 — geometry-central cross-validation (GC-1) — would you be interested in co-authoring a Newton-vs-Ptolemy-flips comparison?
- Q6 — CGAL submission strategy — one package or several?
- 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.