% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{graph_generators}
\alias{graph_generators}
\alias{edges.path}
\alias{edges.cycle}
\alias{edges.mesh}
\alias{edges.occupied.mesh}
\alias{edges.cylinder}
\alias{edges.torus}
\alias{edges.irregular.ball}
\alias{edges.irregular.shell}
\alias{edges.irregular.torus}
\alias{edges.sphere}
\alias{edges.irregular.annulus}
\alias{edges.irregular.pair.of.pants}
\alias{edges.irregular.double.torus}
\alias{edges.irregular.sphere}
\alias{edges.cube}
\alias{edges.kary.tree}
\alias{edges.recursive.mask.grid}
\alias{edges.recursive.triangle.mask}
\alias{edges.recursive.tetrahedron.mask}
\alias{edges.recursive.cube.mask}
\alias{edges.triangulated.polyhedron}
\alias{edges.triangulated.annulus}
\alias{edges.triangulated.pair.of.pants}
\alias{edges.vicsek}
\alias{edges.menger.sponge}
\alias{edges.cube.periodic.tunnels}
\alias{edges.cube.asymmetric.cavities}
\alias{edges.cube.channel.network}
\alias{edges.sierpinski.triangle}
\alias{edges.sierpinski.tetrahedron}
\alias{edges.sierpinski.carpet}
\title{Sample graph generators}
\usage{
edges.path(n)

edges.cycle(n)

edges.mesh(h, w = h, connectivity = c("orthogonal", "diagonal"))

edges.occupied.mesh(keep, connectivity = c("orthogonal", "diagonal"))

edges.cylinder(h, w = h)

edges.torus(h, w = h)

edges.irregular.ball(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1,
  layers = 3,
  outer_radius = 1,
  radial_irregularity = 0.25,
  layer_twist = 0.35
)

edges.irregular.shell(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1,
  layers = 3,
  inner_radius = 0.45,
  outer_radius = 1,
  radial_irregularity = 0.25,
  layer_twist = 0.35
)

edges.irregular.torus(
  major_rings = 8,
  tube_count = 16,
  count_irregularity = 0.2,
  major_irregularity = 0.25,
  phase_twist = 0.35
)

edges.sphere(h, w = h)

edges.irregular.annulus(
  rings = 6,
  outer_count = 28,
  outer_radius = 1,
  inner_radius = 0.45,
  count_irregularity = 0.2,
  radial_irregularity = 0.35,
  phase_twist = 0.35
)

edges.irregular.pair.of.pants(
  slices = 11,
  outer_count = 28,
  outer_radius = 1.1,
  hole_radius = 0.24,
  hole_offset = 0.38,
  hole_height = 0.18,
  count_irregularity = 0.2,
  vertical_irregularity = 0.35,
  phase_twist = 0.35
)

edges.irregular.double.torus(
  slices = 11,
  tube_count = 14,
  branch_length = 0.85,
  branch_offset = 0.72,
  tube_radius = 0.28,
  transition_width = 0.42,
  count_irregularity = 0.2,
  axial_irregularity = 0.3,
  phase_twist = 0.35
)

edges.irregular.sphere(
  bands = 6,
  equator_count = 28,
  count_irregularity = 0.2,
  lat_irregularity = 0.35,
  phase_twist = 0.35
)

edges.cube(side = 2)

edges.kary.tree(k = 2, depth = 2)

edges.recursive.mask.grid(mask, level = 2)

edges.recursive.triangle.mask(mask = mask.triangle.classic(), level = 2)

edges.recursive.tetrahedron.mask(mask = mask.tetrahedron.classic(), level = 2)

edges.recursive.cube.mask(mask, level = 2)

edges.triangulated.polyhedron(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1
)

edges.triangulated.annulus(
  resolution = 12,
  outer_radius = 1,
  inner_radius = 0.45
)

edges.triangulated.pair.of.pants(
  resolution = 12,
  outer_radius = 1.1,
  hole_radius = 0.24,
  hole_offset = 0.38,
  hole_height = 0.18
)

edges.vicsek(level = 2)

edges.menger.sponge(level = 2)

edges.cube.periodic.tunnels(
  level = 2,
  side = 5,
  tunnel_width = 1,
  tunnel_period = 2,
  tunnel_offset = 2
)

edges.cube.asymmetric.cavities(
  level = 2,
  side = 5,
  cavity_size = 2,
  pocket_size = max(1L, cavity_size - 1L)
)

edges.cube.channel.network(
  level = 2,
  side = 5,
  channel_width = 1,
  branch_offset = 2
)

edges.sierpinski.triangle(level = 2)

edges.sierpinski.tetrahedron(level = 2)

edges.sierpinski.carpet(level = 2)
}
\arguments{
\item{n}{Number of vertices.}

\item{h}{Number of rows.}

\item{w}{Number of columns. Defaults to \code{h}.}

\item{connectivity}{Mesh neighborhood rule. \code{"orthogonal"} keeps the
4-neighbor grid; \code{"diagonal"} also adds both diagonals of every unit
square.}

\item{keep}{Logical or numeric occupancy matrix. Non-zero entries are kept.}

\item{base}{Base polyhedron for \code{edges.triangulated.polyhedron()}. One
of \code{"tetrahedron"}, \code{"octahedron"}, or \code{"icosahedron"}.}

\item{level}{Recursion depth. For \code{edges.recursive.mask.grid()},
\code{edges.recursive.cube.mask()}, \code{edges.vicsek()},
\code{edges.menger.sponge()}, and \code{edges.sierpinski.carpet()},
\code{level} must be at least 1; \code{edges.recursive.triangle.mask()},
\code{edges.recursive.tetrahedron.mask()}, and
\code{edges.triangulated.polyhedron()} also allow \code{level = 0}.}

\item{layers}{Number of non-center radial layers for
\code{edges.irregular.ball()} and number of inner-to-outer layers for
\code{edges.irregular.shell()}.}

\item{outer_radius}{Positive outer boundary radius for
\code{edges.triangulated.annulus()} and
\code{edges.triangulated.pair.of.pants()}.}

\item{radial_irregularity}{Within-ring radial irregularity level for
\code{edges.irregular.annulus()}.}

\item{layer_twist}{Finite z-axis twist applied across radial layers in
\code{edges.irregular.ball()} and \code{edges.irregular.shell()}.}

\item{inner_radius}{Positive inner annulus radius for
\code{edges.triangulated.annulus()}.}

\item{major_rings}{Number of cyclic major rings for
\code{edges.irregular.torus()}.}

\item{tube_count}{Approximate number of vertices around each minor cycle for
\code{edges.irregular.torus()} and around each tube-like loop for
\code{edges.irregular.double.torus()}.}

\item{count_irregularity}{Irregularity level for sample counts in
\code{edges.irregular.torus()}, \code{edges.irregular.annulus()},
\code{edges.irregular.pair.of.pants()},
\code{edges.irregular.double.torus()}, and \code{edges.irregular.sphere()}.}

\item{major_irregularity}{Major-angle ring-spacing irregularity level for
\code{edges.irregular.torus()}.}

\item{phase_twist}{Angular phase offset used to desynchronize neighboring
rings, slice samples, or latitude bands in the irregular torus,
irregular annulus, irregular pair-of-pants, irregular double torus,
and irregular sphere families.}

\item{rings}{Number of concentric sample rings for
\code{edges.irregular.annulus()}.}

\item{outer_count}{Approximate number of vertices on the outer boundary for
\code{edges.irregular.annulus()} and across the widest slices for
\code{edges.irregular.pair.of.pants()}.}

\item{slices}{Number of horizontal sample slices for
\code{edges.irregular.pair.of.pants()}.}

\item{hole_radius}{Positive radius of each interior hole for
\code{edges.triangulated.pair.of.pants()}.}

\item{hole_offset}{Positive horizontal offset of the two hole centers for
\code{edges.triangulated.pair.of.pants()}.}

\item{hole_height}{Shared vertical coordinate of the two hole centers for
\code{edges.triangulated.pair.of.pants()}.}

\item{vertical_irregularity}{Slice-spacing irregularity level for
\code{edges.irregular.pair.of.pants()}.}

\item{branch_length}{Half-length of the three-loop central region for
\code{edges.irregular.double.torus()}.}

\item{branch_offset}{Offset of the outer loop centers from the middle loop
for \code{edges.irregular.double.torus()}.}

\item{tube_radius}{Baseline radius of each tube-like loop for
\code{edges.irregular.double.torus()}.}

\item{transition_width}{Width of the single-loop to three-loop transition
regions for \code{edges.irregular.double.torus()}.}

\item{axial_irregularity}{Slice-spacing irregularity level for
\code{edges.irregular.double.torus()}.}

\item{bands}{Number of non-pole latitude bands for
\code{edges.irregular.sphere()}.}

\item{equator_count}{Approximate number of vertices near the equator for
\code{edges.irregular.sphere()}.}

\item{lat_irregularity}{Latitude-band spacing irregularity level for
\code{edges.irregular.sphere()}.}

\item{side}{Number of lattice points along each cube edge.}

\item{k}{Branching factor.}

\item{depth}{Number of levels below the root.}

\item{mask}{Keep-mask describing which recursive cells are retained. For
\code{edges.recursive.mask.grid()}, \code{mask} must be a square logical
or numeric keep-matrix whose non-zero entries are kept at each recursive
subdivision step. For
\code{edges.recursive.triangle.mask()}, \code{mask} must instead be a
four-entry vector in \code{left}, \code{right}, \code{top},
\code{center} order, and for \code{edges.recursive.tetrahedron.mask()},
\code{mask} must be a four-entry vector in \code{base_left},
\code{base_right}, \code{base_back}, \code{apex} order. For
\code{edges.recursive.cube.mask()}, \code{mask} must be a cubic logical
or numeric keep-array whose non-zero entries are kept at each recursive
subdivision step.}

\item{resolution}{Positive lattice-resolution control used by
\code{edges.triangulated.annulus()} and
\code{edges.triangulated.pair.of.pants()}.}

\item{tunnel_width}{Width of each removed tunnel band in
\code{edges.cube.periodic.tunnels()}.}

\item{tunnel_period}{Spacing between successive tunnel bands in
\code{edges.cube.periodic.tunnels()}.}

\item{tunnel_offset}{Starting index of the first tunnel band in
\code{edges.cube.periodic.tunnels()}.}

\item{cavity_size}{Side length of the larger interior cavity block in
\code{edges.cube.asymmetric.cavities()}.}

\item{pocket_size}{Side length of the smaller secondary cavity block in
\code{edges.cube.asymmetric.cavities()}.}

\item{channel_width}{Width of each removed channel in
\code{edges.cube.channel.network()}.}
}
\value{
A two-column integer matrix of undirected edges. Vertex labels are
  consecutive integers starting at 1.
}
\description{
Convenience helpers that build small undirected graph families as two-column
integer edge matrices suitable for \code{\link{grip}()}. These
helpers are meant for examples, experiments, and reproducible tests.
}
\details{
The occupied-grid, recursive masked-grid, and Sierpinski families are
exposed explicitly rather than overloading a single generator with
layout-dimension-dependent behavior: \code{\link{edges.occupied.mesh}()}
builds a finite perforated-mesh family from an occupancy matrix,
\code{\link{edges.recursive.mask.grid}()} builds a generic square-mask
family, \code{\link{edges.recursive.triangle.mask}()} builds a generic
triangle-mask family, \code{\link{edges.recursive.tetrahedron.mask}()}
builds a generic tetrahedron-mask family,
\code{\link{edges.recursive.cube.mask}()} builds a generic cube-mask
family, \code{\link{edges.vicsek}()} builds the connected axial-cross
variant, \code{\link{edges.menger.sponge}()} builds the classic cubical
sponge variant, \code{\link{edges.triangulated.polyhedron}()} builds a
generic irregular triangulated-surface family,
\code{\link{edges.sierpinski.triangle}()} builds the 2-simplex family,
\code{\link{edges.sierpinski.tetrahedron}()} builds the 3-simplex family,
and \code{\link{edges.sierpinski.carpet}()} builds a 2D cell-adjacency
carpet graph.
}
\section{Functions}{
\itemize{
\item \code{edges.path()}: Path graph on \code{n} vertices.

\item \code{edges.cycle()}: Cycle graph on \code{n} vertices.

\item \code{edges.mesh()}: Rectangular grid graph with \code{h} rows and \code{w}
columns.

\item \code{edges.occupied.mesh()}: Rectangular occupied-grid graph whose vertices
are kept cells and whose edges connect orthogonally adjacent kept cells.
With \code{connectivity = "diagonal"}, both diagonals are added for every
fully occupied 2-by-2 block.

\item \code{edges.cylinder()}: Cylindrical grid graph with \code{h} rows and wrapped
width \code{w}.

\item \code{edges.torus()}: Toroidal grid graph with wrapped height and
width.

\item \code{edges.irregular.ball()}: Deterministically irregular tetrahedralized ball
graph built from nested subdivided polyhedral shells connected by a
layered prism-to-tetrahedra edge pattern.

\item \code{edges.irregular.shell()}: Deterministically irregular tetrahedralized shell
graph built from nested subdivided polyhedral shells connected by a
layered prism-to-tetrahedra edge pattern.

\item \code{edges.irregular.torus()}: Deterministically irregular torus graph built
from major-cycle rings with varying sample counts and stitched into a
locally triangulated closed surface.

\item \code{edges.sphere()}: Sphere surface graph with \code{h} latitude
levels (including the poles) and wrapped longitude \code{w}.

\item \code{edges.irregular.annulus()}: Deterministically irregular annulus graph built
from concentric sample rings with varying sample counts and stitched into a
locally triangulated surface-with-boundary graph.

\item \code{edges.irregular.pair.of.pants()}: Deterministically irregular pair-of-pants graph
built from horizontal slice intervals with varying sample counts and
stitched into a locally triangulated surface-with-boundary graph.

\item \code{edges.irregular.double.torus()}: Deterministically irregular double-torus graph
built from cyclic slices whose cross-sections follow a `1 -> 3 -> 1` loop
transition between two poles.

\item \code{edges.irregular.sphere()}: Deterministically irregular sphere graph built
from latitude bands with varying sample counts and stitched into a locally
triangulated closed surface.

\item \code{edges.cube()}: Cube surface graph on the boundary of a
\code{side x side x side} lattice.

\item \code{edges.kary.tree()}: Full \code{k}-ary tree of depth \code{depth}.

\item \code{edges.recursive.mask.grid()}: Recursively refined square-mask grid graph whose
vertices are occupied cells and whose edges connect orthogonally adjacent
cells.

\item \code{edges.recursive.triangle.mask()}: Recursively refined triangle-mask graph whose
vertices are the retained subdivision vertices of an equilateral triangle.

\item \code{edges.recursive.tetrahedron.mask()}: Recursively refined tetrahedron-mask graph whose
vertices are the retained subdivision vertices of a tetrahedron.

\item \code{edges.recursive.cube.mask()}: Recursively refined cube-mask graph whose
vertices are occupied subcubes and whose edges connect face-adjacent
occupied cells.

\item \code{edges.triangulated.polyhedron()}: Triangulated closed-surface graph obtained by
repeatedly splitting the triangular faces of a tetrahedron, octahedron, or
icosahedron.

\item \code{edges.triangulated.annulus()}: Triangulated annulus graph obtained by clipping
a regular triangular lattice to the region between two concentric circles.

\item \code{edges.triangulated.pair.of.pants()}: Triangulated pair-of-pants graph obtained by
clipping a regular triangular lattice to a disk with two interior circular
holes.

\item \code{edges.vicsek()}: Connected Vicsek-style cross family derived from
a \code{3 x 3} axial-cross keep-mask.

\item \code{edges.menger.sponge()}: Classic Menger-sponge cubical cell-adjacency
graph derived from the \code{3 x 3 x 3} keep-mask that removes the center
cube and the six face-center cubes at each recursion step.

\item \code{edges.cube.periodic.tunnels()}: Periodic cubical tunnel family derived from a
repeated tunnel-band keep-mask. The classic Menger sponge appears as the
\code{side = 3}, \code{tunnel_width = 1} special case.

\item \code{edges.cube.asymmetric.cavities()}: Cubical porous family with two offset interior
cavity blocks repeated recursively.

\item \code{edges.cube.channel.network()}: Cubical porous family with a deterministic
branched channel network carved through each recursive block.

\item \code{edges.sierpinski.triangle()}: Two-dimensional Sierpinski triangle graph at
recursion depth \code{level}.

\item \code{edges.sierpinski.tetrahedron()}: Three-dimensional tetrahedral Sierpinski graph
at recursion depth \code{level}.

\item \code{edges.sierpinski.carpet()}: Two-dimensional Sierpinski carpet graph whose
vertices are occupied cells and whose edges connect orthogonally adjacent
cells.

}}
\examples{
edges <- edges.path(6)
coords <- grip(edges, n = 6, dim = 2, seed = 1)
plot.layout(coords, edges, main = "Path graph", pch = 16, cex = 0.8)
edges <- edges.sierpinski.triangle(2)
n <- max(edges)
coords <- grip(edges, n = n, dim = 2,
                      placement = "circle",
                      seed = 1)
plot.layout(coords, edges, main = "Sierpinski triangle", pch = 16, cex = 0.7)
}
