Optimize a layout under the landmark geodesic KK energy

landmark.geodesic.kk() applies a deterministic warm-started gradient-descent polish under the sparse landmark geodesic KK energy. It starts from an existing layout and refines it, rather than replacing the full multiscale GRIP refinement pipeline.

Usage

landmark.geodesic.kk(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  local.nbrs = 20L,
  landmark.count = 8L,
  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
)

Arguments

coords

Numeric coordinate matrix with 2 or 3 columns.

prepared

Optional object returned by prepare.landmark.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.

local.nbrs

Number of nearest graph-metric neighbors retained per vertex when prepared is not supplied.

landmark.count

Number of farthest-point landmarks retained per vertex when prepared is not supplied.

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.

Value

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

Details

The implementation fits the LGKK target scale L0 once from the starting layout and then optimizes against those fixed target path lengths. That keeps the gradient simple and makes the resulting line search robust for an initial implementation.

Examples

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