Field Creation

✨ Quick Reference

• sim_add_field(ctx, shape[, options]) allocates a field and returns a Field handle (userdata) bound to the context. shape is an array of positive integers.
• Element types: type = "double" (default real) or type = "complex_double" (real/imag pairs). Element size follows automatically.
• Initialization: fill seeds every element (number or {re, im} for complex). initializer (Lua fn) overrides fill for 1D fields and is called with (index, coord).
• Spatial metadata: origin and spacing annotate coordinate mapping for initializers and some operators; they do not change storage layout.

🛠️ Options

Option	Type	Default	Notes
type	string	"double"	"complex_double" stores interleaved {re, im} pairs.
fill	number or {re, im}	0	Applied before initializer; complex fill requires a 2-element table.
initializer	function(index, coord) -> number or {re, im}	none	Only supported for 1D fields. Called for each element; return type must match type.
origin	number	0.0	Starting coordinate passed to initializer as coord.
spacing	number	1.0	Step size for coordinate progression in initializer.

🎉 Happy-Path Creation

local ctx = sim.sim_create()

-- Real 2D grid
local density = sim.sim_add_field(ctx, {256, 256}, { type = "double", fill = 0.0 })

-- Complex 1D grid with initializer
local wave = sim.sim_add_field(ctx, {1024}, {
    type = "complex_double",
    origin = -3.14,
    spacing = 0.0062,
    initializer = function(i, x)
        return { math.cos(x), math.sin(x) }
    end
})

💡 Best Practices

1. Provide a positive shape for each dimension; Lua errors on zero/negative entries.
2. Choose type up front; it fixes element size (sizeof(double) or 2*sizeof(double)).
3. Prefer fill for constant seeds and initializer for gradients or waveforms.
4. Capture the returned Field handle to pass into operators and to query rank/shape/values later.