% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grip_quality.R
\name{score.landmark.geodesic.kk}
\alias{score.landmark.geodesic.kk}
\title{Score a layout under the landmark geodesic KK energy}
\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{
\item{coords}{Numeric coordinate matrix with 2 or 3 columns.}

\item{prepared}{Optional object returned by
\code{\link{prepare.landmark.geodesic.kk}()}.}

\item{edges}{Two-column integer matrix of edges (1-based vertex ids).}

\item{n}{Number of vertices.}

\item{adj_list}{Adjacency list (1-based) for an undirected graph.}

\item{weight_list}{Optional parallel list of positive edge weights.}

\item{edge_weights}{Optional positive edge-weight vector parallel to
\code{edges}.}

\item{local_nbrs}{Number of nearest graph-metric neighbors retained per
vertex when \code{prepared} is not supplied.}

\item{landmark_count}{Number of farthest-point landmarks retained per vertex
when \code{prepared} is not supplied.}

\item{stiffness}{Global stiffness constant \(K\).}

\item{distance_floor}{Small positive floor used in
\code{k_ij = K / max(g_ij, distance_floor)^2}.}

\item{edge_length_epsilon}{Small positive stabilizer added inside each
embedded edge length.}

\item{return_pair_details}{If \code{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.
}
\description{
\code{score.landmark.geodesic.kk()} evaluates a layout using the
landmark geodesic KK objective described in
\code{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 \code{L0} is fit analytically for the supplied layout
so that rankings are not dominated by an arbitrary global drawing scale.
}
\details{
This is a scoring and comparison helper, not an optimizer.
}
