From faf96ee28c37893df1ddc7cca5ec90efced36f7f Mon Sep 17 00:00:00 2001
From: Tarik Moussa <tarikmoussa@MacBookAir.fritz.box>
Date: Sun, 31 May 2026 00:00:15 +0200
Subject: [PATCH] doc(roadmap): add research item for 2/3-ideal hyper-ideal
 volume formulas

Follow-up to the Finding-A fix (face_energy guard).  The throw is the
correct safe behaviour for now; the mathematically complete solution
requires formulas for semi-ideal and fully-ideal tetrahedra that are
absent from the Java reference.

Adds a structured research entry to research-track.md (Phase 9b+):
- primary references: Kolpakov-Mednykh arXiv:math/0603097, Milnor 1982,
  Vinberg 1985
- acceptance criteria: two new volume functions + gradient-check tests +
  limiting-behaviour continuity witness
- explicit note that the throw in face_energy() must not be removed
  without implementing and testing the replacement formulas

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 doc/reviewer/external-audit-2026-05-30.md |  6 +++
 doc/roadmap/research-track.md             | 60 +++++++++++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/doc/reviewer/external-audit-2026-05-30.md b/doc/reviewer/external-audit-2026-05-30.md
index 851b400..5ed628e 100644
--- a/doc/reviewer/external-audit-2026-05-30.md
+++ b/doc/reviewer/external-audit-2026-05-30.md
@@ -170,6 +170,12 @@ Instead it:
 **Test result:** 262/262 CGAL tests pass (was 246 before + 3 new guard tests + 13 from
 prior suite growth). No regressions.
 
+**Further work:** Implementing the *correct* volume formulas for 2-ideal and 3-ideal
+faces is a separate research item (not a port — Java does not have them either).
+It is now tracked in `doc/roadmap/research-track.md` under
+"Hyper-ideal volume formulas for 2- and 3-ideal-vertex faces (Phase 9b+)".
+The `throw` remains the correct safe behaviour until that research item is resolved.
+
 ### Acceptance criteria
 - [x] All 8 cases (2³ combinations) are either correct or throw explicitly
 - [x] Three new tests cover the three guard cases
diff --git a/doc/roadmap/research-track.md b/doc/roadmap/research-track.md
index e9cbc0d..d6152e5 100644
--- a/doc/roadmap/research-track.md
+++ b/doc/roadmap/research-track.md
@@ -133,6 +133,66 @@ The phase numbers match `doc/roadmap/phases.md`.
 
 ## Planned research (not yet PR)
 
+### Hyper-ideal volume formulas for 2- and 3-ideal-vertex faces (Phase 9b+, 🔲 planned)
+
+* **Mathematical sources:**
+  - **Kolpakov, A. & Mednykh, A.** (2012). *Spherical structures on torus
+    knots and links.* Sibirsk. Mat. Zh. 53(3), 535–541 — see the earlier
+    arXiv:math/0603097 for the one-ideal-vertex formula already implemented
+    as `calculateTetrahedronVolumeWithIdealVertexAtGamma`.
+  - **Milnor, J.** (1982). *Hyperbolic geometry: The first 150 years.*
+    Bull. Amer. Math. Soc. 6(1), 9–24.  → Volume of an ideal tetrahedron
+    via Clausen function; this is the all-ideal case with 4 ideal vertices.
+  - **Vinberg, E. B.** (1985). *Hyperbolic reflection groups.*
+    Uspekhi Mat. Nauk 40(1), 29–66. → general semi-ideal / orthoscheme approach.
+  - Study arXiv:math/0603097 §3–4 carefully to determine whether the
+    one-ideal formula already yields the correct limit as γ₂ → 0
+    (ideal v2): if Л(0) = 0 absorbs the second ideal vertex naturally,
+    the extension to 2-ideal may be free; if not, a different formula is needed.
+
+* **Java reference:** ❌ **none.**  `HyperIdealUtility.java` has exactly two
+  volume functions; the Java `HyperIdealFunctional` silently falls through the
+  `if/else-if` cascade for 2+ideal faces (uses the one-ideal formula for the
+  first ideal vertex found, ignoring subsequent ideal vertices).  C++ now
+  throws `std::logic_error` instead (fixed 2026-05-30, Finding-A).
+
+* **Context:**
+  In the standard workflow (`assign_all_dof_indices`) every vertex is
+  hyper-ideal and no face has ideal vertices — the currently missing formulas
+  are never reached.  They only matter for:
+  (a) mixed configurations with some pinned (ideal) vertices; and
+  (b) cusped hyperbolic surfaces (Θᵥ = 0 for a cusp vertex).
+  Use case (b) is the main motivation for eventually implementing these.
+
+* **Acceptance criteria:**
+  - Identify the correct formula for a hyper-ideal tetrahedron with exactly
+    2 ideal vertices from the literature (check Kolpakov-Mednykh generalisations
+    and Vinberg orthoscheme decomposition).
+  - Implement `calculateTetrahedronVolumeWithTwoIdealVertices(…)` analogous
+    to the existing Kolpakov-Mednykh function.
+  - Implement `calculateTetrahedronVolumeWithThreeIdealVertices(…)` (one
+    hyper-ideal + three ideal = fully cusp-like case).
+  - Replace the `throw std::logic_error` in `face_energy()` with the correct
+    branch for each case; update the guard to throw only for `ideal_count > 3`
+    (which is topologically impossible).
+  - Gradient check passes for each new configuration at machine precision
+    (central FD vs. analytic, tol = 1e-4).
+  - Limiting-behaviour test: as `b_v → 0` for a hyper-ideal vertex, the
+    energy from the 0-ideal formula must converge to the 1-ideal formula to
+    1e-6 (continuity witness).
+
+* **Effort:** medium (3–5 days: 1–2 days literature study + derivation,
+  1–2 days implementation, 1 day tests).
+
+* **Phase:** 9b+ (add to Phase 9b milestone once the analytic Hessian PR lands;
+  the two features are independent).
+
+* **Note:** The `throw` introduced in the 2026-05-30 fix is the **correct
+  safe behaviour** until this item is resolved.  Do not remove it without
+  implementing and testing the replacement formulas.
+
+---
+
 ### Hyper-ideal Hessian — full analytic (Phase 9b-analytic, 🔲 planned)
 
 * **Mathematical sources:**