% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grip_quality.R
\name{landmark.geodesic.kk}
\alias{landmark.geodesic.kk}
\title{Optimize a layout under the landmark geodesic KK energy}
\usage{
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,
  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
)
}
\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{max_iter}{Maximum number of gradient-descent iterations.}

\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{initial_step}{Initial line-search step size.}

\item{step_shrink}{Multiplicative shrink factor in `(0, 1)` for backtracking.}

\item{armijo_factor}{Non-negative Armijo decrease constant.}

\item{grad_tol}{Non-negative stopping tolerance on the gradient norm.}

\item{min_step}{Positive minimum accepted line-search step before giving up.}

\item{recenter}{If \code{TRUE}, recenter the layout to zero mean after each
accepted step.}

\item{return_trace}{If \code{TRUE}, include per-iteration diagnostics and the
accepted intermediate coordinate frames.}
}
\value{
A list with \code{coords}, \code{trace}, \code{frames},
  \code{prepared}, and \code{score}.
}
\description{
\code{landmark.geodesic.kk()} applies a deterministic
warm-started gradient-descent polish under the sparse landmark geodesic KK
energy. It starts from an existing layout and refines it, rather than
replacing the full multiscale GRIP refinement pipeline.
}
\details{
The implementation fits the LGKK target scale \code{L0} once from the
starting layout and then optimizes against those fixed target path lengths.
That keeps the gradient simple and makes the resulting line search robust for
an initial implementation.
}
