Compute a weighted geometry-aware GRIP layout — globalrep.weighted.grip • grip

globalrep.weighted.grip() is the compatibility backend equivalent to grip(..., metric = "edge_length"). It runs the edge-length multiscale core, which uses edge lengths in the filtration, local neighborhoods, insertion, refinement forces, and optional in-core multiscale LGKK refinement.

Usage

globalrep.weighted.grip(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 3,
  placement = c("barycenter", "circle"),
  preset = NULL,
  rounds = 160,
  final.rounds = 384,
  num.init = 24,
  num.nbrs = 20,
  r = 0.03,
  s = 7.5,
  repulsion.factor = 2.5,
  coarse.repulsion.factor = 1.5,
  coarse.repulsion.sample = 16,
  coarse.repulsion.exact.below = 64,
  final.anchor.factor = 0,
  final.move.scale.after.first = 1,
  final.mode = c("fr", "kk_repulse"),
  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,
  lgkk.polish.rounds = 0L,
  lgkk.multiscale.rounds = 0L,
  lgkk.rounds.coarse = NULL,
  lgkk.rounds.pre.final = NULL,
  lgkk.rounds.final = NULL,
  lgkk.local.nbrs = 20L,
  lgkk.landmark.count = 8L,
  lgkk.multiscale.scope = c("all", "coarse"),
  lgkk.active.limit = 4096L,
  metric.neighbor.cap = NULL,
  length.normalization = c("median", "mean", "none"),
  tinit.factor = 6,
  seed = 6,
  disconnected = c("components", "error")
)

Arguments

edges: Two-column integer matrix of edges (1-based vertex ids). Supply either edges/edge.weights or adj.list/weight.list, not both. Fractional, nonfinite, and out-of-range vertex ids are rejected before integer conversion.
n: Number of vertices, a finite positive integer.
adj.list: Adjacency list (1-based) for undirected graphs.
weight.list: Parallel list of positive edge lengths for adj.list; required when adjacency-list input is used.
edge.weights: Positive edge lengths for edges, in row order; required when edge-list input is used.
dim: Layout dimension (2 or 3). Default is 3.
placement: Initial placement strategy. "circle" is only used for 2D.
preset: Optional weighted tuning preset. NULL uses the quality-first defaults for the weighted core. "mesh" targets rectangular and near-mesh weighted surfaces, "cylinder" targets cylindrical grids, "torus" targets wrapped surface grids, "sphere" targets closed near-spherical meshes, "irregular" targets irregular manifold-like weighted families, "tree" targets intrinsic weighted trees, and "carpet" keeps a high-neighborhood profile for carpet-like recursive lattices. Explicit tuning arguments override the preset field by field.
rounds: Initial rounds for refinement.
final.rounds: Final rounds for refinement.
num.init: Number of initial vertices in the coarsest level.
num.nbrs: Maximum number of graph-distance neighbors retained for local refinement at each filtration level.
r: Main local temperature adaptation rate in [0, 1].
s: Non-negative boost factor applied when successive displacements have a consistent direction.
repulsion.factor: Non-negative multiplier applied to GRIP's finest-level repulsive force scale.
coarse.repulsion.factor: Non-negative multiplier applied to the extra coarse-level active-set repulsion term. 0 disables that extra term; when the remaining tuning arguments also match legacy.grip(), the result matches the legacy layout behavior.
coarse.repulsion.sample: Positive integer sample size used to approximate active-set-wide repulsion on larger coarse levels.
coarse.repulsion.exact.below: Positive integer threshold. When the active set size is at most this value, the coarse repulsion is computed exactly against all currently active vertices instead of being sampled.
final.anchor.factor: Non-negative multiplier for an anchor term that pulls the final FR stage back toward the pre-final full-graph layout. 0 disables the anchor and preserves the current behavior.
final.move.scale.after.first: Scalar in [0, 1] applied to the final FR displacement after the first finest-level round. Values below 1 damp later full-graph movement while keeping the first FR round unchanged.
final.mode: Final full-graph refinement mode. "fr" keeps the current Fruchterman-Reingold-style final stage. "kk_repulse" uses a KK-style local distance-matching update with explicit active-set repulsion instead of the final FR phase.
insertion.anchor.count: Positive integer number of anchor vertices used during multiscale insertion on non-initial MISF refinement levels. This is the closest current implementation to a global K_mish parameter.
insertion.anchor.scope: Anchor-eligibility rule used during multiscale insertion. "any_higher" matches the historical GRIP behavior and allows anchors from any already placed higher MISF level. "prev_misf" restricts anchors to the immediately previous MISF level only.
insertion.anchor.strategy: Anchor-selection rule used during multiscale insertion. "first" keeps the historical first-anchors-found BFS behavior. "distance_band" keeps exploring until the K_mish-th anchor distance band is exhausted, then places the new vertex from that less order-sensitive anchor pool. "balanced_band" uses the same band expansion, then explicitly selects a subset whose centroid stays centered in the candidate cloud while remaining geometrically spread out. "spread_prev" is a symmetry-oriented band strategy intended to be paired with insertion.anchor.scope = "prev_misf"; it selects anchors with broad angular and geometric coverage before placement.
level0.insertion.mode: Level-0 insertion placement override used only when the finest filtration level is first populated. "inherit" keeps the current GRIP behavior. "barycenter" disables the 2D circle heuristic at level 0 and uses barycentric anchor placement. "least_squares" uses a multi-anchor least-squares distance fit at level 0 before any local micro-polish.
level0.anchor.count: Positive integer number of already placed anchors to collect for level-0 insertion experiments. By default this inherits insertion.anchor.count. The legacy behavior uses 3.
level0.local.kk.steps: Non-negative integer number of tiny local KK micro-polish steps applied immediately after each level-0 insertion. The legacy behavior uses 3.
lgkk.polish.rounds: Non-negative integer number of experimental landmark-geodesic KK polish iterations applied after the main GRIP solve. 0 disables the polish.
lgkk.multiscale.rounds: Non-negative integer number of compiled landmark-geodesic KK refinement rounds applied inside the multiscale solver after each eligible MISF level completes its standard GRIP rounds. This legacy shared budget is used as a fallback when any of the more specific per-stage budgets below are left NULL.
lgkk.rounds.coarse: Optional non-negative integer number of compiled LGKK rounds applied on coarse MISF levels with misf_level > 1. When NULL, this falls back to lgkk.multiscale.rounds.
lgkk.rounds.pre.final: Optional non-negative integer number of compiled LGKK rounds applied on the last coarse level just before the full graph is opened (misf_level == 1). When NULL, this falls back to lgkk.multiscale.rounds.
lgkk.rounds.final: Optional non-negative integer number of compiled LGKK rounds applied after the full graph level completes its standard GRIP rounds (misf_level == 0). When NULL, this falls back to lgkk.multiscale.rounds.
lgkk.local.nbrs: Number of nearest graph-metric neighbors retained per vertex in the LGKK sparse local set when either LGKK stage is enabled.
lgkk.landmark.count: Number of farthest-point landmarks retained per vertex in the LGKK sparse long-range set when either LGKK stage is enabled.
lgkk.multiscale.scope: Scope for the compiled multiscale LGKK stage. "all" applies it after every eligible MISF level, including the final full-graph level. "coarse" applies it only on coarse levels.
lgkk.active.limit: Positive integer upper bound on the active-set size for compiled multiscale LGKK cache construction. Levels larger than this skip the multiscale LGKK stage.
metric.neighbor.cap: Optional cap on the number of settled Dijkstra vertices used when building weighted neighborhood caches for inserted vertices. NULL (default) keeps the exact weighted neighborhood search, but now stops as soon as the required weighted neighbors and anchors are filled. Supplying a positive integer enables an approximate weighted neighborhood mode for larger graphs.
length.normalization: Global edge-length normalization: "median" (default), "mean", or "none".
tinit.factor: Initial temperature factor.
seed: Optional RNG seed for reproducibility. If NULL, uses current time.
disconnected: How to handle disconnected graphs: "components" (default) lays out each connected component separately and packs them into one coordinate matrix; "error" stops with an error.

Value

A numeric matrix with n rows and dim columns.

Examples

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