Field Handles & Methods

🎯 Getting a Handle

• Use sim_add_field to allocate or sim_get_field(ctx, index) to retrieve an existing one.
• 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).

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

📖 Usage

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

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

for i, z in ipairs(f:values()) do
    sim.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.