Many-body Force¶

detroit.force_many_body() → ForceManyBody¶

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. This implementation uses a quadtree and the Barnes–Hut approximation to greatly improve performance; the accuracy can be customized using the theta parameter.

Unlike the link force, which only affect two linked nodes, the charge force is global: every node affects every other node, even if they are on disconnected subgraphs.

Returns:: Force object
Return type:: ForceManyBody

class detroit.force.many_body.ForceManyBody¶

initialize(nodes: list[SimulationNode], random: Callable[[None], float])¶

set_strength(strength: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceManyBody¶

Sets the strength accessor to the specified number or function, re-evaluates the strength accessor for each node, and returns this force. A positive value causes nodes to attract each other, similar to gravity, while a negative value causes nodes to repel each other, similar to electrostatic charge.

Parameters:

strength (SimulationNodeFunction[float] | float) –

Strength function or constant value. If it is a function, it takes the following arguments:

node (SimulationNode) - the node element
i (int) - the index of the node
nodes (list[SimulationNode]) - the list of nodes

It returns the strength value (float)

Returns:

Itself

Return type:

ForceManyBody

set_distance_min(distance_min: float) → ForceManyBody¶

Sets the minimum distance between nodes over which this force is considered.

A minimum distance establishes an upper bound on the strength of the force between two nearby nodes, avoiding instability. In particular, it avoids an infinitely-strong force if two nodes are exactly coincident; in this case, the direction of the force is random.

Parameters:: distance_min (float) – Minimum distance value
Returns:: Itself
Return type:: ForceManyBody

set_distance_max(distance_max: float) → ForceManyBody¶

sets the maximum distance between nodes over which this force is considered.

Specifying a finite maximum distance improves performance and produces a more localized layout.

Parameters:: distance_max (float) – Maximum distance value
Returns:: Itself
Return type:: ForceManyBody

set_theta(theta: float) → ForceManyBody¶

Sets the Barnes-Hut approximation criterion to the specified number and returns this force.

To accelerate computation, this force implements the Barnes - Hut approximation which takes \(O(n \cdot \log(n))\) per application where \(n\) is the number of nodes. For each application, a quadtree stores the current node positions; then for each node, the combined force of all other nodes on the given node is computed. For a cluster of nodes that is far away, the charge force can be approximated by treating the cluster as a single, larger node. The theta parameter determines the accuracy of the approximation: if the ratio \(w / l\) of the width w of the quadtree cell to the distance \(l\) from the node to the cell’s center of mass is less than \(\theta\), all nodes in the given cell are treated as a single node rather than individually.

Parameters:: theta (float) – Barnes-Hut approximation criterion value
Returns:: Itself
Return type:: ForceManyBody