Running Simulations

⌨️ CLI Scripting Basics

When running simulations from the command line, you typically control the main loop yourself. This gives you full flexibility over logging, checkpoints, and termination conditions.

local ctx = ooc.sim_create()

-- add fields/operators...

local integrator = ooc.sim_create_context_integrator(ctx, "rkf45", {
    initial_dt = 0.01,
    adaptive = true
})

ooc.sim_set_integrator(ctx, integrator)

for step = 1, 10000 do
    if not ooc.sim_step(ctx) then
        ooc.log(ooc.LOG_LEVEL_ERROR, "step %d failed", step)
        break
    end
    if step % 100 == 0 then
        local m = ooc.sim_step_metrics_latest(ctx)
        if m then ooc.log("t=%.3f dt=%.4f rms=%.2e",
            ooc.sim_get_time(ctx), m.accepted_dt, m.rms_error)
        end
    end
end

ooc.sim_shutdown(ctx)

CLI Execution Model

In CLI mode, your script is responsible for the simulation loop. You call sim_step repeatedly to advance the simulation. This gives you control over timing, logging, and error handling.

Using the Scheduler Directly

You can also hand control to the scheduler in CLI or embedder contexts: sim_run(ctx, [config]) starts the scheduler loop, and sim_pause / sim_resume toggle it. The optional config table accepts the same keys as sim_create (worker count, logging, profiling, heuristics, base seed, etc.).

🟢 Scheduler State & Logs

sim_is_running(ctx) -> boolean

Returns true when the scheduler loop is currently driving the context (started via sim_run and not yet shut down).

sim_scheduler_drain_logs(ctx, [min_level], [callback]) -> boolean

Drains the scheduler’s async log buffer (only when scheduler logging is enabled). Returns true if any records were drained.

Accepted call patterns:

• sim_scheduler_drain_logs(ctx) drains and discards all pending records.
• sim_scheduler_drain_logs(ctx, "warn") drains only warn and above (discarded).
• sim_scheduler_drain_logs(ctx, function(level, message) ... end) drains and invokes the callback for each record.
• sim_scheduler_drain_logs(ctx, "info", function(level, message) ... end) combines filtering + callback.

Metrics & Diagnostics

You can access step metrics and diagnostics at any time using:

• sim_step_metrics_latest(ctx) - latest step metrics (dt, error, etc.)
• sim_step_metrics_history(ctx) - full history of step metrics
• sim_field_continuity_counts(ctx, field_index) - continuity violation counts per field/operator

🖥️ GUI Scripting Basics

When launching from the GUI, the script should return a context (or table containing it). Minimal smooth setup:

local N = 512
local dt = 0.025
local ctx = ooc.sim_create()

ooc.sim_set_timestep(ctx, dt)

local field_1 = ooc.sim_add_field(ctx, {N}, {
    type = "complex_double",
    fill = {0.0, 0.0}
})

ooc.sim_add_zero_field_operator(ctx, field_1)

ooc.sim_add_stimulus_operator(ctx, field_1, {
    type = "stimulus_sine",
    amplitude = 0.25,
    wavenumber = 0.025,
    omega = 0.1
})

local integrator = ooc.sim_create_context_integrator(ctx, "euler")

ooc.sim_set_integrator(ctx, integrator)

return ctx

GUI Execution Model

In GUI mode, the host application manages the simulation loop. Your script sets up the context and returns it. The GUI will then call sim_step repeatedly to advance the simulation, handling timing, rendering, and user input.

• The host may adjust timing to sync with rendering or user input; expect slight variations in step cadence.

Context Return

When scripting for the GUI, ensure your script returns the context object (or a table containing it). The GUI uses this to manage simulation execution.

Evented Callbacks

If you register sim_on_step or similar callbacks, remember they are invoked by the GUI loop. Avoid long-running computations in these callbacks to prevent UI freezes.

📸 Applying Snapshots

sim_apply_snapshot(ctx, snapshot_table) -> applied_count

Applies a snapshot produced by the visual tooling or your own saved state. Each entry must include:

• name (operator name)
• schema (schema key)
• blob (hex string of the serialized params)
• optional index (operator index hint) and size (expected blob size)

Operators are matched by GUID/name (and index hint when present) and updated in place.

Example:

-- assume `snap` was captured previously (e.g., from GUI)
local applied = ooc.sim_apply_snapshot(ctx, {
    { name = "stimulus_sine#0", schema = "stimulus_sine", blob = "<hex...>" }
})
ooc.log("applied %d snapshot entries", applied)

Snapshot Compatibility

• Ensure the snapshot matches the current context’s operators; mismatched or missing entries are skipped.
• If operators have been added/removed since capture, only matching ones are applied.

Inspecting Snapshot Effects

Pair with sim_operator_param_* helpers to inspect values after application, or rerun the plan after a snapshot to re-validate continuity if you changed field wiring.