07c653cb4c
Adds the two research-track questions to the front of the queue, where
they belong for a reader whose publication line maps directly onto our
research-track roadmap entries.
briefing.md gains two new sections:
* Research alignments — a 6-row table mapping the reader's research
threads (decorated DCE, canonical tessellations, hyperideal
rigidity, optimal cone placement, polygon Laplacian, Schläfli
machinery) onto concrete phases of the roadmap, with the closest
published line cited generically (year + venue only).
* What's new on this snapshot — the 6 new porting phases + 9 new
citations + Phase 9f (RESEARCH, no Java parent) + output_uv_map
extension to Inversive-Distance.
questions.md restructures the question set from 5 to 7:
* Q1 (NEW) — research-track alignment: which of 9d.2 / 9f / 10c /
10c′ would unblock concrete experiments?
* Q2 (NEW) — decorated-DCE API surface: A/B/C named parameter vs
new solver vs property-map auto-detect?
* Q3 — Phase 9b-analytic (was Q2)
* Q4 — Phase 9c port-literal vs re-derive (was Q1)
* Q5 — GC-1 cross-validation co-authorship (was Q5)
* Q6 — CGAL submission packaging (was Q4)
* Q7 — The "no" question (was the trailing section)
Also drops Q3 from the previous list (CP-Euclidean output_uv_map),
since that question is now answered (Phase 9c, runtime error today,
on the deferred list — no reviewer input needed).
Adds a final "After the meeting — would you collaborate?" block so
the post-meeting collaboration options (acknowledgement / co-author /
cadence / PRs) do not surprise the reader on the day.
agenda.md reorders §2 to match the new question order; the timing
shifts Q1/Q2/Q3 (research) to the front and Q4/Q6 (project
management) to the back. Memo template at the bottom now has 7
named answer slots instead of 5 numbered ones.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
166 lines
9.0 KiB
Markdown
166 lines
9.0 KiB
Markdown
# 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.
|