Module

Hylograph.ForceEngine.Simulation

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

Force Engine Simulation

High-level API for running force simulations. This module provides a clean interface for:

  • Creating and configuring simulations
  • Running the animation loop
  • Handling tick callbacks for rendering

The forces are PureScript (hylograph-forces: d3-force's seven, bit for bit, and the Rust kernel's additions). There is no D3 here. Each simulation has its own seeded generator for separating coincident nodes, so the same nodes, links and forces give the same layout every time.

== IMPORTANT: forces read their values when they are initialized

A force evaluates its per-node and per-link values (targets, radii, strengths, filters) once, when it is given its nodes. If you update node.gridX and call reheat, a force whose target reads gridX still has the old values. setNodes, setLinks, reinitializeForces and updateGridXYAndReinit make every force again from its recipe.

#SimulationNode Source

type SimulationNode :: Row Type -> Typetype SimulationNode r = Record (D3_ID + D3_XY + D3_VxyFxy + r)

A simulation node with all required fields for force simulation and transitions. Extends user data row with id, position (x/y), velocity (vx/vy), and fixed position (fx/fy).

Example:

type MyNode = SimulationNode (name :: String, group :: Int)
-- Expands to: { id :: Int, x, y, vx, vy, fx, fy, name :: String, group :: Int }

#NodeID Source

type NodeID = Int

Node ID type (Int for efficient lookups)

#D3_ID Source

type D3_ID :: Row Type -> Row Typetype D3_ID row = (id :: NodeID | row)

Composable row types for building simulation nodes These can be combined with (+) to create custom node types

#D3_XY Source

type D3_XY :: Row Type -> Row Typetype D3_XY row = (x :: Number, y :: Number | row)

#D3_VxyFxy Source

type D3_VxyFxy :: Row Type -> Row Typetype D3_VxyFxy row = (fx :: Nullable Number, fy :: Nullable Number, vx :: Number, vy :: Number | row)

#D3_FocusXY Source

type D3_FocusXY :: Row Type -> Row Typetype D3_FocusXY row = (cluster :: Int, focusX :: Number, focusY :: Number | row)

#Simulation Source

type Simulation :: Row Type -> Row Type -> Typetype Simulation row linkRow = { alpha :: Ref Number, callbacks :: Maybe SimulationCallbacks, cancelAnimation :: Ref (Effect Unit), config :: SimConfig, forces :: Ref (Map String (ForceHandle row)), links :: Ref (Array { source :: Int, target :: Int | linkRow }), nodes :: Ref (Array (SimulationNode row)), prevAlpha :: Ref Number, random :: RandomSource, running :: Ref Boolean, settings :: Ref SimConfig, tickCallback :: Ref (Effect Unit) }

A running simulation This is a mutable structure that holds the simulation state

#SimConfig Source

type SimConfig = { alphaDecay :: Number, alphaMin :: Number, alphaTarget :: Number, velocityRetention :: Number }

Simulation configuration

#defaultConfig Source

defaultConfig :: SimConfig

Default simulation configuration

#create Source

create :: forall row linkRow. SimConfig -> Effect (Simulation row linkRow)

Create a new simulation (without callbacks)

For the new callback-based API, use createWithCallbacks instead.

#createWithCallbacks Source

createWithCallbacks :: forall row linkRow. SimConfig -> SimulationCallbacks -> Effect (Simulation row linkRow)

Create a new simulation with callback system

Example:

callbacks <- defaultCallbacks
onSimulationTick updateDOM callbacks
onSimulationStop (log "Simulation settled") callbacks
sim <- createWithCallbacks config callbacks

#setNodes Source

setNodes :: forall row linkRow. Array (SimulationNode row) -> Simulation row linkRow -> Effect Unit

Set the nodes for the simulation This initializes the nodes and makes every force again for them.

The simulation adopts these records: it writes into them (an index, a place for a node without one, and then every tick's positions and velocities), as d3 does, and getNodes returns these same records. Drag, and a DOM bound to the nodes, rely on that. For nodes as values, the same on both engines, use Hylograph.Simulation.Stepped.

#addForce Source

addForce :: forall row linkRow. ForceSpec -> Simulation row linkRow -> Effect Unit

Add a force to the simulation

#addForceRecipe Source

addForceRecipe :: forall row linkRow. String -> ForceRecipe row -> Simulation row linkRow -> Effect Unit

Add a force from its recipe, under a name (used for later removal). A force already there under that name is replaced.

Throws, changing nothing, if a link names a node that is not among the nodes.

#addForceHandle Source

addForceHandle :: forall row linkRow. String -> ForceRecipe row -> Simulation row linkRow -> Effect Unit

Deprecated: the old name of addForceRecipe. A force used to be handed over as a handle that had already been initialized; it is now handed over as a recipe and initialized here, so a call to Core.initializeForce before this one is no longer needed.

#removeForce Source

removeForce :: forall row linkRow. String -> Simulation row linkRow -> Effect Unit

Remove a force from the simulation

#clearForces Source

clearForces :: forall row linkRow. Simulation row linkRow -> Effect Unit

Clear all forces from the simulation Used when switching between force configurations (e.g., grid vs tree vs orbit)

#reinitializeForces Source

reinitializeForces :: forall row linkRow. Simulation row linkRow -> Effect Unit

Make every force again from its recipe, for the simulation's current nodes and links. Needed after anything a force's per-node or per-link values are computed from has changed.

Throws, changing nothing, if a link names a node that is not among the nodes (node not found: <id>).

#start Source

start :: forall row linkRow. Simulation row linkRow -> Effect Unit

Start the simulation animation loop

#stop Source

stop :: forall row linkRow. Simulation row linkRow -> Effect Unit

Stop the simulation

#tick Source

tick :: forall row linkRow. Simulation row linkRow -> Effect Number

Run a single tick of the simulation Returns the new alpha value

#reheat Source

reheat :: forall row linkRow. Simulation row linkRow -> Effect Unit

Reheat the simulation (set alpha to 1)

#onTick Source

onTick :: forall row linkRow. Effect Unit -> Simulation row linkRow -> Effect Unit

Set the tick callback (legacy single-callback API) This is called after each simulation tick

#setCallbacks Source

setCallbacks :: forall row linkRow. SimulationCallbacks -> Simulation row linkRow -> Simulation row linkRow

Set the callbacks for a simulation (new multi-callback API) Note: This replaces any callbacks passed to createWithCallbacks

#getCallbacks Source

getCallbacks :: forall row linkRow. Simulation row linkRow -> Maybe SimulationCallbacks

Get the current callbacks (if any)

#isRunning Source

isRunning :: forall row linkRow. Simulation row linkRow -> Effect Boolean

Check if the simulation is running

#getAlpha Source

getAlpha :: forall row linkRow. Simulation row linkRow -> Effect Number

Get the current alpha value

#getNodes Source

getNodes :: forall row linkRow. Simulation row linkRow -> Effect (Array (SimulationNode row))

Get the current nodes (with updated positions): the records given to setNodes, moved in place, the same ones every time.

#PositionMap Source

type PositionMap = Object { x :: Number, y :: Number }

Position map type (keyed by node id as string)

#updatePositionsInPlace Source

updatePositionsInPlace :: forall row linkRow. PositionMap -> Simulation row linkRow -> Effect Unit

Update node positions in place from a position map Mutates the simulation's internal nodes (the same objects the DOM is bound to)

#interpolatePositionsInPlace Source

interpolatePositionsInPlace :: forall row linkRow. PositionMap -> PositionMap -> Number -> Simulation row linkRow -> Effect Unit

Interpolate node positions in place between start and target Progress should be 0.0 to 1.0 (apply easing before calling)

#pinNodesInPlace Source

pinNodesInPlace :: forall row linkRow. Simulation row linkRow -> Effect Unit

Pin all nodes at their current positions (fx = x, fy = y) Use before starting a transition to freeze current state

#unpinNodesInPlace Source

unpinNodesInPlace :: forall row linkRow. Simulation row linkRow -> Effect Unit

Unpin all nodes (fx = null, fy = null) Use after transition to Grid scene to let forces take over

#pinNodesAtPositions Source

pinNodesAtPositions :: forall row linkRow. PositionMap -> Simulation row linkRow -> Effect Unit

Pin nodes at specific positions from a position map Sets both x/y and fx/fy - use at end of transition to non-Grid scenes

#interpolatePositionsInPlace_ Source

#pinNodesInPlace_ Source

#unpinNodesInPlace_ Source

#updateGridPositionsInPlace Source

updateGridPositionsInPlace :: forall row linkRow. PositionMap -> Simulation row linkRow -> Effect Unit

Update node gridX/gridY positions in place from a positions map Used to change force targets before reheating the simulation The positions map is keyed by node.id (as string) -> { x, y } where x becomes gridX and y becomes gridY

#updateGridXWithFn Source

updateGridXWithFn :: forall row linkRow. (SimulationNode row -> Number) -> Simulation row linkRow -> Effect Unit

Update gridX for all nodes using a function Useful for toggle animations where only the X target changes Example: toggle between combined (all same X) and separated (X by department)

#updateGridYWithFn Source

updateGridYWithFn :: forall row linkRow. (SimulationNode row -> Number) -> Simulation row linkRow -> Effect Unit

Update gridY for all nodes using a function Useful for toggle animations where only the Y target changes

#updateGridXYAndReinit Source

updateGridXYAndReinit :: forall row linkRow. Maybe (SimulationNode row -> Number) -> Maybe (SimulationNode row -> Number) -> Simulation row linkRow -> Effect Unit

Update gridX and/or gridY for all nodes, make the forces again so that they read the new values, and reheat.

This is the recommended way to animate force-directed transitions: a force reads its targets when it is initialized, so updating node.gridX alone changes nothing.

Example:

-- Move nodes to new X positions (Y unchanged)
updateGridXYAndReinit (Just (\node -> departmentX node.department)) Nothing sim

(Until 2026-11-18 this also took the handles of the forces to re-initialize; it now re-initializes them all.)

#attachDrag Source

attachDrag :: forall row linkRow. Array Element -> Simulation row linkRow -> Effect Unit

Attach simulation-aware drag behavior to node elements

This sets up pointer handlers (native Pointer Events, no D3) that:

  1. Reheat the simulation on drag start
  2. Update fx/fy (fixed position) during drag
  3. Clear fx/fy on drag end (release node)

Example:

elements <- select ".node" >>= selectAll
attachDrag elements sim

#attachGroupDrag Source

attachGroupDrag :: forall row linkRow. Array Element -> String -> Simulation row linkRow -> Effect Unit

Attach drag to transformed group elements (like bubble packs)

Unlike attachDrag, this version takes a container selector to get pointer coordinates in the correct coordinate space. Use this when dragging <g> elements that have transform attributes.

Example:

-- For bubble packs inside a zoom group
packElements <- select ".module-pack" >>= selectAll
attachGroupDrag packElements "#zoom-group" sim

#attachPinningDrag Source

attachPinningDrag :: forall row linkRow. Array Element -> Simulation row linkRow -> Effect Unit

Attach drag with toggle-pinning behavior

Unlike attachDrag, this version keeps nodes pinned after drag ends.

  • First drag: pins the node where you drop it
  • Subsequent drags: if you barely move (< 3px), unpins the node

This is useful for force playgrounds and exploration where users want to "fix" certain nodes in place while letting others float freely.

Example:

nodeElements <- select ".node" >>= selectAll
attachPinningDrag nodeElements sim

#querySelectorElements Source

querySelectorElements :: String -> Effect (Array Element)

Query DOM elements by CSS selector

Convenience re-export from Core for getting element references.

Example:

nodeCircles <- querySelectorElements "#my-graph circle"
attachPinningDrag nodeCircles sim