d3-force

…

Installing

If you use NPM, npm install d3-force. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0 alpha. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3_force global is exported:

<script src="https://d3js.org/d3-collection.v0.1.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v0.4.min.js"></script>
<script src="https://d3js.org/d3-quadtree.v0.7.min.js"></script>
<script src="https://d3js.org/d3-timer.v0.4.min.js"></script>
<script src="https://d3js.org/d3-force.v0.3.min.js"></script>
<script>

var simulation = d3_force.forceSimulation(nodes);

</script>

Try d3-force in your browser.

API Reference

…

Simulation

…

# d3.forceSimulation([nodes])

Creates a new velocity Verlet simulator with the specified array of nodes and no forces. If nodes is not specified, it defaults to the empty array. The simulator starts automatically; if you wish to run the simulation manually, call simulation.stop, and then call simulation.tick as desired.

# simulation.restart()

…

# simulation.stop()

…

# simulation.tick()

Invokes each registered force, passing the current alpha; then updates the positions and velocities of each node according to the following formula: velocity *= 1 - drag, position += velocity. Returns true if the current alpha is less than alphaMin, indicating that the simulation would normally stop after this tick, and false otherwise.

The current alpha is defined as exp(iteration × alphaDecay) where iteration is the number of times this method can be called since the simulation started. Thus, the exact number of iterations needed to terminate the simulation naturally is ⌈log(alphaMin) / -alphaDecay⌉. For example:

for (var i = 0, n = Math.ceil(Math.log(simulation.alphaMin()) / -simulation.alphaDecay()); i < n; ++i) {
  simulation.tick();
}

Manual invocation is useful for computing static layouts, such as in a background web worker or on the server.

This method does not dispatch events; events are only dispatched by the internal timer when the simulation is started automatically upon creation or by calling simulation.restart.

# simulation.nodes([nodes])

…

• index - the node’s zero-based index into nodes
• x - the node’s current x-position
• y - the node’s current y-position
• vx - the node’s current x-velocity
• vy - the node’s current y-velocity

# simulation.alphaMin([alpha])

…

# simulation.alphaDecay([decay])

…

# simulation.drag([drag])

…

# simulation.force(name[, force])

…

# simulation.on(typenames, [callback])

…

Forces

A force is simply a function that modifies nodes’ positions or velocities; in this context, a force can apply a classical physical force such as electrical charge or gravity, or it can resolve a geometric constraint, such as keeping nodes within a bounding box or keeping links nodes a fixed distance apart. For example, a simple positioning force that moves nodes towards the origin ⟨0,0⟩ might be implemented as:

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;
  }
}

Forces typically read the node’s current position ⟨x,y⟩ and then add to (or subtract from) the node’s current velocity ⟨vx,vy⟩. However, forces may also “peek ahead” to the predicted next position of the node, ⟨x + vx,y + vy⟩, which is useful for geometric constraints that are resolved through iterative relaxation. Forces may also modify the position directly, which is sometimes useful to avoid adding energy (instability) to the simulation, such as when recentering the simulation in the viewport.

Simulations typically compose multiple forces as desired. This module provides several for your enjoyment:

• Centering
• Circle Collision
• Circle Containment
• Links
• Many-Body
• Positioning

Forces may optionally implement force.initialize to receive the simulation’s array of nodes.

# force(alpha)

Applies this force, optionally observing the specified alpha. Typically, the force is applied to the array of nodes previously passed to force.initialize, however, some forces may apply to a subset of nodes, or behave differently. For example, d3.forceLink applies to the source and target of each link.

# force.initialize(nodes)

… This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes. A force may perform any necessary work during initialization, such as evaluating per-node parameters, rather than performing that work for each application of the force.

Centering

The centering force moves nodes so that their center of mass (assuming all nodes are equal-weight) is at the given position ⟨x,y⟩. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceCenter([x, y])

…

# center.x([x])

…

# center.y([y])

…

Circle Collision

The circle collision force prevents circular nodes with a given radius from overlapping. More formally, two nodes a and b are separated so that the distance between a and b is at least radius(a) + radius(b). To reduce jitter, this is by default a “soft” constraint with a configurable strength. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceCollide([radius])

…

# collide.radius([radius])

…

# collide.strength([strength])

…

# collide.iterations([iterations])

…

Circle Containment

The circle containment force constrains nodes to fit within a circle of a given radius and center ⟨x,y⟩. The radius and center can be specified on a per-node basis. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceContain([radius[, x, y]])

…

# contain.radius([radius])

…

# contain.x([x])

…

# contain.y([y])

…

Links

The link force pushes linked nodes closer together or farther apart according to the desired link distance, which may be specified on a per-node basis. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceLink([links])

…

# link.links([links])

…

• index - the zero-based index into links
• source - the link’s source node; see simulation.nodes
• target - the link’s target node; see simulation.nodes

The source and target properties may be initialized using link.id.

# link.id([id])

…

# link.distance([distance])

…

# link.strength([strength])

…

# link.iterations([iterations])

…

Many-Body

The many-body (or n-body) force applies mutally amongst all nodes. It can be used to simulate gravity (attraction) if the strength is positive, or eletrical charge (repulsion) if the strength is negative. This implementation uses quadtrees and the Barnes–Hut approximation to greatly improve performance; the accuracy can be customized using the theta parameter. The strength can be specified on a per-node basis. (This parameter is only recomputed when the force is initialized, not on every application.)

# d3.forceManyBody()

…

# manyBody.strength([strength])

…

# manyBody.theta([theta])

…

# manyBody.distanceMin([distance])

…

# manyBody.distanceMax([distance])

…

Positioning

The positioning force pushes nodes towards a desired position ⟨x,y⟩. The position and strength can be specified on a per-node basis. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forcePosition([x, y])

…

# position.strength([strength])

…

# position.x([x])

…

# position.y([y])

…