sphere_surface_helpers: Weighted sphere surface helpers

Description

Convenience helpers that embed the sampled sphere graph into \(\mathbb{R}^3\) and use the induced Euclidean edge lengths as positive graph weights. These helpers are intended for benchmark families where the graph topology follows the current pole-plus-latitude-rings sphere graph but the intended metric comes from a curved or spatially varying 3D realization.

Usage

sphere.surface.embedding(
  h,
  w = h,
  surface = c("standard", "ellipsoid", "wavy"),
  radius = 1,
  amplitude = 0.2,
  freq_theta = 3,
  freq_lat = 2,
  twist = 0.25
)
sphere.surface.graph(
  h,
  w = h,
  surface = c("standard", "ellipsoid", "wavy"),
  radius = 1,
  amplitude = 0.2,
  freq_theta = 3,
  freq_lat = 2,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)

Value

sphere.surface.embedding() returns an n x 3 numeric matrix with columns x, y, and z, where n = 2 + (h - 2) * w.

sphere.surface.graph() returns a list with components:

edges: the undirected sphere-graph edges,
n: number of vertices,
edge_weights: induced positive edge lengths,
coords_surface: the 3D surface embedding,
coords_param: the 2D longitude-latitude parameter coordinates,
weight_scale: the normalization constant applied to the raw edge lengths,
family: always "sphere",
surface: the chosen surface name,
label: a human-readable family label.

Arguments

h: Number of latitude levels including the poles. Must be at least 3.
w: Wrapped longitude count. Defaults to h; must be at least 3.
surface: Sphere surface family. One of "standard", "ellipsoid", or "wavy".
radius: Positive baseline radius.
amplitude: Finite deformation amplitude. For "ellipsoid", positive values make the shape oblate and negative values make it prolate, while keeping all axis lengths positive. For "wavy", the local radius must remain positive everywhere.
freq_theta: Positive longitudinal frequency used only when surface = "wavy".
freq_lat: Positive latitudinal frequency used only when surface = "wavy".
twist: Finite longitude twist applied smoothly by latitude. The twist vanishes at the poles.
normalize: Normalization applied to the induced edge lengths. One of "median", "mean", or "none".

Details

`sphere.surface.embedding()` returns the 3D coordinates of the sampled surface in the same vertex order as edges.sphere(): north pole first, then latitude rings from north to south, then the south pole. `sphere.surface.graph()` returns a reusable weighted-graph bundle containing the sphere edges, induced edge weights, the 3D surface coordinates, and a 2D longitude-latitude parameterization.