conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs(reviewer): research alignments + 2 new Q1/Q2 + reordered agenda

Browse Source 
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>
This commit is contained in:
Tarik Moussa
2026-05-26 00:21:50 +02:00
parent 1eff8c6bce
commit 07c653cb4c
3 changed files with 245 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
doc/reviewer/agenda.md
View File

@@ -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. **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 Goal: get clear answers to as many of the 7 questions in
[`questions.md`](questions.md) as possible. Order matters: [`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). 1. **Q1 — research-track alignment** (which of 9d.2 / 9f / 10c / 10c′
This sets the framing for the rest. ~5 min. would unblock concrete experiments?). ~8 min. Most likely to
2. **Q1** (Phase 9c port-literal vs re-derive). ~5 min. make them feel the project is genuinely *for* their work, not just
3. **Q2** (Phase 9b-analytic — is the 6× speedup worth ~2 weeks?). adjacent to it.
May trigger longer math discussion; cap at 10 min and offer to 2. **Q2 — decorated-DCE API surface** (A/B/C named parameter vs new
continue async. solver vs property-map auto-detect). ~7 min. Sets a concrete
4. **Q5** (GC-1 cross-validation co-authorship). ~5 min. shape we can sketch in code right after the meeting.
5. **Q3** (CP-Euclidean output_uv_map). ~5 min. 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 **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 (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. 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 [`questions.md`](questions.md) §Q7: *"Is there one architecture
architecture decision where you think 'no, that's the wrong call'?"* decision where you think 'no, that's the wrong call'?"*
Ask explicitly. Wait. Don't fill silence. Negative feedback at this Ask explicitly. Wait. Don't fill silence. Negative feedback at this
phase is the highest-value information of the entire meeting. phase is the highest-value information of the entire meeting.
## §4 Wrap-up — 5 min ## §4 Wrap-up — 5 min
- **Summarise**: 1 sentence per Q1–Q5 answer. - **Summarise**: 1 sentence per Q1–Q7 answer.
- **Next steps**: - **Next steps**:
- Items they offered to help on (if any) → I'll send a follow-up - Items they offered to help on (if any) → I'll send a follow-up
email within 48 h. email within 48 h.
@@ -97,12 +112,13 @@ phase is the highest-value information of the entire meeting.
Reviewer: ____ Reviewer: ____
Duration: ____ min Duration: ____ min
Q1 answer: ____ Q1 answer (research-track alignment): ____
Q2 answer: ____ Q2 answer (decorated-DCE API): ____
Q3 answer: ____ Q3 answer (Phase 9b-analytic): ____
Q4 answer: ____ Q4 answer (Phase 9c port choice): ____
Q5 answer: ____ Q5 answer (GC-1 co-authorship): ____
"No" pointer: ____ Q6 answer (CGAL packaging): ____
Q7 "no" pointer: ____
Action items: Action items:
[ ] (within 48 h) ____ [ ] (within 48 h) ____

66
doc/reviewer/briefing.md
View File

@@ -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 index. It links to the Doxygen API, the key markdown documents, and
shows static quality-gate status. 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 ## What's true about this snapshot
| Claim | Concrete evidence | | Claim | Concrete evidence |
@@ -47,20 +83,32 @@ shows static quality-gate status.
## What we want from you ## What we want from you
Five concrete questions are in Seven concrete questions are in
[`doc/reviewer/questions.md`](questions.md) — please skim them [`doc/reviewer/questions.md`](questions.md) — please skim them
beforehand. They are deliberately scoped: each can be answered with beforehand. They are deliberately scoped: each can be answered with
"go this way" / "no, go that way" / "either is fine". "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, 1. **Q1 — Research-track alignment** — of the three RESEARCH-track
or re-derive from Springborn 2020 §5? phases (9d.2 non-Euclidean cones, 9f polygon Laplacian, 10c
2. **Phase 9b-analytic** — is the ~6× speedup over our current block-FD canonical tessellations + 10c′ Koebe polyhedra), which would
Hessian (full Schläfli-based analytic) worth ~2 weeks? Working-mesh unblock concrete experiments you have wanted to run?
size that justifies it? 2. **Q2 — Decorated-DCE API surface** — what's the minimum public
3. **CGAL submission strategy** — submit as a single package or split API for Penner-coordinate / decorated-DCE work? Named parameter
the five DCE solvers into separate packages? 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) ## What's deliberately deferred (so we can discuss with you first)

222
doc/reviewer/questions.md
View File

@@ -4,13 +4,111 @@
> "do A" / "do B" / "either is fine" is a sufficient answer; deeper > "do A" / "do B" / "either is fine" is a sufficient answer; deeper
> dives are welcome but not required. > dives are welcome but not required.
These are the five decisions that would benefit most from a second These are the seven items that would benefit most from a second opinion.
opinion. Items 1-3 affect the porting roadmap directly; 4-5 affect
the long-term goal (CGAL submission). * **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: 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). - **conformallab++**: Newton on the fixed mesh (no intrinsic flips).
- **Derived but not implemented**: analytic Hessian via the Schläfli - **geometry-central**: Ptolemy flips on an intrinsic triangulation.
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**: An automated comparison on common meshes would be:
- At what mesh size does the ~6× become user-visible enough to - A short paper (the disagreement modes are interesting in their own
justify ~2 weeks of implementation work? right and connect to the decorated-DCE framework via canonical
- Are you aware of subtleties in the Schläfli-based derivation our tessellation invariants).
document might be missing? - 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 **Question:** would you be interested in co-authoring such a comparison
after the meeting. 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? ## Q6 — CGAL submission strategy: one package or several?
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: 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). [`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md) §7).
Either submission packaging is achievable from this base. Either submission packaging is achievable from this base.
**Question**: what's the CGAL editor convention for related-but-distinct **Question:** what's the CGAL editor convention for related-but-distinct
algorithms — Polygon_mesh_processing as one example (one package, many algorithms — `Polygon_mesh_processing` as one example (one package, many
algorithms), vs Triangulation_2/Triangulation_3/Periodic_*/Hyperbolic_* algorithms), vs `Triangulation_2`/`Triangulation_3`/`Periodic_*`/
as another (multiple packages for related algorithms)? `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 Looking at any of the 12 architecture decisions in
directions: [`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). This is a deliberately blunt question because positive feedback is
- **geometry-central**: Ptolemy flips on an intrinsic triangulation. 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<P>` 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 "No" is the most useful answer.
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?
--- ---
@@ -133,21 +210,24 @@ the Crane group who would?
[`code/deps/THIRD-PARTY-LICENSES.md`](../../code/deps/THIRD-PARTY-LICENSES.md)). [`code/deps/THIRD-PARTY-LICENSES.md`](../../code/deps/THIRD-PARTY-LICENSES.md)).
- Build system (CMake ≥ 3.20, header-only consumer + optional - Build system (CMake ≥ 3.20, header-only consumer + optional
CLI/Viewer). CLI/Viewer).
- Documentation tooling (Doxygen with auto-generated `headers.md`).
These are conscious decisions matched to CGAL conventions and aren't These are conscious decisions matched to CGAL conventions and are
load-bearing in the sense that revisiting them later is cheap. 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 A separate "after the meeting" conversation, but flagged here so it
nice but negative feedback is rarer and more valuable: does not surprise you on the day:
**Looking at any of the 12 architecture decisions in - **Acknowledgement** in any future CGAL submission / paper would be
[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md), is the default, and we would ask first.
there one where you think "no, that's the wrong call, here's why"?** - **Co-authorship** on Q5 (the GC-1 cross-validation note) is on the
table if you said yes there.
The 🔴 load-bearing decisions are the most consequential to revisit, - **Periodic update cadence** (quarterly? per-milestone?) — open
because waiting longer makes them more expensive. No is the most question, no expectation.
useful answer. - **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.