grip (version 0.2.0)

repulsive.state: Evaluate a pure repulsive layout objective

Description

`repulsive.state()` evaluates only the repulsion term used by the experimental GMDS repulsive-unfolding operators. Unlike [edge.repulsive.state()], this function has no graph-edge term and does not require placeholder edges or edge lengths.

Usage

repulsive.state(
  coords,
  lambda = 1,
  pair.index = NULL,
  pair.weights = NULL,
  repulsion.family = c("log", "inverse_power"),
  repulsion.delta = 0.001,
  repulsion.power = 1,
  distance.eps = 1e-10,
  engine = c("cpp", "R")
)

Value

A list containing energy, unscaled repulsion energy, gradient, gradient norm, and embedded pair lengths.

Arguments

coords

Numeric `n` by `dim` coordinate matrix.

lambda

Repulsion strength. The returned total energy is `lambda * repel.energy`; the gradient is scaled by `lambda`.

pair.index

Optional two-column matrix of 1-based vertex pairs. If `NULL` and `lambda > 0`, all unordered pairs are used.

pair.weights

Optional non-negative pair weights parallel to `pair.index`.

repulsion.family

Repulsion potential family, either `"log"` or `"inverse_power"`.

repulsion.delta

Small positive softening parameter for pair distances.

repulsion.power

Power used by the `"inverse_power"` repulsion.

distance.eps

Small positive distance floor used in derivatives.

engine

Backend engine. `"cpp"` is the default; `"R"` uses the reference implementation.

Examples

theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
state <- repulsive.state(coords, lambda = 0.1, engine = "R")