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

---

## Q1 — 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`.

---

## Q2 — 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).

**Question**:

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

If the answer is "implement", we'd target Phase 9b-analytic right
after the meeting.

---

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

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

---

## Q5 — geometry-central cross-validation (GC-1)

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

---

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

These are conscious decisions matched to CGAL conventions and aren't
load-bearing in the sense that revisiting them later is cheap.

---

## What I'm hoping you'll say "no" to

This is a deliberately blunt question because positive feedback is
nice but negative feedback is rarer and more valuable:

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