Optimize an embedding with the MISF-based geodesic-KK pipeline

`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.

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

prepared: Optional prepared object. This can be either a full geodesic-KK prepared object or a MISF-GKK prepared object.
edges: Two-column integer matrix of edges (1-based vertex ids).
n: Number of vertices. If omitted with `adj_list`, defaults to `length(adj_list)`. If omitted with `edges`, defaults to `max(edges)`.
adj_list: Adjacency list (1-based) for an undirected graph.
weight_list: Optional parallel list of positive edge weights.
edge_weights: Optional positive edge-weight vector parallel to `edges`.
tie_mode: Shortest-path aggregation mode inherited from [prepare.geodesic.kk()].
num_init: Target top-level active-set size passed to `build.misf`.
num_nbrs: Per-level local-neighborhood schedule metadata passed to `build.misf`.
dim: Target embedding dimension (`2` or `3`) for the multiscale solve.
top_level_pair_mode: Optional override for the top-level pair policy.
top_level_full_limit: Optional override for the top-level exact/sparse threshold.
top_level_local_nbrs: Optional override for the sparse top-level local neighborhood size.
top_level_landmark_count: Optional override for the sparse top-level landmark count.
top_level_restarts: Number of top-level restarts used by the coarse MISF-GKK solve.
top_level_max_iter: Top-level iteration budget.
top_level_init: Optional override for the top-level initializer.
insertion_anchor_policy: Optional insertion anchor policy.
insertion_anchor_count: Optional insertion anchor count.
insertion_anchor_weight_mode: Optional insertion anchor weighting mode.
insertion_max_iter: Optional per-vertex insertion iteration budget.
insertion_mode: Optional insertion warm-start mode.
insertion_layout_k: Optional active-level layout graph size used by layout-based insertion modes.
insertion_weighted_preset: Optional preset passed to weighted GRIP insertion.
insertion_grip_args: Optional named list of extra arguments passed to combinatorial GRIP insertion.
insertion_weighted_args: Optional named list of extra arguments for weighted GRIP insertion.
insertion_fr_niter: Optional FR iteration budget for FR-based insertion.
refinement_pair_mode: Optional active-level pair policy.
refinement_full_limit: Optional active-level exact/sparse threshold.
refinement_local_nbrs: Optional active-level sparse local neighborhood size.
refinement_landmark_count: Optional active-level sparse landmark count.
refinement_anchor_weight: Optional initial anchor weight used to pin inactive and coarser-level vertices during KK refinement.
refinement_anchor_weight_end: Optional final anchor weight used at the end of the active-level continuation schedule.
refinement_continuation: Optional continuation schedule used for the active-level anchor penalty.
refinement_max_iter: Optional active-level refinement iteration budget.
final_pair_mode: Optional final full-graph pair policy.
final_full_limit: Optional final full-graph exact/sparse threshold.
final_local_nbrs: Optional final full-graph sparse local neighborhood size.
final_landmark_count: Optional final full-graph sparse landmark count.
final_max_iter: Optional final polish iteration budget.
stiffness: Global stiffness constant \(K\).
distance_floor: Small positive floor used in k_ij = K / max(g_ij, distance_floor)^2.
edge_length_epsilon: Small positive stabilizer added inside each embedded edge length.
initial_step: Initial line-search step size.
step_shrink: Multiplicative shrink factor in `(0, 1)` for backtracking.
armijo_factor: Non-negative Armijo decrease constant.
grad_tol: Non-negative stopping tolerance on the gradient norm.
min_step: Positive minimum accepted line-search step before giving up.
recenter: If `TRUE`, recenter accepted proposals to zero mean after each accepted step.
return_trace: If `TRUE`, retain detailed stage traces.
return_frames: If `TRUE`, retain intermediate coordinate frames.
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.