Weighted GRIP layout in arbitrary dimensions

weighted.grip.nd() is an opt-in weighted GRIP layout backend for embeddings in dimensions dim >= 2. It is implemented beside the legacy 2D/3D GRIP code path so that existing weighted-GRIP entry points and their dimensionality checks are unchanged.

Usage

weighted.grip.nd(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 3,
  preset = NULL,
  placement = c("barycenter", "circle"),
  rounds = 160,
  final.rounds = 256,
  num.init = NULL,
  num.nbrs = 24,
  r = 0.03,
  s = 6,
  repulsion.factor = 1.5,
  tinit.factor = 2,
  final.move.scale.after.first = 1,
  final.mode = c("fr", "kk_repulse"),
  metric.neighbor.cap = NULL,
  insertion.anchor.count = 3,
  insertion.anchor.scope = c("any_higher", "prev_misf"),
  insertion.anchor.strategy = c("first", "distance_band", "balanced_band", "spread_prev"),
  level0.insertion.mode = c("inherit", "barycenter", "least_squares"),
  level0.anchor.count = insertion.anchor.count,
  level0.local.kk.steps = 3,
  length.normalization = c("median", "mean", "none"),
  disconnected = c("components", "error"),
  seed = 6
)

Arguments

edges: Two-column integer matrix of edges (1-based vertex ids).
n: Number of vertices.
adj.list: Adjacency list (1-based) for an undirected graph.
weight.list: Parallel list of strictly positive edge lengths.
edge.weights: Optional vector of edge lengths for edges.
dim: Embedding dimension. Must be at least 2.
preset: Optional weighted layout preset: "carpet", "mesh", "cylinder", "torus", "sphere", "irregular", or "tree".
placement: Initial insertion placement strategy. "circle" is only available for dim = 2; higher dimensions use "barycenter".
rounds: Number of weighted refinement rounds before the final phase.
final.rounds: Number of final weighted refinement rounds.
num.init: Coarsest-level size control. Defaults to at least dim + 1.
num.nbrs: Local-neighborhood control used by the ND backend.
r: Movement-rate parameter in [0, 1].
s: Repulsion scale parameter.
repulsion.factor: Non-edge repulsion multiplier.
tinit.factor: Initial spread multiplier.
final.move.scale.after.first: Final-stage FR displacement multiplier applied after the first final round. Must be in [0, 1].
final.mode: Final refinement mode: "fr" or "kk_repulse".
metric.neighbor.cap: Optional cap on the number of settled Dijkstra vertices used when building weighted neighborhood caches for inserted vertices. NULL keeps the exact weighted neighborhood search.
insertion.anchor.count: Number of already placed anchor vertices used when inserting non-final MISF levels.
insertion.anchor.scope: Anchor eligibility rule: "any_higher" or "prev_misf".
insertion.anchor.strategy: Anchor selection rule: "first", "distance_band", "balanced_band", or "spread_prev".
level0.insertion.mode: Level-0 insertion placement override: "inherit", "barycenter", or "least_squares".
level0.anchor.count: Number of anchors used during level-0 insertion.
level0.local.kk.steps: Number of local weighted-KK polish steps used immediately after level-0 insertion.
length.normalization: Global edge-length normalization: "median" (default), "mean", or "none".
disconnected: How to handle disconnected graphs: "components" lays out each component separately and packs them; "error" rejects disconnected graphs.
seed: Optional RNG seed for reproducibility. If NULL, uses current time.

Value

Numeric matrix with one row per vertex and dim columns.

Examples

cycle_edges <- edges.cycle(6)
cycle_lengths <- seq(0.8, 1.3, length.out = nrow(cycle_edges))
layout <- weighted.grip.nd(
  edges = cycle_edges, n = 6, edge.weights = cycle_lengths,
  dim = 4, rounds = 1, final.rounds = 1,
  num.init = 5, num.nbrs = 2, seed = 1
)