Struct Simulation 

pub struct Simulation { /* private fields */ }

One built model and its schedule, stepped by its caller.

On native targets a CPU simulation runs the model code of each stepping, sampling, view, layout and action call inside one rayon::scope on the current pool, and pool.install(|| simulation.run_for(n)) picks the pool. run_for(0) and a run_to at or behind the current tick step nothing and enter no pool. Self::write_state enters it for its view preparation alone, and Self::set_param runs no parallel pass and stays on the calling thread. A GPU simulation runs each call on the calling thread, inside wgpu error scopes that keep a device error on the call that raised it.

Note that a call made from outside the pool runs as one job on it, and a worker waiting in another host’s join can run that job nested. The other host’s join then waits for the whole call. A host that steps independently steps inside install on its own pool.

An error no scope catches is stored in the context’s FaultSink, and whichever holder of the context waits next reports it. A lost device fails the next call that waits for the device with FaultKind::DeviceLost. Simulations that step at once on several threads each take their own device, for example from one henad::gpu::acquire_headless call per thread. A second GpuContext::new on one device takes over its error handling from the first context.

A call that returns a Fault can stop part way through a step or an action, with some of its edits applied. Every later stepping, sampling, live edit, action, view and layout call then returns a FaultKind::Refused fault that carries the first fault’s message, or FaultKind::DeviceLost once the device is lost. Rebuild from Self::setup to go on.

Implementations

impl Simulation

pub fn setup(&self) -> &RunSetup

Setup the simulation was built from. Live Self::set_param edits and immediate Self::act calls leave it unchanged.

pub fn tick(&self) -> u64

Number of ticks stepped so far.

pub fn population(&self) -> u64

Size of the population: its cells, its agents or its live nodes.

pub fn heap_bytes(&self) -> usize

Approximate memory the state owns: host heap for a CPU state, device buffers and textures for a GPU state.

pub fn parallel_jobs(&self) -> Option<usize>

Number of jobs one step splits into. None for a backend with no such split.

pub fn step(&mut self) -> Result<(), Fault>

Steps one tick. Same as run_for(1).

Note that each call enters the rayon pool once on the CPU and waits for the device once on the GPU. A loop of step() pays that per tick, where Self::run_for pays it once. A loop of step() from outside the pool belongs inside rayon::scope or pool.install.

Errors

Returns a Fault when the model panics or the device reports an error. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn run_for(&mut self, ticks: u64) -> Result<(), Fault>

Steps ticks ticks.

Note that without the template’s profile block, a debug build runs the kernels at opt-level 0 in the crate that registers the model, or in henad-models for an example entry, and its timings mean little. --release is the measured configuration.

Errors

Returns a Fault when the model panics or the device reports an error. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn run_to(&mut self, tick: u64) -> Result<(), Fault>

Steps up to tick and never past it. A tick at or behind the current one steps nothing.

Errors

Returns a Fault when the model panics or the device reports an error. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn run_sampled<B: WasmNotSend>( &mut self, end_tick: u64, interval: u64, on_sample: impl FnMut(&StatSample) -> ControlFlow<B> + WasmNotSend, ) -> Result<ControlFlow<B>, Fault>

Runs to end_tick, calling on_sample at the current tick, at each later multiple of interval, and at end_tick.

Returns the Break of the first sample that asks to stop, or Continue once end_tick is reached. Each sample is taken as Self::stats takes it. An end_tick at or behind the current tick steps nothing and takes the one sample at the current tick. Each call samples the tick it starts on, and two calls back to back both sample the tick they share.

On native targets a CPU model enters the pool once for the whole call, and on_sample runs inside it on a pool worker. It needs Send, and it holds that worker while it runs. A GPU model calls it on the calling thread. Either way on_sample runs outside the fault scopes, and a panic in it unwinds to the caller as an ordinary panic.

Note that a CPU model’s whole call can run nested under another host’s join on the same pool, as the type’s docs describe. An on_sample that waits on another user of the pool, for example through a bounded channel, can then deadlock.

Errors

Returns a Fault when the model panics or the device reports an error. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

Panics

Panics when interval is 0.

pub fn stats(&mut self) -> Result<StatSample, Fault>

Returns the stats of the current tick, sampled as a sweep track samples them: prepare_view first on the CPU, a blocking stats-only readback on the GPU.

Errors

Returns a Fault when the model panics or the device reports an error. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn set_param( &mut self, id: &str, value: impl Into<ParamValue>, ) -> Result<(), SetupError>

Sets parameter id on the running model.

Errors

Returns SetupError::Param for an unknown id or a value the descriptor rejects, SetupError::ReloadOnly for a parameter that takes effect only when the model is built, and SetupError::Fault when the model panics or the device reports an error. Once an earlier call returned a fault, a value the descriptor accepts gets FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn act(&mut self, action_id: &str) -> Result<(), SetupError>

Runs action action_id now, between ticks.

Errors

Returns SetupError::UnknownAction for an id the model does not declare, and SetupError::Fault when the model panics or the device rejects the action’s pass. Once an earlier call returned a fault, a declared action gets FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn views(&mut self) -> Result<SimulationViews<'_>, Fault>

Prepares the views as a publish would, then borrows all three together. A GPU model’s views stay on the device, and each view is None.

Errors

Returns a Fault when the model panics while preparing its views. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn relax_layout(&mut self, budget_ms: f32) -> Result<(), Fault>

Relaxes a network model’s layout for budget_ms milliseconds. A model without a layout keeps its points where they are.

Errors

Returns a Fault when the model panics. Once an earlier call returned a fault, the fault is FaultKind::Refused, or FaultKind::DeviceLost once the device is lost.

pub fn write_state(&mut self, writer: &mut dyn Write) -> Result<(), ExportError>

Writes the grid, points or edges as --export does.

Every section the model has is written, so a model with a field under its agents writes both the grid and the points. The views are prepared first, as Self::views prepares them.

Errors

Returns ExportError::Fault when the model panics while preparing its views. Once an earlier call returned a fault, it returns ExportError::Fault for every model, holding FaultKind::Refused, or FaultKind::DeviceLost once the device is lost. Otherwise it returns ExportError::GpuState for a GPU model, whose views stay on the device, and ExportError::Io when writer fails.

Trait Implementations

impl Debug for Simulation

Prints the setup and the tick, and leaves out the state.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.