grip (version 0.2.0)

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.

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)