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 or planned phase would unblock concrete experiments you want to run?

The roadmap now contains six phases close to live research lines,
each with concrete acceptance criteria (or, for the Java-port phases,
a clear specification from the Java original).  Three are RESEARCH-only
(no Java parent, no immediate user request); three are Java-port
phases whose existence is settled but whose priority is open:

| Phase | Track | What it would add | Closest published line |
|---|---|---|---|
| **9d.2** | RESEARCH | 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** | RESEARCH | 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′** | planned | 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) |
| **10e** | planned | Quasi-isothermic maps (~800 lines Lawson-correspondence) — generalises conformality to meshes where exact conformality is impossible.  Six new classes including a discrete Beltrami-field solver. | Java original `QuasiisothermicUtility` line; no obvious single-paper reference in the existing literature index |
| **10b** | planned | Hyperelliptic surfaces (genus g ≥ 2 with Z₂ symmetry); period matrices with block-diagonal structure; Penner-coordinate variant via `HyperIdealHyperellipticUtility` | Bobenko–Bücking 2009 *Conformal Structures and Period Matrices of Polyhedral Surfaces* |
| **9d.4** | planned | Möbius centring of Poincaré-disk layouts as a *variational* problem (Lorentz energy with full gradient + Hessian), replacing today's iterative Fréchet-mean fallback in `normalise_hyperbolic()` | Java original `MobiusCenteringFunctional`; closest published context: decorated-DCE Möbius normalisation, also used in canonical-tessellation post-processing |

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

**Question C:** is there a *seventh* line we are missing — a research
thread close to your own where you would want infrastructure that the
table above does not yet cover?

Context:
[`research-track.md`](../roadmap/research-track.md) §"Non-Euclidean
cone extensions" and §"Polygon Laplacian";
[`phases.md`](../roadmap/phases.md) for the per-phase porting plan;
[`java-parity.md`](../roadmap/java-parity.md) for the reverse Java
class table; 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.