repository·main·Indexed 24 days ago
https://github.com/d3/d3-forceA physical simulation engine for D3 that uses a velocity Verlet integrator to simulate forces acting on particles. It is designed for visualizing complex structures like networks and hierarchies, or managing spatial layouts such as collision detection in bubble charts. The library provides functions for creating simulations via forceSimulation and applying various forces including forceManyBody, forceCollide, forceLink, forceRadial, forceCenter, forceX, and forceY.
To create a new force simulation, call the default export of d3-force with an array of node objects. The simulation manages the lifecycle of these nodes, applying forces and updating their positions over time.
Nodes in the array should ideally contain x and y properties. If they are missing or NaN, the simulation will automatically initialize them using a default spiral pattern.
.nodes(nodes) method allows you to get or set the array of nodes used by the simulation. If you provide a new array, the simulation will re-initialize the nodes and re-initialize all existing forces.The simulation emits events that you can listen to using the .on(name, listener) method. The two primary events are:
tick: Fired on every step of the simulation. The listener receives the simulation object.end: Fired when the alpha value falls below alphaMin. The listener receives the simulation object.Use simulation.find(x, y, radius) to find the node closest to the specified (x, y) coordinates within a given radius. If radius is not provided, it defaults to Infinity.
Returns the closest node object, or undefined if no node is within the radius.
The simulation uses an alpha parameter to control the 'temperature' or intensity of the simulation. As the simulation runs, alpha decays toward alphaTarget. When alpha falls below alphaMin, the simulation automatically stops.
Use the following methods to tune the simulation behavior:
alpha(value): Sets the current intensity.alphaMin(value): Sets the threshold below which the simulation stops.alphaDecay(value): Sets the rate at which alpha decreases.alphaTarget(value): Sets the value that alpha decays toward.The simulation runs using an internal timer. Use these methods to control its execution:
restart(): Restarts the timer, resuming the simulation.stop(): Stops the timer, pausing the simulation.tick(iterations): Manually advances the simulation by a specific number of iterations (defaults to 1).Forces are applied to the nodes during each tick. You can add a force using .force(name, forceFunction) and retrieve an existing force using .force(name). To remove a force, call .force(name, null).
When a force is added, the simulation calls the force's .initialize(nodes, random) method if it exists.
forceManyBody to simulate long-range forces between nodes, such as electrostatic repulsion or gravitational attraction. This is commonly used to prevent nodes from overlapping by applying a charge to each node.forceCollide to simulate physical collisions between nodes. This force prevents nodes from overlapping by treating them as circles with a specific radius.forceX and forceY to pull nodes toward specific x or y coordinates. These are useful for aligning nodes along axes or constraining them to specific vertical or horizontal positions.forceLink to simulate connections between nodes. This force pulls connected nodes toward each other based on a specified distance, effectively creating a network or graph structure.