Time & Timestep

Time & Timestep Management

Set the timestep used by the integrator or direct plan execution with:

sim_set_timestep(ctx, dt)

Read the accumulated simulation time, timestep, and step index with:

sim_get_time(ctx) -> time
sim_get_timestep(ctx) -> dt
sim_get_step_index(ctx) -> step_index

On-step Callbacks

Register a callback to be invoked after each successful step:

sim_on_step(ctx, fn)

Step Metrics

After each successful step, the runtime records metrics including accepted/requested timestep, RMS error, dirty/stable writes, and active warp mask. Access these via sim_step_metrics_latest and sim_step_metrics_history.

sim_step_metrics_latest(ctx) -> metrics
sim_step_metrics_history(ctx, [max_count]) -> metrics_array

The metrics table has the following fields:

Field	Type	Description
requested_dt	number	The timestep requested at the start of the step.
accepted_dt	number	The timestep accepted at the end of the step.
next_dt	number	The suggested next timestep for adaptive integrators.
rms_error	number	The RMS error estimate for the step.
dirty_writes	integer	Number of fields/operators that wrote data this step.
stable_writes	integer	Number of fields/operators that wrote stable data this step.
active_warp_mask	integer	Bitmask of active warps during this step.

⚙️ Integrator Controls

Attach an integrator to the context with sim_set_integrator, then control its behavior with the following functions:

sim_set_integrator_adaptive(ctx, enabled)
sim_set_integrator_stochastic(ctx, enabled)
sim_set_integrator_stochastic_strength(ctx, strength)
sim_set_integrator_noise(ctx, noise_type)
sim_set_integrator_seed(ctx, seed)
sim_integrator_info(ctx) -> info_table

The info_table returned by sim_integrator_info includes:

Field	Type	Description
name	string	The integrator’s name (e.g., “rkf45”).
adaptive_enabled	boolean	Whether adaptivity is enabled.
enable_stochastic	boolean	Whether stochastic perturbations are enabled.
stochastic_strength	number	The strength of stochastic perturbations.
noise	string	The type of noise applied (e.g., “gaussian”).
random_seed	integer	The RNG seed currently in use.
min_dt	number	The minimum allowed timestep for adaptive integrators.
max_dt	number	The maximum allowed timestep for adaptive integrators.
tolerance	number	The error tolerance for adaptive integrators.
safety	number	The safety factor for adaptive timestep selection.
current_dt	number	The current timestep being used by the integrator.

🔍 Reading Clocks & Metrics

local ok = sim.sim_step(ctx)
if ok then
    local t = sim.sim_get_time(ctx)
    local metrics = sim.sim_step_metrics_latest(ctx)
    if metrics then
        sim.log("t=%.4f dt=%.4f rms=%.2e writes=%d",
            t, metrics.accepted_dt, metrics.rms_error, metrics.dirty_writes)
    end
end

-- Grab a rolling window (up to SIM_STEP_METRIC_HISTORY)
for _, m in ipairs(sim.sim_step_metrics_history(ctx, 32)) do
    -- m has the same shape as metrics above
end

sim_sleep(seconds) is available when you need to yield control in GUI/evented loops without shutting down the context.

🪝 On-step Hooks for Sweeps/Logging

local t = 0

sim.sim_on_step(ctx, function(context)
    t = t + 1
    local s = math.sin(t * 0.000005)
    sim.sim_operator_param_set(ctx, 1, "wavenumber", s)
end)

Use this for lightweight parameter sweeps or GUI-driven probes. Because the plan is invalidated each step, avoid heavy work inside the callback; keep it to parameter updates or logging.

🔄 Typical Drive Loop

1. Seed the timestep with sim_set_timestep (or leave the default if your integrator supplies one).
2. Attach an integrator and optionally enable adaptivity/noise policies.
3. Step with sim_step, read sim_get_time and metrics, and adjust parameters mid-run if needed.