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.