% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grip_quality.R
\name{score.geodesic.kk}
\alias{score.geodesic.kk}
\title{Score a layout under the full geodesic KK energy}
\usage{
score.geodesic.kk(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  stiffness = 1,
  distance_floor = 1e-08,
  edge_length_epsilon = 1e-08,
  scale_mode = c("profiled", "user"),
  scale.L0 = NULL,
  return_pair_details = FALSE
)
}
\arguments{
\item{coords}{Numeric coordinate matrix with 2 or 3 columns.}

\item{prepared}{Optional object returned by
\code{\link{prepare.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{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{scale_mode}{Either \code{"profiled"} to fit \code{L0} analytically
for the supplied layout or \code{"user"} to use \code{scale.L0}.}

\item{scale.L0}{Optional user-supplied geodesic KK scale, required when
\code{scale_mode = "user"}.}

\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 or user-supplied scale factor
  and full geodesic KK energy summary.
}
\description{
\code{score.geodesic.kk()} evaluates a layout using the full all-pairs
geodesic Kamada--Kawai objective. Distances are measured along fixed chosen
graph shortest paths, not by straight-line chord length.
}
\details{
By default the global target scale \code{L0} is fit analytically for the
supplied layout. Alternatively, the score can be evaluated at a user-supplied
scale.
}
