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`](https://github.com/varylab/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`](../math/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`](../roadmap/phases.md) for the per-phase
porting plan, [`doc/roadmap/research-track.md`](../roadmap/research-track.md)
for the items beyond Java parity with explicit acceptance criteria,
and [`doc/roadmap/java-parity.md`](../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`](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 | b | c`) shipped instead |

These are all flagged in
[`doc/architecture/locked-vs-flexible.md`](../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`](../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

```bash
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.