Optimize a layout under the full geodesic KK energy

geodesic.kk() applies a deterministic gradient-descent polish under the full all-pairs geodesic Kamada–Kawai objective.

Usage

geodesic.kk(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  max.iter = 16L,
  stiffness = 1,
  distance.floor = 1e-08,
  edge.length.epsilon = 1e-08,
  initial.step = 1,
  step.shrink = 0.5,
  armijo.factor = 1e-04,
  grad.tol = 1e-08,
  min.step = 1e-08,
  recenter = TRUE,
  return.trace = FALSE,
  scale.mode = c("fixed_initial", "profiled", "user"),
  scale.L0 = NULL
)

Arguments

coords: Numeric coordinate matrix with 2 or 3 columns.
prepared: Optional object returned by prepare.geodesic.kk().
edges: Two-column integer matrix of edges (1-based vertex ids).
n: Number of vertices.
adj.list: Adjacency list (1-based) for an undirected graph.
weight.list: Optional parallel list of positive edge weights.
edge.weights: Optional positive edge-weight vector parallel to edges.
max.iter: Maximum number of gradient-descent iterations.
stiffness: Global stiffness constant \(K\).
distance.floor: Small positive floor used in k_ij = K / max(g_ij, distance.floor)^2.
edge.length.epsilon: Small positive stabilizer added inside each embedded edge length.
initial.step: Initial line-search step size.
step.shrink: Multiplicative shrink factor in (0, 1) for backtracking.
armijo.factor: Non-negative Armijo decrease constant.
grad.tol: Non-negative stopping tolerance on the gradient norm.
min.step: Positive minimum accepted line-search step before giving up.
recenter: If TRUE, recenter the layout to zero mean after each accepted step.
return.trace: If TRUE, include per-iteration diagnostics and the accepted intermediate coordinate frames.
scale.mode: One of "fixed_initial", "profiled", or "user".
scale.L0: Optional user-supplied fixed scale, required when scale.mode = "user".

Value

A list with coords, trace, frames, prepared, and score.

Details

The optimizer supports three scale policies. With scale.mode = "fixed_initial" the target scale is fit once from the starting layout and then held fixed during optimization, matching the landmark geodesic KK behavior. With scale.mode = "profiled" the scale is re-fit analytically at each evaluation. With scale.mode = "user", a fixed user-supplied scale.L0 is used throughout.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
prepared <- prepare.geodesic.kk(cycle_edges, n = 6)
fit <- geodesic.kk(initial, prepared = prepared, max.iter = 1)