graphology-layout-physics

Vis-style physics layout for graphology: FA2 linear repulsion, Hooke springs with rest length, and velocity damping integration (à la vis-network).

Install

pnpm add graphology-layout-physics
# peer: graphology

Synchronous layout

import Graph from 'graphology';
import layoutPhysics from 'graphology-layout-physics';

const graph = new Graph();
// nodes must have x, y set beforehand

const positions = layoutPhysics(graph, {
  iterations: 500,
  settings: layoutPhysics.inferSettings(graph)
});

layoutPhysics.assign(graph, {iterations: 500});

Worker (continuous)

Uses a Blob URL worker (createWorker(fn)), same pattern as graphology-layout-forceatlas2.

import LayoutPhysics from 'graphology-layout-physics/worker';

const layout = new LayoutPhysics(graph, {settings: {damping: 0.4}});
layout.start();
layout.stop();
layout.isStabilized();
layout.kill();

Force model notes

• charge (q = 1 + \sum w): used for repulsion and central gravity strength (FA2-style).
• mass (inertial, default 1, or node attribute mass): used only in (a = (F - \texttt{damping}\cdot v) / m).

Default settings

| Setting | Default | Role | |---------|---------|------| | springLength | 100 | Edge rest length | | springConstant | 0.08 | Spring stiffness | | scalingRatio | 10 | Linear repulsion strength | | gravity | 0.01 | Central gravity | | damping | 0.4 | Velocity damping | | timestep | 0.5 | Integration step | | maxVelocity | 50 | Speed clamp | | minVelocity | 0.75 | Stabilization threshold | | barnesHutOptimize | false | O(n log n) repulsion | | autoStop | true | Worker stops when stabilized |

Debug / energy diagnostics

Energy tooling lives on a separate entry so production imports stay clean:

import layoutPhysics from 'graphology-layout-physics';
import diagnose, {
  computeGraphEnergy
} from 'graphology-layout-physics/debug';

// Production layout
layoutPhysics.assign(graph, {
  iterations: 500,
  settings: layoutPhysics.inferSettings(graph)
});

// Debug: same options shape — swap the import to sample energy each step
const report = diagnose(graph, {
  iterations: 500,
  settings: diagnose.inferSettings(graph)
  // sampleEvery: 10  // optional downsample for large graphs
});
// report.samples, report.e0, report.eFinal, report.stabilized, ...

diagnose.assign(graph, {iterations: 500}); // also writes positions back
const e = computeGraphEnergy(graph, {settings: {damping: 0.4}});

Energy convergence diagnostic

Running npm test evaluates a deterministic 128-node graph via graphology-layout-physics/debug and writes test-results/energy-convergence.svg. The SVG plots total mechanical energy and maximum node speed for every iteration, together with stabilization and energy-monotonicity statistics.