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:

Quick Setup 💡

1. Create & configure — call create() with optional config, then set your timestep.
2. Add state — allocate fields and operators, then attach an integrator with set_integrator.
3. Drive the loop — step manually with step or hand off to a scheduler via run. Use on_step for lightweight instrumentation.

Configuration Keys 🔑

Top-level Config

Note: Implicit Global Config

If you call create() or context_init_with_universe() without an explicit config table, Oakfield will also look for a global sim_config table and apply the same keys from there.

Continuity Override

Note: Continuity Override Behavior

Continuity overrides are applied immediately after creation via context_set_continuity_override, so the first operator you register already reflects the chosen policy.

Runtime Continuity Controls

You can update (or disable) the global continuity override at any time:

-- enable/replace override
ooc.context_set_continuity_override(ctx, true, {
    mode = "limited",
    tolerance = 1.0e-3,
    boundary = "neumann",
})

-- disable override (keeps defaults from schemas)
ooc.context_set_continuity_override(ctx, false)

Note: Scheduler-backed Execution

worker_count, enable_logging, enable_profiling, enable_timestep_heuristics, frame_time_budget_ms, and log_path primarily affect scheduler-backed execution.

That includes run(ctx, ...), and also step(ctx) when the runtime chooses the scheduler path internally (for example: multi-worker execution with an attached integrator and no Lua operator callbacks). When step falls back to the legacy single-threaded path, those knobs have little or no effect.

Caution: Log Path Safety

log_path must be a safe relative path (no absolute paths or .. traversal). Invalid paths raise an error when the config is applied.

Example 📖

local ctx = ooc.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",
    }
})

ooc.set_timestep(ctx, 0.025)

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

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

ooc.set_integrator(ctx, integrator)

ooc.on_step(ctx, function(c)
    local t = ooc.get_time(c)
    ooc.log("step %d at t=%.3f", ooc.get_step_index(c), t)
end)

ooc.step(ctx)   -- single-step drive
ooc.shutdown(ctx)

Tip: When to use run

run, pause, and resume are thin scheduling helpers intended for GUI/evented drivers.

For scriptable batch jobs (as in lua/scripts/cli/*), explicit step loops keep control flow and logging predictable.

Universe & Seeding (Advanced) 🧬

Most scripts should use create. If you need to control the special-function universe at context construction time, use:

context_init_with_universe([config], [universe]) -> ctx

The function accepts either order (config/universe are auto-detected by keys). universe may include:

• q (number)
• K (integer, non-negative)
• epsilon (number)
• sieve_sigma (number)
• poles (array of {x,y,z,residue,type}; type is "digamma"|"trigamma"|"tetragamma")

You can read the normalized base seed used for deterministic RNG streams with:

context_seed(ctx) -> integer

Representation & Time Model 🧭

Representation mode governs determinism guarantees and what kinds of operators/kernels are allowed:

context_set_representation_mode(ctx, mode)
context_representation_mode(ctx) -> mode_value, mode_name

mode accepts strict, relaxed, or exploration.

Common aliases are also accepted:

• explore / experimental for exploration

Time model controls whether dt refinement is treated as convergent (continuous flow) or as part of a discrete map:

context_set_time_model(ctx, "continuous" | "map")

Aliases:

• flow for continuous
• discrete for map

Backend Escape Hatch 🔌

Most scripts should use the backend / backend_fallback config keys. For lower-level host integration, the context also exposes its raw backend pointer:

context_backend(ctx) -> lightuserdata|nil
context_set_backend(ctx, backend_ptr_or_nil)

Passing nil detaches any explicitly assigned backend. This is primarily for embedders or tooling that already owns backend instances.

Drift Sandbox 🧪

Drift mode is a “no side effects” evaluation mode used by tooling to probe operators without updating continuity counters/warp masks. Some operators also implement optional save/restore hooks so state is reverted.

context_begin_drift(ctx)
context_end_drift(ctx)
context_in_drift(ctx) -> boolean

Context Logger 🧾

Attach a per-context logger callback (distinct from the scheduler’s async logger):

context_set_logger(ctx, fn_or_nil)

fn_or_nil is called as fn(level_int, message_string).

Emit warnings through the context logger (falls back to stderr if no logger is set):

context_log_warning(ctx, fmt, ...)

Determinism & Kernel Gating 🧷

These helpers let tooling decide whether a kernel-backed operator is allowed given the current backend and representation policy:

context_allows_determinism(ctx, flags) -> boolean
context_kernel_allowed(ctx, required_features, determinism_flags) -> boolean
context_kernel_allowed_mode(ctx, mode, required_features, determinism_flags) -> boolean

flags / determinism_flags can be an integer bitmask or a table of strings: "pure_time", "rewind_safe", "no_stateful_nodes", "deterministic_rng_only".

Memory Limits & Scratch Accounting 🧠

Contexts track memory usage for fields and scratch allocations and enforce configurable limits:

context_set_memory_limits(ctx, limits_table)
context_get_memory_limits(ctx) -> limits_table
context_memory_usage(ctx) -> {fields, scratch, total}
context_check_field_limits(ctx, element_count, field_bytes) -> ok, result_code
context_reserve_scratch(ctx, bytes) -> ok, result_code
context_release_scratch(ctx, bytes)

limits_table keys:

• max_field_elements
• max_field_bytes
• max_fields
• max_total_field_bytes
• max_scratch_bytes_per_operator

Diagnostics & Special-Function Flush 🩺

Read the context diagnostics snapshot (fault counts, representation adjustments, etc.):

context_diagnostics(ctx) -> table|nil
context_diagnostics_const(ctx) -> table|nil

When compiled with SIM_DIAGNOSTICS, you can flush accumulated special-function diagnostics into the context:

context_flush_special_diagnostics(ctx)

If diagnostics are disabled, the Lua binding returns false, "SIM_DIAGNOSTICS disabled".

Manual Operator Application 🧰

Apply a single operator immediately (bypassing step/integrators). Useful for debugging or tooling:

context_apply_operator(ctx, operator_or_index) -> ok, result_code