Context Creation

✨ Lifecycle at a Glance

The simulation context (ctx) is the core object managing state, operators, fields, and execution. Use the following functions to create and control contexts:

Function	Description
`sim_create([config])`	Create a new simulation context with optional configuration.
`sim_step(ctx)`	Advance the simulation by one timestep.
`sim_on_step(ctx, fn)`	Register a callback to execute after each step (accepts `nil` to clear).
`sim_run(ctx, [config])`	Start a scheduling loop (GUI mode) with optional config.
`sim_pause(ctx)`	Pause the scheduling loop.
`sim_resume(ctx)`	Resume a paused scheduling loop.
`sim_shutdown(ctx)`	Shutdown the simulation context, releasing resources.

💡 Quick Setup

Create & configure — call sim_create() with optional config, then set your timestep.
Add state — allocate fields and operators, then attach an integrator with sim_set_integrator.
Drive the loop — step manually with sim_step or hand off to a scheduler via sim_run. Use sim_on_step for lightweight instrumentation.

🔑 Configuration Keys

Top-level Config

Key	Type	Notes
`worker_count`	integer	Number of worker threads; defaults to the runtime’s autodetected value.
`frame_time_budget_ms`	number	Soft budget for per-frame work; used by schedulers that honor frame pacing.
`log_path`	string	Optional log file path for the async logger.
`continuity_override`	table	Optional continuity guard applied across operators (see below).

Continuity Override

Key	Type	Allowed Values	Notes
`enabled`	boolean	`true`/`false`	Toggles continuity guards globally.
`mode`	string	`none`, `strict`, `clamped`, `limited`	Modes mirror operator schema defaults; `strict` preserves analytic continuity while `clamped/limited` bound singularities.
`clamp_min` / `clamp_max`	number	any	Hard bounds applied when `clamped` or `limited`.
`tolerance`	number	any	Blending window for `limited` mode.
`boundary`	string	`neumann`, `dirichlet`, `periodic`, `reflective`	Inherits boundary policy definitions from operator schemas.
`spacing` / `dx`	number or number[]	positive	Optional spatial spacing override; `spacing` accepts an array, `dx` a scalar.

📖 Example

local sim = require("libsimcore")

local ctx = sim.sim_create({
    worker_count = 2,
    log_path = "logs/run.log",
    continuity_override = {
        enabled = true,
        mode = "clamped",
        clamp_min = -4.0,
        clamp_max = 4.0,
        boundary = "neumann",
    }
})

sim.sim_set_timestep(ctx, 0.025)

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

local integrator = sim.sim_create_context_integrator(ctx, "rkf45", {
    initial_dt = 0.025,
    tolerance = 1.0e-3,
    safety = 0.9
})

sim.sim_set_integrator(ctx, integrator)

sim.sim_on_step(ctx, function(c)
    local t = sim.sim_get_time(c)
    sim.log("step %d at t=%.3f", sim.sim_get_step_index(c), t)
end)

sim.sim_step(ctx)   -- single-step drive
sim.sim_shutdown(ctx)