% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gmds_edge_repulsive_unfolding.R
\name{repulsive.stage}
\alias{repulsive.stage}
\title{Optimize one pure repulsive layout stage}
\usage{
repulsive.stage(
  coords,
  lambda = 1,
  pair.index = NULL,
  pair.weights = NULL,
  repulsion.family = c("log", "inverse_power"),
  repulsion.delta = 0.001,
  repulsion.power = 1,
  max.iter = 80L,
  initial.step = 0.02,
  step.shrink = 0.5,
  armijo = 1e-04,
  min.step = 1e-08,
  grad.tol = 1e-07,
  recenter = TRUE,
  distance.eps = 1e-10,
  return.frames = FALSE,
  engine = c("cpp", "R")
)
}
\arguments{
\item{coords}{Numeric `n` by `dim` coordinate matrix.}

\item{lambda}{Repulsion strength. The returned total energy is
`lambda * repel.energy`; the gradient is scaled by `lambda`.}

\item{pair.index}{Optional two-column matrix of 1-based vertex pairs. If
`NULL` and `lambda > 0`, all unordered pairs are used.}

\item{pair.weights}{Optional non-negative pair weights parallel to
`pair.index`.}

\item{repulsion.family}{Repulsion potential family, either `"log"` or
`"inverse_power"`.}

\item{repulsion.delta}{Small positive softening parameter for pair distances.}

\item{repulsion.power}{Power used by the `"inverse_power"` repulsion.}

\item{max.iter}{Maximum number of gradient-descent iterations.}

\item{initial.step}{Initial gradient step size.}

\item{step.shrink}{Multiplicative shrink factor used by backtracking.}

\item{armijo}{Armijo sufficient-decrease coefficient.}

\item{min.step}{Minimum allowable step before the stage stops.}

\item{grad.tol}{Gradient-norm stopping tolerance.}

\item{recenter}{Logical; whether to recenter coordinates after each proposal.}

\item{distance.eps}{Small positive distance floor used in derivatives.}

\item{return.frames}{Logical; whether to return accepted coordinate frames.
Frame 0 is the starting coordinate matrix and later frames are accepted
updates.}

\item{engine}{Backend engine. `"cpp"` is the default; `"R"` uses the
reference implementation.}
}
\value{
A list with `coords`, final `state`, a data-frame `trace`, and,
  when requested, a list of coordinate `frames`.
}
\description{
`repulsive.stage()` performs a gradient-descent stage for the
pure repulsion objective evaluated by [repulsive.state()]. It is intended
for GMDS experiments that need to inspect repulsion separately from
edge-length repair.
}
