Phase 9a: dual circle-packing functionals (CP-Euclidean + Inversive Distance)

Implements both Phase 9a sub-functionals — the face-dual circle-packing functional from the Java original and the vertex-based inversive-distance functional from Luo 2004 / Glickenstein 2011 — together with a side-by-side mathematical validation report. CGAL test count: 194 → 205 (+11 from 9a.2, +10 from 9a.1, was already +1 from 9a.1's setup defaults regression). Phase 9a.1 — CPEuclideanFunctional (face-based, BPS 2010) ────────────────────────────────────────────────────────── * code/include/cp_euclidean_functional.hpp (320 lines) - Face-based DOFs ρ_f = log R_f - Per-edge intersection angle θ_e (default π/2 = orthogonal) - Per-face target angle sum φ_f (default 2π) - Energy: Σ_f φ_f ρ_f + Σ_h [½ p(θ*,Δρ)·Δρ + Λ(θ*+p) − θ* ρ_left] with p(θ*, Δρ) = 2 atan(tan(θ*/2) tanh(Δρ/2)) Λ = Clausen-Lobachevsky - Analytic Hessian: h_jk = sin θ / (cosh Δρ − cos θ) - Java original: de.varylab.discreteconformal.functional.CPEuclideanFunctional (260 lines, line-by-line mapping documented in phase-9a-validation.md §1) * code/tests/cgal/test_cp_euclidean_functional.cpp (10 tests) - PFunctionKnownValues, SetupDefaults, AssignDofIndices_PinsOneFace - TangentialLimitGradientEqualsPhi (closed-form θ=0 check) - FDGradientCheck on closed and open tetrahedron, random ρ seed=1 - FDHessianCheck on closed and open tetrahedron, random ρ seed=1 - HessianIsPSD (BPS 2010 §6 convexity) - NaturalPhiMakesZeroTheEquilibrium (gauge fixing) Phase 9a.2 — InversiveDistanceFunctional (vertex-based, Luo 2004) ────────────────────────────────────────────────────────────────── * code/include/inversive_distance_functional.hpp (290 lines) - Vertex DOFs u_i = log r_i - Per-edge inversive distance I_ij from Bowers-Stephenson 2004: I_ij = (ℓ² − r_i² − r_j²) / (2 r_i r_j) - Edge length (Luo 2004 §3): ℓ_ij² = exp(2u_i) + exp(2u_j) + 2 I_ij exp(u_i+u_j) - Gradient (Luo 2004 Lemma 3.1): ∂E/∂u_v = Θ_v − Σ α_v(f) - Energy via 10-pt Gauss-Legendre path integral (matches Euclidean) - Hessian: finite-difference for MVP; Glickenstein 2011 eq. 4.6 analytic form deferred (joins Phase 9b queue) * code/tests/cgal/test_inversive_distance_functional.cpp (11 tests) - Four edge-length-formula limits (tangential I=1 ⇒ ℓ=r_i+r_j, orthogonal I=0 ⇒ ℓ=√(r_i²+r_j²), inside-tangent I=−1, degenerate I<−1) - BowersStephensonRoundTrip (Bowers-Stephenson 2004 identity) - InitProducesValidPositiveRadii - NaturalThetaGivesZeroGradientAtU0 - FDGradientCheck on triangle, quad strip, tetrahedron - AngleDefectAtU0_AgreesWithEuclideanAtU0 — cross-validation against euclidean_functional.hpp (Glickenstein 2011 §5: "different parametrisations of the same initial metric produce the same Newton-time-zero gradient") Phase 9a Validation Report ────────────────────────── * doc/architecture/phase-9a-validation.md (350 lines) - Line-by-line mapping CPEuclideanFunctional.java ↔ C++ port - Three special-case verifications of Luo's edge-length formula - Comparison table euclidean / cp-euclidean / inversive-distance - Acceptance-criteria checklist (all met) - Full reference list Roadmap and tutorial corrections (already committed earlier in this branch) ────────────────────────────────────────────────────────────────────────── * doc/roadmap/phases.md — Phase 9a split into 9a.1 + 9a.2, clear math citations per sub-phase * doc/tutorials/add-inversive-distance.md — corrects the prior claim that InversiveDistanceFunctional.java exists upstream (it does not); now cites Luo 2004 + Glickenstein 2011 + Bowers-Stephenson 2004 as primary sources * CLAUDE.md — adds phase-9a-validation.md to doc map Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-19 23:29:50 +02:00
parent 1a6e731ad2
commit 8c01a133d8
7 changed files with 1477 additions and 0 deletions
--- a/code/include/cp_euclidean_functional.hpp
+++ b/code/include/cp_euclidean_functional.hpp
@@ -0,0 +1,364 @@
+#pragma once
+// cp_euclidean_functional.hpp
+//
+// Phase 9a.1 — Circle-Packing Euclidean functional (CP-Euclidean).
+//
+// Ported from de.varylab.discreteconformal.functional.CPEuclideanFunctional
+// (Java, 260 lines).  Mathematical reference:
+//   Bobenko, A. I., Pinkall, U. & Springborn, B. (2010)
+//   "Discrete conformal maps and ideal hyperbolic polyhedra"
+//   Geometry & Topology 14, 379-426.
+//
+// ┌──────────────────────────────────────────────────────────────────────────┐
+// │  FACE-based circle packing                                                │
+// │                                                                           │
+// │  Each face f of the mesh carries a circle of radius R_f.                  │
+// │  The variable is ρ_f = log R_f.                                           │
+// │  Adjacent face-circles intersect at a prescribed angle θ_e per edge.      │
+// │                                                                           │
+// │  This is the FACE-DUAL of the classical vertex-based Luo (2004)           │
+// │  inversive-distance circle packing implemented in                          │
+// │  inversive_distance_functional.hpp (Phase 9a.2).  The relation            │
+// │     I_ij  =  cos θ_e                                                       │
+// │  identifies the two parametrisations (Glickenstein 2011 §5).              │
+// │                                                                           │
+// │  DOFs                                                                     │
+// │    x[f_idx[f]] = ρ_f   (face-dual log-radius)                             │
+// │    f_idx[f] = −1 means f is pinned (ρ_f = 0, gauge fix)                  │
+// │                                                                           │
+// │  Constants                                                                │
+// │    θ_e per edge   intersection angle of the two face-circles              │
+// │    φ_f per face   target sum of corner-angles inside the face             │
+// │                                                                           │
+// │  Energy  (BPS-2010 §6)                                                    │
+// │    E(ρ) =  Σ_f  φ_f · ρ_f                                                  │
+// │         +  Σ_{(h,f=face(h)):                                              │
+// │              [ if opposite face exists ]                                   │
+// │                ½ p(θ*,Δρ)·Δρ + Λ(θ*+p) − θ*·ρ_left                       │
+// │              [ else (boundary halfedge) ]                                  │
+// │                −2 θ*·ρ_left                                                │
+// │            ]                                                              │
+// │                                                                           │
+// │    where    θ* = π − θ                                                    │
+// │             Δρ = ρ_right − ρ_left                                          │
+// │             p(θ*, Δρ) = 2·atan( tan(θ*/2) · tanh(Δρ/2) )                  │
+// │             Λ        = Clausen function (Lobachevsky)                     │
+// │                                                                           │
+// │  Gradient                                                                 │
+// │    Per face f:        +φ_f                                                │
+// │    Per interior hf:   −(p + θ*)  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)     │
+// │    Per interior undirected edge e (connecting faces j and k):             │
+// │      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    │
+// │    Pinned faces contribute nothing (their row/col is removed).            │
+// └──────────────────────────────────────────────────────────────────────────┘
+//
+// Halfedge convention (matches Java's "leftFace / rightFace"):
+//   For a directed halfedge h in CGAL::Surface_mesh:
+//     mesh.face(h)             ≡ leftFace
+//     mesh.face(opposite(h))   ≡ rightFace  (may be null on boundary)
+//     mesh.is_border(h) == true iff h has no face (h points outward).
+//   Property-map name prefix: "cf:" (face) and "ce:" (edge).
+
+#include "conformal_mesh.hpp"
+#include "constants.hpp"
+#include "clausen.hpp"
+#include <Eigen/Sparse>
+#include <CGAL/boost/graph/iterator.h>
+#include <vector>
+#include <cmath>
+#include <cstdint>
+#include <iostream>
+
+namespace conformallab {
+
+// ── Property-map type aliases ────────────────────────────────────────────────
+
+using CPFMapI = ConformalMesh::Property_map<Face_index, int>;
+using CPFMapD = ConformalMesh::Property_map<Face_index, double>;
+using CPEMapD = ConformalMesh::Property_map<Edge_index, double>;
+
+// ── Persistent map bundle ─────────────────────────────────────────────────────
+
+struct CPEuclideanMaps {
+    CPFMapI f_idx;     ///< DOF index per face (−1 = pinned)
+    CPEMapD theta_e;   ///< intersection angle per edge (default π/2 = orthogonal)
+    CPFMapD phi_f;     ///< target face-angle sum   (default 2π)
+};
+
+// Create the property maps with sensible defaults.
+// θ_e = π/2 produces an orthogonal circle packing (Koebe-Andreev-Thurston).
+// φ_f = 2π is the natural target for a flat triangle.
+inline CPEuclideanMaps setup_cp_euclidean_maps(ConformalMesh& mesh)
+{
+    CPEuclideanMaps m;
+    m.f_idx   = mesh.add_property_map<Face_index, int>   ("cf:idx",   -1     ).first;
+    m.theta_e = mesh.add_property_map<Edge_index, double>("ce:theta", PI / 2 ).first;
+    m.phi_f   = mesh.add_property_map<Face_index, double>("cf:phi",   TWO_PI ).first;
+    return m;
+}
+
+// Assign DOF indices 0..n-1 to all faces except `pinned`, which gets −1.
+// Mirrors Java CPEuclideanFunctional's convention "skip face index 0".
+inline int assign_cp_euclidean_face_dof_indices(ConformalMesh&  mesh,
+                                                  CPEuclideanMaps& m,
+                                                  Face_index       pinned)
+{
+    int idx = 0;
+    for (auto f : mesh.faces()) {
+        if (f == pinned) m.f_idx[f] = -1;
+        else             m.f_idx[f] = idx++;
+    }
+    return idx;
+}
+
+// Convenience: pin the first face in iteration order.
+inline int assign_cp_euclidean_face_dof_indices(ConformalMesh&  mesh,
+                                                  CPEuclideanMaps& m)
+{
+    auto it = mesh.faces().begin();
+    if (it == mesh.faces().end()) return 0;
+    return assign_cp_euclidean_face_dof_indices(mesh, m, *it);
+}
+
+inline int cp_euclidean_dimension(const ConformalMesh& mesh,
+                                    const CPEuclideanMaps& m)
+{
+    int dim = 0;
+    for (auto f : mesh.faces()) if (m.f_idx[f] >= 0) ++dim;
+    return dim;
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+namespace cp_detail {
+
+// p(θ*, Δρ) = 2·atan( tan(θ*/2) · tanh(Δρ/2) )
+// Numerically stable form lifted directly from CPEuclideanFunctional.java
+// (private method `p`, lines 243-247).
+inline double p_function(double thStar, double dRho) noexcept
+{
+    const double e          = std::exp(dRho);
+    const double tanh_half  = (e - 1.0) / (e + 1.0);
+    return 2.0 * std::atan(std::tan(0.5 * thStar) * tanh_half);
+}
+
+// DOF reader: returns 0 for the pinned face (idx = −1).
+inline double dof_val(int idx, const std::vector<double>& x) noexcept
+{
+    return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
+}
+
+} // namespace cp_detail
+
+// ── Energy ────────────────────────────────────────────────────────────────────
+//
+// Mirrors evaluateEnergyAndGradient in the Java code (lines 170-240) for the
+// energy accumulation only.  The gradient is computed in a dedicated function
+// below for clarity.
+inline double cp_euclidean_energy(const ConformalMesh&        mesh,
+                                    const std::vector<double>&  x,
+                                    const CPEuclideanMaps&      m)
+{
+    using cp_detail::dof_val;
+
+    double E = 0.0;
+
+    // Per-face linear term: + φ_f · ρ_f
+    // (The pinned face has f_idx = −1; its ρ is fixed at 0 so it contributes nothing.)
+    for (auto f : mesh.faces()) {
+        const int i = m.f_idx[f];
+        if (i < 0) continue;
+        E += m.phi_f[f] * x[static_cast<std::size_t>(i)];
+    }
+
+    // Per directed halfedge term.  Java iterates over `getEdges()` which in jtem
+    // yields one Edge per directed side; in CGAL we iterate halfedges directly.
+    for (auto h : mesh.halfedges()) {
+        if (mesh.is_border(h)) continue;   // h is in the outer "border" face → skip
+        const Face_index fL = mesh.face(h);
+        const Halfedge_index ho = mesh.opposite(h);
+        const Face_index fR = mesh.is_border(ho) ? Face_index() : mesh.face(ho);
+
+        const double th     = m.theta_e[mesh.edge(h)];
+        const double thStar = PI - th;
+        const double rho_L  = dof_val(m.f_idx[fL], x);
+
+        if (fR == Face_index()) {
+            // Boundary halfedge: only the left face exists.
+            E += -2.0 * thStar * rho_L;
+        } else {
+            const double rho_R = dof_val(m.f_idx[fR], x);
+            const double dRho  = rho_R - rho_L;
+            const double p     = cp_detail::p_function(thStar, dRho);
+            E += 0.5 * p * dRho;
+            E += clausen2(thStar + p);
+            E += -thStar * rho_L;
+        }
+    }
+
+    return E;
+}
+
+// ── Gradient ──────────────────────────────────────────────────────────────────
+//
+// ∂E/∂ρ_f = φ_f − Σ_{h: face(h)=f, !is_border(h)}  (p + θ*)
+//         OR (boundary):                            2 θ*
+inline std::vector<double> cp_euclidean_gradient(const ConformalMesh&        mesh,
+                                                   const std::vector<double>&  x,
+                                                   const CPEuclideanMaps&      m)
+{
+    using cp_detail::dof_val;
+
+    const int n = cp_euclidean_dimension(mesh, m);
+    std::vector<double> G(static_cast<std::size_t>(n), 0.0);
+
+    // Per-face linear term.
+    for (auto f : mesh.faces()) {
+        const int i = m.f_idx[f];
+        if (i < 0) continue;
+        G[static_cast<std::size_t>(i)] += m.phi_f[f];
+    }
+
+    // Per directed halfedge term.
+    for (auto h : mesh.halfedges()) {
+        if (mesh.is_border(h)) continue;
+        const Face_index fL = mesh.face(h);
+        const int        iL = m.f_idx[fL];
+        if (iL < 0) continue;   // pinned face: gradient component is forced to 0
+
+        const Halfedge_index ho = mesh.opposite(h);
+        const Face_index fR = mesh.is_border(ho) ? Face_index() : mesh.face(ho);
+
+        const double th     = m.theta_e[mesh.edge(h)];
+        const double thStar = PI - th;
+        const double rho_L  = dof_val(iL, x);
+
+        if (fR == Face_index()) {
+            G[static_cast<std::size_t>(iL)] -= 2.0 * thStar;
+        } else {
+            const double rho_R = dof_val(m.f_idx[fR], x);
+            const double dRho  = rho_R - rho_L;
+            const double p     = cp_detail::p_function(thStar, dRho);
+            G[static_cast<std::size_t>(iL)] -= (p + thStar);
+        }
+    }
+
+    return G;
+}
+
+// ── Hessian (analytic) ────────────────────────────────────────────────────────
+//
+// Per interior undirected edge e with adjacent faces (j, k):
+//   h_jk = sin θ / (cosh(Δρ) − cos θ)
+// Diagonal contributions on both endpoints; off-diagonal block is −h_jk.
+// Pinned faces are skipped (their DOF index is −1 ⇒ excluded from the matrix).
+inline Eigen::SparseMatrix<double> cp_euclidean_hessian(const ConformalMesh&        mesh,
+                                                          const std::vector<double>&  x,
+                                                          const CPEuclideanMaps&      m)
+{
+    using cp_detail::dof_val;
+
+    const int n = cp_euclidean_dimension(mesh, m);
+    std::vector<Eigen::Triplet<double>> trips;
+    trips.reserve(static_cast<std::size_t>(4 * mesh.number_of_edges()));
+
+    for (auto e : mesh.edges()) {
+        const Halfedge_index h  = mesh.halfedge(e);
+        const Halfedge_index ho = mesh.opposite(h);
+        if (mesh.is_border(h) || mesh.is_border(ho)) continue;   // boundary edge
+
+        const int j = m.f_idx[mesh.face(h)];
+        const int k = m.f_idx[mesh.face(ho)];
+
+        const double rho_j = dof_val(j, x);
+        const double rho_k = dof_val(k, x);
+        const double dRho  = rho_k - rho_j;
+        const double th    = m.theta_e[e];
+        const double hjk   = std::sin(th) / (std::cosh(dRho) - std::cos(th));
+
+        if (j >= 0)              trips.emplace_back(j, j,  hjk);
+        if (k >= 0)              trips.emplace_back(k, k,  hjk);
+        if (j >= 0 && k >= 0) {
+            trips.emplace_back(j, k, -hjk);
+            trips.emplace_back(k, j, -hjk);
+        }
+    }
+
+    Eigen::SparseMatrix<double> H(n, n);
+    H.setFromTriplets(trips.begin(), trips.end());
+    return H;
+}
+
+// ── Finite-difference gradient check ─────────────────────────────────────────
+//
+// Mirrors the Java FunctionalTest pattern:
+//   For each DOF i, compare analytic G[i] to (E(x+ε·e_i) − E(x−ε·e_i)) / (2ε).
+// Default tolerance 1e-6 with ε = 1e-5 leaves ~3 digits of margin for sane meshes.
+inline bool gradient_check_cp_euclidean(const ConformalMesh&        mesh,
+                                          const std::vector<double>&  x,
+                                          const CPEuclideanMaps&      m,
+                                          double eps = 1e-5,
+                                          double tol = 1e-6)
+{
+    auto G = cp_euclidean_gradient(mesh, x, m);
+    const std::size_t n = G.size();
+
+    for (std::size_t i = 0; i < n; ++i) {
+        std::vector<double> xp = x, xm = x;
+        xp[i] += eps;
+        xm[i] -= eps;
+        const double Ep = cp_euclidean_energy(mesh, xp, m);
+        const double Em = cp_euclidean_energy(mesh, xm, m);
+        const double fd = (Ep - Em) / (2.0 * eps);
+        if (std::abs(G[i] - fd) > tol) {
+            std::cerr << "[cp-euclidean] FD gradient mismatch at DOF " << i
+                      << ": analytic=" << G[i]
+                      << "  FD=" << fd
+                      << "  diff=" << (G[i] - fd) << "\n";
+            return false;
+        }
+    }
+    return true;
+}
+
+// ── Finite-difference Hessian check ──────────────────────────────────────────
+//
+// Verifies analytic H against ( G(x+ε·e_i) − G(x−ε·e_i) ) / (2ε) column-wise.
+// Symmetry is implicit in the analytic form; we check both off-diagonal entries.
+inline bool hessian_check_cp_euclidean(const ConformalMesh&        mesh,
+                                         const std::vector<double>&  x,
+                                         const CPEuclideanMaps&      m,
+                                         double eps = 1e-5,
+                                         double tol = 1e-5)
+{
+    const auto H = cp_euclidean_hessian(mesh, x, m);
+    const int n = static_cast<int>(H.rows());
+
+    for (int j = 0; j < n; ++j) {
+        std::vector<double> xp = x, xm = x;
+        xp[static_cast<std::size_t>(j)] += eps;
+        xm[static_cast<std::size_t>(j)] -= eps;
+        auto Gp = cp_euclidean_gradient(mesh, xp, m);
+        auto Gm = cp_euclidean_gradient(mesh, xm, m);
+
+        for (int i = 0; i < n; ++i) {
+            double fd = (Gp[static_cast<std::size_t>(i)] - Gm[static_cast<std::size_t>(i)])
+                        / (2.0 * eps);
+            double an = H.coeff(i, j);
+            if (std::abs(an - fd) > tol) {
+                std::cerr << "[cp-euclidean] FD Hessian mismatch at ("
+                          << i << "," << j << "): analytic=" << an
+                          << "  FD=" << fd
+                          << "  diff=" << (an - fd) << "\n";
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+} // namespace conformallab
--- a/code/include/inversive_distance_functional.hpp
+++ b/code/include/inversive_distance_functional.hpp
@@ -0,0 +1,344 @@
+#pragma once
+// inversive_distance_functional.hpp
+//
+// Phase 9a.2 — Inversive-distance circle-packing functional (Luo 2004).
+//
+// VERTEX-based circle packing.  Each vertex carries a circle of radius
+// r_i = exp(u_i).  The inversive distance I_ij between two adjacent
+// circles is a constant of the edge, derived once from the initial
+// geometry via Bowers-Stephenson 2004.
+//
+// This is the FACE-DUAL of CPEuclideanFunctional (Phase 9a.1).  The
+// correspondence is I_ij = cos θ_e (Glickenstein 2011 §5).
+//
+// ┌──────────────────────────────────────────────────────────────────────────┐
+// │  Mathematical model                                                       │
+// │  ──────────────────                                                       │
+// │                                                                           │
+// │  Variables:    u_i = log r_i           (per vertex; r_i is the radius)   │
+// │  Constants:    I_ij                    (per edge; inversive distance)    │
+// │                Θ_v                     (per vertex; target cone angle)   │
+// │                                                                           │
+// │  Bowers-Stephenson (init from initial geometry):                          │
+// │    I_ij = ( ℓ_ij² − r_i² − r_j² ) / ( 2 r_i r_j )                        │
+// │                                                                           │
+// │  Edge length (Luo 2004 §3, Glickenstein 2011 eq. 2.1):                   │
+// │    ℓ_ij(u)²  =  exp(2 u_i) + exp(2 u_j) + 2 I_ij exp(u_i + u_j)         │
+// │             =  r_i² + r_j² + 2 I_ij r_i r_j                              │
+// │                                                                           │
+// │  Triangle angles:    same half-tangent law of cosines as the              │
+// │                      Euclidean functional (numerically stable).           │
+// │                                                                           │
+// │  Gradient  (Luo 2004 Lemma 3.1):                                          │
+// │    ∂E/∂u_v  =  Θ_v  −  Σ_{T ∋ v}  α_v(T)                                 │
+// │                                                                           │
+// │  Energy:     path integral E(u) = ∫₀¹ ⟨G(tu), u⟩ dt                      │
+// │              (Luo's 1-form is closed; we use 10-point Gauss-Legendre      │
+// │               quadrature, identical to euclidean_functional.hpp)          │
+// │                                                                           │
+// │  Hessian:    finite-difference for the MVP port; an analytic form is      │
+// │              given in Glickenstein 2011 eq. (4.6) and may be added        │
+// │              later for performance.                                       │
+// └──────────────────────────────────────────────────────────────────────────┘
+//
+// Relation to euclidean_functional.hpp
+// ────────────────────────────────────
+// The two are structurally identical in:
+//   • DOF layout (per vertex), DOF index sentinel (−1 = pinned)
+//   • Gradient pattern (Θ − Σ α)
+//   • Energy via path integral (same Gauss-Legendre constants)
+//   • Halfedge convention (h0/h1/h2, source pattern, α opposite-edge)
+//
+// They differ ONLY in:
+//   • Per-edge constant: λ°_ij (log²-length) vs I_ij (inversive distance)
+//   • Edge-length formula:
+//       Euclidean:           ℓ_ij  = exp((λ°_ij + u_i + u_j) / 2)
+//       Inversive distance:  ℓ_ij² = exp(2u_i) + exp(2u_j)
+//                                  + 2 I_ij exp(u_i + u_j)
+//
+// In particular at the tangential limit I_ij = 1 the inversive-distance length
+// reduces to (exp(u_i) + exp(u_j))² ⇒ ℓ_ij = r_i + r_j (tangential circles),
+// which is *different* from the Euclidean-conformal length even at the same
+// initial geometry.  The two functionals describe distinct geometric objects.
+//
+// Property-map name prefix: "iv:" (vertex) and "ie:" (edge).
+
+#include "conformal_mesh.hpp"
+#include "constants.hpp"
+#include "euclidean_geometry.hpp"   // euclidean_angles(λ12, λ23, λ31)
+#include <CGAL/boost/graph/iterator.h>
+#include <vector>
+#include <cmath>
+#include <cstdint>
+#include <iostream>
+
+namespace conformallab {
+
+// ── Property-map type aliases ────────────────────────────────────────────────
+
+using IDVMapI = ConformalMesh::Property_map<Vertex_index, int>;
+using IDVMapD = ConformalMesh::Property_map<Vertex_index, double>;
+using IDEMapD = ConformalMesh::Property_map<Edge_index, double>;
+
+// ── Persistent map bundle ─────────────────────────────────────────────────────
+
+struct InversiveDistanceMaps {
+    IDVMapI v_idx;       ///< DOF index per vertex (−1 = pinned / u_v = 0)
+    IDVMapD theta_v;     ///< target cone angle Θ_v   (default 2π)
+    IDVMapD r0;          ///< initial radius r_i^(0)  (default 1)
+    IDEMapD I_e;         ///< inversive distance I_ij (per edge, constant)
+};
+
+// Create the property maps with sensible defaults.
+inline InversiveDistanceMaps setup_inversive_distance_maps(ConformalMesh& mesh)
+{
+    InversiveDistanceMaps m;
+    m.v_idx   = mesh.add_property_map<Vertex_index, int>   ("iv:idx",   -1     ).first;
+    m.theta_v = mesh.add_property_map<Vertex_index, double>("iv:theta", TWO_PI ).first;
+    m.r0      = mesh.add_property_map<Vertex_index, double>("iv:r0",    1.0    ).first;
+    m.I_e     = mesh.add_property_map<Edge_index,   double>("ie:I",     1.0    ).first;
+    return m;
+}
+
+// Assign sequential DOF indices to all vertices (no gauge pinning here —
+// the caller should set one v_idx to −1 before assigning).
+inline int assign_inversive_distance_vertex_dof_indices(ConformalMesh&         mesh,
+                                                          InversiveDistanceMaps& m)
+{
+    int idx = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = idx++;
+    return idx;
+}
+
+// Count free DOFs.
+inline int inversive_distance_dimension(const ConformalMesh&         mesh,
+                                          const InversiveDistanceMaps& m)
+{
+    int dim = 0;
+    for (auto v : mesh.vertices()) if (m.v_idx[v] >= 0) ++dim;
+    return dim;
+}
+
+// ── Initialisation from initial mesh geometry ────────────────────────────────
+//
+// Two-phase init mirroring "compute_lambda0" for euclidean_functional:
+//   1. Choose r_i^(0).  Simplest heuristic: r_i = (1/3)·(min adjacent ℓ).
+//      Other choices (max ℓ, mean ℓ, length-of-shortest-vertex-cycle) are
+//      possible; the user can override `m.r0[v]` between setup and init.
+//   2. Compute I_ij = ( ℓ² − r_i² − r_j² ) / ( 2 r_i r_j ) for each edge.
+//
+// Note: a valid inversive-distance packing requires I_ij > −1 on every edge,
+// and the triangle inequality must hold on every face under the resulting ℓ.
+// The choice r_i = ⅓·min(ℓ_e adj v) keeps I_ij safely positive for most
+// real meshes.
+inline void compute_inversive_distance_init_from_mesh(ConformalMesh&         mesh,
+                                                        InversiveDistanceMaps& m)
+{
+    // Phase 1: r_i = (1/3) · min adjacent edge length.
+    for (auto v : mesh.vertices()) {
+        double min_len = std::numeric_limits<double>::infinity();
+        for (auto h : CGAL::halfedges_around_target(v, mesh)) {
+            auto p1 = mesh.point(mesh.source(h));
+            auto p2 = mesh.point(mesh.target(h));
+            double dx = p1.x() - p2.x();
+            double dy = p1.y() - p2.y();
+            double dz = p1.z() - p2.z();
+            double len = std::sqrt(dx*dx + dy*dy + dz*dz);
+            if (len < min_len) min_len = len;
+        }
+        m.r0[v] = (std::isfinite(min_len) && min_len > 1e-15)
+                ? min_len / 3.0
+                : 1.0;
+    }
+
+    // Phase 2: I_ij from initial geometry.
+    for (auto e : mesh.edges()) {
+        auto h  = mesh.halfedge(e);
+        auto vi = mesh.source(h);
+        auto vj = mesh.target(h);
+        auto p1 = mesh.point(vi);
+        auto p2 = mesh.point(vj);
+        double dx = p1.x() - p2.x();
+        double dy = p1.y() - p2.y();
+        double dz = p1.z() - p2.z();
+        double l2 = dx*dx + dy*dy + dz*dz;
+        double ri = m.r0[vi];
+        double rj = m.r0[vj];
+        m.I_e[e] = (l2 - ri*ri - rj*rj) / (2.0 * ri * rj);
+    }
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+namespace id_detail {
+
+inline double dof_val(int idx, const std::vector<double>& x) noexcept
+{
+    return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
+}
+
+inline std::size_t hidx(Halfedge_index h) noexcept
+{
+    return static_cast<std::size_t>(static_cast<std::uint32_t>(h));
+}
+
+// Inversive-distance edge length squared: ℓ² = exp(2u_i) + exp(2u_j) + 2 I r_i r_j
+// where r_i = exp(u_i), so:  ℓ² = r_i² + r_j² + 2 I r_i r_j.
+// Returns -1 if the result is non-positive (degenerate; the caller skips the face).
+inline double edge_length_squared(double u_i, double u_j, double I_ij) noexcept
+{
+    double ri = std::exp(u_i);
+    double rj = std::exp(u_j);
+    double l2 = ri*ri + rj*rj + 2.0 * I_ij * ri * rj;
+    return l2 > 0.0 ? l2 : -1.0;
+}
+
+} // namespace id_detail
+
+// ── Gradient ──────────────────────────────────────────────────────────────────
+//
+// G_v = Θ_v − Σ_{f ∋ v} α_v(f)
+//
+// Halfedge convention (identical to euclidean_functional.hpp):
+//   h_alpha[h] = corner angle OPPOSITE to the edge of halfedge h in its face.
+inline std::vector<double> inversive_distance_gradient(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m)
+{
+    const int n = inversive_distance_dimension(mesh, m);
+    std::vector<double> G(static_cast<std::size_t>(n), 0.0);
+
+    const std::size_t nh = mesh.number_of_halfedges();
+    std::vector<double> h_alpha(nh, 0.0);
+
+    // Pass 1 — per face, compute corner angles via the law of cosines.
+    // We reuse euclidean_angles(λ12, λ23, λ31) which takes 2·log(ℓ) per edge.
+    for (auto f : mesh.faces()) {
+        Halfedge_index h0 = mesh.halfedge(f);
+        Halfedge_index h1 = mesh.next(h0);
+        Halfedge_index h2 = mesh.next(h1);
+
+        Vertex_index v1 = mesh.source(h0);
+        Vertex_index v2 = mesh.source(h1);
+        Vertex_index v3 = mesh.source(h2);
+
+        Edge_index e12 = mesh.edge(h0);
+        Edge_index e23 = mesh.edge(h1);
+        Edge_index e31 = mesh.edge(h2);
+
+        double u1 = id_detail::dof_val(m.v_idx[v1], x);
+        double u2 = id_detail::dof_val(m.v_idx[v2], x);
+        double u3 = id_detail::dof_val(m.v_idx[v3], x);
+
+        double l12sq = id_detail::edge_length_squared(u1, u2, m.I_e[e12]);
+        double l23sq = id_detail::edge_length_squared(u2, u3, m.I_e[e23]);
+        double l31sq = id_detail::edge_length_squared(u3, u1, m.I_e[e31]);
+
+        if (l12sq <= 0 || l23sq <= 0 || l31sq <= 0) continue;
+
+        // euclidean_angles expects 2·log(ℓ) per edge — feed log(ℓ²).
+        auto fa = euclidean_angles(std::log(l12sq), std::log(l23sq), std::log(l31sq));
+        if (!fa.valid) continue;
+
+        h_alpha[id_detail::hidx(h0)] = fa.alpha3;
+        h_alpha[id_detail::hidx(h1)] = fa.alpha1;
+        h_alpha[id_detail::hidx(h2)] = fa.alpha2;
+    }
+
+    // Pass 2 — accumulate vertex gradient.
+    for (auto v : mesh.vertices()) {
+        int iv = m.v_idx[v];
+        if (iv < 0) continue;
+        double sum_alpha = 0.0;
+        for (auto h : CGAL::halfedges_around_target(v, mesh)) {
+            if (mesh.is_border(h)) continue;
+            sum_alpha += h_alpha[id_detail::hidx(mesh.prev(h))];
+        }
+        G[static_cast<std::size_t>(iv)] = m.theta_v[v] - sum_alpha;
+    }
+
+    return G;
+}
+
+// ── Energy via Gauss-Legendre path integral ─────────────────────────────────
+//
+// E(u) = ∫₀¹ ⟨G(tu), u⟩ dt   (10-point GL, identical constants to euclidean_functional)
+inline double inversive_distance_energy(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m)
+{
+    static const double gl_s[10] = {
+        -0.9739065285171717,  -0.8650633666889845,
+        -0.6794095682990244,  -0.4333953941292472,
+        -0.1488743389816312,   0.1488743389816312,
+         0.4333953941292472,   0.6794095682990244,
+         0.8650633666889845,   0.9739065285171717
+    };
+    static const double gl_w[10] = {
+        0.0666713443086881,  0.1494513491505806,
+        0.2190863625159820,  0.2692667193099963,
+        0.2955242247147529,  0.2955242247147529,
+        0.2692667193099963,  0.2190863625159820,
+        0.1494513491505806,  0.0666713443086881
+    };
+
+    const std::size_t n = x.size();
+    double E = 0.0;
+    std::vector<double> tx(n);
+    for (int k = 0; k < 10; ++k) {
+        double t  = (1.0 + gl_s[k]) * 0.5;
+        double wt = gl_w[k] * 0.5;
+        for (std::size_t i = 0; i < n; ++i) tx[i] = t * x[i];
+        auto G = inversive_distance_gradient(mesh, tx, m);
+        double dot = 0.0;
+        for (std::size_t i = 0; i < n; ++i) dot += G[i] * x[i];
+        E += wt * dot;
+    }
+    return E;
+}
+
+// ── Finite-difference gradient check ─────────────────────────────────────────
+inline bool gradient_check_inversive_distance(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m,
+    double eps = 1e-5,
+    double tol = 1e-6)
+{
+    auto G = inversive_distance_gradient(mesh, x, m);
+    const std::size_t n = G.size();
+
+    for (std::size_t i = 0; i < n; ++i) {
+        std::vector<double> xp = x, xm = x;
+        xp[i] += eps;
+        xm[i] -= eps;
+        double Ep = inversive_distance_energy(mesh, xp, m);
+        double Em = inversive_distance_energy(mesh, xm, m);
+        double fd = (Ep - Em) / (2.0 * eps);
+        if (std::abs(G[i] - fd) > tol) {
+            std::cerr << "[inversive-distance] FD gradient mismatch at DOF " << i
+                      << ": analytic=" << G[i]
+                      << "  FD=" << fd
+                      << "  diff=" << (G[i] - fd) << "\n";
+            return false;
+        }
+    }
+    return true;
+}
+
+// ── Newton equilibrium check: gradient vanishes at converged u ──────────────
+inline bool is_inversive_distance_equilibrium(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m,
+    double tol = 1e-8)
+{
+    auto G = inversive_distance_gradient(mesh, x, m);
+    for (double g : G)
+        if (std::abs(g) > tol) return false;
+    return true;
+}
+
+} // namespace conformallab