ConformalLabpp/doc/reviewer/questions.md

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 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 — 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 §"Non-Euclidean cone extensions" and §"Polygon Laplacian"; the integrated literature sits in 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; the existing named-parameter helpers in 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 (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:

• 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 reference implementation (Mathematica notebook, paper appendix, other research codebase) we should cross-validate against?

Context: doc/roadmap/phases.md §Phase 9c, doc/roadmap/porting-status.md.

---

Q5 — geometry-central cross-validation (GC-1): would you co-author?

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 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).

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?

---

Q6 — CGAL submission strategy: one package or several?

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 §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)?

---

Q7 — The "no" question (this is the highest-value answer)

Looking at any of the 12 architecture decisions in locked-vs-flexible.md, is there one where you think "no, that's the wrong call, here's why"?

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:

• #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)

"No" is the most useful answer.

---

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).
• 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 are not load-bearing in the sense that revisiting them later is cheap.

---

After the meeting — would you collaborate?

A separate "after the meeting" conversation, but flagged here so it does not surprise you on the day:

• 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.