% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gmds_layout_interface.R
\name{edge.kk}
\alias{edge.kk}
\title{Optimize an edge-KK local repair layout}
\usage{
edge.kk(
  coords = NULL,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  dim = 2L,
  init = c("metric_mds", "weighted_grip", "random"),
  weighted.grip.args = list(),
  stiffness_method = c("density", "uniform", "distance_power"),
  stiffness_transform = c("identity", "sqrt", "log"),
  density_mix_schedule = c(0, 0.25, 0.5, 0.75, 1),
  bandwidth = NULL,
  density_n = 512L,
  distance_power = 0,
  stiffness_floor = 0,
  stiffness_ceiling = Inf,
  scale_mode = c("profiled", "identity", "fixed_initial", "user"),
  scale = NULL,
  max_iter = 50L,
  initial_step = 1,
  step_shrink = 0.5,
  armijo_factor = 1e-04,
  grad_tol = 1e-08,
  min_step = 1e-08,
  edge_length_epsilon = 1e-08,
  distance_floor = 1e-08,
  recenter = TRUE,
  return_trace = TRUE,
  diagnostics = TRUE,
  seed = 1L,
  engine = c("cpp", "R")
)
}
\arguments{
\item{coords}{Optional starting coordinates. If omitted, `init` is used.}

\item{prepared}{Optional object returned by [prepare.edge.kk()],
[prepare.graph.geodesic.mds()] or [prepare.geodesic.kk()].
Edge-only objects from [prepare.edge.kk()] report only edge
diagnostics; all-pairs GMDS path and chord diagnostics are unavailable.}

\item{edges}{Two-column edge matrix used when `prepared` is omitted.}

\item{n}{Number of vertices used when `prepared` is omitted.}

\item{adj_list}{Optional adjacency list used when `prepared` is omitted.}

\item{weight_list}{Optional edge-weight list parallel to `adj_list`.}

\item{edge_weights}{Optional positive edge weights parallel to `edges`.}

\item{dim}{Target embedding dimension.}

\item{init}{Starting layout used when `coords` is omitted. `"metric_mds"`
uses ordinary metric MDS from an all-pairs prepared object,
`"weighted_grip"` runs [grip()] with `metric = "edge_length"` on the
graph edges first, and
`"random"` uses centered Gaussian coordinates.}

\item{weighted.grip.args}{Named list of additional tuning arguments passed
to [grip()] when `init = "weighted_grip"`. Graph inputs, `dim`, `seed`,
and `metric` are supplied by `edge.kk()` and may not be repeated here.}

\item{stiffness_method, stiffness_transform, density_mix_schedule, bandwidth, density_n}{Parameters passed to [edge.length.density.stiffness()].}

\item{distance_power, stiffness_floor, stiffness_ceiling}{Additional stiffness
constructor parameters.}

\item{scale_mode}{Scale policy for edge targets. `"profiled"` analytically
refits `s` at every state evaluation, `"identity"` fixes `s = 1`,
`"fixed_initial"` fits `s` once at the first continuation stage, and
`"user"` uses `scale`.}

\item{scale}{User scale for `scale_mode = "user"`.}

\item{max_iter}{Maximum iterations per continuation stage.}

\item{initial_step, step_shrink, armijo_factor, grad_tol, min_step}{Line-search
controls.}

\item{edge_length_epsilon}{Small stabilizer for fixed-path embedded lengths.}

\item{distance_floor}{Positive floor for relative residuals.}

\item{recenter}{If `TRUE`, recenter the layout after accepted steps.}

\item{return_trace}{If `TRUE`, keep per-iteration trace rows and coordinate
frames. If `FALSE`, omit those payloads while retaining compact stage
summaries in `metadata$stage_summaries`.}

\item{diagnostics}{If `TRUE`, attach the common GMDS diagnostic panel.}

\item{seed}{Random seed used for `init = "weighted_grip"` and
`init = "random"`.}

\item{engine}{Optimizer engine. `"cpp"` uses the Rcpp backend for the
edge-stress loop; `"R"` uses the reference implementation.}
}
\value{
A `"grip_gmds_layout"` object with method `"edge_kk"`.
}
\description{
`edge.kk()` is the edge-restricted Kamada--Kawai local repair operator for
the experimental GMDS layout program. Earlier notes called this operator
edge-gKK or edge-isometric GMDS; edge-KK is the preferred name because the
objective is restricted to graph edges rather than all graph-geodesic pairs.
It minimizes weighted edge-length stress
\deqn{
  \frac{1}{2}\sum_{(i,j)\in E} k_{ij}
  \left(\|z_i-z_j\|_2 - s w_{ij}\right)^2
}
using deterministic gradient descent with Armijo backtracking. The default
`density_mix_schedule` runs a continuation from density-weighted stiffnesses
toward uniform stiffnesses.
}
\details{
For scalable repair from an existing layout, pass `coords` or an edge-only
object from [prepare.edge.kk()]. When raw graph inputs are supplied,
`edge.kk()` uses edge-only preparation whenever `coords` are supplied or
`init != "metric_mds"`. Use `init = "weighted_grip"` for a scalable
weighted-GRIP warm start followed by edge-KK polish. If `coords` is omitted
and `init = "metric_mds"`, use an all-pairs prepared object from
[prepare.graph.geodesic.mds()] or [prepare.geodesic.kk()] instead.
}
