Potential & Stimulus Operators

All stimulus operators take a destination field and an options table; most support scale_by_dt (bool) to scale writes by the simulation timestep.

🧭 Shared Coordinate Mapping

Most spatial stimuli support alternate coordinate mappings (2D, angle, radial). Applies to: stimulus_sine, stimulus_standing, stimulus_chirp, stimulus_gaussian_pulse, stimulus_spectral_lines, stimulus_checkerboard, stimulus_gabor, stimulus_digamma_square, digamma_square_warp.

Parameter	Type	Default	Description
coord_mode	enum	"axis"	Coordinate mode: axis, angle, radial, separable
coord_axis	enum	"x"	Axis for coord_mode = "axis"
coord_combine	enum	"multiply"	Separable combine rule: multiply, add
coord_angle	double	0.0	Angle for coord_mode = "angle" (radians)
origin_x, origin_y	double	0.0	Coordinate origin for 2D mappings
spacing_x, spacing_y	double	1.0	Coordinate spacing for 2D mappings
coord_center_x, coord_center_y	double	0.0	Radial coordinate center (units)
coord_velocity_x, coord_velocity_y	double	0.0	Radial center velocity (units/s)

Wavevector overrides (for stimulus_sine, stimulus_chirp, stimulus_spectral_lines, stimulus_gabor):

Parameter	Type	Default	Description
kx, ky	double	0.0	Wavevector components (rad/unit)
use_wavevector	boolean	false	Use kx/ky instead of wavenumber + coordinate mapping

⏱️ Shared Timing & Phase Controls

Parameter	Type	Default	Description
amplitude	double	Peak output amplitude (before dt scaling)
wavenumber	double	Spatial wavenumber k (rad/unit)
omega	double	Angular frequency (rad/s)
phase	double	0.0	Phase offset (radians)
time_offset	double	0.0	Shift time by constant before evaluation
nominal_dt	double	0.0	Fixed timestep for fixed_clock = true
fixed_clock	boolean	false	Lock evolution to nominal_dt
scale_by_dt	boolean	true	Multiply write by dt
rotation	double	0.0	Complex phase rotation on output (radians)

---

〰️ Sine

sim_add_stimulus_operator(ctx, field, opts)

Generate a travelling sinusoidal wave. Fundamental building block for wave propagation, oscillating forcing, and harmonic analysis.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_sine".

Mathematical Formulation

$$u(x, t) = A \cdot \sin(k \cdot x - \omega \cdot t + \phi)$$

where:

• $A$ is the amplitude
• $k$ is the wavenumber
• $\omega$ is the angular frequency
• $\phi$ is the phase offset

Phase velocity: $v_p = \omega / k$

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_sine"
amplitude	double	unbounded	Peak amplitude (required)
wavenumber	double	unbounded	Spatial wavenumber k (required)
omega	double	unbounded	Angular frequency (required)
phase	double	0.0	unbounded	Phase offset (radians)
time_offset	double	0.0	unbounded	Temporal shift
rotation	double	0.0	unbounded	Complex phase rotation
nominal_dt	double	0.0	≥0	Fixed timestep
fixed_clock	boolean	false	—	Use nominal_dt
scale_by_dt	boolean	true	—	Scale by dt

Plus all shared coordinate mapping parameters.

Examples

-- Basic travelling wave
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_sine",
    amplitude = 0.3,
    wavenumber = 1.0,
    omega = 0.6
})

-- Standing-like behavior (omega = 0)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_sine",
    amplitude = 0.5,
    wavenumber = 2.0,
    omega = 0.0,
    phase = math.pi / 4
})

-- 2D wavevector specification
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_sine",
    amplitude = 0.4,
    use_wavevector = true,
    kx = 0.5,
    ky = 0.5,
    omega = 1.0
})

---

🌊 Standing Wave

sim_add_stimulus_operator(ctx, field, opts)

Generate a standing-wave sinusoid with fixed nodes and antinodes. Models resonant cavity modes and stationary vibration patterns.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_standing".

Mathematical Formulation

$$u(x, t) = A \cdot \sin(k \cdot x + \phi) \cdot \cos(\omega \cdot t)$$

Equivalently, this is the superposition of two counter-propagating waves:

$$u = \frac{A}{2}[\sin(kx - \omega t) + \sin(kx + \omega t)]$$

• Nodes: Points where $\sin(kx + \phi) = 0$ (always zero)
• Antinodes: Points where $|\sin(kx + \phi)| = 1$ (maximum oscillation)

Parameters

Same as stimulus_sine:

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_standing"
amplitude	double	Peak amplitude (required)
wavenumber	double	Spatial wavenumber (required)
omega	double	Angular frequency (required)
phase	double	0.0	Controls node/antinode placement

Plus timing and coordinate parameters.

Examples

-- Basic standing wave
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_standing",
    amplitude = 0.4,
    wavenumber = 0.8,
    omega = 0.8,
    phase = 0.25
})

-- Half-wavelength shifted nodes
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_standing",
    amplitude = 0.5,
    wavenumber = 1.0,
    omega = 1.0,
    phase = math.pi / 2
})

---

🐦 Chirp

sim_add_stimulus_operator(ctx, field, opts)

Generate a sinusoid with time-varying frequency and/or wavenumber. Models frequency sweeps, dispersive waves, and time-frequency analysis signals.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_chirp".

Mathematical Formulation

$$u(x, t) = A \cdot \sin\left((k_0 + \dot{k}t) \cdot x - (\omega_0 + \dot{\omega}t) \cdot t + \phi\right)$$

where:

• $k_0$ is the initial wavenumber
• $\dot{k}$ is kdot (wavenumber rate)
• $\omega_0$ is the initial angular frequency
• $\dot{\omega}$ is wdot (frequency rate)

Instantaneous frequency: $f(t) = \frac{\omega_0 + \dot{\omega}t}{2\pi}$

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_chirp"
amplitude	double	unbounded	Peak amplitude (required)
wavenumber	double	unbounded	Initial wavenumber (required)
omega	double	unbounded	Initial angular frequency (required)
kdot	double	0.0	unbounded	Wavenumber rate (rad/unit/s)
wdot	double	0.0	unbounded	Frequency rate (rad/s²)
phase	double	0.0	unbounded	Phase offset
rotation	double	0.0	unbounded	Complex phase rotation
time_offset	double	0.0	unbounded	Temporal shift

Plus timing and coordinate parameters.

Examples

-- Linear frequency chirp
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_chirp",
    amplitude = 0.5,
    wavenumber = 1.0,
    omega = 0.3,
    kdot = 0.1,
    wdot = 0.2
})

-- Spatial chirp only
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_chirp",
    amplitude = 0.4,
    wavenumber = 0.5,
    omega = 1.0,
    kdot = 0.5,
    wdot = 0.0
})

---

💥 Gaussian Pulse

sim_add_stimulus_operator(ctx, field, opts)

Generate a pure Gaussian envelope without carrier oscillation. Models localized pulses, initial conditions, and smooth spatial masks.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_gaussian_pulse".

Mathematical Formulation

1D:

$$u(x, t) = A \cdot \exp\left(-\frac{(x - x_0 - v \cdot t)^2}{2\sigma^2}\right)$$

2D separable:

$$u(x, y, t) = A \cdot \exp\left(-\frac{(x - x_0 - v_x t)^2}{2\sigma_x^2} - \frac{(y - y_0 - v_y t)^2}{2\sigma_y^2}\right)$$

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_gaussian_pulse"
amplitude	double	unbounded	Peak amplitude (required)
center_x, center_y	double	0.0	unbounded	1D/2D center position
sigma_x, sigma_y	double	1.0	>0	1D/2D standard deviations
velocity_x, velocity_y	double	0.0	unbounded	1D/2D velocities
time_offset	double	0.0	unbounded	Temporal shift
rotation	double	0.0	unbounded	Complex phase rotation

Plus timing parameters.

Examples

-- Static 1D Gaussian
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_gaussian_pulse",
    coord_center_x = 128,
    sigma_x = 30,
    amplitude = 1.0
})

-- Moving pulse
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_gaussian_pulse",
    coord_center_x = 0,
    sigma_x = 10,
    amplitude = 0.5,
    velocity_x = 2.0
})

-- 2D elliptical Gaussian
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_gaussian_pulse",
    amplitude = 0.8,
    coord_mode = "separable",
    coord_center_x = 128,
    coord_center_y = 128,
    sigma_x = 20,
    sigma_y = 40
})

---

🌈 Spectral Lines

sim_add_stimulus_operator(ctx, field, opts)

Generate harmonic series with configurable power weighting. Models multi-tone signals, harmonic oscillators, and comb-like spectra.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_spectral_lines".

Mathematical Formulation

$$u(x, t) = A \sum_{n=1}^{N} n^{-p} \cdot \sin(n \cdot k \cdot x - n \cdot \omega \cdot t + \phi)$$

where:

• $N$ is harmonic_count
• $p$ is harmonic_power
• Higher $p$ reduces high-frequency content

Special cases:

• $p = 0$: Equal amplitude harmonics
• $p = 1$: $1/n$ amplitude decay (approaching square wave)
• $p = 2$: $1/n²$ amplitude decay (faster rolloff)

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_spectral_lines"
amplitude	double	unbounded	Peak amplitude (required)
wavenumber	double	unbounded	Fundamental wavenumber
omega	double	unbounded	Fundamental frequency
phase	double	0.0	unbounded	Phase offset
harmonic_count	integer	1	≥1	Number of harmonics
harmonic_power	double	0.0	≥0	Power weighting exponent

Plus timing and coordinate parameters.

Examples

-- Single fundamental
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_spectral_lines",
    amplitude = 1.0,
    wavenumber = 0.5,
    harmonic_count = 1
})

-- Rich harmonic content
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_spectral_lines",
    amplitude = 0.2,
    harmonic_count = 4,
    harmonic_power = 0.9,
    fixed_clock = true
})

-- Square-wave approximation (odd harmonics with 1/n decay)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_spectral_lines",
    amplitude = 0.5,
    wavenumber = 1.0,
    omega = 1.0,
    harmonic_count = 8,
    harmonic_power = 1.0
})

---

🎛️ Fourier Waveform

sim_add_stimulus_operator(ctx, field, opts)

Generate bandlimited waveforms using BLIT, PolyBLEP, or miniBLEP synthesis. Produces alias-free sawtooth, square, and triangle waves.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_fourier".

Mathematical Formulation

Sawtooth (ideal):

$$u(t) = A \cdot \left(\frac{t}{\tau} \mod 1 - 0.5\right)$$

Square (ideal):

$$u(t) = A \cdot \text{sign}\left(\sin\left(\frac{2\pi t}{\tau}\right)\right)$$

Triangle (ideal):

$$u(t) = A \cdot \left(4 \left|\frac{t}{\tau} \mod 1 - 0.5\right| - 1\right)$$

The method parameter selects the anti-aliasing technique:

• blit: Band-Limited Impulse Train
• polyblep: Polynomial BLEP correction
• miniblep: Minimum-phase BLEP

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_fourier"
amplitude	double	unbounded	Waveform amplitude (required)
frequency	double	>0	Fundamental frequency in Hz (required)
shape	enum	"saw"	see below	Waveform shape
method	enum	"polyblep"	see below	Anti-aliasing method
duty	double	0.5	[0, 1]	Duty cycle for square/triangle
phase	double	0.0	[0, 1)	Initial phase in cycles
rotation	double	0.0	unbounded	Complex phase rotation

Shape options: saw, square, triangle

Method options: blit, polyblep, miniblep

Plus timing parameters.

Examples

-- Bandlimited sawtooth at 440 Hz
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fourier",
    amplitude = 0.8,
    frequency = 440.0,
    shape = "saw",
    method = "polyblep"
})

-- Square wave with 25% duty cycle
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fourier",
    amplitude = 0.5,
    frequency = 220.0,
    shape = "square",
    duty = 0.25
})

-- Triangle wave
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fourier",
    amplitude = 0.6,
    frequency = 110.0,
    shape = "triangle"
})

---

🏁 Checkerboard

sim_add_stimulus_operator(ctx, field, opts)

Generate checker or stripe patterns. Works on complex fields with configurable periods and phase.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_checkerboard".

Mathematical Formulation

$$u(x, y) = A \cdot \text{sign}\left(\sin\left(\frac{2\pi x}{P_x}\right) \cdot \sin\left(\frac{2\pi y}{P_y}\right)\right) \cdot e^{i\phi_c}$$

where:

• $P_x$, $P_y$ are the periods
• $\phi_c$ is the complex phase rotation

Setting one period to infinity produces stripes along that axis.

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_checkerboard"
amplitude	double	unbounded	Pattern amplitude (required)
period_x	double	8.0	>0	X-axis period (samples)
period_y	double	8.0	>0	Y-axis period (samples)
phase	double	0.0	unbounded	Scalar phase offset
complex_phase	double	0.0	unbounded	Complex rotation (radians)
scale_by_dt	boolean	true	—	Scale by dt

Examples

-- Standard checkerboard
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_checkerboard",
    amplitude = 1.0,
    period_x = 8,
    period_y = 8
})

-- Rectangular cells with complex phase
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_checkerboard",
    amplitude = 0.5,
    period_x = 12,
    period_y = 6,
    complex_phase = 0.75
})

-- Vertical stripes (large period_y)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_checkerboard",
    amplitude = 0.8,
    period_x = 16,
    period_y = 1000
})

---

📦 Gabor Kernel

sim_add_stimulus_operator(ctx, field, opts)

Generate a Gaussian-windowed sinusoid (Gabor function). Optimal for joint time-frequency localization and models neural receptive fields.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_gabor".

Mathematical Formulation

1D:

$$u(x, t) = A \cdot \exp\left(-\frac{(x - x_0 - vt)^2}{2\sigma^2}\right) \cdot \sin(k(x - x_0) - \omega t + \phi)$$

2D with envelope rotation:

$$u(x, y, t) = A \cdot \exp\left(-\frac{x'^2}{2\sigma_x^2} - \frac{y'^2}{2\sigma_y^2}\right) \cdot \sin(k_x x' + k_y y' - \omega t + \phi)$$

where $(x', y')$ are coordinates rotated by envelope_angle.

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_gabor"
amplitude	double	unbounded	Peak amplitude (required)
wavenumber	double	unbounded	Carrier wavenumber
omega	double	0.0	unbounded	Carrier frequency
phase	double	0.0	unbounded	Carrier phase
center_x, center_y	double	0.0	unbounded	1D/2D center
sigma_x, sigma_y	double	1.0	>0	1D/2D envelope widths
velocity_x, velocity_y	double	0.0	unbounded	1D/2D velocities
envelope_angle	double	0.0	unbounded	Envelope rotation (radians)
rotation	double	0.0	unbounded	Complex output rotation
time_offset	double	0.0	unbounded	Temporal shift

Plus timing parameters.

Examples

-- 1D Gabor wavelet
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_gabor",
    amplitude = 0.4,
    sigma_x = 12.0,
    wavenumber = 0.5
})

-- Moving Gabor pulse
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_gabor",
    amplitude = 0.2,
    omega = 0.5,
    rotation = 0.3,
    coord_center_x = 64,
    sigma_x = 20,
    velocity_x = 1.0
})

-- 2D oriented Gabor (receptive field model)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_gabor",
    amplitude = 0.5,
    coord_mode = "separable",
    coord_center_x = 128,
    coord_center_y = 128,
    sigma_x = 15,
    sigma_y = 30,
    wavenumber = 0.3,
    envelope_angle = math.pi / 4
})

---

📐 Digamma Square Wave

sim_add_digamma_square_operator(ctx, field, opts)

Generate a digamma-based square wave driver. Uses the digamma function to produce bandlimited waveforms with reduced aliasing and controllable harmonics.

Method Signature

sim_add_digamma_square_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Mathematical Formulation

The digamma square wave approximates:

$$u(x, t) = A \cdot \text{Im}\left[\psi\left(\frac{1}{2} + iH\sin(kx - \omega t + \phi)\right)\right]$$

where $\psi$ is the digamma function and $H$ is the harmonics parameter controlling bandwidth.

Shape variants:

• default: Standard square wave approximation
• sawtooth: Asymmetric rising/falling
• triangle: Linear interpolation between extrema

Parameters

Parameter	Type	Default	Range	Description
amplitude	double	unbounded	Peak amplitude (required)
wavenumber	double	unbounded	Spatial wavenumber (required)
omega	double	unbounded	Angular frequency (required)
phase	double	0.0	unbounded	Phase offset
time_offset	double	0.0	unbounded	Temporal shift
harmonics	double	4.0	[0.25, 12]	Harmonic content control
shape	enum	"default"	see below	Waveform shape
backend	enum	"12_tail"	see below	Digamma computation method
tolerance	double	1e-12	≥0	Tolerance for adaptive backend
rotation	double	0.0	unbounded	Complex phase rotation

Shape options: default, sawtooth, triangle

Backend options: 5_tail, 7_tail, 12_tail, adaptive, mortici

Plus timing parameters.

Examples

-- Basic digamma square wave
ooc.sim_add_digamma_square_operator(ctx, field, {
    amplitude = 0.3,
    wavenumber = 1.0,
    omega = 0.6,
    harmonics = 6.0
})

-- Sawtooth variant
ooc.sim_add_digamma_square_operator(ctx, field, {
    amplitude = 0.5,
    wavenumber = 0.8,
    omega = 1.0,
    shape = "sawtooth",
    harmonics = 8.0
})

-- High-precision adaptive backend
ooc.sim_add_digamma_square_operator(ctx, field, {
    amplitude = 0.4,
    wavenumber = 1.0,
    omega = 0.5,
    backend = "adaptive",
    tolerance = 1e-14
})

---

🌀 Digamma Square (Warp)

sim_add_digamma_square_warp_operator(ctx, field, warp, opts)

Generate a digamma square wave modulated by an external warp field. Enables complex pattern generation through field-driven modulation.

Method Signature

sim_add_digamma_square_warp_operator(ctx, field, warp, [options]) -> operator

Returns: Operator handle (userdata)

Mathematical Formulation

The warp field modulates the base digamma square wave:

$$u(x, t) = f\left(\text{digamma\_square}(x, t), w(x) \cdot m + b\right)$$

where:

• $w(x)$ is the warp field value
• $m$ is warp_mix
• $b$ is warp_bias
• $f$ is the mixing function determined by warp_mode

Warp modes:

• sum: $\text{out} = \text{base} + w \cdot m + b$
• multiply: $\text{out} = \text{base} \cdot (w \cdot m + b)$
• crossfade: $\text{out} = (1 - m) \cdot \text{base} + m \cdot w$

Parameters

Parameter	Type	Default	Range	Description
amplitude	double	unbounded	Peak amplitude (required)
wavenumber	double	unbounded	Spatial wavenumber (required)
omega	double	unbounded	Angular frequency (required)
phase	double	0.0	unbounded	Phase offset
time_offset	double	0.0	unbounded	Temporal shift
harmonics	double	4.0	[0.25, 12]	Harmonic content
warp_mix	double	1.0	unbounded	Warp mixing factor
warp_bias	double	0.0	unbounded	Warp bias
warp_mode	enum	"sum"	see below	Mixing strategy
shape	enum	"default"	see below	Waveform shape
backend	enum	"12_tail"	see below	Digamma backend
tolerance	double	1e-12	≥0	Adaptive tolerance
rotation	double	0.0	unbounded	Complex rotation

Warp mode options: sum, multiply, crossfade

Shape options: default, sawtooth, triangle

Backend options: 5_tail, 7_tail, 12_tail, adaptive, mortici

Plus timing parameters.

Examples

-- Crossfade between digamma square and warp field
ooc.sim_add_digamma_square_warp_operator(ctx, field, warp, {
    amplitude = 0.3,
    wavenumber = 1.0,
    omega = 0.6,
    warp_mode = "crossfade",
    warp_mix = 0.5,
    harmonics = 8.0
})

-- Additive warp modulation
ooc.sim_add_digamma_square_warp_operator(ctx, field, warp, {
    amplitude = 0.4,
    wavenumber = 0.8,
    omega = 1.0,
    warp_mode = "sum",
    warp_mix = 0.3,
    warp_bias = 0.1
})

-- Multiplicative warp (AM-like)
ooc.sim_add_digamma_square_warp_operator(ctx, field, warp, {
    amplitude = 0.5,
    wavenumber = 1.0,
    omega = 0.5,
    warp_mode = "multiply",
    warp_mix = 2.0
})