Compute a GRIP layout with coarse global repulsion

This compatibility entry point is equivalent to grip(..., metric = "hop"). It keeps the old global-repulsion name available 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). 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

Optional parallel list of positive edge lengths for adj.list. NULL treats every edge as length 1.

edge.weights

Optional positive edge lengths for edges, in row order. NULL treats every edge as length 1.

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