Oakfield Studio Lua API
On this page
📖 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 | Transform complex-field magnitudes while preserving phase direction | add_phase_feature_operator |
| Minimal Convolution | Compact FIR convolution with symmetric or asymmetric kernels | add_minimal_convolution_operator |
| Sieve | Filtering and smoothing with Gaussian, windowed, and polynomial kernels | 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 | Colored stochastic noise with spectral controls and a choice of calculus law | 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 | Compare warped and reference fields with configurable nonlinear residue transforms | 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 →