From ec2f423ba53b2ad40146ee97ab827db4b26ccc23 Mon Sep 17 00:00:00 2001 From: vasco Date: Sat, 10 Nov 2018 20:09:57 -0800 Subject: [PATCH] Fix #111. Add iterations to tick method. --- README.md | 32 +++++++++++++++++--------------- src/simulation.js | 28 +++++++++++++++++----------- 2 files changed, 34 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 4dd2527..894ee70 100644 --- a/README.md +++ b/README.md @@ -43,23 +43,25 @@ var simulation = d3.forceSimulation(nodes); Creates a new simulation with the specified array of [*nodes*](#simulation_nodes) and no [forces](#simulation_force). If *nodes* is not specified, it defaults to the empty array. The simulator [starts](#simulation_restart) automatically; use [*simulation*.on](#simulation_on) to listen for tick events as the simulation runs. If you wish to run the simulation manually instead, call [*simulation*.stop](#simulation_stop), and then call [*simulation*.tick](#simulation_tick) as desired. -# simulation.restart() [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L80 "Source") +# simulation.restart() [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L86 "Source") Restarts the simulation’s internal timer and returns the simulation. In conjunction with [*simulation*.alphaTarget](#simulation_alphaTarget) or [*simulation*.alpha](#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](#simulation_stop). -# simulation.stop() [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L84 "Source") +# simulation.stop() [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L90 "Source") 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](#simulation_tick). -# simulation.tick() [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L38 "Source") +# simulation.tick([iterations]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L38 "Source") -Increments the current [*alpha*](#simulation_alpha) by ([*alphaTarget*](#simulation_alphaTarget) - *alpha*) × [*alphaDecay*](#simulation_alphaDecay); then invokes each registered [force](#simulation_force), passing the new *alpha*; then decrements each [node](#simulation_nodes)’s velocity by *velocity* × [*velocityDecay*](#simulation_velocityDecay); lastly increments each node’s position by *velocity*. +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*](#simulation_alpha) by ([*alphaTarget*](#simulation_alphaTarget) - *alpha*) × [*alphaDecay*](#simulation_alphaDecay); then invokes each registered [force](#simulation_force), passing the new *alpha*; then decrements each [node](#simulation_nodes)’s velocity by *velocity* × [*velocityDecay*](#simulation_velocityDecay); lastly increments each node’s position by *velocity*. This method does not dispatch [events](#simulation_on); events are only dispatched by the internal timer when the simulation is started automatically upon [creation](#forceSimulation) or by calling [*simulation*.restart](#simulation_restart). The natural number of ticks when the simulation is started is ⌈*log*([*alphaMin*](#simulation_alphaMin)) / *log*(1 - [*alphaDecay*](#simulation_alphaDecay))⌉; by default, this is 300. This method can be used in conjunction with [*simulation*.stop](#simulation_stop) to compute a [static force layout](https://bl.ocks.org/mbostock/1667139). For large graphs, static layouts should be computed [in a web worker](https://bl.ocks.org/mbostock/01ab2e85e8727d6529d20391c0fd9a16) to avoid freezing the user interface. -# simulation.nodes([nodes]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L88 "Source") +# simulation.nodes([nodes]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L94 "Source") If *nodes* is specified, sets the simulation’s nodes to the specified array of objects, initializing their positions and velocities if necessary, and then [re-initializes](#force_initialize) any bound [forces](#simulation_force); returns the simulation. If *nodes* is not specified, returns the simulation’s array of nodes as specified to the [constructor](#forceSimulation). @@ -82,29 +84,29 @@ At the end of each [tick](#simulation_tick), after the application of any forces 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. -# simulation.alpha([alpha]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L92 "Source") +# simulation.alpha([alpha]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L98 "Source") If *alpha* is specified, sets the current alpha to the specified number in the range [0,1] and returns this simulation. If *alpha* is not specified, returns the current alpha value, which defaults to 1. -# simulation.alphaMin([min]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L96 "Source") +# simulation.alphaMin([min]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L102 "Source") If *min* is specified, sets the minimum *alpha* to the specified number in the range [0,1] and returns this simulation. If *min* is not specified, returns the current minimum *alpha* value, which defaults to 0.001. The simulation’s internal timer stops when the current [*alpha*](#simulation_alpha) is less than the minimum *alpha*. The default [alpha decay rate](#simulation_alphaDecay) of ~0.0228 corresponds to 300 iterations. -# simulation.alphaDecay([decay]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L100 "Source") +# simulation.alphaDecay([decay]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L106 "Source") If *decay* is specified, sets the [*alpha*](#simulation_alpha) decay rate to the specified number in the range [0,1] and returns this simulation. If *decay* is not specified, returns the current *alpha* decay rate, which defaults to 0.0228… = 1 - *pow*(0.001, 1 / 300) where 0.001 is the default [minimum *alpha*](#simulation_alphaMin). The alpha decay rate determines how quickly the current alpha interpolates towards the desired [target *alpha*](#simulation_alphaTarget); 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*](#simulation_alphaTarget) greater than the [minimum *alpha*](#simulation_alphaMin). -# simulation.alphaTarget([target]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L104 "Source") +# simulation.alphaTarget([target]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L110 "Source") If *target* is specified, sets the current target [*alpha*](#simulation_alpha) to the specified number in the range [0,1] and returns this simulation. If *target* is not specified, returns the current target alpha value, which defaults to 0. -# simulation.velocityDecay([decay]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L108 "Source") +# simulation.velocityDecay([decay]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L114 "Source") If *decay* is specified, sets the velocity decay factor to the specified number in the range [0,1] and returns this simulation. If *decay* is not specified, returns the current velocity decay factor, which defaults to 0.4. The decay factor is akin to atmospheric friction; after the application of any forces during a [tick](#simulation_tick), each node’s velocity is multiplied by 1 - *decay*. As with lowering the [alpha decay rate](#simulation_alphaDecay), less velocity decay may converge on a better solution, but risks numerical instabilities and oscillation. -# simulation.force(name[, force]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L112 "Source") +# simulation.force(name[, force]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L118 "Source") If *force* is specified, assigns the [force](#forces) for the specified *name* and returns this simulation. If *force* is not specified, returns the force with the specified name, or undefined if there is no such force. (By default, new simulations have no forces.) For example, to create a new simulation to layout a graph, you might say: @@ -121,11 +123,11 @@ To remove the force with the given *name*, pass null as the *force*. For example simulation.force("charge", null); ``` -# simulation.find(x, y[, radius]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L116 "Source") +# simulation.find(x, y[, radius]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L122 "Source") Returns 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. -# simulation.on(typenames, [listener]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L139 "Source") +# simulation.on(typenames, [listener]) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L145 "Source") If *listener* is specified, 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. If *listener* is not specified, returns the first currently-assigned listener matching the specified *typenames*, if any. When a specified event is dispatched, each *listener* will be invoked with the `this` context as the simulation. @@ -164,11 +166,11 @@ Simulations typically compose multiple forces as desired. This module provides s Forces may optionally implement [*force*.initialize](#force_initialize) to receive the simulation’s array of nodes. -# force(alpha) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L44 "Source") +# force(alpha) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L47 "Source") Applies this force, optionally observing the specified *alpha*. Typically, the force is applied to the array of nodes previously passed to [*force*.initialize](#force_initialize), however, some forces may apply to a subset of nodes, or behave differently. For example, [d3.forceLink](#links) applies to the source and target of each link. -# force.initialize(nodes) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L71 "Source") +# force.initialize(nodes) [<>](https://github.com/d3/d3-force/blob/master/src/simulation.js#L77 "Source") Assigns the array of *nodes* to this force. This method is called when a force is bound to a simulation via [*simulation*.force](#simulation_force) and when the simulation’s nodes change via [*simulation*.nodes](#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. diff --git a/src/simulation.js b/src/simulation.js index b33232f..083be26 100644 --- a/src/simulation.js +++ b/src/simulation.js @@ -35,22 +35,28 @@ export default function(nodes) { } } - function tick() { + function tick(iterations) { var i, n = nodes.length, node; - alpha += (alphaTarget - alpha) * alphaDecay; + if (iterations === undefined) iterations = 1; - forces.each(function(force) { - force(alpha); - }); + for (var k = 0; k < iterations; ++k) { + alpha += (alphaTarget - alpha) * alphaDecay; - for (i = 0; i < n; ++i) { - node = nodes[i]; - if (node.fx == null) node.x += node.vx *= velocityDecay; - else node.x = node.fx, node.vx = 0; - if (node.fy == null) node.y += node.vy *= velocityDecay; - else node.y = node.fy, node.vy = 0; + forces.each(function (force) { + force(alpha); + }); + + for (i = 0; i < n; ++i) { + node = nodes[i]; + if (node.fx == null) node.x += node.vx *= velocityDecay; + else node.x = node.fx, node.vx = 0; + if (node.fy == null) node.y += node.vy *= velocityDecay; + else node.y = node.fy, node.vy = 0; + } } + + return simulation; } function initializeNodes() {