Skip to contents

Optimize a layout under the full geodesic KK energy

Source: R/grip_quality.R
geodesic.kk.Rd

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.