Force simulations¶

detroit_live.force_simulation(nodes: list[SimulationNode] | None = None) → LiveForceSimulation¶

A force simulation implements a velocity Verlet numerical integrator for simulating physical forces on particles (nodes). The simulation assumes a constant unit time step \(\Delta 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 \(\Delta t\), and can be simulated simply by adding to the particle’s velocity, which is then added to the particle’s position.

Parameters:: nodes (list[SimulationNode] | None) – List of nodes
Returns:: Simulation object
Return type:: LiveForceSimulation

class detroit_live.force.simulation.LiveForceSimulation(nodes: list[SimulationNode])¶

restart() → LiveForceSimulation¶

Restarts the simulation’s internal timer and returns the simulation. In conjunction with alpha_target or alpha, this method can be used to “reheat” the simulation during interaction, such as when dragging a node, or to resume the simulation after temporarily pausing it with simulation.stop.

Returns:: Itself
Return type:: LiveForceSimulation

stop() → LiveForceSimulation¶

Stops the simulation’s internal timer, if it is running, and returns the simulation. If the timer is already stopped, this method does nothing. This method is useful for running the simulation manually; see simulation.tick.

Returns:: Itself
Return type:: LiveForceSimulation

on(typename: str, listener: Callable[[LiveForceSimulation], None], extra_nodes: list[Element] | None = None) → LiveForceSimulation¶

Sets the event listener for the specified typenames and returns this simulation.

When a specified event is dispatched, each listener will be invoked with the this context as the simulation.

The typename must be one of the following:

tick - after each tick of the simulation’s internal timer.
end - after the simulation’s timer stops when alpha < alpha_min.

Parameters:

typename (str) – Typename
listener (Callable[[LiveForceSimulation], None]) – Listener
extra_nodes (list[etree.Element] | None) – Extra nodes to update when the listener is called

Returns:

Itself

Return type:

LiveForceSimulation

Notes

Tick events are not dispatched when simulation.tick is called manually; events are only dispatched by the internal timer and are intended for interactive rendering of the simulation. To affect the simulation, register forces instead of modifying nodes’ positions or velocities inside a tick event listener.