Score a layout under the landmark geodesic KK energy

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
)

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.

Value

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

Details

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