feat: output_uv_map for InversiveDistance, error for CP-Euclidean, reviewer trio

Three reviewer-meeting deliverables in one commit. (1) output_uv_map for the two remaining DCE entries ───────────────────────────────────────────────── * Discrete_inversive_distance.h: full implementation. After Newton, reconstruct effective Euclidean edge lengths from the converged log-radii via the Bowers-Stephenson identity `ℓᵢⱼ² = rᵢ² + rⱼ² + 2·Iᵢⱼ·rᵢ·rⱼ`, populate a temporary EuclideanMaps with `lambda0 = log(ℓᵢⱼ²)`, and reuse the existing `euclidean_layout(mesh, 0, eucl)` priority-BFS. Per-vertex Point_2 coordinates written into the user-supplied pmap. Optional `normalise_layout(true)` applies the canonical PCA centroid + major-axis rotation, same as the other 3 entries. * Discrete_circle_packing.h: throws std::runtime_error with a clear pointer to Phase 9c rather than silently producing nonsense. CP-Euclidean is face-based; the faithful output is a per-face circle packing in ℝ², not a per-vertex Point_2 map. A true layout requires BPS-2010 §6 (~150 lines, on the porting roadmap as Phase 9c). Failing loudly is the honest default. Tests: 2 new cases in test_cgal_phase8b_lite.cpp (OutputUvMap_InversiveDistance_PopulatesPmap; OutputUvMap_CPEuclidean_ThrowsClearly). Both green. Suite total now 259 (was 257, +2). CGAL subtotal: 234 → 236. (2) Reviewer meeting documents ────────────────────────── New directory doc/reviewer/ with three files: * briefing.md — one-page orientation for the reviewer. What the project is, where to look first (https://tmoussa.codeberg.page/ConformalLabpp/), the headline evidence (tests/coverage/sanitizers/license), what we want from them, what's deferred and why, and the 5 questions in a separate file. * questions.md — the 5 concrete decisions we want their second opinion on: Q1 Phase 9c (port-literal vs re-derive) Q2 Phase 9b-analytic (worth ~2 weeks for ~6× speedup?) Q3 CP-Euclidean output_uv_map (build now or defer?) Q4 CGAL submission strategy (one package or five?) Q5 geometry-central cross-validation co-authorship Plus an explicit "what would you say no to?" question at the bottom — negative feedback is the highest-value information. * agenda.md — my own internal playbook (NOT to be sent). 60-min flow: 5-min thank-you, 10-min architecture tour, 30-min for Q1-Q5 in the order Q4-Q1-Q2-Q5-Q3, 5-min "no" question, 5-min wrap-up. Includes post-meeting memo template to fill out in the 30 min after. * README.md — index for the directory; says which file goes to whom and when to send. (3) locked-vs-flexible.md known-limitations update ───────────────────────────────────────────── "output_uv_map covers 3 of 5 entries" → "covers 4 of 5". CP-Euclidean's throws-clearly behaviour documented as a Phase 9c deliverable rather than a passive gap. Bonus: extended .codespellrc ignore list (acknowledgement, the British-English spelling I used in agenda.md). Verifications on this commit: 259/259 tests pass (0 skipped) scripts/check-test-counts.sh: OK (23 + 236 = 259) scripts/quality/license-headers.sh: OK (66/66 SPDX) python3 scripts/quality/cgal-conventions.py: OK (0/6 violations) scripts/quality/codespell.sh: OK (0 typos) scripts/quality/shellcheck.sh: OK (0 findings) python3 scripts/check-markdown-links.py: OK (143/143) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-24 21:15:19 +02:00
parent 32253a8f5e
commit f25174ed69
10 changed files with 554 additions and 3 deletions
--- a/doc/reviewer/README.md
+++ b/doc/reviewer/README.md
@@ -0,0 +1,28 @@
+# Reviewer meeting materials
+
+A single landing page for the three documents associated with the
+external-reviewer meeting (Springborn/Bobenko alumnus, May 2026).
+
+| Document | Audience | Purpose |
+|---|---|---|
+| [`briefing.md`](briefing.md) | **the reviewer** | one-page orientation: what the project is, where to look first, what we want from them |
+| [`questions.md`](questions.md) | **the reviewer** | the 5 concrete decisions we want their opinion on (skim before the meeting) |
+| [`agenda.md`](agenda.md) | **me** | my own meeting playbook: timing, order, the "no" question, post-meeting memo template |
+
+After the meeting, a fourth file `2026-XX-XX-meeting-notes.md` should
+land here too — the memo template at the bottom of `agenda.md` is the
+suggested structure.
+
+## When to send to the reviewer
+
+- **briefing.md** + **questions.md**: as part of the meeting-confirmation
+  email, ~5 business days before the meeting.  Subject line: *"Pre-read
+  for our conformallab++ chat (~15 min)"*.
+- **agenda.md**: never send.  This is internal scaffolding.
+
+## Quick links the reviewer should bookmark
+
+- 🌐 Reviewer-hub landing page: <https://tmoussa.codeberg.page/ConformalLabpp/>
+- 📦 Source: <https://codeberg.org/TMoussa/ConformalLabpp>
+- 📝 Architecture decisions: [`../architecture/locked-vs-flexible.md`](../architecture/locked-vs-flexible.md)
+- 📐 Schläfli derivation (for Q2): [`../math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
--- a/doc/reviewer/agenda.md
+++ b/doc/reviewer/agenda.md
@@ -0,0 +1,114 @@
+# Reviewer meeting — agenda (for me)
+
+> **Audience.** Myself, before the meeting. Not shared with the
+> reviewer (they have [`briefing.md`](briefing.md) and
+> [`questions.md`](questions.md) instead).
+>
+> **Purpose.** Keep the conversation on the high-stakes items
+> without slipping into detail-tour mode.
+
+**Length:** ~60 min (default; willing to extend if conversation is
+productive).
+
+## Opening — 5 min
+
+- **Thank-you** + ~30 s on why I value their time specifically
+  (Springborn/Bobenko background = best-positioned audience for
+  this material).
+- **Confirm format**: they've read `briefing.md`? Yes → skip ahead.
+  No → take 3 min to walk through it together via the reviewer-hub
+  URL.
+
+## §1 Architectural tour — 10 min
+
+Goal: they leave §1 with a mental map of what's where.
+
+1. Open <https://tmoussa.codeberg.page/ConformalLabpp/>.
+2. Click through:
+   - Doxygen → `discrete_conformal_map_euclidean` (the canonical entry,
+     shows the named-parameter pattern + traits).
+   - `locked-vs-flexible.md` § Summary table.
+   - `dependencies.md` § TL;DR.
+3. **Don't** demo running the test suite live unless they ask —
+   they can verify the green badges later.
+
+**Cue to move on**: when they have no more "where is X?" questions.
+
+## §2 The five questions — 30 min
+
+Goal: get clear answers to as many of the 5 questions in
+[`questions.md`](questions.md) as possible.  Order matters:
+
+1. **Q4 first** (CGAL submission strategy — single package vs five).
+   This sets the framing for the rest.  ~5 min.
+2. **Q1** (Phase 9c port-literal vs re-derive).  ~5 min.
+3. **Q2** (Phase 9b-analytic — is the 6× speedup worth ~2 weeks?).
+   May trigger longer math discussion; cap at 10 min and offer to
+   continue async.
+4. **Q5** (GC-1 cross-validation co-authorship).  ~5 min.
+5. **Q3** (CP-Euclidean output_uv_map).  ~5 min.
+
+**Trap to avoid**: don't relitigate any of the already-made decisions
+(e.g. Surface_mesh as default, Eigen as backend) unless they bring it
+up under "anything you'd say no to".  Move forward, not sideways.
+
+## §3 The "no" question — 5 min
+
+Last paragraph of [`questions.md`](questions.md): *"Is there one
+architecture decision where you think 'no, that's the wrong call'?"*
+
+Ask explicitly. Wait.  Don't fill silence.  Negative feedback at this
+phase is the highest-value information of the entire meeting.
+
+## §4 Wrap-up — 5 min
+
+- **Summarise**: 1 sentence per Q1–Q5 answer.
+- **Next steps**: 
+  - Items they offered to help on (if any) → I'll send a follow-up
+    email within 48 h.
+  - Items they flagged as worth changing → I'll write a one-page
+    plan + send for sign-off before starting work.
+- **Cadence**: do they want a periodic update? Once-a-quarter? When
+  hitting Phase 9c milestone?
+- **Citation**: ask whether they want acknowledgement in the
+  CGAL submission's `THANKS.md`.
+
+## Material I have ready (in tabs)
+
+1. <https://tmoussa.codeberg.page/ConformalLabpp/>
+2. <https://codeberg.org/TMoussa/ConformalLabpp> (source)
+3. Local terminal in the repo (for any "show me X" requests)
+4. `doc/math/hyperideal-hessian-derivation.md` open in editor
+   (for Q2)
+5. `doc/architecture/locked-vs-flexible.md` open at "Summary table"
+6. This file, [`questions.md`](questions.md), and
+   [`briefing.md`](briefing.md) for backstop.
+
+## After the meeting
+
+- 30-min decompression — don't take notes during the meeting beyond
+  bullet-tracking of Q1–Q5 answers; write up a full memo in the 30 min
+  AFTER.
+- Memo template:
+  ```
+  Date:  ____
+  Reviewer:  ____
+  Duration:  ____ min
+  
+  Q1 answer:  ____
+  Q2 answer:  ____
+  Q3 answer:  ____
+  Q4 answer:  ____
+  Q5 answer:  ____
+  "No" pointer:  ____
+  
+  Action items:
+    [ ] (within 48 h)  ____
+    [ ] (within 2 wks) ____
+    [ ] (longer term)  ____
+  
+  Cadence agreed:  ____
+  ```
+
+- Store the memo at `doc/reviewer/2026-XX-XX-meeting-notes.md`
+  (gitignored if confidential, otherwise committed).
--- a/doc/reviewer/briefing.md
+++ b/doc/reviewer/briefing.md
@@ -0,0 +1,112 @@
+# Reviewer briefing — conformallab++
+
+> **Audience.** External reviewer with a discrete-conformal-geometry
+> background (Springborn / Bobenko alumnus, ~30 minutes lead-time
+> before the meeting).
+>
+> **Purpose of this document.** A single page they can read once
+> before the meeting and feel oriented — what the project is, what
+> we want from them, and where to look first.
+
+## 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.
--- a/doc/reviewer/questions.md
+++ b/doc/reviewer/questions.md
@@ -0,0 +1,153 @@
+# Questions for the external reviewer
+
+> Please skim this before the meeting.  Each question is scoped so that
+> "do A" / "do B" / "either is fine" is a sufficient answer; deeper
+> dives are welcome but not required.
+
+These are the five decisions that would benefit most from a second
+opinion.  Items 1-3 affect the porting roadmap directly; 4-5 affect
+the long-term goal (CGAL submission).
+
+---
+
+## Q1 — Phase 9c (4g-polygon canonical form): port-literal vs re-derive?
+
+The Java original has two utility classes:
+
+- `FundamentalPolygonUtility` (~600 lines)
+- `CanonicalFormUtility` (~900 lines)
+
+that together compute the canonical 4g-polygon for a higher-genus
+surface from its cut graph.
+
+We can either:
+
+- **(A) Port literally** (~2 weeks).  Faithful, predictable, fixes
+  the Java algorithm in C++.  Down-side: we inherit the Java code's
+  ad-hoc style and edge-case handling.
+- **(B) Re-derive from Springborn 2020 §5** (~3 weeks).  Uses our
+  existing `cut_graph.hpp` + holonomy infrastructure cleanly.
+  Down-side: longer; potential for new bugs not seen by the Java
+  original's test cases.
+
+**Question**: which route do you prefer, and is there a Springborn-era
+reference implementation (Mathematica notebook, paper appendix) we
+should cross-validate against?
+
+Context: `doc/roadmap/phases.md` §Phase 9c, `doc/roadmap/porting-status.md`.
+
+---
+
+## Q2 — Phase 9b-analytic Hessian: implement now or later?
+
+We have:
+
+- **Done**: per-face block-FD Hessian (96× faster than naive full-FD).
+- **Derived but not implemented**: analytic Hessian via the Schläfli
+  identity, expected ~6× further speedup over block-FD.
+- **Derivation document**:
+  [`doc/math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
+  (805 lines, all sign pitfalls covered, references Schläfli 1858,
+  Milnor 1982, Vinberg 1993, Cho-Kim 1999, Glickenstein 2011,
+  Springborn 2020).
+
+**Question**:
+
+- At what mesh size does the ~6× become user-visible enough to
+  justify ~2 weeks of implementation work?
+- Are you aware of subtleties in the Schläfli-based derivation our
+  document might be missing?
+
+If the answer is "implement", we'd target Phase 9b-analytic right
+after the meeting.
+
+---
+
+## Q3 — `output_uv_map` for CP-Euclidean: build now or defer?
+
+For CP-Euclidean (face-based DOFs, BPS 2010) the natural output is a
+**per-face circle packing** in ℝ² — not a per-vertex `Point_2` map
+the way the other four DCE entries produce.
+
+Today the entry throws `std::runtime_error` with a helpful pointer if
+the caller passes `output_uv_map(...)`.  A faithful layout would be
+~150 lines implementing BPS-2010 §6.
+
+**Question**: do *your* CP-Euclidean use cases need a UV-like output,
+or are the face circle radii themselves the deliverable?  The answer
+shapes whether Phase 9c gets it now or later.
+
+---
+
+## Q4 — CGAL submission strategy: one package or five?
+
+For the long-term CGAL submission:
+
+- **(A) One package** "Discrete_conformal_map" — single entry header,
+  five solver functions, one set of named parameters.  Easier for
+  users to find; harder to compartmentalise reviews.
+- **(B) Five packages** "Discrete_*" — each DCE model is its own
+  CGAL package with its own concept + reference manual.  More
+  ceremony for users; more familiar review surface for CGAL editors.
+
+Today the code is structured per-functional (Strategy C — see
+[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md) §7).
+Either submission packaging is achievable from this base.
+
+**Question**: what's the CGAL editor convention for related-but-distinct
+algorithms — Polygon_mesh_processing as one example (one package, many
+algorithms), vs Triangulation_2/Triangulation_3/Periodic_*/Hyperbolic_*
+as another (multiple packages for related algorithms)?
+
+---
+
+## Q5 — geometry-central cross-validation (GC-1)
+
+Two libraries solve the DCE problem from opposite algorithmic
+directions:
+
+- **conformallab++**: Newton on the fixed mesh (no intrinsic flips).
+- **geometry-central**: Ptolemy flips on an intrinsic triangulation.
+
+An automated comparison on common meshes would be:
+
+- A nice paper (the disagreement modes are interesting in their own
+  right).
+- A confidence-building tool for both libraries (we benefit from
+  catching corner-case bugs, they benefit from cross-validation
+  against a Newton baseline).
+- ~3 days of plumbing (CMake-fetch geometry-central, write 5 common
+  test meshes, compare `u_per_vertex` to a tolerance).
+
+**Question**: would you be interested in co-authoring such a comparison
+note (with us doing the implementation)?  Or do you know someone in
+the Crane group who would?
+
+---
+
+## Things you do *not* need to comment on (unless you want)
+
+- C++ style choices captured in `.clang-format` + `.clang-tidy`.
+- Test framework choice (GTest).
+- License (MIT, with vendored deps catalogued in
+  [`code/deps/THIRD-PARTY-LICENSES.md`](../../code/deps/THIRD-PARTY-LICENSES.md)).
+- Build system (CMake ≥ 3.20, header-only consumer + optional
+  CLI/Viewer).
+
+These are conscious decisions matched to CGAL conventions and aren't
+load-bearing in the sense that revisiting them later is cheap.
+
+---
+
+## What I'm hoping you'll say "no" to
+
+This is a deliberately blunt question because positive feedback is
+nice but negative feedback is rarer and more valuable:
+
+**Looking at any of the 12 architecture decisions in
+[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md), is
+there one where you think "no, that's the wrong call, here's why"?**
+
+The 🔴 load-bearing decisions are the most consequential to revisit,
+because waiting longer makes them more expensive.  No is the most
+useful answer.