Module

Hylograph.Simulation

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

Hylograph Force Simulation

High-level API for running force-directed simulations. Two engines with the same interface: the default, in PureScript (hylograph-forces, no D3), and the Rust/WASM kernel.

Quick Start

import Hylograph.Simulation (runSimulation, Engine(..), SimulationEvent(..))
import Hylograph.Simulation.Emitter (subscribe)

main = do
  -- Run simulation - returns handle AND event emitter
  { handle, events } <- runSimulation
    { engine: Pure  -- or WASM (same config!)
    , setup: setup "physics"
        [ manyBody "charge" # withStrength (static (-30.0))
        , center "center"
        ]
    , nodes: myNodes
    , links: []
    , container: "#my-svg"
    , alphaMin: 0.001
    }

  -- Subscribe to events (framework-agnostic)
  unsubscribe <- subscribe events \event -> case event of
    Tick { alpha } -> log $ "Alpha: " <> show alpha
    Completed -> log "Simulation converged!"
    _ -> pure unit

  -- Get nodes for rendering (use HATS or your own rendering)
  nodes <- handle.getNodes

  -- Update data (GUP semantics, auto-reheat)
  result <- handle.updateData newNodes newLinks

Framework Integration

Halogen: Use toHalogenEmitter from Hylograph.Simulation.Halogen React: Use subscribe in a useEffect hook with cleanup Vanilla: Just call subscribe directly

#runSimulation Source

runSimulation :: forall r. SimulationConfig r -> Effect (SimulationResult r)

Run a force simulation with Hylograph visualization.

Returns both a handle for controlling the simulation AND an event emitter for subscribing to simulation events. This design is framework-agnostic:

  • The emitter works with Halogen, React, or vanilla JS
  • Events include Tick, Started, Stopped, and Completed
  • The same code works for both engines Note: No Ord constraint required! We use renderTreeKeyed with a key function based on node.id, which doesn't require Ord on the datum type. This allows SimulationNode r (an extensible record) to work without needing Ord derivation.

#SimulationResult Source

type SimulationResult :: Row Type -> Typetype SimulationResult r = { events :: SimulationEmitter, handle :: SimulationHandle r }

Result returned by runSimulation

  • handle: Control the simulation (update data, stop, start, etc.)
  • events: Subscribe to simulation events (Tick, Completed, etc.)

#SimulationConfig Source

type SimulationConfig :: Row Type -> Typetype SimulationConfig r = { alphaMin :: Number, container :: String, engine :: Engine, links :: Array { source :: Int, target :: Int }, nodes :: Array (SimulationNode r), setup :: Setup (SimulationNode r) }

Configuration for running a simulation

Note: There's no onComplete callback - use the events emitter instead. This keeps the API framework-agnostic.

Rendering is handled externally via the Tick event and handle.getNodes. Use HATS or any other rendering approach to render node positions on each tick.

#Engine Source

data Engine

Which engine runs the forces.

  • Pure: the default. hylograph-forces: d3-force's forces bit for bit and the Rust kernel's additions, in PureScript. Nothing to load, no D3.
  • WASM: the Rust/WASM kernel, the fast path. Needs initWASM (or installKernel) first.
  • D3: deprecated, and the same as Pure. It is kept so that code written when the default engine drove d3-force's functions still compiles; there is no D3 behind it any more.

Constructors

#SimulationHandle Source

type SimulationHandle :: Row Type -> Typetype SimulationHandle r = { getAlpha :: Effect Number, getNodes :: Effect (Array (SimulationNode r)), interpolatePositions :: PositionMap -> PositionMap -> Number -> Effect Unit, pinNodes :: Effect Unit, reheat :: Effect Unit, start :: Effect Unit, stop :: Effect Unit, unpinNodes :: Effect Unit, updateData :: Array (SimulationNode r) -> Array { source :: Int, target :: Int } -> Effect { links :: GUPLinkResult (), nodes :: GUPResult (SimulationNode r) }, updateSetup :: Setup (SimulationNode r) -> Effect Unit }

Handle for controlling the simulation

#PositionMap Source

type PositionMap = PositionMap

Position map for interpolation - keyed by node ID (as string)

#initWASM Source

initWASM :: String -> Aff Unit

Initialize the WASM physics engine. Call once at application startup before using Engine.WASM.

Example: initWASM "./pkg/force_kernel.js"

#installKernel Source

installKernel :: KernelModule -> Effect Unit

Install a kernel module loaded by other means instead of initWASM (hylograph-wasm-kernel makes one from bytes it carries). If a module is already installed, this does nothing.

Re-exports from Hylograph.ForceEngine.Setup

#Setup Source

type Setup node = { forces :: Array (ForceConfig node), name :: String, params :: SetupParams }

Complete setup: forces + simulation params

#GUPResult Source

type GUPResult node = { entered :: Array node, exited :: Array node, updated :: Array node }

Result of a node data update with enter/update/exit categorization

  • entered: Nodes newly added to simulation (use for enter animations)
  • updated: Existing nodes that were modified (simulation state preserved)
  • exited: Nodes removed from simulation (use for exit animations)

#GUPLinkResult Source

type GUPLinkResult :: Row Type -> Typetype GUPLinkResult linkRow = { entered :: Array { source :: NodeID, target :: NodeID | linkRow }, exited :: Array { source :: NodeID, target :: NodeID | linkRow }, updated :: Array { source :: NodeID, target :: NodeID | linkRow } }

Result of a link data update with enter/update/exit categorization Links are keyed by (source, target) pair

#withY Source

withY :: forall node. Value node Number -> ForceConfig node -> ForceConfig node

Set Y: the target of PositionY (per node if dynamic), or the centre of Center and Radial (static only).

#withX Source

withX :: forall node. Value node Number -> ForceConfig node -> ForceConfig node

Set X: the target of PositionX (per node if dynamic), or the centre of Center and Radial (static only).

#withTheta Source

withTheta :: forall node. Number -> ForceConfig node -> ForceConfig node

Set theta (Barnes-Hut approximation, for ManyBody)

#withStrength Source

withStrength :: forall node. Value node Number -> ForceConfig node -> ForceConfig node

Set strength.

Per node (dynamic) for ManyBody, PositionX/Y, Radial, Towards and Cohesion. Collide, Center, RectCollide and Contain have one strength: a static sets it, a dynamic is ignored. For Link and Directional a static sets every link's strength and a dynamic, being a function of a node, is ignored: use withLinkStrength.

#withRadius Source

withRadius :: forall node. Value node Number -> ForceConfig node -> ForceConfig node

Set radius (Collide and Radial; the node's own radius for Contain)

#withIterations Source

withIterations :: forall node. Int -> ForceConfig node -> ForceConfig node

Set iterations (for Collide, Link, RectCollide, Directional)

#withFilter Source

withFilter :: forall node. (node -> Boolean) -> ForceConfig node -> ForceConfig node

Add a filter predicate: the force only applies to matching nodes. For ManyBody (a filtered-out node exerts no charge but is still pushed), Collide and RectCollide (a filtered-out node collides with nothing), PositionX, PositionY, Radial, Towards and Cohesion.

#withDistanceMin Source

withDistanceMin :: forall node. Number -> ForceConfig node -> ForceConfig node

Set distance min (for ManyBody)

#withDistanceMax Source

withDistanceMax :: forall node. Number -> ForceConfig node -> ForceConfig node

Set distance max (for ManyBody)

#withDistance Source

withDistance :: forall node. Value node Number -> ForceConfig node -> ForceConfig node

Set every link's distance (for Link; static only: a dynamic here is a function of a node and is ignored, use withLinkDistance).

#static Source

static :: forall node a. a -> Value node a

Create a static value

#setup Source

setup :: forall node. String -> Array (ForceConfig node) -> Setup node

Create a setup with default params

#radial Source

radial :: forall node. String -> ForceConfig node

Create a radial force Default: radius 100, center (0,0), strength 0.1

#positionY Source

positionY :: forall node. String -> ForceConfig node

Create a Y-positioning force Default: y = 0, strength 0.1

#positionX Source

positionX :: forall node. String -> ForceConfig node

Create an X-positioning force Default: x = 0, strength 0.1

#manyBody Source

manyBody :: forall node. String -> ForceConfig node

Create a many-body (charge) force Default: repulsive with strength -30

#dynamic Source

dynamic :: forall node a. (node -> a) -> Value node a

Create a dynamic (per-node, or per-link) value

#collide Source

collide :: forall node. String -> ForceConfig node

Create a collision force Default: radius 1, strength 1

#center Source

center :: forall node. String -> ForceConfig node

Create a centering force Default: center at (0, 0), strength 1

Re-exports from Hylograph.ForceEngine.Simulation

#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 }

Re-exports from Hylograph.ForceEngine.WASM

#KernelModule Source

data KernelModule

The kernel's wasm-bindgen module, already instantiated: what the loader generated by wasm-pack (--target web) exports once its default export has been awaited, with Simulation among its exports. Made by whatever carries the module (the hylograph-wasm-kernel package makes one from bytes it carries) and handed to installKernel.

Re-exports from Hylograph.Simulation.Emitter

#SimulationEvent Source

data SimulationEvent

Event types emitted by simulations

These are the same regardless of whether D3 or WASM is running the physics.

Constructors

Instances

#SimulationEmitter Source

newtype SimulationEmitter

Framework-agnostic event emitter

This is intentionally opaque - use subscribe to listen for events. The internal representation is a list of listeners with unique IDs.

#subscribe Source

subscribe :: SimulationEmitter -> (SimulationEvent -> Effect Unit) -> Effect Unsubscribe

Subscribe to events

Returns an unsubscribe function that removes the listener.

unsubscribe <- subscribe emitter \event -> case event of
  Tick { alpha } -> log $ "Alpha: " <> show alpha
  Completed -> log "Simulation converged!"
  _ -> pure unit

-- Later, to stop listening:
unsubscribe