From 07c653cb4cc23854a667ad1c057fb039112c43d5 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Tue, 26 May 2026 00:21:50 +0200 Subject: [PATCH] docs(reviewer): research alignments + 2 new Q1/Q2 + reordered agenda MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- doc/reviewer/agenda.md | 58 ++++++---- doc/reviewer/briefing.md | 66 ++++++++++-- doc/reviewer/questions.md | 222 ++++++++++++++++++++++++++------------ 3 files changed, 245 insertions(+), 101 deletions(-) diff --git a/doc/reviewer/agenda.md b/doc/reviewer/agenda.md index 22d9a46..a5a93e2 100644 --- a/doc/reviewer/agenda.md +++ b/doc/reviewer/agenda.md @@ -36,35 +36,50 @@ Goal: they leave §1 with a mental map of what's where. **Cue to move on**: when they have no more "where is X?" questions. -## §2 The five questions — 30 min +## §2 The seven questions — 35 min -Goal: get clear answers to as many of the 5 questions in -[`questions.md`](questions.md) as possible. Order matters: +Goal: get clear answers to as many of the 7 questions in +[`questions.md`](questions.md) as possible. Order is chosen so the +research-relevant questions come *first* (their answer has the largest +downstream effect on the roadmap): -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. +1. **Q1 — research-track alignment** (which of 9d.2 / 9f / 10c / 10c′ + would unblock concrete experiments?). ~8 min. Most likely to + make them feel the project is genuinely *for* their work, not just + adjacent to it. +2. **Q2 — decorated-DCE API surface** (A/B/C named parameter vs new + solver vs property-map auto-detect). ~7 min. Sets a concrete + shape we can sketch in code right after the meeting. +3. **Q3 — Phase 9b-analytic** (Schläfli Hessian — implement now?). + ~8 min. May trigger longer math discussion; cap at 10 min and + offer to continue async via the derivation note. +4. **Q5 — GC-1 cross-validation co-authorship**. ~4 min. Read the + room: if they're warm, push; if cool, leave as "let me follow up + in writing". +5. **Q4 — Phase 9c port-literal vs re-derive** (algorithm choice). + ~4 min. Less critical than Q1–Q3 because we have a viable default + either way. +6. **Q6 — CGAL submission packaging** (one package vs several). + ~4 min. Project-management question; their answer is *advisory* + even if it's confident. **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. +Keep Q4/Q6 *short* — they are project management; Q1–Q3 are the +research-flavoured ones their time is best spent on. -## §3 The "no" question — 5 min +## §3 Q7 — 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'?"* +[`questions.md`](questions.md) §Q7: *"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. +- **Summarise**: 1 sentence per Q1–Q7 answer. - **Next steps**: - Items they offered to help on (if any) → I'll send a follow-up email within 48 h. @@ -97,12 +112,13 @@ phase is the highest-value information of the entire meeting. Reviewer: ____ Duration: ____ min - Q1 answer: ____ - Q2 answer: ____ - Q3 answer: ____ - Q4 answer: ____ - Q5 answer: ____ - "No" pointer: ____ + Q1 answer (research-track alignment): ____ + Q2 answer (decorated-DCE API): ____ + Q3 answer (Phase 9b-analytic): ____ + Q4 answer (Phase 9c port choice): ____ + Q5 answer (GC-1 co-authorship): ____ + Q6 answer (CGAL packaging): ____ + Q7 "no" pointer: ____ Action items: [ ] (within 48 h) ____ diff --git a/doc/reviewer/briefing.md b/doc/reviewer/briefing.md index 4e2e615..e15f85a 100644 --- a/doc/reviewer/briefing.md +++ b/doc/reviewer/briefing.md @@ -33,6 +33,42 @@ 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 | @@ -47,20 +83,32 @@ shows static quality-gate status. ## What we want from you -Five concrete questions are in +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". -The high-stakes ones: +Ordered by reviewer-value (the first two are the ones your research +profile makes you best-positioned to answer): -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? +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) diff --git a/doc/reviewer/questions.md b/doc/reviewer/questions.md index dc8c640..131fa15 100644 --- a/doc/reviewer/questions.md +++ b/doc/reviewer/questions.md @@ -4,13 +4,111 @@ > "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). +These are the seven items that would benefit most from a second opinion. + +* **Q1–Q2** are research-track questions — your active publication line + in **decorated DCE / Penner coordinates / canonical tessellations / + hyperideal polyhedra** makes you the best-positioned reader for them. + They ask whether conformallab++ could become *infrastructure for your + own future numerical experiments*, and what the minimum API surface + would be. +* **Q3–Q4** are porting decisions in our roadmap where your view of the + underlying mathematics would change the answer. +* **Q5–Q6** are project-management questions where peer input is + valuable but not blocking. +* **Q7** is an open invitation to push back on any architecture + decision you think we got wrong. --- -## Q1 — Phase 9c (4g-polygon canonical form): port-literal vs re-derive? +## Q1 — Research-track alignment: which RESEARCH phase would unblock concrete experiments you want to run? + +Three phases in `doc/roadmap/research-track.md` are research-only +(no Java parent, no immediate user request), but each maps onto a +recognised live research line and each has explicit acceptance +criteria: + +| Phase | What it would add | Closest published line | +|---|---|---| +| **9d.2** | Decorated DCE in non-Euclidean (spherical + hyperbolic) geometries; Penner coordinates as first-class DOF; automatic cone placement for non-Euclidean targets | Decorated DCE in non-Euclidean geometries (2025, *Discrete Comput. Geom.*); optimal cone singularities for Euclidean flattening (2018, *SIGGRAPH*) | +| **9f** | Discrete Laplace–Beltrami on **non-triangular** polygonal meshes (virtual-node / generalised cotangent), making DCE work on quad / Voronoi tessellations without re-triangulation | Polygon Laplacians (2011 *SIGGRAPH* + 2020 *TOG*) | +| **10c + 10c′** | Canonical Delaunay tessellations of decorated hyperbolic surfaces; Koebe polyhedron realisation (KAT) with rigidity-aware Newton | Canonical tessellations of decorated hyperbolic surfaces (2023, *Geom. Dedicata*); rigidity of circle / hyperideal polyhedra (2026, preprint) | + +**Question A:** which of these (if any) would unblock concrete +numerical experiments you have wanted to run but currently have no +reference implementation for? + +**Question B:** for the one(s) you would use, would you want us to +target the *next* milestone after Phase 9c, or is there a different +order that would serve your research better? + +Context: +[`research-track.md`](../roadmap/research-track.md) §"Non-Euclidean +cone extensions" and §"Polygon Laplacian"; the integrated literature +sits in [`math/references.md`](../math/references.md). + +--- + +## Q2 — Decorated-DCE API surface: what would you need from us to use the library for Penner-coordinate work? + +If you wanted to compute the variational energy + Newton update for +**decorated discrete conformal equivalence** (vertex `u`-DOFs plus +per-edge Penner decoration `λ_e`), the existing five-solver scaffold +gives us three plausible API directions: + +- **(A) Named parameter on the existing Euclidean entry.** + `discrete_conformal_map_euclidean(mesh, parameters::penner_decoration_map(λ))`. + Smallest change; preserves the single-entry-per-geometry pattern; + hides the decoration as "just another property map". +- **(B) Separate `decorated_*` solver headers.** + New entry `CGAL::decorated_discrete_conformal_map_{euclidean, + spherical, hyperbolic}` with its own `Default_decorated_*_traits`. + Cleaner separation of concerns; mirrors the way CP-Euclidean and + Inversive-Distance are their own headers. +- **(C) Per-edge decoration as just another property map** that the + existing solvers consume when present (zero-decoration = current + behaviour by construction). Minimal API expansion; risk of + surprising convergence behaviour when decoration is silently zero + vs explicitly zero. + +**Question:** which of A / B / C matches what you would expect from +a CGAL-style header? If "none of the above" — what would you write +in our place? + +Context: Phase 9d.2 in +[`research-track.md`](../roadmap/research-track.md); the existing +named-parameter helpers in +[`code/include/CGAL/Conformal_map/internal/parameters.h`](../../code/include/CGAL/Conformal_map/internal/parameters.h). + +--- + +## Q3 — 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, Rivin–Springborn 1999). + +**Question:** + +- At what mesh size does the ~6× become user-visible enough to + justify ~2 weeks of implementation work, given the typical sizes + in your 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. + +--- + +## Q4 — Phase 9c (4g-polygon canonical form): port-literal vs re-derive? The Java original has two utility classes: @@ -38,48 +136,30 @@ Context: `doc/roadmap/phases.md` §Phase 9c, `doc/roadmap/porting-status.md`. --- -## Q2 — Phase 9b-analytic Hessian: implement now or later? +## Q5 — geometry-central cross-validation (GC-1): would you co-author? -We have: +Two libraries solve the DCE problem from opposite algorithmic +directions: -- **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). +- **conformallab++**: Newton on the fixed mesh (no intrinsic flips). +- **geometry-central**: Ptolemy flips on an intrinsic triangulation. -**Question**: +An automated comparison on common meshes would be: -- 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? +- A short paper (the disagreement modes are interesting in their own + right and connect to the decorated-DCE framework via canonical + tessellation invariants). +- A confidence-building tool for both libraries. +- ~3 days of plumbing (CMake-fetch geometry-central, write 5 common + test meshes, compare `u_per_vertex` to a tolerance). -If the answer is "implement", we'd target Phase 9b-analytic right -after the meeting. +**Question:** would you be interested in co-authoring such a comparison +note (with us doing the implementation)? Or do you know someone in a +neighbouring group who would be a natural co-author? --- -## 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? +## Q6 — CGAL submission strategy: one package or several? For the long-term CGAL submission: @@ -94,34 +174,31 @@ 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)? +**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) +## Q7 — The "no" question (this is the highest-value answer) -Two libraries solve the DCE problem from opposite algorithmic -directions: +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"*? -- **conformallab++**: Newton on the fixed mesh (no intrinsic flips). -- **geometry-central**: Ptolemy flips on an intrinsic triangulation. +This is a deliberately blunt question because positive feedback is +nice but negative feedback is rarer and more valuable. The 🔴 +load-bearing decisions are the most consequential to revisit, because +waiting longer makes them more expensive: -An automated comparison on common meshes would be: +- **#1** `CGAL::Surface_mesh

` as default mesh +- **#3** header-only, no compiled library +- **#6** Eigen as linear-algebra back-end +- **#11** MIT license (only relevant if it conflicts with a CGAL- + submission constraint) -- 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? +"No" is the most useful answer. --- @@ -133,21 +210,24 @@ the Crane group who would? [`code/deps/THIRD-PARTY-LICENSES.md`](../../code/deps/THIRD-PARTY-LICENSES.md)). - Build system (CMake ≥ 3.20, header-only consumer + optional CLI/Viewer). +- Documentation tooling (Doxygen with auto-generated `headers.md`). -These are conscious decisions matched to CGAL conventions and aren't -load-bearing in the sense that revisiting them later is cheap. +These are conscious decisions matched to CGAL conventions and are +not load-bearing in the sense that revisiting them later is cheap. --- -## What I'm hoping you'll say "no" to +## After the meeting — would you collaborate? -This is a deliberately blunt question because positive feedback is -nice but negative feedback is rarer and more valuable: +A separate "after the meeting" conversation, but flagged here so it +does not surprise you on the day: -**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. +- **Acknowledgement** in any future CGAL submission / paper would be + the default, and we would ask first. +- **Co-authorship** on Q5 (the GC-1 cross-validation note) is on the + table if you said yes there. +- **Periodic update cadence** (quarterly? per-milestone?) — open + question, no expectation. +- **Pull requests** from your side are welcome and reviewable on the + Codeberg repo. We would not expect them — but we would not turn + them away either.