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). Unrecognized types fall back to "double".
• Initialization: fill seeds every element (number for real, {re, im} for complex). initializer (Lua fn) overrides fill for 1D fields and is called with (index, coord) where index is 0-based and coord = origin + index * spacing.
• Layout: Fields are row-major contiguous; axis 0 is slowest and axis rank-1 is fastest.
• Origin/spacing: Used only to compute initializer coordinates; they are not stored as field metadata.

🛠️ Options

Option	Type	Default	Notes
type	string	"double"	"complex_double" stores interleaved {re, im} pairs.
fill	double or {re, im}	0	Applied before initializer; complex fields require a {re, im} table (numeric fill is ignored).
initializer	function	none	Only supported for 1D fields. index is 0-based and coord = origin + index * spacing.
origin	double	0.0	Start coordinate for initializer (not stored on the field).
spacing	double	1.0	Step size for initializer coordinates (not stored on the field).

🎉 Path Creation

local ctx = ooc.sim_create()

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

-- Complex 1D grid with initializer
local wave = ooc.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 (1D only).
4. Capture the returned Field handle to pass into operators and to query rank/shape/values later.