% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{torus_surface_helpers}
\alias{torus_surface_helpers}
\alias{torus.surface.embedding}
\alias{torus.surface.graph}
\title{Weighted torus surface helpers}
\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")
)
}
\arguments{
\item{h}{Number of wrapped rows. Must be at least \code{3}.}

\item{w}{Number of wrapped columns. Defaults to \code{h}; must be at least
\code{3}.}

\item{surface}{Torus surface family. One of \code{"standard"},
\code{"pinched"}, or \code{"wavy"}.}

\item{major_radius}{Positive distance from the torus center to the center of
the tube.}

\item{minor_radius}{Positive baseline radius of the torus tube. The local
tube radius must remain strictly smaller than \code{major_radius}
everywhere.}

\item{amplitude}{Finite numeric deformation amplitude.}

\item{freq_major}{Positive angular frequency around the major cycle, used by
\code{"wavy"} and the periodic twist.}

\item{freq_minor}{Positive angular frequency around the minor cycle, used by
\code{"wavy"}.}

\item{twist}{Finite phase twist applied periodically to the minor angle as a
function of the major angle.}

\item{normalize}{Normalization applied to the induced edge lengths. One of
\code{"median"}, \code{"mean"}, or \code{"none"}.}
}
\value{
\code{torus.surface.embedding()} returns an \code{n x 3} numeric matrix with
columns \code{x}, \code{y}, and \code{z}.

\code{torus.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the undirected toroidal-grid edges,
  \item \code{n}: number of vertices,
  \item \code{edge_weights}: induced positive edge lengths,
  \item \code{coords_surface}: the 3D surface embedding,
  \item \code{coords_param}: the 2D unwrapped parameter coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"torus"},
  \item \code{surface}: the chosen surface name,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that embed a toroidal grid graph into
\eqn{\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.
}
\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.
}
