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)

Manual Step Hook

sim_on_step is invoked by sim_step after a successful step. Scheduler-driven loops (sim_run) do not call the Lua hook unless the host explicitly steps through sim_step.

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
step_index	integer	The zero-based step counter at the time of the record.
requested_dt	double	The timestep requested at the start of the step.
accepted_dt	double	The timestep accepted at the end of the step.
next_dt	double	The suggested next timestep for adaptive integrators.
rms_error	double	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.

Timestep Heuristics Preview

Query the scheduler’s adaptive timestep recommendation (if enabled):

sim_timestep_decision(ctx) -> decision

The decision table includes:

Field	Type	Description
kind	string	keep, shrink, or expand.
kind_value	integer	Numeric enum value for the decision.
suggested_dt	double	Proposed timestep if the decision is applied.
enabled	boolean	Whether heuristics are enabled (enable_timestep_heuristics).
available	boolean	true when a preview decision is available for the current context.

Decision Availability

available is false until the scheduler has recorded step metrics (and when heuristics are disabled or the scheduler is not active).

⚙️ 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	double	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	double	The minimum allowed timestep for adaptive integrators.
max_dt	double	The maximum allowed timestep for adaptive integrators.
tolerance	double	The error tolerance for adaptive integrators.
safety	double	The safety factor for adaptive timestep selection.
current_dt	double	The current timestep being used by the integrator.

🔍 Reading Clocks & Metrics

local ok = ooc.sim_step(ctx)
if ok then
    local t = ooc.sim_get_time(ctx)
    local metrics = ooc.sim_step_metrics_latest(ctx)
    if metrics then
        ooc.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(ooc.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

ooc.sim_on_step(ctx, function(context)
    t = t + 1
    local s = math.sin(t * 0.000005)
    ooc.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.