refactor(api): consistent naming for spherical + hyper-ideal helpers (A1–A3)

Standardize the low-level free-function API on <verb>_<geom>_<rest>,
matching the already-consistent setup_<geom>_maps. Old names kept as
[[deprecated]] inline aliases for one release; all internal call sites
migrated.

Renames:
  assign_vertex_dof_indices      -> assign_spherical_vertex_dof_indices
  assign_all_spherical_dof_indices -> assign_spherical_all_dof_indices
  assign_all_dof_indices         -> assign_hyper_ideal_all_dof_indices
  compute_lambda0_from_mesh      -> compute_spherical_lambda0_from_mesh
  gradient_check                 -> gradient_check_hyper_ideal

A4/A5 (public CGAL API) intentionally deferred pending the license/
provenance decision (see CGAL submission audit G0/G1).

Verified: 277/277 CGAL tests pass, no deprecation warnings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

code/include/CGAL/Discrete_conformal_map.h

@@ -345,7 +345,7 @@ auto discrete_conformal_map_spherical(
     Conformal_map_result<FT> result;
 
     auto maps = ::conformallab::setup_spherical_maps(mesh);
-    ::conformallab::compute_lambda0_from_mesh(mesh, maps);
+    ::conformallab::compute_spherical_lambda0_from_mesh(mesh, maps);
 
     auto theta_param = parameters::get_parameter(
         np, Conformal_map::internal_np::vertex_curvature_map);
@@ -499,7 +499,7 @@ auto discrete_conformal_map_hyper_ideal(
             maps.theta_v[v] = get(theta_param, v);
     }
 
-    const int n = ::conformallab::assign_all_dof_indices(mesh, maps);
+    const int n = ::conformallab::assign_hyper_ideal_all_dof_indices(mesh, maps);
 
     const FT  tol      = parameters::choose_parameter(
         parameters::get_parameter(np, Conformal_map::internal_np::gradient_tolerance),

code/include/hyper_ideal_functional.hpp

@@ -25,7 +25,7 @@
 // ─────
 //   auto mesh = make_tetrahedron();
 //   auto maps = setup_hyper_ideal_maps(mesh);
-//   int n = assign_all_dof_indices(mesh, maps);   // all variable
+//   int n = assign_hyper_ideal_all_dof_indices(mesh, maps);   // all variable
 //   std::vector<double> x(n, 1.0);
 //   auto res = evaluate_hyper_ideal(mesh, x, maps);
 //   // res.energy, res.gradient
@@ -104,7 +104,7 @@ inline int hyper_ideal_dimension(const ConformalMesh& mesh, const HyperIdealMaps
 /// rotational mode for an all-hyper-ideal configuration).
 ///
 /// \returns total DOF count = `num_vertices(mesh) + num_edges(mesh)`.
-inline int assign_all_dof_indices(ConformalMesh& mesh, HyperIdealMaps& m)
+inline int assign_hyper_ideal_all_dof_indices(ConformalMesh& mesh, HyperIdealMaps& m)
 {
     int idx = 0;
     for (auto v : mesh.vertices()) m.v_idx[v] = idx++;
@@ -112,6 +112,11 @@ inline int assign_all_dof_indices(ConformalMesh& mesh, HyperIdealMaps& m)
     return idx;
 }
 
+/// \deprecated Use `assign_hyper_ideal_all_dof_indices` (API-naming audit A1).
+[[deprecated("renamed to assign_hyper_ideal_all_dof_indices")]]
+inline int assign_all_dof_indices(ConformalMesh& mesh, HyperIdealMaps& m)
+{ return assign_hyper_ideal_all_dof_indices(mesh, m); }
+
 // ── Evaluation result ─────────────────────────────────────────────────────────
 
 /// Output of `evaluate_hyper_ideal()` — the energy value and (optionally)
@@ -467,7 +472,7 @@ inline HyperIdealResult evaluate_hyper_ideal(
 ///
 /// Returns `true` iff `|G[i] − fd[i]| / max(1, |G[i]|) < tol` for every
 /// DOF.  Defaults `eps = 1e-5`, `tol = 1e-4` match the Java `FunctionalTest`.
-inline bool gradient_check(
+inline bool gradient_check_hyper_ideal(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,
     const HyperIdealMaps&      m,
@@ -500,4 +505,14 @@ inline bool gradient_check(
     return ok;
 }
 
+/// \deprecated Use `gradient_check_hyper_ideal` (API-naming audit A3).
+[[deprecated("renamed to gradient_check_hyper_ideal")]]
+inline bool gradient_check(
+    ConformalMesh&             mesh,
+    const std::vector<double>& x0,
+    const HyperIdealMaps&      m,
+    double                     eps = 1E-5,
+    double                     tol = 1E-4)
+{ return gradient_check_hyper_ideal(mesh, x0, m, eps, tol); }
+
 } // namespace conformallab

code/include/newton_solver.hpp

@@ -384,7 +384,7 @@ inline NewtonResult newton_spherical(
 ///
 /// DOF layout: first V_free entries are vertex variables b_v (hyper-ideal radii),
 /// followed by E entries for edge variables a_e (intersection angles).
-/// Use assign_all_dof_indices(mesh, maps) to set v_idx and e_idx automatically —
+/// Use assign_hyper_ideal_all_dof_indices(mesh, maps) to set v_idx and e_idx automatically —
 /// no vertex needs to be pinned.
 ///
 /// \param mesh      Input triangulated surface, genus g ≥ 1.

code/include/spherical_functional.hpp

@@ -75,7 +75,7 @@ struct SphericalMaps {
 ///
 /// Defaults match the Euclidean defaults except that `lambda0 = 0` here
 /// gives `l_e = π` which is degenerate on the unit sphere — always call
-/// `compute_lambda0_from_mesh(mesh, m)` next on a real mesh.
+/// `compute_spherical_lambda0_from_mesh(mesh, m)` next on a real mesh.
 inline SphericalMaps setup_spherical_maps(ConformalMesh& mesh)
 {
     SphericalMaps m;
@@ -96,7 +96,7 @@ inline SphericalMaps setup_spherical_maps(ConformalMesh& mesh)
 ///
 /// On closed spherical surfaces exactly one gauge vertex must be pinned
 /// to remove the global-scale null mode.
-inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
+inline int assign_spherical_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
 {
     int idx = 0;
     for (auto v : mesh.vertices()) m.v_idx[v] = idx++;
@@ -108,7 +108,7 @@ inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
 /// surfaces to fix the global-scale gauge mode in a single call.
 ///
 /// \returns  The number of free DOFs assigned (`num_vertices − 1`).
-inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m,
+inline int assign_spherical_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m,
                                       Vertex_index gauge)
 {
     int idx = 0;
@@ -117,10 +117,22 @@ inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m,
     return idx;
 }
 
+/// \deprecated Use `assign_spherical_vertex_dof_indices`.  Kept one release for
+/// source compatibility (API-naming audit A1, 2026-05-31).
+[[deprecated("renamed to assign_spherical_vertex_dof_indices")]]
+inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
+{ return assign_spherical_vertex_dof_indices(mesh, m); }
+
+/// \deprecated Use `assign_spherical_vertex_dof_indices`.
+[[deprecated("renamed to assign_spherical_vertex_dof_indices")]]
+inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m,
+                                     Vertex_index gauge)
+{ return assign_spherical_vertex_dof_indices(mesh, m, gauge); }
+
 /// Assign DOF indices for all vertices AND all edges (vertex-DOFs first,
 /// then edge-DOFs).  Mirrors `assign_euclidean_all_dof_indices` for the
 /// cyclic spherical formulation.
-inline int assign_all_spherical_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
+inline int assign_spherical_all_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
 {
     int idx = 0;
     for (auto v : mesh.vertices()) m.v_idx[v] = idx++;
@@ -128,6 +140,11 @@ inline int assign_all_spherical_dof_indices(ConformalMesh& mesh, SphericalMaps&
     return idx;
 }
 
+/// \deprecated Use `assign_spherical_all_dof_indices` (API-naming audit A1).
+[[deprecated("renamed to assign_spherical_all_dof_indices")]]
+inline int assign_all_spherical_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
+{ return assign_spherical_all_dof_indices(mesh, m); }
+
 /// Count the free DOFs (vertices + edges with index `≥ 0`).
 inline int spherical_dimension(const ConformalMesh& mesh, const SphericalMaps& m)
 {
@@ -145,7 +162,7 @@ inline int spherical_dimension(const ConformalMesh& mesh, const SphericalMaps& m
 ///
 /// \pre  Every vertex `v` of `mesh` lies on the unit sphere (norm = 1).
 /// \pre  No edge is degenerate (`p_i ≠ p_j` and `p_i ≠ -p_j`).
-inline void compute_lambda0_from_mesh(ConformalMesh& mesh, SphericalMaps& m)
+inline void compute_spherical_lambda0_from_mesh(ConformalMesh& mesh, SphericalMaps& m)
 {
     for (auto e : mesh.edges()) {
         auto h  = mesh.halfedge(e);
@@ -163,6 +180,11 @@ inline void compute_lambda0_from_mesh(ConformalMesh& mesh, SphericalMaps& m)
     }
 }
 
+/// \deprecated Use `compute_spherical_lambda0_from_mesh` (API-naming audit A2).
+[[deprecated("renamed to compute_spherical_lambda0_from_mesh")]]
+inline void compute_lambda0_from_mesh(ConformalMesh& mesh, SphericalMaps& m)
+{ compute_spherical_lambda0_from_mesh(mesh, m); }
+
 // ── Evaluation result ─────────────────────────────────────────────────────────
 
 /// Output of `evaluate_spherical()` — energy plus optional gradient.