% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gmds_kernel_gram_gkk.R
\name{kernel.gram.gkk}
\alias{kernel.gram.gkk}
\title{Optimize a kernel Gram-gKK layout}
\usage{
kernel.gram.gkk(
  coords = NULL,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  X = NULL,
  star = NULL,
  dim = 2L,
  init = c("metric_mds", "random"),
  angle.power = 4,
  reliability = c("length.balance", "none"),
  min.angle.weight = 0,
  star.quantile = 0,
  lambda.edge = 1,
  lambda.gram = 1,
  stiffness_method = c("density", "uniform", "distance_power"),
  stiffness_transform = c("identity", "sqrt", "log"),
  density_mix = 1,
  bandwidth = NULL,
  density_n = 512L,
  distance_power = 0,
  stiffness_floor = 0,
  stiffness_ceiling = Inf,
  scale_mode = c("profiled", "identity", "user"),
  scale = NULL,
  max_iter = 50L,
  initial_step = 0.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{X}{Optional ambient/source coordinates used to build `star` when `star`
is omitted.}

\item{star}{Optional object from [graph.riemannian.star.structure()].}

\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 and `"random"`
uses centered Gaussian coordinates.}

\item{angle.power, reliability, min.angle.weight}{Passed to
[graph.riemannian.star.structure()] when `star` is omitted.}

\item{star.quantile}{Optional quantile filter passed to
[graph.riemannian.star.structure()] when `star` is omitted.}

\item{lambda.edge, lambda.gram}{Non-negative weights for the diagonal
edge-length and off-diagonal Gram penalties.}

\item{stiffness_method, stiffness_transform, density_mix, bandwidth, density_n}{Parameters passed to [edge.length.density.stiffness()] to construct
edge-length stiffnesses for the diagonal edge term.}

\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.}

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

\item{seed}{Random seed used only for `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 `"kernel_gram_gkk"`.
}
\description{
`kernel.gram.gkk()` extends edge-only gKK with a local
Riemannian star penalty. The off-diagonal Gram term preserves target inner
products between pairs of incident edge directions:
\deqn{
  \frac{\lambda_{\mathrm{gram}}}{2}\sum_{u}\sum_{v<v'\in N(u)}
  \omega_u(v,v')\left(
  \langle z_v-z_u,z_{v'}-z_u\rangle
  - s^2 w_{uv}w_{uv'}\cos\alpha_u(v,v')\right)^2.
}
The star weights are built by [graph.riemannian.star.structure()], usually
with an antipodal kernel controlled by `angle.power`.
}
