Handles & Methods

🎯 Getting a Handle

• Use sim_add_field to allocate or sim_get_field(ctx, index) to retrieve an existing one (indices are 0-based).
• The returned userdata carries methods defined in lua_bindings.c and keeps the field pinned to the context.

🛠️ Methods

• field:rank() returns the tensor rank (dimension count) via sim_field_rank.
• field:shape() returns a Lua array of extents for each dimension.
• field:components() returns components per element (1 for real, 2 for complex).
• field:values() materializes the field into a Lua table (numbers for real, {re, im} tables for complex).
  • Values are returned in row-major order (axis rank-1 fastest).
  • values() returns a copy; changing it does not mutate the field.
  • Only double and complex_double storage are supported; other formats raise an error.

__tostring is also provided for debugging (Field(<ptr>) or Field(nil)), and garbage collection clears the handle without touching the underlying context storage.

🧰 Context Helpers

• sim_field_count(ctx) returns the number of fields in the context.
• sim_get_field(ctx, index) returns a Field handle for the 0-based index (errors if out of range).
• sim_field_info(ctx, index) returns a table or nil if the field is missing:
  • index, rank, element_count, shape
  • format (e.g. real_double, complex_double) and numeric format_value
  • components, element_size, byte_size
• sim_field_stats(ctx, index_or_field) returns a stats proxy with cached values for the current step.
  • Access fields like mean_re, mean_im, mean_abs, rms, var_re, var_im, var_abs, max_abs, phase_coherence, circularity, spectral_entropy, spectral_bandwidth, phase_coherence_weighted, phase_coherence_ema, phase_coherence_k0, phase_sample_count, phase_lock_state, phase_regime, count, continuity_dirty_ops, continuity_stable_ops.
  • Call stats:refresh() to force a recompute; pairs(stats) iterates a snapshot table.
• sim_field_continuity_counts(ctx, index) returns { index, dirty, stable } for the last step.

📖 Usage

local ctx = ooc.sim_create()
local f = ooc.sim_add_field(ctx, {8}, { type = "complex_double", fill = {1, 0} })

ooc.log("rank=%d shape=%s components=%d",
    f:rank(),
    table.concat(f:shape(), "×"),
    f:components())

for i, z in ipairs(f:values()) do
    ooc.log("[%d] = %.1f + %.1fi", i, z[1], z[2])
end

When to use field:values()

values() copies the entire buffer into Lua, which is convenient for logging and small diagnostics. For large fields, prefer native operators or export via C-side hooks to avoid unnecessary copies.