irregular_torus_surface_helpers: Weighted irregular torus surface helpers

Description

Convenience helpers that build a torus from deterministically irregular major-cycle rings with varying sample counts, stitch adjacent rings into a locally triangulated toroidal graph, and then realize that graph in \(\mathbb{R}^3\) using either a standard, pinched, or wavy tube geometry.

Usage

irregular.torus.surface.embedding(
  major_rings = 8,
  tube_count = 16,
  count_irregularity = 0.2,
  major_irregularity = 0.25,
  phase_twist = 0.35,
  surface = c("standard", "pinched", "wavy"),
  major_radius = 2,
  minor_radius = 0.75,
  amplitude = 0.2,
  freq_major = 2,
  freq_minor = 1,
  twist = 0.25
)
irregular.torus.surface.graph(
  major_rings = 8,
  tube_count = 16,
  count_irregularity = 0.2,
  major_irregularity = 0.25,
  phase_twist = 0.35,
  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

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

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

edges: the irregular torus edges,
n: number of vertices,
edge_weights: induced positive edge lengths,
coords_surface: the 3D embedding,
coords_param: the irregular angular parameter coordinates,
weight_scale: the normalization constant applied to the raw edge lengths,
family: always "irregular.torus",
surface: the chosen surface name,
major_rings: number of major-cycle rings,
ring_sizes: sample counts around each ring,
label: a human-readable family label.

Arguments

major_rings: Number of cyclic major rings around the torus.
tube_count: Approximate number of vertices around each minor cycle.
count_irregularity: Irregularity level for the per-ring sample counts. Must lie in [0, 1).
major_irregularity: Irregularity level for the major-angle ring spacing. Must lie in [0, 1].
phase_twist: Finite phase offset used to desynchronize neighboring minor cycles.
surface: Torus geometry 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.
amplitude: Finite 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".