This module implements a velocity Verlet numerical integrator for simulating physical forces on particles. The simulation is simplified: it assumes a constant unit time step Δt = 1 for each step, and a constant unit mass m = 1 for all particles. As a result, a force F acting on a particle is equivalent to a constant acceleration a over the time interval Δt, and can be simulated simply by adding to the particle’s velocity, which is then added to the particle’s position.
In the domain of information visualization, physical simulations are useful for studying networks and hierarchies!
This is a conveninence function for wrapping data up as Entities. The initial position of entities is arranged in a phylotaxic pattern.
Create a new simulation by passing a list of forces.
This holds internal state of the simulation.
Has the simulation stopped?
Resets the computation. This is useful if you need to change the parameters at runtime, such as the position or velocity of nodes during a drag operation.
You can set this to control how quickly the simulation should converge. The default value is 300 iterations.
Lower number of iterations will produce a layout quicker, but risk getting stuck in a local minimum. Higher values take longer, but typically produce better results.
This will run the entire simulation until it is completed and then returns the entities. Essentially keeps calling
tick until the simulation is done.
Note that computing these is fairly computationally expensive and may freeze the UI for a while if the dataset is large.
Advances the simulation a single tick, returning both updated entities and a new State of the simulation.
A force 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 linked nodes a fixed distance apart.
The centering force translates nodes uniformly so that the mean position of all nodes (the center of mass) is at the given position ⟨x,y⟩. This force modifies the positions of nodes on each application; it does not modify velocities, as doing so would typically cause the nodes to overshoot and oscillate around the desired center. This force helps keep nodes in the center of the viewport, and it does not distort their relative positions.
The link force pushes linked nodes together or apart according to the desired link distance. The strength of the force is proportional to the difference between the linked nodes’ distance and the target distance, similar to a spring force.
The link distance here is 30, the strength of the force is proportional to the number of links on each side of the
present link, according to the formule: 1 / min (count souce) (count target) where count if a function that counts
links connected to those nodes.
Allows you to specify the link distance and optionally the strength. You must also specify the iterations count, however this parameter is currently ignored (so set it to 1). This will change in a future release.
The many-body (or n-body) force applies mutually amongst all nodes. It can be used to simulate gravity (attraction) if the strength is positive, or electrostatic charge (repulsion) if the strength is negative.
Unlike links, which only affect two linked nodes, the charge force is global: it affects all nodes whose ids are passed to it.
The default strength is -30 simulating a repulsing charge.
This allows you to specify the strength of the many-body force.
Visualization.Force needs to compute and update positions and velocities on any objects that it is simulating. However, you can use your own data structure to manage these, as long as the individual objects expose the necessary properties. Therefore this type alias is an extensible record allowing you to avoid excessive nesting.
The
idproperty must be unique among objects, otherwise some of the colliding objects will be ignored by the simulation.Also take care when initializing the positions so that the points don't overlap.