score.landmark.geodesic.kk: Score a layout under the landmark geodesic KK energy

Description

score.landmark.geodesic.kk() evaluates a layout using the landmark geodesic KK objective described in landmark\_geodesic\_kk\_spec\_2026-03-30.tex. Distances are measured along fixed chosen graph shortest paths, not by straight-line chord length. The target scale factor L0 is fit analytically for the supplied layout so that rankings are not dominated by an arbitrary global drawing scale.

Usage

score.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,
  stiffness = 1,
  distance_floor = 1e-08,
  edge_length_epsilon = 1e-08,
  return_pair_details = FALSE
)

Value

A one-row data frame with the fitted scale factor and landmark geodesic KK energy summary.

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.
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.
return_pair_details: If TRUE, include pairwise path lengths and residuals in a list column.

Details

This is a scoring and comparison helper, not an optimizer.