# 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:

| 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) |
| **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/research-track.md`](../roadmap/research-track.md)
for the per-phase acceptance criteria and
[`doc/roadmap/phases.md`](../roadmap/phases.md) for the porting plan.

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

- **+6 new porting-roadmap phases** (9d cones / 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.
- **+9 literature citations** integrated into the roadmap, all
  Tier-1/2 in the research line above (Bobenko–Lutz 2024 IMRN;
  Bobenko–Lutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD;
  Bowers–Bowers–Lutz 2026; Crane et al. 2018; Alexa–Wardetzky 2011;
  Alexa 2020; Rivin–Springborn 1999).
- **Phase 9f** (polygon Laplacian on general meshes) added as
  RESEARCH-only — no Java parent — so you can influence its design
  before it exists.
- **`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.