@types/d3-force

Version 3.0.10
Published 4 months ago
50.8 kB
No dependencies
MIT license

Install

npm i @types/d3-force

yarn add @types/d3-force

pnpm add @types/d3-force

Overview

TypeScript definitions for d3-force

Functions

function forceCenter

forceCenter: <NodeDatum extends SimulationNodeDatum>(
    x?: number,
    y?: number
) => ForceCenter<NodeDatum>;

Create a new centering force with the specified x- and y- coordinates. If x and y are not specified, they default to [0,0].
The centering force translates nodes uniformly so that the mean position of all nodes (the center of mass if all nodes have equal weight) 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 keeps nodes in the center of the viewport, and unlike the positioning force, it does not distort their relative positions.
The generic refers to the type of data for a node.
Parameter x
An optional x-coordinate for the centering position, defaults to 0.
Parameter y
An optional y-coordinate for the centering position, defaults to 0.

function forceCollide

forceCollide: <NodeDatum extends SimulationNodeDatum>(
    radius?: number | ((node: NodeDatum, i: number, nodes: NodeDatum[]) => number)
) => ForceCollide<NodeDatum>;

Creates a new circle collision force with the specified radius. If radius is not specified, it defaults to the constant one for all nodes.

function forceLink

forceLink: <
    NodeDatum extends SimulationNodeDatum,
    LinksDatum extends SimulationLinkDatum<NodeDatum>
>(
    links?: LinksDatum[]
) => ForceLink<NodeDatum, LinksDatum>;

Creates a new link force with the specified links and default parameters. If links is not specified, it defaults to the empty array.

function forceManyBody

forceManyBody: <
    NodeDatum extends SimulationNodeDatum
>() => ForceManyBody<NodeDatum>;

Creates a new many-body force with the default parameters.
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 quadtrees and the Barnes–Hut approximation to greatly improve performance; the accuracy can be customized using the theta parameter.
Unlike links, which only affect two linked nodes, the charge force is global: every node affects every other node, even if they are on disconnected subgraphs.
The generic refers to the type of data for a node.

function forceRadial

forceRadial: <NodeDatum extends SimulationNodeDatum>(
    radius: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number),
    x?: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number),
    y?: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
) => ForceRadial<NodeDatum>;

Create a new radial positioning force towards a circle of the specified radius centered at ⟨x,y⟩. If x and y are not specified, they default to ⟨0,0⟩.
The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position. While this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
The generic refers to the type of data for a node.

function forceSimulation

forceSimulation: {
    <NodeDatum extends SimulationNodeDatum>(nodesData?: NodeDatum[]): Simulation<
        NodeDatum,
        undefined
    >;
    <
        NodeDatum extends SimulationNodeDatum,
        LinkDatum extends SimulationLinkDatum<NodeDatum>
    >(
        nodesData?: NodeDatum[]
    ): Simulation<NodeDatum, LinkDatum>;
};

Create a new simulation with the specified array of nodes and no forces. If nodes is not specified, it defaults to the empty array. The simulator starts automatically; use simulation.on to listen for tick events as the simulation runs. If you wish to run the simulation manually instead, call simulation.stop, and then call simulation.tick as desired.
Use this signature, when creating a simulation WITHOUT link force(s).
The generic refers to the type of the data for a node.
Parameter nodesData
Optional array of nodes data, defaults to empty array.
Create a new simulation with the specified array of nodes and no forces. If nodes is not specified, it defaults to the empty array. The simulator starts automatically; use simulation.on to listen for tick events as the simulation runs. If you wish to run the simulation manually instead, call simulation.stop, and then call simulation.tick as desired.
Use this signature, when creating a simulation WITH link force(s).
The first generic refers to the type of data for a node. The second generic refers to the type of data for a link.
Parameter nodesData
Optional array of nodes data, defaults to empty array.

function forceX

forceX: <NodeDatum extends SimulationNodeDatum>(
    x?: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
) => ForceX<NodeDatum>;

Creates a new positioning force along the x-axis towards the given position x. If x is not specified, it defaults to 0.

function forceY

forceY: <NodeDatum extends SimulationNodeDatum>(
    y?: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
) => ForceY<NodeDatum>;

Creates a new positioning force along the y-axis towards the given position y. If y is not specified, it defaults to 0.

Interfaces

interface Force

interface Force<
    NodeDatum extends SimulationNodeDatum,
    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined
> {}

A force is simply a function that 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.
Forces typically read the node’s current position [x,y] and then add to (or subtract from) the node’s velocity [vx,vy]. However, forces may also “peek ahead” to the anticipated next position of the node, [x + vx,y + vy]; this is necessary for resolving geometric constraints through iterative relaxation. Forces may also modify the position directly, which is sometimes useful to avoid adding energy to the simulation, such as when recentering the simulation in the viewport.
Forces may optionally implement force.initialize to receive the simulation’s array of nodes.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

call signature

(alpha: number): void;

Apply this force, optionally observing the specified alpha. Typically, the force is applied to the array of nodes previously passed to force.initialize, however, some forces may apply to a subset of nodes, or behave differently. For example, d3.forceLink applies to the source and target of each link.

interface ForceCenter

interface ForceCenter<NodeDatum extends SimulationNodeDatum>
    extends Force<NodeDatum, any> {}

The centering force translates nodes uniformly so that the mean position of all nodes (the center of mass if all nodes have equal weight) 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 keeps nodes in the center of the viewport, and unlike the positioning force, it does not distort their relative positions.
The generic refers to the type of data for a node.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method strength

strength: { (): number; (strength: number): this };

Returns the force’s current strength, which defaults to 1.
Sets the centering force’s strength. A reduced strength of e.g. 0.05 softens the movements on interactive graphs in which new nodes enter or exit the graph.
Parameter strength
The centering force's strength.

method x

x: { (): number; (x: number): this };

Return the current x-coordinate of the centering position, which defaults to zero.
Set the x-coordinate of the centering position.
Parameter x
x-coordinate.

method y

y: { (): number; (y: number): this };

Return the current y-coordinate of the centering position, which defaults to zero.
Set the y-coordinate of the centering position.
Parameter y
y-coordinate.

interface ForceCollide

interface ForceCollide<NodeDatum extends SimulationNodeDatum>
    extends Force<NodeDatum, any> {}

The collision force treats nodes as circles with a given radius, rather than points, and prevents nodes from overlapping. More formally, two nodes a and b are separated so that the distance between a and b is at least radius(a) + radius(b). To reduce jitter, this is by default a “soft” constraint with a configurable strength and iteration count.
The generic refers to the type of data for a node.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method iterations

iterations: { (): number; (iterations: number): this };

Return the current iteration count which defaults to 1.
Sets the number of iterations per application to the specified number and return this force.
Increasing the number of iterations greatly increases the rigidity of the constraint and avoids partial overlap of nodes, but also increases the runtime cost to evaluate the force.
Parameter iterations
Number of iterations.

method radius

radius: {
    (): (node: NodeDatum, i: number, nodes: NodeDatum[]) => number;
    (
        radius:
            | number
            | ((node: NodeDatum, i: number, nodes: NodeDatum[]) => number)
    ): this;
};

Returns the current radius accessor function.
Sets the radius accessor to the specified number or function, re-evaluates the radius accessor for each node, and returns this force. The radius accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the radius of each node is only recomputed when the force is initialized or when this method is called with a new radius, and not on every application of the force.

method strength

strength: { (): number; (strength: number): this };

Return the current strength, which defaults to 1.
Set the force strength to the specified number in the range [0,1] and return this force. The default strength is 1.
Overlapping nodes are resolved through iterative relaxation. For each node, the other nodes that are anticipated to overlap at the next tick (using the anticipated positions [x + vx,y + vy]) are determined; the node’s velocity is then modified to push the node out of each overlapping node. The change in velocity is dampened by the force’s strength such that the resolution of simultaneous overlaps can be blended together to find a stable solution.
Parameter strength
Strength.

interface ForceLink

interface ForceLink<
    NodeDatum extends SimulationNodeDatum,
    LinkDatum extends SimulationLinkDatum<NodeDatum>
> extends Force<NodeDatum, LinkDatum> {}

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 first generic refers to the type of data for a node. The second generic refers to the type of data for a link.

method distance

distance: {
    (): (link: LinkDatum, i: number, links: LinkDatum[]) => number;
    (
        distance:
            | number
            | ((link: LinkDatum, i: number, links: LinkDatum[]) => number)
    ): this;
};

Return the current distance accessor, which defaults to implying a default distance of 30.
Sets the distance accessor to the specified number or function, re-evaluates the distance accessor for each link, and returns this force. The distance accessor is invoked for each link, being passed the link and its zero-based index. The resulting number is then stored internally, such that the distance of each link is only recomputed when the force is initialized or when this method is called with a new distance, and not on every application of the force.

method id

id: {
    (): (node: NodeDatum, i: number, nodesData: NodeDatum[]) => string | number;
    (
        id: (
            node: NodeDatum,
            i: number,
            nodesData: NodeDatum[]
        ) => string | number
    ): this;
};

Return the current node id accessor, which defaults to the numeric node.index.
Set the node id accessor to the specified function and return this force.
The default id accessor allows each link’s source and target to be specified as a zero-based index into the nodes array.
The id accessor is invoked for each node whenever the force is initialized, as when the nodes or links change, being passed the node, the zero-based index of the node in the node array, and the node array.
Parameter id
A node id accessor function which is invoked for each node in the simulation, being passed the node, the zero-based index of the node in the node array, and the node array. It returns a string or number to represent the node id which can be used for matching link source and link target strings during the ForceLink initialization.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method iterations

iterations: { (): number; (iterations: number): this };

Return the current iteration count which defaults to 1.
Sets the number of iterations per application to the specified number and return this force.
Increasing the number of iterations greatly increases the rigidity of the constraint and is useful for complex structures such as lattices, but also increases the runtime cost to evaluate the force.
Parameter iterations
Number of iterations.

method links

links: { (): LinkDatum[]; (links: LinkDatum[]): this };

Return the current array of links, which defaults to the empty array.
Set the array of links associated with this force, recompute the distance and strength parameters for each link, and return this force.
Each link is an object with the following properties: * source - the link’s source node; see simulation.nodes * target - the link’s target node; see simulation.nodes * index - the zero-based index into links, assigned by this method
For convenience, a link’s source and target properties may be initialized using numeric or string identifiers rather than object references; see link.id. When the link force is initialized (or re-initialized, as when the nodes or links change), any link.source or link.target property which is not an object is replaced by an object reference to the corresponding node with the given identifier. If the specified array of links is modified, such as when links are added to or removed from the simulation, this method must be called again with the new (or changed) array to notify the force of the change; the force does not make a defensive copy of the specified array.
Parameter links
An array of link data.

method strength

strength: {
    (): (link: LinkDatum, i: number, links: LinkDatum[]) => number;
    (
        strength:
            | number
            | ((link: LinkDatum, i: number, links: LinkDatum[]) => number)
    ): this;
};

Return the current strength accessor. For details regarding the default behavior see: https://github.com/d3/d3-force#link_strength
Sets the strength accessor to the specified number or function, re-evaluates the strength accessor for each link, and returns this force. The strength accessor is invoked for each link, being passed the link and its zero-based index. The resulting number is then stored internally, such that the strength of each link is only recomputed when the force is initialized or when this method is called with a new strength, and not on every application of the force.

interface ForceManyBody

interface ForceManyBody<NodeDatum extends SimulationNodeDatum>
    extends Force<NodeDatum, any> {}

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 quadtrees and the Barnes–Hut approximation to greatly improve performance; the accuracy can be customized using the theta parameter.
Unlike links, which only affect two linked nodes, the charge force is global: every node affects every other node, even if they are on disconnected subgraphs.
The generic refers to the type of data for a node.

method distanceMax

distanceMax: { (): number; (distance: number): this };

Returns the current maximum distance over which this force is considered, which defaults to infinity.
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.
The default value is infinity.
Parameter distance
The maximum distance between nodes over which this force is considered.

method distanceMin

distanceMin: { (): number; (distance: number): this };

Returns the current minimum distance over which this force is considered, which defaults to 1.
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.
The default value is 1.
Parameter distance
The minimum distance between nodes over which this force is considered.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method strength

strength: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (
        strength:
            | number
            | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
    ): this;
};

Return the current strength accessor.
For details regarding the default behavior see: https://github.com/d3/d3-force#manyBody_strength
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. The strength accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the strength of each node is only recomputed when the force is initialized or when this method is called with a new strength, and not on every application of the force.

method theta

theta: { (): number; (theta: number): this };

Return the current value of the Barnes–Hut approximation criterion , which defaults to 0.9
Set 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 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.
The default value is 0.9.
Parameter theta
Value for the theta parameter.

interface ForceRadial

interface ForceRadial<NodeDatum extends SimulationNodeDatum>
    extends Force<NodeDatum, any> {}

The radial force is similar to the x- and y-positioning forces, except it pushes nodes towards the closest point on a given circle. The circle is of the specified radius centered at ⟨x,y⟩. If x and y are not specified, they default to ⟨0,0⟩. The strength of the force is proportional to the one-dimensional distance between the node’s position and the target position. While this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
The generic refers to the type of data for a node.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Assigns the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method radius

radius: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (
        radius: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
    ): this;
};

Return the current radius accessor for the circle.
Sets the circle radius to the specified number or function, re-evaluates the radius accessor for each node, and returns this force. The radius accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the target radius of each node is only recomputed when the force is initialized or when this method is called with a new radius, and not on every application of the force.

method strength

strength: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (
        strength:
            | number
            | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
    ): this;
};

Returns the current strength accessor, which defaults to a constant strength for all nodes of 0.1.
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. The strength accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the strength of each node is only recomputed when the force is initialized or when this method is called with a new strength, and not on every application of the force.

method x

x: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (x: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)): this;
};

Return the current x-accessor for the circle center, which defaults to a function returning 0 for all nodes.
Sets the x-coordinate of the circle center to the specified number and returns this force.

method y

y: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (y: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)): this;
};

Return the current y-accessor for the circle center, which defaults to a function returning 0 for all nodes.
Sets the y-coordinate of the circle center to the specified number and returns this force.

interface ForceX

interface ForceX<NodeDatum extends SimulationNodeDatum>
    extends Force<NodeDatum, any> {}

The x-positioning 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 this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
The generic refers to the type of data for a node.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method strength

strength: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (
        strength:
            | number
            | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
    ): this;
};

Returns the current strength accessor, which defaults to a constant strength for all nodes of 0.1.
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. The strength accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the strength of each node is only recomputed when the force is initialized or when this method is called with a new strength, and not on every application of the force.

method x

x: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (x: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)): this;
};

Return the current x-accessor, which defaults to a function returning 0 for all nodes.
Sets the x-coordinate accessor to the specified number or function, re-evaluates the x-accessor for each node, and returns this force. The x-accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the target x-coordinate of each node is only recomputed when the force is initialized or when this method is called with a new x, and not on every application of the force.

interface ForceY

interface ForceY<NodeDatum extends SimulationNodeDatum>
    extends Force<NodeDatum, any> {}

The y-positioning 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 this force can be used to position individual nodes, it is intended primarily for global forces that apply to all (or most) nodes.
The generic refers to the type of data for a node.

method initialize

initialize: (nodes: NodeDatum[], random: () => number) => void;

Supplies the array of nodes and random source to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes.
A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

method strength

strength: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (
        strength:
            | number
            | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)
    ): this;
};

Returns the current strength accessor, which defaults to a constant strength for all nodes of 0.1.
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 y-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. The strength accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the strength of each node is only recomputed when the force is initialized or when this method is called with a new strength, and not on every application of the force.

method y

y: {
    (): (d: NodeDatum, i: number, data: NodeDatum[]) => number;
    (y: number | ((d: NodeDatum, i: number, data: NodeDatum[]) => number)): this;
};

Return the current y-accessor, which defaults to a function returning 0 for all nodes.
Sets the y-coordinate accessor to the specified number or function, re-evaluates the y-accessor for each node, and returns this force. The y-accessor is invoked for each node in the simulation, being passed the node and its zero-based index. The resulting number is then stored internally, such that the target y-coordinate of each node is only recomputed when the force is initialized or when this method is called with a new y, and not on every application of the force.

interface Simulation

interface Simulation<
    NodeDatum extends SimulationNodeDatum,
    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined
> {}

A Force Simulation
The first generic refers to the type of the datum associated with a node in the simulation. The second generic refers to the type of the datum associated with a link in the simulation, if applicable.

method alpha

alpha: { (): number; (alpha: number): this };

Return the current alpha of the simulation, which defaults to 1.
alpha is roughly analogous to temperature in simulated annealing. It decreases over time as the simulation “cools down”. When alpha reaches alphaMin, the simulation stops; see simulation.restart.
Set the current alpha to the specified number in the range [0,1] and return this simulation. The default is 1.
alpha is roughly analogous to temperature in simulated annealing. It decreases over time as the simulation “cools down”. When alpha reaches alphaMin, the simulation stops; see simulation.restart.
Parameter alpha
Current alpha of simulation.

method alphaDecay

alphaDecay: { (): number; (decay: number): this };

Return the current alpha decay rate, which defaults to 0.0228… = 1 - pow(0.001, 1 / 300) where 0.001 is the default minimum alpha.
Set the alpha decay rate to the specified number in the range [0,1] and return this simulation. The default is 0.0228… = 1 - pow(0.001, 1 / 300) where 0.001 is the default minimum alpha.
The alpha decay rate determines how quickly the current alpha interpolates towards the desired target alpha; since the default target alpha is zero, by default this controls how quickly the simulation cools. Higher decay rates cause the simulation to stabilize more quickly, but risk getting stuck in a local minimum; lower values cause the simulation to take longer to run, but typically converge on a better layout. To have the simulation run forever at the current alpha, set the decay rate to zero; alternatively, set a target alpha greater than the minimum alpha.
Parameter decay
Alpha decay rate.

method alphaMin

alphaMin: { (): number; (min: number): this };

Return the current minimum alpha value, which defaults to 0.001.
Set the minimum alpha to the specified number in the range [0,1] and return this simulation. The default is 0.001. The simulation’s internal timer stops when the current alpha is less than the minimum alpha. The default alpha decay rate of ~0.0228 corresponds to 300 iterations.
Parameter min
Minimum alpha of simulation.

method alphaTarget

alphaTarget: { (): number; (target: number): this };

Returns the current target alpha value, which defaults to 0.
Set the current target alpha to the specified number in the range [0,1] and return this simulation. The default is 0.
Parameter target
Alpha target value.

method find

find: (x: number, y: number, radius?: number) => NodeDatum | undefined;

Return the node closest to the position [x,y] with the given search radius. If radius is not specified, it defaults to infinity. If there is no node within the search area, returns undefined.
Parameter x
x-coordinate
Parameter y
y-coordinate
Parameter radius
Optional search radius. Defaults to infinity.

method force

force: {
    <F extends Force<NodeDatum, LinkDatum>>(name: string): F | undefined;
    (name: string, force: Force<NodeDatum, LinkDatum>): this;
};

Return the force with the specified name, or undefined if there is no such force. (By default, new simulations have no forces.)
Given that it is in general not known, what type of force has been registered under a specified name, use the generic to cast the result to the appropriate type, if known.
Parameter name
Name of the registered force.
If force is specified, assigns the force for the specified name and returns this simulation. To remove the force with the given name, pass null as the force.

method nodes

nodes: { (): NodeDatum[]; (nodesData: NodeDatum[]): this };

Returns the simulation’s array of nodes as specified to the constructor.
Set the simulation’s nodes to the specified array of objects, initialize their positions and velocities if necessary, and then re-initialize any bound forces; Returns the simulation.
Each node must be an object. The following properties are assigned by the simulation: - index (the node’s zero-based index into nodes) - x (the node’s current x-position) - y (the node’s current y-position) - vx (the node’s current x-velocity) - vy (the node’s current y-velocity)
The position [x,y] and velocity [vx,vy] may be subsequently modified by forces and by the simulation. If either vx or vy is NaN, the velocity is initialized to [0,0]. If either x or y is NaN, the position is initialized in a phyllotaxis arrangement, so chosen to ensure a deterministic, uniform distribution.
To fix a node in a given position, you may specify two additional properties: - fx (the node’s fixed x-position) - fy (the node’s fixed y-position)
At the end of each tick, after the application of any forces, a node with a defined node.fx has node.x reset to this value and node.vx set to zero; likewise, a node with a defined node.fy has node.y reset to this value and node.vy set to zero. To unfix a node that was previously fixed, set node.fx and node.fy to null, or delete these properties.
If the specified array of nodes is modified, such as when nodes are added to or removed from the simulation, this method must be called again with the new (or changed) array to notify the simulation and bound forces of the change; the simulation does not make a defensive copy of the specified array.

method on

on: {
    (typenames: 'tick' | 'end' | string): (
        this: Simulation<NodeDatum, LinkDatum>
    ) => void;
    (typenames: string, listener: (this: this) => void): this;
};

Return the first currently-assigned listener matching the specified typenames, if any.
Parameter typenames
The typenames is a string containing one or more typename separated by whitespace. Each typename is a type, optionally followed by a period (.) and a name, such as "tick.foo" and "tick.bar"; the name allows multiple listeners to be registered for the same type. The type must be one of the following: "tick" (after each tick of the simulation’s internal timer) or "end" (after the simulation’s timer stops when alpha < alphaMin).
Sets the event listener for the specified typenames and returns this simulation. If an event listener was already registered for the same type and name, the existing listener is removed before the new listener is added. If listener is null, removes the current event listeners for the specified typenames, if any. When a specified event is dispatched, each listener will be invoked with the this context as the simulation.

method randomSource

randomSource: { (): () => number; (source: () => number): this };

Returns this simulation’s current random source which defaults to a fixed-seed linear congruential generator. See also random.source.
Sets the function used to generate random numbers; this should be a function that returns a number between 0 (inclusive) and 1 (exclusive).
Parameter source
The function used to generate random numbers.

method restart

restart: () => this;

Restart the simulation’s internal timer and return the simulation. In conjunction with simulation.alphaTarget or simulation.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.

method stop

stop: () => this;

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

method tick

tick: (iterations?: number) => this;

Manually steps the simulation by the specified number of *iterations*, and returns the simulation. If *iterations* is not specified, it defaults to 1 (single step).
For each iteration, it increments the current alpha by (alphaTarget - alpha) × alphaDecay; then invokes each registered force, passing the new alpha; then decrements each node’s velocity by velocity × velocityDecay; lastly increments each node’s position by velocity.
This method does not dispatch events; events are only dispatched by the internal timer when the simulation is started automatically upon creation or by calling simulation.restart. The natural number of ticks when the simulation is started is ⌈log(alphaMin) / log(1 - alphaDecay)⌉; by default, this is 300.

method velocityDecay

velocityDecay: { (): number; (decay: number): this };

Return the current target alpha value, which defaults to 0.4.
Set the velocity decay factor to the specified number in the range [0,1] and return this simulation. The default is 0.4.
The decay factor is akin to atmospheric friction; after the application of any forces during a tick, each node’s velocity is multiplied by 1 - decay. As with lowering the alpha decay rate, less velocity decay may converge on a better solution, but risks numerical instabilities and oscillation.
Parameter decay
Velocity Decay.

interface SimulationLinkDatum

interface SimulationLinkDatum<NodeDatum extends SimulationNodeDatum> {}

The base data structure for the datum of a Simulation Link, as used by ForceLink. The optional properties contained in this data structure are internally assigned by when initializing with ForceLink.links(...)
IMPORTANT: The source and target properties may be internally mutated in type during the ForceLink initialization process (possibly being changed from a node index in the nodes array, or a node id string to the simulation node object which was mapped in using the current ForceLink.id(...) accessor function.)

property index

index?: number | undefined;

The zero-based index into the links array. Internally generated when calling ForceLink.links(...)

property source

source: NodeDatum | string | number;

Link’s source node. For convenience, a link’s source and target properties may be initialized using numeric or string identifiers rather than object references; see link.id. When the link force is initialized (or re-initialized, as when the nodes or links change), any link.source or link.target property which is not an object is replaced by an object reference to the corresponding node with the given identifier. After initialization, the source property represents the source node object.

property target

target: NodeDatum | string | number;

Link’s source link For convenience, a link’s source and target properties may be initialized using numeric or string identifiers rather than object references; see link.id. When the link force is initialized (or re-initialized, as when the nodes or links change), any link.source or link.target property which is not an object is replaced by an object reference to the corresponding node with the given identifier. After initialization, the target property represents the target node object.

interface SimulationNodeDatum

interface SimulationNodeDatum {}

The base data structure for the datum of a Simulation Node. The optional properties contained in this data structure are internally assigned by the Simulation upon (re-)initialization.
When defining a data type to use for node data, it should be an extension of this interface and respect the already "earmarked" properties used by the simulation.
IMPORTANT: Prior to initialization, the following properties are optional: index, x, y, vx, and vy. After initialization they will be defined. The optional properties fx and fy are ONLY defined, if the node's position has been fixed.

property fx

fx?: number | null | undefined;

Node’s fixed x-position (if position was fixed)

property fy

fy?: number | null | undefined;

Node’s fixed y-position (if position was fixed)

property index

index?: number | undefined;

Node’s zero-based index into nodes array. This property is set during the initialization process of a simulation.

property vx

vx?: number | undefined;

Node’s current x-velocity

property vy

vy?: number | undefined;

Node’s current y-velocity

property x

x?: number | undefined;

Node’s current x-position

property y

y?: number | undefined;

Node’s current y-position

Package Files (1)

index.d.ts

Dependencies (0)

No dependencies.

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@types/d3-force.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@types/d3-force)

HTML

<a href="https://www.jsdocs.io/package/@types/d3-force"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 4 months ago.
Package analyzed in 3318 ms.
Missing or incorrect documentation? Open an issue for this package.

@types/d3-force

Install

Overview

Index

Functions

Interfaces

Functions

function forceCenter

Parameter x

Parameter y

function forceCollide

function forceLink

function forceManyBody

function forceRadial

function forceSimulation

Parameter nodesData

Parameter nodesData

function forceX

function forceY

Interfaces

interface Force

method initialize

call signature

interface ForceCenter

method initialize

method strength

Parameter strength

method x

Parameter x

method y

Parameter y

interface ForceCollide

method initialize

method iterations

Parameter iterations

method radius

method strength

Parameter strength

interface ForceLink

method distance

method id

Parameter id

method initialize

method iterations

Parameter iterations

method links

Parameter links

method strength

interface ForceManyBody

method distanceMax

Parameter distance

method distanceMin

Parameter distance

method initialize

method strength

method theta

Parameter theta

interface ForceRadial

method initialize

method radius

method strength

method x

method y

interface ForceX

method initialize

method strength

method x

interface ForceY

method initialize

method strength

method y

interface Simulation

method alpha

Parameter alpha

method alphaDecay

Parameter decay

method alphaMin

Parameter min

method alphaTarget

Parameter target