Oakfield API Documentation

📖 Overview

Oakfield exposes a composable operator calculus through Lua. A script creates a SimContext, adds fields and operators, assigns an integrator, then advances time. All APIs documented here are verified against the current source.

🗂️ API Index

Contexts Manage simulation contexts, including field and operator lifetimes.

Fields Create and manipulate multi-dimensional scalar and complex fields.

Integrators Time integration schemes for evolving fields.

Loggers Asynchronous logging utilities for simulation data.

Flux Lens Spectral energy flux tracking and adaptive bandpass reconstruction for 1D fields.

Examples Practical Lua scripts demonstrating Oakfield API usage.

📑 Operator Index

Coupling Operators Operators for field-field interactions and couplings.

Measurement Operators Operators for extracting observables from fields.

Noise Operators Stochastic perturbations and noise injection operators.

Potential & Stimulus Operators External potential landscapes and stimulus functions.

Reaction Operators Nonlinear reaction terms and local dynamics operators.

Thermostat Operators Temperature control and energy regulation operators.

Advection Operators Phase-aware analytic warps and spatial derivatives.

Diffusion & Dissipation Operators Laplacian, hyper-Laplacian, and custom dissipation operators.

Utility Operators Utility operators for field manipulation and transformations.

Custom Operators Defining and using user-defined operators.

🔢 Indexing & Conventions

Zero-Based Indexing

Field indices, operator indices, and integrator references inside the engine are zero-based.

One-Based Lua Tables

Lua tables returned to user (e.g. field:shape(), field:values()) are 1-based (Lua default).

Complex Number Representation

Complex numbers are passed either as real number or {re, im} table.

Enum Helpers

Enum values and modes exposed as integers also have string helpers where provided.

Data Layout

Fields are stored in row-major order, with the fastest-varying dimension last.

Coordinate Systems

Spatial coordinates follow a right-handed system, with positive axes defined per context.

Boundary Conditions

Default boundary conditions are periodic; others (Dirichlet, Neumann, Periodic, Reflective) can be set per field.

♻️ Userdata & GC Semantics

Userdata objects (contexts, fields, operators, integrators, loggers, profilers) are managed by Lua’s garbage collector (GC). Each userdata type has specific metamethods and GC behaviors:

Type	Metamethods	GC Behavior
Context (SimContext)	__gc, __tostring	Destroys context, releases managed integrators, frees native memory.
Field	__gc, __tostring, methods: rank, shape, values, components	GC detaches handle only (sets pointers NULL); underlying field owned by context until context GC.
Operator	__gc, __tostring, methods: name, symbolic_form	GC detaches handle only; operator lifetime owned by context.
Integrator	__gc, __tostring	GC destroys integrator and frees workspace.
Logger	__gc, __tostring, methods: log, pop, clear	GC destroys async logger and frees memory.
Profiler	__gc, __tostring, methods: begin_frame, end_frame, record_operator, record_operator_delta, snapshot	GC destroys profiler and frees memory.

Detaching (field/operator) means subsequent method calls on that handle error (expected Field userdata).