Oakfield API Documentation

📖 Overview

Oakfield exposes a composable operator calculus through Lua. A script creates a simulation context, 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.

Logging & Profiling Structured logging, async ring-buffer logger, and runtime profiling helpers.

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

Examples Practical Lua scripts demonstrating Oakfield API usage.

📑 Operator Index

Oakfield ships 69 built-in operators across 10 categories. Click any operator name to jump directly to its documentation.

Coupling

Field–field mixing and gating. Full reference →

Operator	Description	Function
Mask	Gate a field by a mask with optional soft feathering	add_mask_operator
Mixer	Blend two fields: linear, AM/FM/PM, ring-mod, feedback, and more	add_mixer_operator
Metal Mix experimental	Metal-safe mixer subset with linear and crossfade modes	add_metal_mix_operator

Measurement

Extract observables and derived quantities from fields. Full reference →

Operator	Description	Function
Phase Feature	Extract instantaneous frequency, phase, envelope, and coherence	add_phase_feature_operator
Minimal Convolution	Compact FIR convolution with symmetric or asymmetric kernels	add_minimal_convolution_operator
Sieve	Threshold-based conditional field gating and reduction	add_sieve_operator
Sound Observation experimental	Acoustic field monitor	add_sound_observation_operator

Noise

Stochastic perturbations and noise injection. Several operators use add_stimulus_operator with a type key — see the Function column. Full reference →

Operator	Description	Function
Stochastic Noise	Additive white noise drawn from a uniform or normal distribution	add_stochastic_noise_operator
Ornstein-Uhlenbeck	Mean-reverting stochastic dynamics for real or complex fields	add_ornstein_uhlenbeck_operator
Random Fourier	Spectral noise via random-phase Fourier modes	add_stimulus_operator "stimulus_random_fourier"
White Noise	Flat-spectrum white noise injection	add_stimulus_operator "stimulus_white_noise"
Spectral Shells	Band-limited noise confined to annular spectral shells	add_stimulus_operator "stimulus_spectral_shells"
Fractional Brownian Motion	Correlated noise with configurable Hurst exponent	add_stimulus_operator "stimulus_fbm"
Worley Noise	Cellular noise from nearest-feature distances	add_stimulus_operator "stimulus_worley_noise"
Turbulence	Billowy fractal cascade with centered absolute-value octaves	add_stimulus_operator "stimulus_turbulence"
Multifractal	Multiplicative cascade noise with octave-to-octave coupling	add_stimulus_operator "stimulus_multifractal"
Hybrid fBm	Hybrid fractal Brownian motion with bounded cascade weights	add_stimulus_operator "stimulus_hybrid_fbm"
Ridged Noise	Ridged multifractal noise for crest-like structures	add_stimulus_operator "stimulus_ridged_noise"

Stimulus

External driving and spatial pattern generation. Most operators use add_stimulus_operator with a type key — see the Function column. Full reference →

Operator	Description	Function
Sine	Traveling or standing sinusoidal plane wave	add_stimulus_operator "stimulus_sine"
Standing Wave	Two counter-propagating sine waves forming a standing pattern	add_stimulus_operator "stimulus_standing_wave"
Chirp	Frequency-swept sinusoid (linear or exponential)	add_stimulus_operator "stimulus_chirp"
Gaussian Pulse	Spatiotemporal Gaussian envelope	add_stimulus_operator "stimulus_gaussian_pulse"
Heat Kernel	Diffusing Gaussian heat packet with optional mass preservation	add_stimulus_operator "stimulus_heat_kernel"
Spectral Lines	Superposition of sinusoids at specified frequencies	add_stimulus_operator "stimulus_spectral_lines"
Fourier Waveform	Arbitrary waveform synthesized from Fourier coefficients	add_stimulus_operator "stimulus_fourier_waveform"
Checkerboard	2D spatial checkerboard pattern	add_stimulus_operator "stimulus_checkerboard"
Lissajous	Gaussian ridge pattern around coupled sinusoidal traces	add_stimulus_operator "stimulus_lissajous"
Gabor Kernel	Localized sinusoid in a Gaussian envelope (oriented)	add_stimulus_operator "stimulus_gabor_kernel"
Digamma Square	Deformable digamma waveform with optional field-driven warp mix	add_digamma_square_operator
Moiré	Interference pattern from overlapping spatial grids	add_stimulus_operator "stimulus_moire"
Log-Polar experimental	Rings-and-spokes pattern built from log-radius and angle	add_stimulus_operator "stimulus_log_polar"
Positional Encoding	Multi-scale sinusoidal position encoding (transformer-style)	add_stimulus_operator "stimulus_positional_encoding"
Log Spectral Grid	Logarithmically spaced spectral grid stimulus	add_stimulus_operator "stimulus_log_spectral_grid"
Morlet Wavelet Field	2D Morlet wavelet spatial pattern	add_stimulus_operator "stimulus_morlet_wavelet"
Steerable Wavelet	Orientation-steerable wavelet basis function	add_stimulus_operator "stimulus_steerable_wavelet"
Optical Vortex	Phase-singular beam with topological charge	add_stimulus_operator "stimulus_optical_vortex"
Bessel Beam	Cylindrical Bessel beam with configurable order	add_stimulus_operator "stimulus_bessel_beam"
Airy Beam	Finite-energy Airy beam with apodized lobes	add_stimulus_operator "stimulus_airy_beam"
Hermite-Gaussian Beam	Separable transverse beam modes in a Gaussian envelope	add_stimulus_operator "stimulus_hermite_gaussian_beam"
Chladni	Nodal-line plate pattern from vibrating rectangular modes	add_stimulus_operator "stimulus_chladni"
Wave Modes	Fixed-boundary standing modes of the wave equation	add_stimulus_operator "stimulus_wave_modes"
Traveling Wave Packet	Gaussian-envelope packet with drifting carrier	add_stimulus_operator "stimulus_traveling_wave_packet"
Cylindrical Wave Emitter	Regularized cylindrical wave radiating from a moving source	add_stimulus_operator "stimulus_cylindrical_wave_emitter"
Laplace-Beltrami	Analytic eigenmodes on rectangles, cylinders, and flat tori	add_stimulus_operator "stimulus_laplace_beltrami"
Zone Plate	Fresnel-style quadratic radial phase plate	add_stimulus_operator "stimulus_zone_plate"
RD Seed	Reaction-diffusion seed pattern initializer	add_stimulus_operator "stimulus_rd_seed"

Reaction

Local nonlinear reaction terms. Full reference →

Operator	Description	Function
Remainder	Pointwise modulo (remainder) of field values	add_remainder_operator

Thermostat

Energy regulation and power control. Full reference →

Operator	Description	Function
Thermostat	Rescale field energy toward a target RMS or total power	add_thermostat_operator

Advection

Spatial warps, analytic deformations, and finite-difference derivatives. Full reference →

Operator	Description	Function
Analytic Warp	Nonlinear field deformation using special function profiles (digamma, tanh, power, …)	add_analytic_warp_operator
Spatial Derivative	First-order ∂u/∂x or ∂u/∂y via finite difference stencils	add_spatial_derivative_operator
Gradient	Full 2D gradient (∂u/∂x, ∂u/∂y) to separate output fields	add_gradient_operator
Divergence	Scalar divergence ∂vx/∂x + ∂vy/∂y from vector components	add_divergence_operator
Curl	Scalar 2D curl ∂vy/∂x - ∂vx/∂y from vector components	add_curl_operator

Diffusion & Dissipation

Laplacian, spectral dissipation, and fractional operators. Full reference →

Operator	Description	Function
Linear Dissipative	Exponential decay with optional frequency-dependent damping	add_linear_dissipative_operator
Linear Spectral Fusion	Spectral-domain weighted blend and dissipation	add_linear_spectral_fusion_operator
Dispersion	Frequency-dependent phase velocity (dispersive propagation)	add_dispersion_operator
Fractional Memory	Long-range temporal memory via fractional integration	add_fractional_memory_operator
Laplacian	Standard and fractional Laplacian (hyper-diffusion)	add_laplacian_operator

Nonlinear

Pointwise nonlinear operations and discrete chaotic maps. Full reference →

Operator	Description	Function
Elementwise Math	Discrete math: floor, fract, mod, step, comparisons, conditional select	add_elementwise_math_operator
Complex Math	Complex arithmetic, transcendentals, and component extraction	add_complex_math_operator
Chaos Map	Discrete chaotic maps: standard (Chirikov), Ikeda, exponential	add_chaos_map_operator
Hysteretic	Stateful hysteresis: Schmitt trigger, play model, Bouc-Wen	add_hysteretic_operator
Neural Infer experimental	Inference-only learned operator with explicit execution contract	add_neural_infer_operator
Neural Hybrid experimental	Analytic baseline plus learned residual correction	add_neural_hybrid_operator

Utility

Field manipulation, routing, and coordinate generation. Full reference →

Operator	Description	Function
Coordinate	Write index or spatial coordinates into a field (axis, radial, angle, separable)	add_coordinate_operator
Phase Rotate	Apply a uniform complex rotation at a given angular rate	add_phase_rotate_operator
Copy	Copy one field to another, with optional accumulation	add_copy_operator
Scale	Multiply field samples by a constant factor	add_scale_operator
Zero Field	Zero all samples in a field	add_zero_field_operator

Custom Operators

Extend Oakfield with your own Lua-implemented operators registered into the simulation plan. Full reference →