Compute a GRIP layout with coarse global repulsion

This compatibility entry point is an alias of grip(). It keeps the old global-repulsion name available during the API migration, while using the same quality-first multiscale GRIP engine and adaptive final_rounds schedule as the primary layout API.

Usage

globalrep.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,
  tinit_factor = 6,
  seed = 6,
  disconnected = c("components", "error")
)

Arguments

edges: Two-column integer matrix of edges (1-based vertex ids).
n: Number of vertices.
adj_list: Adjacency list (1-based) for undirected graphs.
weight_list: Optional parallel list of edge weights (edge lengths). If NULL, all edges are treated as weight 1. All weights must be finite and strictly positive.
edge_weights: Optional vector of edge weights for edges. All weights must be finite and strictly positive.
dim: Layout dimension (2 or 3). Default is 3.
placement: Initial placement strategy. "circle" is only used for 2D.
preset: Optional tuning preset. NULL uses the quality-first defaults. "carpet" applies a preset tuned for Sierpinski-carpet-like graphs and validated on carpet levels 3 and 4. "mesh" applies a preset tuned for rectangular lattice graphs and validated on 8x8 and 12x12 mesh layouts. "torus" applies a preset tuned for 3D torus layouts and validated on torus sizes from 8x8 through 20x20. "tree" applies a preset tuned for symmetric force-directed layouts of tree-like graphs and validated on binary trees of depths 5 and 6. Presets only fill in tuning arguments that you did not supply explicitly.
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.
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

edges <- edges.mesh(4, 4)
coords <- globalrep.grip(edges, n = max(edges), dim = 2,
                                rounds = 8, final_rounds = 8,
                                num_init = 6, num_nbrs = 8,
                                coarse_repulsion_factor = 0.2,
                                coarse_repulsion_sample = 8,
                                coarse_repulsion_exact_below = 32,
                                seed = 1)
round(coords, 3)
#>          [,1]    [,2]
#>  [1,] -30.381  11.534
#>  [2,] -34.778  28.115
#>  [3,] -41.766  45.130
#>  [4,] -51.024  69.776
#>  [5,] -11.076  20.481
#>  [6,]  -9.886  48.386
#>  [7,] -18.109  49.605
#>  [8,] -22.313  67.137
#>  [9,]  -2.743   0.128
#> [10,]   4.240  15.684
#> [11,]   7.425  37.568
#> [12,]   3.373  59.540
#> [13,]  20.785 -19.658
#> [14,]  17.578  -1.038
#> [15,]  29.872  28.742
#> [16,]  32.344  48.595