% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grip_geodesic_misf_kk.R
\name{misf.geodesic.kk}
\alias{misf.geodesic.kk}
\title{Optimize an embedding with the MISF-based geodesic-KK pipeline}
\usage{
misf.geodesic.kk(
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  tie_mode = NULL,
  num_init = 24L,
  num_nbrs = 20L,
  dim = NULL,
  top_level_pair_mode = NULL,
  top_level_full_limit = NULL,
  top_level_local_nbrs = NULL,
  top_level_landmark_count = NULL,
  top_level_restarts = NULL,
  top_level_max_iter = NULL,
  top_level_init = NULL,
  insertion_anchor_policy = NULL,
  insertion_anchor_count = NULL,
  insertion_anchor_weight_mode = NULL,
  insertion_max_iter = NULL,
  insertion_mode = NULL,
  insertion_layout_k = NULL,
  insertion_weighted_preset = NULL,
  insertion_grip_args = NULL,
  insertion_weighted_args = NULL,
  insertion_fr_niter = NULL,
  refinement_pair_mode = NULL,
  refinement_full_limit = NULL,
  refinement_local_nbrs = NULL,
  refinement_landmark_count = NULL,
  refinement_anchor_weight = NULL,
  refinement_anchor_weight_end = NULL,
  refinement_continuation = NULL,
  refinement_max_iter = NULL,
  final_pair_mode = NULL,
  final_full_limit = NULL,
  final_local_nbrs = NULL,
  final_landmark_count = NULL,
  final_max_iter = NULL,
  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,
  return_frames = FALSE,
  seed = 6L
)
}
\arguments{
\item{prepared}{Optional prepared object. This can be either a full
geodesic-KK prepared object or a MISF-GKK prepared object.}

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

\item{n}{Number of vertices. If omitted with `adj_list`, defaults to
`length(adj_list)`. If omitted with `edges`, defaults to `max(edges)`.}

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

\item{tie_mode}{Shortest-path aggregation mode inherited from
[prepare.geodesic.kk()].}

\item{num_init}{Target top-level active-set size passed to `build.misf`.}

\item{num_nbrs}{Per-level local-neighborhood schedule metadata passed to
`build.misf`.}

\item{dim}{Target embedding dimension (`2` or `3`) for the multiscale solve.}

\item{top_level_pair_mode}{Optional override for the top-level pair policy.}

\item{top_level_full_limit}{Optional override for the top-level exact/sparse
threshold.}

\item{top_level_local_nbrs}{Optional override for the sparse top-level local
neighborhood size.}

\item{top_level_landmark_count}{Optional override for the sparse top-level
landmark count.}

\item{top_level_restarts}{Number of top-level restarts used by the coarse
MISF-GKK solve.}

\item{top_level_max_iter}{Top-level iteration budget.}

\item{top_level_init}{Optional override for the top-level initializer.}

\item{insertion_anchor_policy}{Optional insertion anchor policy.}

\item{insertion_anchor_count}{Optional insertion anchor count.}

\item{insertion_anchor_weight_mode}{Optional insertion anchor weighting mode.}

\item{insertion_max_iter}{Optional per-vertex insertion iteration budget.}

\item{insertion_mode}{Optional insertion warm-start mode.}

\item{insertion_layout_k}{Optional active-level layout graph size used by
layout-based insertion modes.}

\item{insertion_weighted_preset}{Optional preset passed to weighted GRIP
insertion.}

\item{insertion_grip_args}{Optional named list of extra arguments passed to
combinatorial GRIP insertion.}

\item{insertion_weighted_args}{Optional named list of extra arguments for
weighted GRIP insertion.}

\item{insertion_fr_niter}{Optional FR iteration budget for FR-based
insertion.}

\item{refinement_pair_mode}{Optional active-level pair policy.}

\item{refinement_full_limit}{Optional active-level exact/sparse threshold.}

\item{refinement_local_nbrs}{Optional active-level sparse local neighborhood
size.}

\item{refinement_landmark_count}{Optional active-level sparse landmark count.}

\item{refinement_anchor_weight}{Optional initial anchor weight used to pin
inactive and coarser-level vertices during KK refinement.}

\item{refinement_anchor_weight_end}{Optional final anchor weight used at the
end of the active-level continuation schedule.}

\item{refinement_continuation}{Optional continuation schedule used for the
active-level anchor penalty.}

\item{refinement_max_iter}{Optional active-level refinement iteration budget.}

\item{final_pair_mode}{Optional final full-graph pair policy.}

\item{final_full_limit}{Optional final full-graph exact/sparse threshold.}

\item{final_local_nbrs}{Optional final full-graph sparse local neighborhood
size.}

\item{final_landmark_count}{Optional final full-graph sparse landmark count.}

\item{final_max_iter}{Optional final polish iteration budget.}

\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 `TRUE`, recenter accepted proposals to zero mean after
each accepted step.}

\item{return_trace}{If `TRUE`, retain detailed stage traces.}

\item{return_frames}{If `TRUE`, retain intermediate coordinate frames.}

\item{seed}{Optional integer seed reused for MISF extraction.}
}
\value{
A list with `coords`, `prepared`, the per-stage multiscale results,
  the stage trace, optional trace/frame details, timing, and the final MISF
  score summary.
}
\description{
`misf.geodesic.kk()` runs a multiscale MISF-based geodesic-KK
pipeline. It solves the top MISF graph with either full GKK or sparse LGKK,
inserts lower-level vertices with the existing MISF placement helpers, refines
each active MISF level under a GKK/LGKK objective, and finishes with a final
full-graph polish.
}
