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.

Examples

mesh_edges <- edges.mesh(4, 4)
fit <- misf.geodesic.kk(
  edges = mesh_edges, n = 16, num_init = 4, dim = 2,
  top_level_restarts = 2, top_level_max_iter = 3,
  insertion_mode = "geodesic", insertion_max_iter = 6,
  refinement_pair_mode = "auto", refinement_full_limit = 4,
  refinement_max_iter = 3, final_pair_mode = "landmark",
  final_full_limit = 4, final_max_iter = 3,
  return_trace = TRUE, seed = 1
)