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 }
#D3_FocusXY Source
type D3_FocusXY :: Row Type -> Row Typetype D3_FocusXY row = (cluster :: Int, focusX :: Number, focusY :: Number | row)
#SwizzledLink Source
type SwizzledLink :: Row Type -> Row Type -> Typetype SwizzledLink nodeData r = { source :: SimulationNode nodeData, target :: SimulationNode nodeData | r }
Swizzled link where source/target are node object references
#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
#defaultConfig Source
defaultConfig :: SimConfigDefault 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 UnitSet 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 UnitAdd a force to the simulation
#addForceRecipe Source
addForceRecipe :: forall row linkRow. String -> ForceRecipe row -> Simulation row linkRow -> Effect UnitAdd 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 UnitDeprecated: 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 UnitRemove a force from the simulation
#clearForces Source
clearForces :: forall row linkRow. Simulation row linkRow -> Effect UnitClear 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 UnitMake 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 UnitStart the simulation animation loop
#tick Source
tick :: forall row linkRow. Simulation row linkRow -> Effect NumberRun a single tick of the simulation Returns the new alpha value
#reheat Source
reheat :: forall row linkRow. Simulation row linkRow -> Effect UnitReheat the simulation (set alpha to 1)
#setCallbacks Source
setCallbacks :: forall row linkRow. SimulationCallbacks -> Simulation row linkRow -> Simulation row linkRowSet 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 SimulationCallbacksGet the current callbacks (if any)
#isRunning Source
isRunning :: forall row linkRow. Simulation row linkRow -> Effect BooleanCheck if the simulation is running
#getAlpha Source
getAlpha :: forall row linkRow. Simulation row linkRow -> Effect NumberGet 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.
#getLinks Source
getLinks :: forall row linkRow. Simulation row linkRow -> Effect (Array { source :: Int, target :: Int | linkRow })Get the current links from the simulation Note: These are the raw links with source/target as Int IDs. For swizzled links (with node references), use swizzleLinksByIndex from Links module.
#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 UnitUpdate 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 UnitInterpolate 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 UnitPin 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 UnitUnpin 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 UnitPin 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
interpolatePositionsInPlace_ :: forall row. PositionMap -> PositionMap -> Number -> Ref (Array (SimulationNode row)) -> Effect Unit#pinNodesInPlace_ Source
pinNodesInPlace_ :: forall row. Ref (Array (SimulationNode row)) -> Effect Unit#unpinNodesInPlace_ Source
unpinNodesInPlace_ :: forall row. Ref (Array (SimulationNode row)) -> Effect Unit#updateGridPositionsInPlace Source
updateGridPositionsInPlace :: forall row linkRow. PositionMap -> Simulation row linkRow -> Effect UnitUpdate 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 UnitUpdate 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 UnitUpdate 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 UnitUpdate 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 UnitAttach simulation-aware drag behavior to node elements
This sets up pointer handlers (native Pointer Events, no D3) that:
- Reheat the simulation on drag start
- Update fx/fy (fixed position) during drag
- 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 UnitAttach 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 UnitAttach 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
- Modules
- Hylograph.
Config. Force - Hylograph.
Config. Scene - Hylograph.
ForceEngine - Hylograph.
ForceEngine. Core - Hylograph.
ForceEngine. Demo - Hylograph.
ForceEngine. Events - Hylograph.
ForceEngine. Links - Hylograph.
ForceEngine. Registry - Hylograph.
ForceEngine. Render - Hylograph.
ForceEngine. Setup - Hylograph.
ForceEngine. Setup. WASM - Hylograph.
ForceEngine. Simulation - Hylograph.
ForceEngine. Types - Hylograph.
ForceEngine. WASM - Hylograph.
ForceEngine. WASMEngine - Hylograph.
Scene. Engine - Hylograph.
Scene. Handle - Hylograph.
Scene. Rules - Hylograph.
Scene. Types - Hylograph.
Simulation - Hylograph.
Simulation. Emitter - Hylograph.
Simulation. HATS - Hylograph.
Simulation. Scene - Hylograph.
Simulation. Stepped - Hylograph.
Transition. Consumers - Hylograph.
Transition. Example