% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{irregular_torus_surface_helpers}
\alias{irregular_torus_surface_helpers}
\alias{irregular.torus.surface.embedding}
\alias{irregular.torus.surface.graph}
\title{Weighted irregular torus surface helpers}
\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")
)
}
\arguments{
\item{major_rings}{Number of cyclic major rings around the torus.}

\item{tube_count}{Approximate number of vertices around each minor cycle.}

\item{count_irregularity}{Irregularity level for the per-ring sample counts.
Must lie in \code{[0, 1)}.}

\item{major_irregularity}{Irregularity level for the major-angle ring
spacing. Must lie in \code{[0, 1]}.}

\item{phase_twist}{Finite phase offset used to desynchronize neighboring
minor cycles.}

\item{surface}{Torus geometry 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.}

\item{amplitude}{Finite 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{irregular.torus.surface.embedding()} returns an \code{n x 3} numeric
matrix with columns \code{x}, \code{y}, and \code{z}.

\code{irregular.torus.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the irregular torus edges,
  \item \code{n}: number of vertices,
  \item \code{edge_weights}: induced positive edge lengths,
  \item \code{coords_surface}: the 3D embedding,
  \item \code{coords_param}: the irregular angular parameter coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"irregular.torus"},
  \item \code{surface}: the chosen surface name,
  \item \code{major_rings}: number of major-cycle rings,
  \item \code{ring_sizes}: sample counts around each ring,
  \item \code{label}: a human-readable family label.
}
}
\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
\eqn{\mathbb{R}^3} using either a standard, pinched, or wavy tube geometry.
}
