Optimize one edge-isometric repulsive unfolding stage

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.

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

coords: Numeric n by dim coordinate matrix.
edges: Integer or numeric matrix with two columns containing 1-based graph edge endpoints.
edge.lengths: Numeric vector of target edge lengths, parallel to edges.
edge.weights: Optional non-negative edge weights. Defaults to one.
lambda: Repulsion strength.
edge.family: Edge potential family, either "quadratic" or "upper_barrier".
eps.plus: Upper-barrier slack parameter.
beta: Upper-barrier strength. When beta <= 0, the edge potential is quadratic.
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.
pair.weights: Optional pair weights, parallel to pair.index.
repulsion.family: Repulsion potential family, either "log" or "inverse_power".
repulsion.delta: Small positive softening parameter for pair distances.
repulsion.power: Power used by the "inverse_power" repulsion.
max.iter: Maximum number of gradient-descent iterations.
initial.step: Initial gradient step size.
step.shrink: Multiplicative shrink factor used by backtracking.
armijo: Armijo sufficient-decrease coefficient.
min.step: Minimum allowable step before the stage stops.
grad.tol: Gradient-norm stopping tolerance.
recenter: Logical; whether to recenter coordinates after each proposal.
distance.eps: Small positive distance floor used in derivatives.
return.frames: Logical; whether to return accepted coordinate frames. Frame 0 is the starting coordinate matrix and later frames are accepted updates.
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.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
fit <- edge.repulsive.stage(
  initial, cycle_edges, rep(1, nrow(cycle_edges)),
  lambda = 0.1, max.iter = 1, engine = "R"
)