docs(reviewer): baustein D — close Java-scan + lit-integration gaps
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 1m59s
API Docs / doc-build (pull_request) Successful in 51s
Markdown link check / check (pull_request) Successful in 43s
C++ Tests / test-cgal (pull_request) Failing after 11m8s
C++ Tests / quality-gates (pull_request) Failing after 1m59s

Earlier baustein B (`07c653c`) added a 6-row Research-Alignments table
+ a "what's new" banner, but only surfaced ~75 % of what the four
Java-scan + literature-integration commits (`f854f0e`, `979f30c`,
`e8a118f`, `8daee1b`) had introduced.  This commit closes the gaps
identified in the lückenprüfung:

Research-Alignments table grows from 6 → 10 rows
─────────────────────────────────────────────────
* +quasi-isothermic maps  (Phase 10e, Java port — 6 classes incl.
  discrete Beltrami-field solver, Lawson correspondence ~800 lines)
* +higher-genus + hyperelliptic surfaces (Phase 10b — `HyperellipticUtility`
  + Bobenko–Bücking 2009)
* +Möbius centring as variational problem (Phase 9d.4 — replaces the
  iterative Fréchet-mean fallback in `normalise_hyperbolic()`)
* +Boundary-First / interactive flattening row (Crane 2017 BFF; Stripe
  Patterns 2015) — listed for comparison even though it is not on the
  porting roadmap, so the reader sees we know about it
* table caption clarifies that some rows are RESEARCH-only (no Java
  parent) and some are planned ports

"What's new" banner
───────────────────
* citation count corrected from "+9" to "+13" — the four Tier-2 papers
  added in commit `e8a118f` (Springborn 2019, Springborn–Veselov 2015,
  Crane 2017 BFF, Bonneel et al. 2015 Stripe Patterns) are now named
* phase count of "+6 phases" kept, but +Phase 9d.4 (Möbius centring)
  and +Phase 10e (quasi-isothermic) are now called out explicitly so
  the reader knows what is in the count
* cross-link to `java-parity.md` for the reverse table (every Java
  class → C++ destination or *do-not-port* rationale)

questions.md / Q1
─────────────────
* expand the table from 3 to 6 candidate phases — adding 10e (quasi-
  isothermic), 10b (hyperelliptic), and 9d.4 (Möbius centring) as
  options alongside the existing 9d.2 / 9f / 10c+10c′
* track column distinguishes RESEARCH-only from planned-port
* +Question C — "is there a seventh line we are missing?" — invites
  the reader to flag a research thread we have not scoped yet

Pages hub will be refreshed to v5 in a follow-up step (separate from
the in-repo commit, lives only on the codeberg `pages` branch).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-26 06:18:26 +02:00
parent 6543abac12
commit 6a712e623b
2 changed files with 56 additions and 27 deletions

View File

@@ -36,7 +36,9 @@ shows static quality-gate status.
## Research alignments — where this library could be infrastructure for your work ## Research alignments — where this library could be infrastructure for your work
The current snapshot already contains, or has roadmap entries for, The current snapshot already contains, or has roadmap entries for,
the following: the following. Most rows match an active publication line in
discrete differential geometry; a few (marked *no Java parent*) are
research-only phases the reader can shape at design stage.
| Your research thread | What this snapshot has | Phase | | Your research thread | What this snapshot has | Phase |
|---|---|---| |---|---|---|
@@ -44,27 +46,43 @@ the following:
| **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 | | **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** (BowersBowersLutz 2026) | HyperIdeal functional + analytic Hessian derivation (805-line LaTeX note) | **9b-analytic** derived; **10c** KAT planned | | **Hyperideal polyhedra rigidity** (BowersBowersLutz 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 | | **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** (AlexaWardetzky 2011; Alexa 2020) | no Java parent; first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) | | **Polygon Laplacian on general meshes** (AlexaWardetzky 2011; Alexa 2020) | *no Java parent* first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) |
| **Quasi-isothermic maps** (generalising conformality where exact conformality is impossible — Lawson-correspondence parameterisation) | scoped as a 6-class port (~800 lines) from the Java original: `QuasiisothermicLayout`, `DBFSolution` (discrete Beltrami field), `SinConditionApplication`, `QuasiisothermicDelaunay`, `QuasiisothermicUtility`, `ConformalStructureUtility` | **10e** planned |
| **Higher-genus + hyperelliptic surfaces** (BobenkoBücking 2009 on polyhedral surfaces; period matrices with block-diagonal Z₂ structure) | port of `HyperellipticUtility` + `HyperIdealHyperellipticUtility` scoped; existing period-matrix code as scaffolding | **10b** planned |
| **Möbius centring for Poincaré-disk layouts** as a variational problem (Lorentz geometry: `E = Σ log(⟨x,p⟩/√(⟨x,x⟩))`) | currently we use iterative Fréchet mean in `normalise_hyperbolic()`; the principled variational alternative is scoped via the Java `MobiusCenteringFunctional` port (full gradient + Hessian) | **9d.4** planned |
| **Boundary-First / interactive flattening** (Crane et al. 2017 BFF; Bonneel et al. 2015 *Stripe Patterns on Surfaces*) | not on the roadmap as ports; documented in [`references.md`](../math/references.md) as comparison points / inspiration for future API design | — |
| **Schläfli-based variational machinery** (RivinSpringborn 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 | | **Schläfli-based variational machinery** (RivinSpringborn 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) See [`doc/roadmap/phases.md`](../roadmap/phases.md) for the per-phase
for the per-phase acceptance criteria and porting plan, [`doc/roadmap/research-track.md`](../roadmap/research-track.md)
[`doc/roadmap/phases.md`](../roadmap/phases.md) for the porting plan. for the items beyond Java parity with explicit acceptance criteria,
and [`doc/roadmap/java-parity.md`](../roadmap/java-parity.md) for the
reverse table (every Java class → C++ destination or *do-not-port*
rationale).
## What's new on this snapshot (since the previous publish) ## What's new on this snapshot (since the previous publish)
- **+6 new porting-roadmap phases** (9d cones / 9e circle-pattern - **+6 new porting-roadmap phases** (9d cones + 9d.4 Möbius centring /
layout / 10d Koebe circle-domain / 10e quasi-isothermic / 10f Koebe 9e circle-pattern layout / 10d Koebe circle-domain / 10e
polyhedra / 10g cyclic-symmetry quotients) derived from a full quasi-isothermic / 10f Koebe polyhedra / 10g cyclic-symmetry
Java-library scan. quotients) derived from a full Java-library scan. See `phases.md`
- **+9 literature citations** integrated into the roadmap, all for the per-phase plan and `java-parity.md` for the reverse table.
Tier-1/2 in the research line above (BobenkoLutz 2024 IMRN; - **+13 literature citations** integrated into the roadmap, all
BobenkoLutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD; Tier-1/2. Decorated-DCE / canonical-tessellation / hyperideal line:
BowersBowersLutz 2026; Crane et al. 2018; AlexaWardetzky 2011; BobenkoLutz 2024 IMRN; BobenkoLutz 2025 *DCG*; Lutz 2023
Alexa 2020; RivinSpringborn 1999). *Geom. Dedicata*; Lutz 2024 PhD; BowersBowersLutz 2026. Cones,
- **Phase 9f** (polygon Laplacian on general meshes) added as polyhedra, period matrices: Crane et al. 2018; Springborn 2019
(hyperbolic polyhedra); BobenkoBücking 2009; RivinSpringborn 1999.
Polygon Laplacians: AlexaWardetzky 2011; Alexa 2020. Integrable +
practical-flattening context: SpringbornVeselov 2015 (cluster
dynamics); Crane et al. 2017 (BFF); Bonneel et al. 2015 (Stripe
Patterns).
- **Phase 9f** (polygon Laplacian on non-triangular meshes) added as
RESEARCH-only — no Java parent — so you can influence its design RESEARCH-only — no Java parent — so you can influence its design
before it exists. before it exists.
- **Phase 10e** (quasi-isothermic maps) and **Phase 9d.4** (variational
Möbius centring) newly scoped from the Java scan; both touch
research lines adjacent to decorated DCE.
- **`output_uv_map`** now covers 4 of 5 DCE solvers (Inversive-Distance - **`output_uv_map`** now covers 4 of 5 DCE solvers (Inversive-Distance
added; CP-Euclidean deferred to Phase 9c with a clear runtime error added; CP-Euclidean deferred to Phase 9c with a clear runtime error
rather than silent failure). rather than silent failure).

View File

@@ -21,18 +21,22 @@ These are the seven items that would benefit most from a second opinion.
--- ---
## Q1 — Research-track alignment: which RESEARCH phase would unblock concrete experiments you want to run? ## Q1 — Research-track alignment: which RESEARCH or planned phase would unblock concrete experiments you want to run?
Three phases in `doc/roadmap/research-track.md` are research-only The roadmap now contains six phases close to live research lines,
(no Java parent, no immediate user request), but each maps onto a each with concrete acceptance criteria (or, for the Java-port phases,
recognised live research line and each has explicit acceptance a clear specification from the Java original). Three are RESEARCH-only
criteria: (no Java parent, no immediate user request); three are Java-port
phases whose existence is settled but whose priority is open:
| Phase | What it would add | Closest published line | | Phase | Track | 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*) | | **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** | Discrete LaplaceBeltrami 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*) | | **9f** | RESEARCH | Discrete LaplaceBeltrami 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) | | **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` | BobenkoBü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 **Question A:** which of these (if any) would unblock concrete
numerical experiments you have wanted to run but currently have no numerical experiments you have wanted to run but currently have no
@@ -42,10 +46,17 @@ reference implementation for?
target the *next* milestone after Phase 9c, or is there a different target the *next* milestone after Phase 9c, or is there a different
order that would serve your research better? 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: Context:
[`research-track.md`](../roadmap/research-track.md) §"Non-Euclidean [`research-track.md`](../roadmap/research-track.md) §"Non-Euclidean
cone extensions" and §"Polygon Laplacian"; the integrated literature cone extensions" and §"Polygon Laplacian";
sits in [`math/references.md`](../math/references.md). [`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).
--- ---