landmark.geodesic.kk: Optimize a layout under the landmark geodesic KK energy

Description

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
)

Value

A list with coords, trace, frames,

prepared, and score.

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.

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.