% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gmds_edge_repulsive_unfolding.R
\name{edge.repulsive.stage}
\alias{edge.repulsive.stage}
\title{Optimize one edge-isometric repulsive unfolding stage}
\usage{
edge.repulsive.stage(
  coords,
  edges,
  edge.lengths,
  edge.weights = NULL,
  lambda = 0,
  edge.family = c("quadratic", "upper_barrier"),
  eps.plus = 0.35,
  beta = 0,
  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{edges}{Integer or numeric matrix with two columns containing 1-based
graph edge endpoints.}

\item{edge.lengths}{Numeric vector of target edge lengths, parallel to
`edges`.}

\item{edge.weights}{Optional non-negative edge weights. Defaults to one.}

\item{lambda}{Repulsion strength.}

\item{edge.family}{Edge potential family, either `"quadratic"` or
`"upper_barrier"`.}

\item{eps.plus}{Upper-barrier slack parameter.}

\item{beta}{Upper-barrier strength. When `beta <= 0`, the edge potential is
quadratic.}

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

\item{pair.weights}{Optional 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{
`edge.repulsive.stage()` performs one gradient-descent stage
for the objective evaluated by `edge.repulsive.state()`. It uses Armijo
backtracking, optionally recenters coordinates after each proposal, and
returns the final coordinates plus a per-iteration trace.
}
