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 = sim.sim_create()

-- add fields/operators...

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

sim.sim_set_integrator(ctx, integrator)

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

sim.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.

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 sim = require("libsimcore")
local N = 512
local dt = 0.025
local ctx = sim.sim_create()

sim.sim_set_timestep(ctx, dt)

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

sim.sim_add_zero_field_operator(ctx, field_1)

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

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

sim.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 = sim.sim_apply_snapshot(ctx, {
    { name = "stimulus_sine#0", schema = "stimulus_sine", blob = "<hex...>" }
})
sim.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.