Introspection

⚡ Fast Lookups

Function	Description
`sim_field_count(ctx)`	Get # of registered fields
`sim_field_info(ctx, index)`	Get info about a specific field
`sim_operator_count(ctx)`	Get # of registered operators
`sim_operator_descriptor(ctx, index)`	Get info about a specific operator
`sim_operator_param(ctx, index, name)`	Get numeric/bool/int parameter
`sim_operator_param_enum(ctx, index, name)`	Get enum parameter key
`sim_operator_param_field(ctx, index, name)`	Get field-index parameter
`sim_field_continuity_counts(ctx, field_index)`	Get continuity violation counts
`sim_special_fault_count(ctx)`	Get total analytic fault count
`sim_special_fault_last(ctx)`	Get latest analytic fault report

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 = sim.sim_field_count(ctx)
for i = 0, count - 1 do
    local info = sim.sim_field_info(ctx, i)
    sim.log("Field %d: %s x %d elements",
        info.index, info.format, info.element_count)
end

📚 Operator Catalog

local op_count = sim.sim_operator_count(ctx)
for i = 0, op_count - 1 do
    local desc = sim.sim_operator_descriptor(ctx, i)
    sim.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 = sim.sim_operator_param(ctx, 0, "amplitude")
local mode = sim.sim_operator_param_enum(ctx, 0, "mode")
local source_field = sim.sim_operator_param_field(ctx, 0, "input")

-- Optional updates
sim.sim_operator_param_set(ctx, 0, "amplitude", amp * 0.5)
sim.sim_operator_param_enum_set(ctx, 0, "mode", "feedback")

Lua-side schema-aware operators (created via sim_add_operator + sim_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

sim_operator_param_field_set(ctx, index, name, field_index_or_handle) writes a field-valued parameter directly. This is equivalent to calling sim_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
sim.sim_operator_param_field_set(ctx, 2, "input", 3)

-- or use a field handle
local f = sim.sim_get_field(ctx, 1)
sim.sim_operator_param_field_set(ctx, 2, "input", f)

🔄 Continuity & Analytic Faults

local counts = sim.sim_field_continuity_counts(ctx, 0)

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

local total_faults = sim.sim_special_fault_count(ctx)
local latest = sim.sim_special_fault_last(ctx)

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

Use sim_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.

🧭 Plan Diagnostics

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

These helpers are part of the core context API (C/FFI). Lua bindings surface the same data via sim_context_metrics(ctx) as plan_operator_count and plan_valid:

local diag = sim.sim_context_metrics(ctx)

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

🛠️ Maintenance Helpers

sim_reset_continuity_counters(ctx) zeroes the dirty/stable write counters for all fields. Useful after manually mutating field data out-of-band so subsequent continuity diagnostics start fresh.
sim_flush_special_diagnostics(ctx) flushes the accumulated special-function diagnostics into the context (C/FFI helper; the scheduler already calls this once per step when diagnostics are enabled).

Lua does not expose these directly; call via FFI or embedder-side glue if you need to reset/flush mid-run. Continuity counters can also be reset implicitly by recreating the context or explicitly invoking the C API:

-- Example using LuaJIT FFI (if available)
local ffi = require("ffi")
ffi.cdef [[ void sim_reset_continuity_counters(void* ctx); ]]
ffi.cdef [[ void sim_flush_special_diagnostics(void* ctx); ]]
ffi.C.sim_reset_continuity_counters(ctx)
ffi.C.sim_flush_special_diagnostics(ctx)