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`](../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:

- `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`](../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)?

---

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

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"*?

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`](../../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.