torus_surface_helpers: Weighted torus surface helpers

Description

Convenience helpers that embed a toroidal grid 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 is toroidal but the intended metric comes from a curved or spatially varying 3D realization.

Usage

torus.surface.embedding(
  h,
  w = h,
  surface = c("standard", "pinched", "wavy"),
  major_radius = 2,
  minor_radius = 0.75,
  amplitude = 0.2,
  freq_major = 2,
  freq_minor = 1,
  twist = 0.25
)
torus.surface.graph(
  h,
  w = h,
  surface = c("standard", "pinched", "wavy"),
  major_radius = 2,
  minor_radius = 0.75,
  amplitude = 0.2,
  freq_major = 2,
  freq_minor = 1,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)

Value

torus.surface.embedding() returns an n x 3 numeric matrix with columns x, y, and z.

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

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

Arguments

h: Number of wrapped rows. Must be at least 3.
w: Number of wrapped columns. Defaults to h; must be at least 3.
surface: Torus surface family. One of "standard", "pinched", or "wavy".
major_radius: Positive distance from the torus center to the center of the tube.
minor_radius: Positive baseline radius of the torus tube. The local tube radius must remain strictly smaller than major_radius everywhere.
amplitude: Finite numeric deformation amplitude.
freq_major: Positive angular frequency around the major cycle, used by "wavy" and the periodic twist.
freq_minor: Positive angular frequency around the minor cycle, used by "wavy".
twist: Finite phase twist applied periodically to the minor angle as a function of the major angle.
normalize: Normalization applied to the induced edge lengths. One of "median", "mean", or "none".

Details

`torus.surface.embedding()` returns the 3D coordinates of the embedded toroidal grid. `torus.surface.graph()` returns a reusable weighted-graph bundle containing the torus edges, induced edge weights, the 3D surface coordinates, and a 2D unwrapped parameterization.