D3.js forceSimulation Coordinate Update Algorithm and Execution Functions

Explains the coordinate update algorithm and execution functions of D3.js forceSimulation.
Tags:

For settings related to interaction forces between nodes, see here. For link settings, see here.

Coordinate Update Information

In D3.js forceSimulation, if the origin is (0, 0) and the amount of position change in one step is (vx, vy), the following function calculates the position change.

function force(alpha) {
  for (var i = 0, n = nodes.length, node, k = alpha * 0.1; i < n; ++i) {
    node = nodes[i];
    node.vx -= node.x * k;
    node.vy -= node.y * k;
  }
}

It updates the coordinates by multiplying the distance from the origin, or the specified x and y, by alpha * 0.1. If alpha is 1, the node moves 10% closer to the origin each time.

Also, alpha is updated by adding the following expression at each simulation step.

( alphaTarget – alpha ) * alphaDecay

The default alphaTarget is 0, and alphaDecay is 0.0228, so alpha gradually decreases. When this alpha falls below alphaMin, whose default value is 0.001, the simulation stops. By default, the setting performs about 300 iterations. You can control these settings and simulation execution with the following functions.

Simulation Execution Functions

Function Description
simulation.restart() Restarts the simulation.
Use this when you want to start a stopped simulation during an event such as dragging.
simulation.stop() Stops the simulation.
If it is already stopped, nothing happens.
simulation.tick() An internal function of the simulation.
It is called when the simulation is created or by restart().
simulation.node() Specifies nodes.
See here for usage.
simulation.alpha() Sets the value of alpha between 0.0 and 1.0.
The default value is 1.
If no value is specified, the current alpha value is returned.
simulation.alphaMin() Sets the value of alphaMin between 0.0 and 1.0.
The default value is 0.001.
If no value is specified, the current alpha value is returned.
The simulation stops when the current alpha is less than alphaMin.
simulation.alphaDecay() Sets the value of alphaDecay between 0.0 and 1.0.
The default value is 0.0228(=1-pow(0.001, 1/300)).
If no value is specified, the current alphaDecay value is returned.
The larger alphaDecay is, the faster the simulation converges, but it may remain in a local solution.
Reducing alphaDecay makes the simulation take longer, but it converges to a better layout.
To keep the simulation running permanently, set alphaDecay to 0 or set alphaTarget to a value greater than alphaMin.
simulation.alphaTarget() Sets the value of alphaTarget between 0.0 and 1.0.
The default value is 0.
If no value is specified, the current alphaTarget value is returned.
simulation.velocityDecay() Sets the node velocity decay coefficient.
You can set a value from 0.0 to 1.0.
If no value is set, the current velocity decay coefficient is returned.
The default value is 0.4.
The current velocity is multiplied by (1 - velocityDecay), and the larger the value, the greater the velocity decay.
If set to 0, nodes continue oscillating; if set to 1, velocity does not change.
simulation.force() Sets interaction between nodes and links.
For nodes, see here, and for links, see here.
simulation.find(x,y[,radius]) Returns the node closest to position (x, y) within the specified search radius.
If radius is not specified, the search radius is infinite.
If there are no nodes in the search area, it returns undefined.
simulation.on(typenames, [listener]) Registers an event listener.
If an event listener with the same type and name is already registered, the new listener overwrites it.
If listener is null, the event listener is removed.
typenames can be "tick" or "end".
  • tick: simulation step update time
  • end: when the simulation completes (alpha < alphaMin)

Appendix: Terms

decay

  1. [noun] decay, corrosion
  2. [noun] decline or deterioration of a social system, etc.
  3. [verb] to decay or rot; to make something decay or rot
  4. [verb] for a building or area to deteriorate

velocity

  1. [noun][technical term] speed
  2. [noun][formal] high speed

tick

  1. [verb] to tick
  2. [verb] to mark with a check
  3. [noun] check mark
  4. [noun] tick