Position Forces

detroit.force_x(x: Callable[[SimulationNode, int, list[SimulationNode]], float] | float | None = None) → ForceX

The x-position force pushes nodes towards a desired position along the given dimension with a configurable strength.

The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position. While these forces can be used to position individual nodes, they are intended primarily for global forces that apply to all (or most) nodes.

Parameters:

x (SimulationNodeFunction[float] | float | None) –

x-coordinate 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 x-coordinate value (float)

Returns:

Force object

Return type:

ForceX

class detroit.force.x.ForceX(x: Callable[[SimulationNode, int, list[SimulationNode]], float])
initialize(nodes: list[SimulationNode], random: Callable[[None], float])
set_strength(strength: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceX

Sets the strength accessor to the specified number or function, re-evaluates the strength accessor for each node, and returns this force.

The strength determines how much to increment the node’s x-velocity: (x - node["x"]) * strength. For example, a value of \(0.1\) indicates that the node should move a tenth of the way from its current x-position to the target x-position with each application. Higher values moves nodes more quickly to the target position, often at the expense of other forces or constraints. A value outside the range \([0,1]\) is not recommended.

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:

ForceX

x(x: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceX

Sets the x-coordinate accessor to the specified number or function, re-evaluates the x-accessor for each node, and returns this force.

Parameters:

x (SimulationNodeFunction[float] | float) –

x-coordinate 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 x-coordinate value (float)

Returns:

Itself

Return type:

ForceX

detroit.force_y(y: Callable[[SimulationNode, int, list[SimulationNode]], float] | float | None = None)

The y-position force pushes nodes towards a desired position along the given dimension with a configurable strength.

The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position. While these forces can be used to position individual nodes, they are intended primarily for global forces that apply to all (or most) nodes.

Parameters:

y (SimulationNodeFunction[float] | float | None) –

y-coordinate 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 y-coordinate value (float)

Returns:

Force object

Return type:

ForceY

class detroit.force.y.ForceY(y: Callable[[SimulationNode, int, list[SimulationNode]], float])
initialize(nodes: list[SimulationNode], random: Callable[[None], float])
set_strength(strength: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceY

Sets the strength accessor to the specified number or function, re-evaluates the strength accessor for each node, and returns this force.

The strength determines how much to increment the node’s y-velocity: (y - node["y"]) * strength. For example, a value of \(0.1\) indicates that the node should move a tenth of the way from its current x-position to the target y-position with each application. Higher values moves nodes more quickly to the target position, often at the expense of other forces or constraints. A value outside the range \([0,1]\) is not recommended.

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:

ForceY

y(y: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceY

Sets the y-coordinate accessor to the specified number or function, re-evaluates the y-accessor for each node, and returns this force.

Parameters:

y (SimulationNodeFunction[float] | float) –

y-coordinate 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 y-coordinate value (float)

Returns:

Itself

Return type:

ForceY

detroit.force_radial(radius: Callable[[SimulationNode, int, list[SimulationNode]], float] | float, x: float | None = None, y: float | None = None) → ForceRadial

Creates a new position force towards a circle of the specified radius centered at :math`(x,y)`. If x and y are not specified, they default to (0,0).

Parameters:

  • radius (SimulationNodeFunction[float] | float) –

    Radius 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 a radius value (float).

  • x (float | None) – X-coordinate of circle center

  • y (float | None) – Y-coordinate of circle center

Returns:

Force object

Return type:

ForceRadial

class detroit.force.radial.ForceRadial(radius: Callable[[SimulationNode, int, list[SimulationNode]], float], x: float, y: float)
initialize(nodes: list[SimulationNode], random: Callable[[None], float])
set_strength(strength: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceRadial

Sets the strength accessor to the specified number or function, re-evaluates the strength accessor for each node, and returns this force. The strength determines how much to increment the node’s x- and y-velocity.

For example, a value of \(0.1\) indicates that the node should move a tenth of the way from its current position to the closest point on the circle with each application. Higher values moves nodes more quickly to the target position, often at the expense of other forces or constraints. A value outside the range \([0,1]\) is not recommended.

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:

ForceRadial

set_radius(radius: Callable[[SimulationNode, int, list[SimulationNode]], float] | float) → ForceRadial

Sets the circle radius to the specified number or function, re-evaluates the radius accessor for each node, and returns this force.

Parameters:

radius (SimulationNodeFunction[float] | float) –

Radius 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 a radius value (float).

Returns:

Force object

Return type:

ForceRadial

x(x: float) → ForceRadial

Sets the x-coordinate of the circle center to the specified number and returns this force.

Parameters:

x (float) – X-coordinate of circle center

Returns:

Itself

Return type:

ForceRadial

y(y: float) → ForceRadial

Sets the y-coordinate of the circle center to the specified number and returns this force.

Parameters:

y (float) – y-coordinate of circle center

Returns:

Itself

Return type:

ForceRadial