Module

Hylograph.Simulation.Stepped

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

One simulation, stepped by its caller, on either engine.

runSimulation owns the clock: it ticks on animation frames and tells you. This is for when you own it: a timeline that can be scrubbed, a layout computed before anything is drawn, a test. create takes the engine, and everything after that is the same record of functions whichever engine is behind it, meaning the same thing:

  • step makes one tick and returns the nodes where it left them; advance makes several and returns them once;
  • settled and the three measures say whether it has come to rest;
  • snapshot and restore go back to a moment exactly: the ticks that follow a restore are the ticks that followed the snapshot. A snapshot carries the tick number, the nodes, the links and the setup, so a restore needs nothing else, even after the nodes, links or forces have been changed;
  • retarget gives a Towards force new targets and reradius gives a Collide, Radial or Contain force new radii, without applying the setup again; reheat puts alpha back to one; pin holds or lets go of one node; relink puts other links between the same nodes;
  • applySetup changes the forces and parameters and keeps the nodes moving.

THE NODES ARE VALUES. create copies the records it is given and never writes into them. step, nodes and restore return records that are new after every tick, on both engines. One thing may be written on the records most recently returned: a pin (fx, fy, as a drag does), which the next step reads. (The engines underneath differ here, and this module is where they are made the same: the default engine, Hylograph.ForceEngine.Simulation, adopts the records it is given and moves them in place, as d3 does; the Rust one, Hylograph.ForceEngine.Setup.WASM, keeps its numbers in the kernel and makes new records each tick.)

ALPHA is zero once it has fallen below the setup's alphaMin, on both engines (it is the default engine's rule; the kernel alone would go on cooling), so a force scaled by alpha has then stopped altogether.

The Rust engine needs initWasm (or installKernel) first, and free when done with. The two engines compute the same rules, the default one in f64 and the Rust one in f32, so they agree to float width over a tick and drift apart after that, as any two roundings of a force layout do.

#Engine Source

data Engine

Which engine runs the simulation: the default one (the pure PureScript kernel, f64, nothing to load) or the Rust kernel (WASM, f32, faster).

Constructors

Instances

#Stepped Source

type Stepped :: Row Type -> Typetype Stepped row = { advance :: Int -> Effect (Array (SimulationNode row)), alpha :: Effect Number, applySetup :: Setup (SimulationNode row) -> Effect Unit, cooled :: Effect Boolean, engine :: Engine, free :: Effect Unit, kineticEnergy :: Effect Number, links :: Effect (Array Link), maxAcceleration :: Effect Number, maxDisplacement :: Effect Number, nodes :: Effect (Array (SimulationNode row)), pin :: Int -> Maybe Point -> Effect Unit, reheat :: Effect Unit, relink :: Array Link -> Effect Unit, reradius :: String -> (SimulationNode row -> Number) -> Effect Boolean, restore :: Snapshot row -> Effect (Array (SimulationNode row)), retarget :: String -> (SimulationNode row -> Maybe Point) -> Effect Boolean, settled :: Tolerance -> Effect Boolean, snapshot :: Effect (Snapshot row), step :: Effect (Array (SimulationNode row)), tick :: Effect Int }

A simulation under its caller's control. The same on both engines.

#Snapshot Source

newtype Snapshot :: Row Type -> Typenewtype Snapshot row

A moment of a simulation, complete: restoring it needs nothing else.

#Tolerance Source

type Tolerance = { acceleration :: Number, step :: Number }

How still is at rest: no node moved further than step in a tick, and no node's step changed by more than acceleration, over the last two.

#Point Source

type Point = { x :: Number, y :: Number }

#create Source

create :: forall row. Engine -> Setup (SimulationNode row) -> Array (SimulationNode row) -> Array { source :: Int, target :: Int } -> Effect (Stepped row)

A simulation of these nodes and links under this setup. The nodes are copied; links name their ends by node id. Throws if the setup has a force along the links and a link names a node that is not there.

#initWasm Source

initWasm :: String -> Aff Unit

Load the Rust kernel (once, before create Rust).

#installKernel Source

installKernel :: KernelModule -> Effect Unit

Install a kernel module loaded by other means instead (once, before create Rust); hylograph-wasm-kernel makes one from bytes it carries.

#snapshotTick Source

snapshotTick :: forall row. Snapshot row -> Int

The tick the snapshot was taken after.

#snapshotNodes Source

snapshotNodes :: forall row. Snapshot row -> Array (SimulationNode row)

#snapshotAlpha Source

snapshotAlpha :: forall row. Snapshot row -> Number

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.