Optimize one pure repulsive layout stage

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.

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

coords

Numeric n by dim coordinate matrix.

lambda

Repulsion strength. The returned total energy is lambda * repel.energy; the gradient is scaled by lambda.

pair.index

Optional two-column matrix of 1-based vertex pairs. If NULL and lambda > 0, all unordered pairs are used.

pair.weights

Optional non-negative 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

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