Module

Hylograph.ForceEngine.Core

Package
purescript-hylograph-simulation
Repository
afcondon/purescript-hylograph-simulation

Force Engine Core

The simulation loop's parts: forces, the position update, cooling, the animation frame and dragging.

The forces are hylograph-forces: d3-force's seven and the Rust kernel's additions, in PureScript, with no D3 anywhere. A force is made in two steps, because a simulation is usually described before its nodes exist:

  1. a ForceRecipe says what the force is (createManyBody config, or Hylograph.ForceEngine.Setup.recipe for anything a Setup can say);
  2. initializeForce gives it the nodes and links and returns a ForceHandle, which applyForce applies each tick.

Per-node and per-link values are read when the force is initialized, so a force has to be initialized again (reinitializeForce) when the nodes, the links, or anything those values are computed from have changed.

Coincident nodes are separated by a seeded generator (RandomSource), one per simulation, so the same nodes, links and forces give the same layout every time.

#Node Source

type Node :: Row Type -> Typetype Node row = Node (NodeRow row)

A simulation node. The same type as SimulationNode row.

#NodeRow Source

type NodeRow :: Row Type -> Row Typetype NodeRow row = Pinnable (id :: Int | row)

What a node has beyond position and velocity: an id, and the pins. Record (NodeRow row) plus x, y, vx, vy is Hylograph.ForceEngine.Simulation.SimulationNode row.

#ForceRecipe Source

newtype ForceRecipe :: Row Type -> Typenewtype ForceRecipe row

What a force is, before it has met its nodes: given the simulation's generator, nodes and links, the force itself, or why it cannot be made (a link naming a node that is not there: node not found: <id>).

Constructors

#ForceHandle Source

newtype ForceHandle :: Row Type -> Typenewtype ForceHandle row

A force that has its nodes, and the recipe it was made from, so that it can be made again when they change.

#RandomSource Source

type RandomSource = Source

The seeded generator that separates coincident nodes: d3's own, started where d3 starts it.

#randomSource Source

randomSource :: Effect RandomSource

A fresh generator, for a new simulation.

#createManyBody Source

createManyBody :: forall row. ManyBodyConfig -> ForceRecipe row

A many-body (charge) force with one strength for every node.

#createCollide Source

createCollide :: forall row. CollideConfig -> ForceRecipe row

A collision force with one radius for every node.

#createCenter Source

createCenter :: forall row. CenterConfig -> ForceRecipe row

A centering force.

#createForceX Source

createForceX :: forall row. ForceXConfig -> ForceRecipe row

A force pulling every node toward one x.

#createForceY Source

createForceY :: forall row. ForceYConfig -> ForceRecipe row

A force pulling every node toward one y.

#createRadial Source

createRadial :: forall row. RadialConfig -> ForceRecipe row

A force pulling every node toward one circle.

#createForceXGrid Source

createForceXGrid :: forall row. Number -> ForceRecipe (gridX :: Number | row)

A force pulling each node toward its own gridX, read off the node when the force is initialized.

#createForceYGrid Source

createForceYGrid :: forall row. Number -> ForceRecipe (gridY :: Number | row)

A force pulling each node toward its own gridY.

#createCollideGrid Source

createCollideGrid :: forall row. Number -> Number -> Int -> ForceRecipe (r :: Number | row)

A collision force whose radius is each node's own r plus a padding. Arguments: padding, strength, iterations.

#initializeNodes Source

initializeNodes :: forall row. Array (Node row) -> Effect Unit

d3's initializeNodes: give every node its index, put a pinned node on its pin, stop a node with no velocity, and give a node with no position a place on d3's phyllotaxis spiral. (Until 2026-11-18 a node with no position was put somewhere at random.)

#initializeForce Source

initializeForce :: forall row. RandomSource -> Array (Node row) -> Links -> ForceRecipe row -> Either String (ForceHandle row)

Make a force for these nodes and links.

#reinitializeForce Source

reinitializeForce :: forall row. RandomSource -> Array (Node row) -> Links -> ForceHandle row -> Either String (ForceHandle row)

Make a force again, from the recipe it was first made from, for nodes or links that have changed.

#applyForce Source

applyForce :: forall row. ForceHandle row -> Number -> Effect Unit

Apply a single force: it changes the velocities (or, for centering, the positions) of the nodes it was initialized with.

#applyForces Source

applyForces :: forall row. Array (ForceHandle row) -> Number -> Effect Unit

Apply forces in order, each seeing what the ones before it did.

#integratePositions Source

integratePositions :: forall row. Array (Node row) -> Number -> Effect Unit

Move the nodes: each velocity is multiplied by velocityRetention and added to the position, and a pinned coordinate goes to its pin and stops. Call once per tick, after the forces.

#constrain Source

constrain :: forall row. Array (ForceHandle row) -> Array (Node row) -> Effect Unit

After the nodes have moved: every hard containment clamps its nodes into their regions, and then pinned coordinates are put back (a pin beats a region). Nothing where no force is a hard containment.

#decayAlpha Source

decayAlpha :: Number -> Number -> Number -> Number -> Number

Cool: alpha moves toward alphaTarget by alphaDecay of the way, and is zero once it has fallen below alphaMin, which is how the loop knows to stop. Arguments: alpha, alphaMin, alphaDecay, alphaTarget.

#simulationTick Source

simulationTick :: forall row. { alpha :: Number, alphaDecay :: Number, alphaMin :: Number, alphaTarget :: Number, forces :: Array (ForceHandle row), nodes :: Array (Node row), velocityRetention :: Number } -> Effect Number

A complete tick: apply the forces at the current alpha, move the nodes, apply hard containment, and return the cooled alpha.

#AnimationHandle Source

type AnimationHandle = Effect Unit

Handle to a running animation (can be used to stop it)

#startAnimation Source

startAnimation :: (Number -> Effect Boolean) -> Effect AnimationHandle

Start an animation loop The callback receives the current timestamp and should return whether to continue

#stopAnimation Source

stopAnimation :: AnimationHandle -> Effect Unit

Stop a running animation

#attachDragWithReheat Source

attachDragWithReheat :: Array Element -> Effect Unit -> Effect Unit

Drag nodes: reheat when a drag starts, pin the node under the pointer while it lasts, release it when it ends. This is Hylograph.Interaction.Pointer.attachSimulationDrag from hylograph-selection, attached to each element.

#attachGroupDragWithReheat Source

attachGroupDragWithReheat :: Array Element -> String -> Effect Unit -> Effect Unit

Drag transformed group elements (like bubble packs)

Unlike attachDragWithReheat, this takes a container selector and reads the pointer in that container's coordinates. Use it when dragging <g> elements that have transform attributes. The node is the datum of the nearest ancestor of what was pressed that has the class module-pack.

#attachPinningDrag Source

attachPinningDrag :: Array Element -> Effect Unit -> Effect Unit

Drag with toggle-pinning behavior

Unlike attachDragWithReheat, a node stays pinned where it is dropped. Pressing a pinned node and releasing it within 3px unpins it.

#querySelectorElements Source

querySelectorElements :: String -> Effect (Array Element)

Query DOM elements by CSS selector

#logNodes Source

logNodes :: forall r. String -> Array (Record r) -> Effect Unit

Log node positions for debugging