Introspection

Fast Lookups ⚡

The context introspection API provides quick access to key metadata and diagnostics about the fields and operators registered within a simulation context. This is useful for debugging, logging, and adaptive control during simulation runs.

Field Inventory 📦

local count = ooc.field_count(ctx)
for i = 0, count - 1 do
    local info = ooc.field_info(ctx, i)
    ooc.log("Field %d: %s x %d elements", 
        info.index, info.format, info.element_count)
end

Note: Field Info Structure

field_info mirrors the native SimVisFieldInfo struct

• index is the zero-based field index
• rank is the number of dimensions
• element_count is the total number of elements (product of shape)
• format is a string such as real_double or complex_double
• shape is a Lua array of dimensions
• element_size/byte_size let you pre-size buffers when exporting data

format_value exposes the numeric enum alongside format, and populated fields also include components, element_size, and byte_size.

Operator Catalog 📚

local op_count = ooc.operator_count(ctx)
for i = 0, op_count - 1 do
    local desc = ooc.operator_descriptor(ctx, i)
    ooc.log("Operator #%d: %s (schema=%s)", 
        desc.index, desc.name or "?", desc.schema_key or "<none>")
end

Descriptors surface the schema key, which in turn defines parameter names, bounds, enum labels, and advanced options.

When a schema exists, the returned table includes the schema itself so you can render parameter forms without hard-coding them.

Parameter Inspection 🔍

local amp = ooc.operator_param(ctx, 0, "amplitude")
local mode = ooc.operator_param_enum(ctx, 0, "mode")
local source_field = ooc.operator_param_field(ctx, 0, "input")

-- Optional updates
ooc.operator_param_set(ctx, 0, "amplitude", amp * 0.5)
ooc.operator_param_enum_set(ctx, 0, "mode", "feedback")

Lua-side schema-aware operators (created via add_operator + operator_set_params) also round-trip correctly through these helpers because the config adapter forwards getters and setters into the Lua-owned parameter buffer.

Field-Parameter Setters

• operator_param_field_set(ctx, index, name, field_index_or_handle) writes a field-valued parameter directly. This is equivalent to calling operator_param_set with a field index, but is type-safe and matches how schemas declare type = "field".

-- point operator #2's "input" param at field #3
ooc.operator_param_field_set(ctx, 2, "input", 3)

-- or use a field handle
local f = ooc.get_field(ctx, 1)
ooc.operator_param_field_set(ctx, 2, "input", f)

Continuity & Analytic Faults 🔄

local counts = ooc.field_continuity_counts(ctx, 0)

ooc.log("field %d writes: dirty=%d stable=%d", 
    counts.index, counts.dirty, counts.stable)

local total_faults = ooc.special_fault_count(ctx)
local latest = ooc.special_fault_last(ctx)

if latest and latest.has_fault then
    ooc.log("last fault: %s at q=%.3g (iterations=%d)", 
        latest.fault, latest.q_param, latest.iterations)
end

Use clear_special_faults(ctx) to reset counters between experiments. Fault records expose the originating special function (function), input value, tuning parameters (q_param, aux_param, exponent_param), and convergence diagnostics (iterations, residual, tolerance), mirroring the reporting fields in lua_api.c.

The returned table also includes:

• count — total faults accumulated so far
• has_fault — false when there is no recorded report yet
• code / fault — numeric and string fault identifiers
• input — complex input as {re, im}

Plan Diagnostics 🧭

• context_plan_operator_count(ctx) returns the number of operators in the compiled execution plan (may be lower than the registered operator count after plan-time pruning).
• context_plan_is_valid(ctx) reports whether the plan graph is currently schedulable.

context_metrics(ctx) surfaces the same data as plan_operator_count and plan_valid fields, along with field_count, operator_count, backend, step_index, time_seconds, dt, and total_bytes — useful for lightweight health dashboards. backend is reported as an uppercase label such as CPU, CUDA, or Metal:

local diag = ooc.context_metrics(ctx)

if not diag.plan_valid then
    ooc.log(ooc.LOG_LEVEL_WARN,
        "Plan invalid: %d operators registered, %d in plan",
        diag.operator_count, diag.plan_operator_count)
end

Maintenance Helpers 🧰

• context_reset_continuity_counters(ctx) zeroes the dirty/stable write counters for all fields. Call this after manually mutating field data out-of-band so subsequent continuity diagnostics start from a clean baseline.
• context_flush_special_diagnostics(ctx) flushes accumulated special-function diagnostics into the context. The scheduler calls this automatically once per step when diagnostics are enabled; call it manually in explicit step loops if you need mid-run flushing.

ooc.context_reset_continuity_counters(ctx)
ooc.context_flush_special_diagnostics(ctx)