`edge.kk()` is the edge-restricted Kamada–Kawai local repair operator for the experimental GMDS layout program. Earlier notes called this operator edge-gKK or edge-isometric GMDS; edge-KK is the preferred name because the objective is restricted to graph edges rather than all graph-geodesic pairs. It minimizes weighted edge-length stress $$ \frac{1}{2}\sum_{(i,j)\in E} k_{ij} \left(\|z_i-z_j\|_2 - s w_{ij}\right)^2 $$ using deterministic gradient descent with Armijo backtracking. The default `density_mix_schedule` runs a continuation from density-weighted stiffnesses toward uniform stiffnesses.
Usage
edge.kk(
coords = NULL,
prepared = NULL,
edges = NULL,
n = NULL,
adj_list = NULL,
weight_list = NULL,
edge_weights = NULL,
dim = 2L,
init = c("metric_mds", "weighted_grip", "random"),
weighted.grip.args = list(),
stiffness_method = c("density", "uniform", "distance_power"),
stiffness_transform = c("identity", "sqrt", "log"),
density_mix_schedule = c(0, 0.25, 0.5, 0.75, 1),
bandwidth = NULL,
density_n = 512L,
distance_power = 0,
stiffness_floor = 0,
stiffness_ceiling = Inf,
scale_mode = c("profiled", "identity", "fixed_initial", "user"),
scale = NULL,
max_iter = 50L,
initial_step = 1,
step_shrink = 0.5,
armijo_factor = 1e-04,
grad_tol = 1e-08,
min_step = 1e-08,
edge_length_epsilon = 1e-08,
distance_floor = 1e-08,
recenter = TRUE,
return_trace = TRUE,
diagnostics = TRUE,
seed = 1L,
engine = c("cpp", "R")
)Arguments
- coords
Optional starting coordinates. If omitted, `init` is used.
- prepared
Optional object returned by [prepare.edge.kk()], [prepare.graph.geodesic.mds()] or [prepare.geodesic.kk()]. Edge-only objects from [prepare.edge.kk()] report only edge diagnostics; all-pairs GMDS path and chord diagnostics are unavailable.
- edges
Two-column edge matrix used when `prepared` is omitted.
- n
Number of vertices used when `prepared` is omitted.
- adj_list
Optional adjacency list used when `prepared` is omitted.
- weight_list
Optional edge-weight list parallel to `adj_list`.
- edge_weights
Optional positive edge weights parallel to `edges`.
- dim
Target embedding dimension.
- init
Starting layout used when `coords` is omitted. `"metric_mds"` uses ordinary metric MDS from an all-pairs prepared object, `"weighted_grip"` runs [weighted.grip()] on the graph edges first, and `"random"` uses centered Gaussian coordinates.
- weighted.grip.args
Named list of additional tuning arguments passed to [weighted.grip()] when `init = "weighted_grip"`. Graph inputs, `dim`, and `seed` are supplied by `edge.kk()` and may not be repeated here.
- stiffness_method, stiffness_transform, density_mix_schedule, bandwidth, density_n
Parameters passed to [edge.length.density.stiffness()].
- distance_power, stiffness_floor, stiffness_ceiling
Additional stiffness constructor parameters.
- scale_mode
Scale policy for edge targets. `"profiled"` analytically refits `s` at every state evaluation, `"identity"` fixes `s = 1`, `"fixed_initial"` fits `s` once at the first continuation stage, and `"user"` uses `scale`.
- scale
User scale for `scale_mode = "user"`.
- max_iter
Maximum iterations per continuation stage.
- initial_step, step_shrink, armijo_factor, grad_tol, min_step
Line-search controls.
- edge_length_epsilon
Small stabilizer for fixed-path embedded lengths.
- distance_floor
Positive floor for relative residuals.
- recenter
If `TRUE`, recenter the layout after accepted steps.
- return_trace
If `TRUE`, keep per-iteration trace rows and coordinate frames. If `FALSE`, omit those payloads while retaining compact stage summaries in `metadata$stage_summaries`.
- diagnostics
If `TRUE`, attach the common GMDS diagnostic panel.
- seed
Random seed used for `init = "weighted_grip"` and `init = "random"`.
- engine
Optimizer engine. `"cpp"` uses the Rcpp backend for the edge-stress loop; `"R"` uses the reference implementation.
Details
For scalable repair from an existing layout, pass `coords` or an edge-only object from [prepare.edge.kk()]. When raw graph inputs are supplied, `edge.kk()` uses edge-only preparation whenever `coords` are supplied or `init != "metric_mds"`. Use `init = "weighted_grip"` for a scalable weighted-GRIP warm start followed by edge-KK polish. If `coords` is omitted and `init = "metric_mds"`, use an all-pairs prepared object from [prepare.graph.geodesic.mds()] or [prepare.geodesic.kk()] instead.