grip (version 0.2.0)

edge.repulsive.state: Evaluate an edge-isometric repulsive unfolding objective

Description

`edge.repulsive.state()` evaluates an experimental GMDS objective that combines an edge-isometric term with a configurable repulsion term. The edge term penalizes deviation of embedded edge lengths from graph edge lengths. The repulsion term can be evaluated on all vertex pairs or on a selected pair set.

Usage

edge.repulsive.state(
  coords,
  edges,
  edge.lengths,
  edge.weights = NULL,
  edge.family = c("quadratic", "upper_barrier"),
  eps.plus = 0.35,
  beta = 0,
  lambda = 0,
  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 total energy, edge and repulsion energies, gradient, gradient norm, feasibility flag, embedded edge lengths, relative edge lengths, edge residuals, and number of upper-barrier wall violations.

Arguments

coords

Numeric `n` by `dim` coordinate matrix.

edges

Integer or numeric matrix with two columns containing 1-based graph edge endpoints.

edge.lengths

Numeric vector of target edge lengths, parallel to `edges`.

edge.weights

Optional non-negative edge weights. Defaults to one.

edge.family

Edge potential family, either `"quadratic"` or `"upper_barrier"`.

eps.plus

Upper-barrier slack parameter.

beta

Upper-barrier strength. When `beta <= 0`, the edge potential is quadratic.

lambda

Repulsion strength.

pair.index

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

pair.weights

Optional 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.

Details

The default `engine = "cpp"` uses the compiled backend. `engine = "R"` keeps a reference implementation available for diagnostics and regression tests.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
state <- edge.repulsive.state(
  coords, cycle_edges, rep(1, nrow(cycle_edges)),
  lambda = 0.1, engine = "R"
)