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.

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

Five 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".

The high-stakes ones:

1. **Phase 9c (4g-polygon)** — port the Java implementation literally,
   or re-derive from Springborn 2020 §5?
2. **Phase 9b-analytic** — is the ~6× speedup over our current block-FD
   Hessian (full Schläfli-based analytic) worth ~2 weeks? Working-mesh
   size that justifies it?
3. **CGAL submission strategy** — submit as a single package or split
   the five DCE solvers into separate packages?

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