Prepare a MISF-based multiscale geodesic-KK object

`prepare.misf.geodesic.kk()` builds the prepared state for a MISF-based geodesic-KK pipeline by layering the maximal independent set filtration (MISF) on top of the existing full geodesic-KK cache. The prepared object stores the graph metadata, the coarsest admissible top-level graph, the exact and sparse top-level prepared caches, and the default controls used by the multiscale MISF-GKK optimizer.

Usage

prepare.misf.geodesic.kk(
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  tie_mode = c("single", "average"),
  num_init = 24L,
  num_nbrs = 20L,
  dim = 2L,
  top_level_mode = c("solve", "skip"),
  top_level_pair_mode = c("auto", "full", "landmark"),
  top_level_full_limit = 512L,
  top_level_local_nbrs = 20L,
  top_level_landmark_count = 8L,
  top_level_restarts = 8L,
  top_level_max_iter = 16L,
  top_level_init = c("geometric", "cmdscale", "random"),
  seed = 6L
)

Arguments

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_mode

Either `"solve"` or `"skip"`. When set to `"solve"`, the coarsest admissible MISF level is optimized immediately and stored in `prepared$top_level_fit`.

top_level_pair_mode

Pair policy for the top MISF level: `"auto"`, `"full"`, or `"landmark"`.

top_level_full_limit

Active-set size threshold used when `top_level_pair_mode = "auto"`.

top_level_local_nbrs

Number of nearest graph-metric neighbors retained per vertex in the sparse top-level LGKK cache.

top_level_landmark_count

Number of farthest-point landmarks retained per vertex in the sparse top-level LGKK cache.

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

Top-level initializer (`"geometric"`, `"cmdscale"`, or `"random"`).

seed

Optional integer seed reused for MISF extraction.

Value

An object of class `"grip_misf_gkk_prepared"` layered on top of the full geodesic-KK prepared structure, with added MISF metadata, top-level coarse-graph caches, and stored default controls for the MISF-GKK optimizer.

Examples

edges <- edges.mesh(4, 4)
prepared <- prepare.misf.geodesic.kk(
  edges = edges,
  n = 16,
  tie_mode = "average",
  num_init = 4,
  top_level_mode = "skip",
  seed = 1
)
prepared$top_level_vertices
#> [1] 12  1 13