conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs(references): M1/M2/M4 citation fixes (audit quick-wins)

Browse Source 
M1: Add two missing references used in hyper_ideal_utility:
  - Kolpakov, Mednykh (2006, arXiv math/0603097) — tetrahedron volume w/ one ideal vertex
  - Meyerhoff, Ushijima (2006) — tetrahedron volume w/ three ideal vertices

M2: Clarify BPS publication year: Geometry & Topology 2015 (arXiv 2010)
  - Update references.md to note "first posted 2010"
  - Normalize all code comments from "BPS-2010" → "BPS-2015" (published version)

M4: Standardize citation format in code comments
  - Normalize all "Luo (2004)" / "Luo-2004" / "Luo's 2004" → "Luo 2004"
  - Matches references.md convention: Author Year (no parens/dashes)

282/282 tests pass. Addresses M1, M2, M4 from math-derivation-citation audit.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-31 14:22:02 +02:00
parent b0946c8704
commit 51d9844f7a
5 changed files with 16 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
code/include/CGAL/Discrete_circle_packing.h
View File

@@ -8,7 +8,7 @@
\ingroup PkgConformalMapRef \ingroup PkgConformalMapRef
User-facing entry for the **face-based** circle-packing functional of User-facing entry for the **face-based** circle-packing functional of
Bobenko-Pinkall-Springborn 2010. See `cp_euclidean_functional.hpp` Bobenko-Pinkall-Springborn 2015. See `cp_euclidean_functional.hpp`
for the underlying algorithm and `doc/architecture/phase-9a-validation.md` for the underlying algorithm and `doc/architecture/phase-9a-validation.md`
for the line-by-line mapping to the Java original for the line-by-line mapping to the Java original
`CPEuclideanFunctional.java`. `CPEuclideanFunctional.java`.
@@ -44,7 +44,7 @@ namespace CGAL {
\ingroup PkgConformalMapConcepts \ingroup PkgConformalMapConcepts
\brief Traits class for `discrete_circle_packing_euclidean()` — \brief Traits class for `discrete_circle_packing_euclidean()` —
declares the kernel, mesh and property-map types used by the declares the kernel, mesh and property-map types used by the
BPS-2010 face-based circle-packing functional. BPS-2015 face-based circle-packing functional.
Primary template; specialise it for non-`Surface_mesh` triangle meshes. Primary template; specialise it for non-`Surface_mesh` triangle meshes.
*/ */
@@ -115,7 +115,7 @@ struct Circle_packing_result
/*! /*!
\ingroup PkgConformalMapRef \ingroup PkgConformalMapRef
Compute the BPS-2010 face-based circle-packing of `mesh`. Compute the BPS-2015 face-based circle-packing of `mesh`.
\tparam TriangleMesh A `CGAL::Surface_mesh<P>`. \tparam TriangleMesh A `CGAL::Surface_mesh<P>`.
\tparam NamedParameters Optional CGAL named-parameter pack. \tparam NamedParameters Optional CGAL named-parameter pack.
@@ -132,7 +132,7 @@ Compute the BPS-2010 face-based circle-packing of `mesh`.
\returns A `Circle_packing_result<FT>` with `ρ_f` per face. \returns A `Circle_packing_result<FT>` with `ρ_f` per face.
\pre `mesh` is a triangle mesh. \pre `mesh` is a triangle mesh.
\pre `φ_f` and `θ_e` satisfy the BPS-2010 admissibility conditions \pre `φ_f` and `θ_e` satisfy the BPS-2015 admissibility conditions
(Σ_f φ_f = 2π·χ + Σ_e (π − θ_e), see paper §6). (Σ_f φ_f = 2π·χ + Σ_e (π − θ_e), see paper §6).
*/ */
template <typename TriangleMesh, template <typename TriangleMesh,
@@ -201,7 +201,7 @@ auto discrete_circle_packing_euclidean(
// //
// For Phase 8b-Lite we deliberately don't fake it. If the caller // For Phase 8b-Lite we deliberately don't fake it. If the caller
// supplies `output_uv_map(pmap)` we throw `std::runtime_error` with a // supplies `output_uv_map(pmap)` we throw `std::runtime_error` with a
// clear pointer to Phase 9c (BPS-2010 §6 face-based circle-packing // clear pointer to Phase 9c (BPS-2015 §6 face-based circle-packing
// layout, ~150 lines, on the porting roadmap). Failing loudly is // layout, ~150 lines, on the porting roadmap). Failing loudly is
// better than silently writing zeros. // better than silently writing zeros.
// //

4
code/include/CGAL/Discrete_inversive_distance.h
View File

@@ -8,7 +8,7 @@
\ingroup PkgConformalMapRef \ingroup PkgConformalMapRef
User-facing entry for the **vertex-based** inversive-distance circle- User-facing entry for the **vertex-based** inversive-distance circle-
packing functional of Luo (2004), with the Bowers-Stephenson (2004) packing functional of Luo 2004, with the Bowers-Stephenson (2004)
initialisation. See `inversive_distance_functional.hpp` for the initialisation. See `inversive_distance_functional.hpp` for the
underlying algorithm and `doc/roadmap/research-track.md` (item 9a.2) underlying algorithm and `doc/roadmap/research-track.md` (item 9a.2)
for the research-track classification — this functional has **no Java for the research-track classification — this functional has **no Java
@@ -98,7 +98,7 @@ struct Default_inversive_distance_traits<CGAL::Surface_mesh<typename K::Point_3>
/*! /*!
\ingroup PkgConformalMapRef \ingroup PkgConformalMapRef
Compute the Luo-2004 vertex-based inversive-distance circle packing of `mesh`. Compute the Luo 2004 vertex-based inversive-distance circle packing of `mesh`.
The per-edge constant `I_ij` is computed once at the start from the input The per-edge constant `I_ij` is computed once at the start from the input
3-D geometry via the Bowers-Stephenson identity 3-D geometry via the Bowers-Stephenson identity

8
code/include/cp_euclidean_functional.hpp
View File

@@ -19,7 +19,7 @@
// │ The variable is ρ_f = log R_f. │ // │ The variable is ρ_f = log R_f. │
// │ Adjacent face-circles intersect at a prescribed angle θ_e per edge. │ // │ Adjacent face-circles intersect at a prescribed angle θ_e per edge. │
// │ │ // │ │
// │ This is the FACE-DUAL of the classical vertex-based Luo (2004) │ // │ This is the FACE-DUAL of the classical vertex-based Luo 2004 │
// │ inversive-distance circle packing implemented in │ // │ inversive-distance circle packing implemented in │
// │ inversive_distance_functional.hpp (Phase 9a.2). The relation │ // │ inversive_distance_functional.hpp (Phase 9a.2). The relation │
// │ I_ij = cos θ_e │ // │ I_ij = cos θ_e │
@@ -33,7 +33,7 @@
// │ θ_e per edge intersection angle of the two face-circles │ // │ θ_e per edge intersection angle of the two face-circles │
// │ φ_f per face target sum of corner-angles inside the face │ // │ φ_f per face target sum of corner-angles inside the face │
// │ │ // │ │
// │ Energy (BPS-2010 §6) │ // │ Energy (BPS-2015 §6) │
// │ E(ρ) = Σ_f φ_f · ρ_f │ // │ E(ρ) = Σ_f φ_f · ρ_f │
// │ + Σ_{(h,f=face(h)): │ // │ + Σ_{(h,f=face(h)): │
// │ [ if opposite face exists ] │ // │ [ if opposite face exists ] │
@@ -52,7 +52,7 @@
// │ Per interior hf: −(p + θ*) added to G[face(h)] │ // │ Per interior hf: −(p + θ*) added to G[face(h)] │
// │ Per boundary hf: −2 θ* added to G[face(h)] │ // │ Per boundary hf: −2 θ* added to G[face(h)] │
// │ │ // │ │
// │ Hessian (analytic, BPS-2010 eq. 6.8; Java getHessian lines 127-166) │ // │ Hessian (analytic, BPS-2015 eq. 6.8; Java getHessian lines 127-166) │
// │ Per interior undirected edge e (connecting faces j and k): │ // │ Per interior undirected edge e (connecting faces j and k): │
// │ h_jk = sin θ / (cosh Δρ − cos θ) │ // │ h_jk = sin θ / (cosh Δρ − cos θ) │
// │ H[j,j] += h_jk, H[k,k] += h_jk, H[j,k] −= h_jk, H[k,j] −= h_jk │ // │ H[j,j] += h_jk, H[k,k] += h_jk, H[j,k] −= h_jk, H[k,j] −= h_jk │
@@ -90,7 +90,7 @@ using CPEMapD = ConformalMesh::Property_map<Edge_index, double>;
// ── Persistent map bundle ───────────────────────────────────────────────────── // ── Persistent map bundle ─────────────────────────────────────────────────────
/// Bundle of the three property maps consumed by the CP-Euclidean /// Bundle of the three property maps consumed by the CP-Euclidean
/// (Bobenko-Pinkall-Springborn 2010) circle-packing functional. /// (Bobenko-Pinkall-Springborn 2015) circle-packing functional.
struct CPEuclideanMaps { struct CPEuclideanMaps {
CPFMapI f_idx; ///< DOF index per face (−1 = pinned) CPFMapI f_idx; ///< DOF index per face (−1 = pinned)
CPEMapD theta_e; ///< intersection angle per edge (default π/2 = orthogonal) CPEMapD theta_e; ///< intersection angle per edge (default π/2 = orthogonal)

4
code/include/newton_solver.hpp
View File

@@ -465,7 +465,7 @@ inline NewtonResult newton_hyper_ideal(
/// Solve the CP-Euclidean circle-packing problem: find ρ ∈ ℝ^F such that the /// Solve the CP-Euclidean circle-packing problem: find ρ ∈ ℝ^F such that the
/// per-face angle sums match φ_f at every free face. /// per-face angle sums match φ_f at every free face.
/// ///
/// The CP-Euclidean energy (Bobenko-Pinkall-Springborn 2010 §6) is strictly /// The CP-Euclidean energy (Bobenko-Pinkall-Springborn 2015 §6) is strictly
/// convex on its open domain of validity, so the Hessian H is PSD and the /// convex on its open domain of validity, so the Hessian H is PSD and the
/// solution is unique up to the gauge mode pinned by `f_idx == −1`. /// solution is unique up to the gauge mode pinned by `f_idx == −1`.
/// `cp_euclidean_hessian` provides the analytic 2×2-per-edge formula /// `cp_euclidean_hessian` provides the analytic 2×2-per-edge formula
@@ -483,7 +483,7 @@ inline NewtonResult newton_hyper_ideal(
/// \note Unlike the Euclidean solver, the CP-Euclidean Hessian is exact /// \note Unlike the Euclidean solver, the CP-Euclidean Hessian is exact
/// (analytic), so the SparseQR fallback only triggers in genuine /// (analytic), so the SparseQR fallback only triggers in genuine
/// gauge-singular situations (no pinned face). /// gauge-singular situations (no pinned face).
/// \see doc/architecture/phase-9a-validation.md §1 for the BPS-2010 mapping. /// \see doc/architecture/phase-9a-validation.md §1 for the BPS-2015 mapping.
inline NewtonResult newton_cp_euclidean( inline NewtonResult newton_cp_euclidean(
ConformalMesh& mesh, ConformalMesh& mesh,
std::vector<double> x0, std::vector<double> x0,

4
doc/math/references.md
View File

@@ -29,12 +29,14 @@ Java reference implementation: [github.com/varylab/conformallab](https://github.
| Reference | Used in | | Reference | Used in |
|---|---| |---|---|
| ✅ **Springborn** — *Ideal Hyperbolic Polyhedra and Discrete Uniformization*, Discrete & Computational Geometry **64** (2020), pp. 63–108. DOI: [10.1007/s00454-019-00132-8](https://doi.org/10.1007/s00454-019-00132-8) | `hyper_ideal_geometry.hpp` — ζ₁₃/ζ₁₄/ζ₁₅ functions; `hyper_ideal_functional.hpp` | | ✅ **Springborn** — *Ideal Hyperbolic Polyhedra and Discrete Uniformization*, Discrete & Computational Geometry **64** (2020), pp. 63–108. DOI: [10.1007/s00454-019-00132-8](https://doi.org/10.1007/s00454-019-00132-8) | `hyper_ideal_geometry.hpp` — ζ₁₃/ζ₁₄/ζ₁₅ functions; `hyper_ideal_functional.hpp` |
| ✅ **Kolpakov, Mednykh** — *A Formula for the Volume of a Hyperbolic Tetrahedron*, arXiv: [math/0603097](https://arxiv.org/abs/math/0603097) (2006) | Tetrahedron volume with one ideal vertex: `calculateTetrahedronVolumeWithIdealVertexAtGamma` in `hyper_ideal_utility.hpp` (Phase 9b analytic Hessian) |
| ✅ **Meyerhoff, Ushijima** — *A Note on the Dirichlet Domain*, in: The Epstein Birthday Schrift (2006) | Tetrahedron volume with three ideal vertices: `calculateTetrahedronVolumeFullyIdeal` in `hyper_ideal_utility.hpp` |
| **Pinkall, Polthier** — *Computing Discrete Minimal Surfaces and Their Conjugates*, Experimental Mathematics (1993) | `euclidean_hessian.hpp` — cotangent Laplacian | | **Pinkall, Polthier** — *Computing Discrete Minimal Surfaces and Their Conjugates*, Experimental Mathematics (1993) | `euclidean_hessian.hpp` — cotangent Laplacian |
| **Bobenko, Springborn** — *Variational Principles for Circle Patterns and Koebe's Theorem*, Transactions AMS (2004) | Variational angle-sum framework underlying all three functionals | | **Bobenko, Springborn** — *Variational Principles for Circle Patterns and Koebe's Theorem*, Transactions AMS (2004) | Variational angle-sum framework underlying all three functionals |
| **Luo** — *Combinatorial Yamabe Flow on Surfaces*, Communications in Contemporary Mathematics (2004) | Inversive-distance functional — **new research** in Phase 9a.2 (no Java original; implemented from this paper + Glickenstein 2011 + Bowers-Stephenson 2004) | | **Luo** — *Combinatorial Yamabe Flow on Surfaces*, Communications in Contemporary Mathematics (2004) | Inversive-distance functional — **new research** in Phase 9a.2 (no Java original; implemented from this paper + Glickenstein 2011 + Bowers-Stephenson 2004) |
| **Bowers, Stephenson** — *Uniformizing dessins and Belyĭ maps via circle packing*, Memoirs of the AMS 170(805) (2004) | Introduces **inversive-distance circle packings** (used in Phase 9a.2). *Hinweis:* die zur Initialisierung benutzte Formel I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j) ist die **klassische** inversive Distanz (vgl. Glickenstein §5.2: ℓ²=r_i²+r_j²+2r_ir_jη), nicht eine eigene „Bowers-Stephenson-Identität" — B–S liefern die Packungstheorie, nicht diese Formel. | | **Bowers, Stephenson** — *Uniformizing dessins and Belyĭ maps via circle packing*, Memoirs of the AMS 170(805) (2004) | Introduces **inversive-distance circle packings** (used in Phase 9a.2). *Hinweis:* die zur Initialisierung benutzte Formel I_ij = (ℓ²−r_i²−r_j²)/(2 r_i r_j) ist die **klassische** inversive Distanz (vgl. Glickenstein §5.2: ℓ²=r_i²+r_j²+2r_ir_jη), nicht eine eigene „Bowers-Stephenson-Identität" — B–S liefern die Packungstheorie, nicht diese Formel. |
| **Glickenstein** — *Discrete conformal variations and scalar curvature on piecewise flat two- and three-dimensional manifolds*, J. Differential Geometry **87**(2) (2011), pp. 201–238 | Analytic Hessian of the inversive-distance functional. ⚠️ *Korrektur:* die Arbeit nummeriert Gleichungen **nicht** im Format „(4.6)" — der Verweis ist durch die **§5.2**-Parametrisierung ℓ²_ij = r²_i + r²_j + 2 r_i r_j η_ij zu ersetzen. Cross-correspondence: η_ij ist die inversive Distanz und entspricht dem Kosinus des **Supplements** des Schnittwinkels (Schnitt bei arccos(−η_ij)) — also I_ij = cos θ_e **nur bis aufs Vorzeichen/Supplement**, nicht wörtlich. | | **Glickenstein** — *Discrete conformal variations and scalar curvature on piecewise flat two- and three-dimensional manifolds*, J. Differential Geometry **87**(2) (2011), pp. 201–238 | Analytic Hessian of the inversive-distance functional. ⚠️ *Korrektur:* die Arbeit nummeriert Gleichungen **nicht** im Format „(4.6)" — der Verweis ist durch die **§5.2**-Parametrisierung ℓ²_ij = r²_i + r²_j + 2 r_i r_j η_ij zu ersetzen. Cross-correspondence: η_ij ist die inversive Distanz und entspricht dem Kosinus des **Supplements** des Schnittwinkels (Schnitt bei arccos(−η_ij)) — also I_ij = cos θ_e **nur bis aufs Vorzeichen/Supplement**, nicht wörtlich. |
| **Bobenko, Pinkall, Springborn** — *Discrete conformal maps and ideal hyperbolic polyhedra*, Geometry & Topology **19**(4) (2015), pp. 2155–2215. arXiv: [1005.2698](https://arxiv.org/abs/1005.2698) | Face-based circle-packing functional (`CPEuclideanFunctional.java` → `cp_euclidean_functional.hpp`, Phase 9a.1) | | ✅ **Bobenko, Pinkall, Springborn** — *Discrete conformal maps and ideal hyperbolic polyhedra*, Geometry & Topology **19**(4) (2015), pp. 2155–2215. arXiv: [1005.2698](https://arxiv.org/abs/1005.2698) (first posted 2010) | Face-based circle-packing functional (`CPEuclideanFunctional.java` → `cp_euclidean_functional.hpp`, Phase 9a.1) |
| **Schläfli** — *On the multiple integral ∫dx dy …*, Quarterly Journal of Pure and Applied Mathematics (1858/60) | Klassische Schläfli-Differentialformel (dV = −½ Σ_e ℓ_e dθ_e). ⚠️ *Hinweis:* die in Phase 9b-analytic benutzte **Randterm-Form** `2 dV = Σ_e aₑ dαₑ + Σ_v bᵥ dβᵥ` steht **nicht** bei Schläfli 1858, sondern ist die verallgemeinerte Fassung für Mannigfaltigkeiten mit Rand → korrekter Beleg: **Rivin–Schlenker 1999** (Phase-10-Liste). Schläfli 1858 nur als historischer Ursprung zitieren. | | **Schläfli** — *On the multiple integral ∫dx dy …*, Quarterly Journal of Pure and Applied Mathematics (1858/60) | Klassische Schläfli-Differentialformel (dV = −½ Σ_e ℓ_e dθ_e). ⚠️ *Hinweis:* die in Phase 9b-analytic benutzte **Randterm-Form** `2 dV = Σ_e aₑ dαₑ + Σ_v bᵥ dβᵥ` steht **nicht** bei Schläfli 1858, sondern ist die verallgemeinerte Fassung für Mannigfaltigkeiten mit Rand → korrekter Beleg: **Rivin–Schlenker 1999** (Phase-10-Liste). Schläfli 1858 nur als historischer Ursprung zitieren. |
| **Erickson, Whittlesey** — *Greedy Optimal Homotopy and Homology Generators*, SODA (2005) | `cut_graph.hpp` — tree-cotree algorithm | | **Erickson, Whittlesey** — *Greedy Optimal Homotopy and Homology Generators*, SODA (2005) | `cut_graph.hpp` — tree-cotree algorithm |
| **Bobenko, Springborn** — *A Discrete Laplace–Beltrami Operator for Simplicial Surfaces*, Discrete & Computational Geometry (2007) | Background for cotangent weights | | **Bobenko, Springborn** — *A Discrete Laplace–Beltrami Operator for Simplicial Surfaces*, Discrete & Computational Geometry (2007) | Background for cotangent weights |