Stimulus: Wave Drivers

These operators share the coordinate mapping and timing controls documented on Stimulus Operators. Most entries use add_stimulus_operator(ctx, field, opts) with the operator-specific type shown below.

Sine 〰️

add_stimulus_operator(ctx, field, opts)

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

Method Signature

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.add_stimulus_operator(ctx, field, {
    type = "stimulus_sine",
    amplitude = 0.3,
    wavenumber = 1.0,
    omega = 0.6
})

-- Standing-like behavior (omega = 0)
ooc.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.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 🌊

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

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.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.add_stimulus_operator(ctx, field, {
    type = "stimulus_standing",
    amplitude = 0.5,
    wavenumber = 1.0,
    omega = 1.0,
    phase = math.pi / 2
})

---

Chirp 🐦

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

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.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.add_stimulus_operator(ctx, field, {
    type = "stimulus_chirp",
    amplitude = 0.4,
    wavenumber = 0.5,
    omega = 1.0,
    kdot = 0.5,
    wdot = 0.0
})

---

Spectral Lines 🌈

add_stimulus_operator(ctx, field, opts)

Adds one or more spatial–temporal plane waves with discrete harmonic spectra to the field.

Method Signature

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.add_stimulus_operator(ctx, field, {
    type = "stimulus_spectral_lines",
    amplitude = 1.0,
    wavenumber = 0.5,
    harmonic_count = 1
})

-- Rich harmonic content
ooc.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.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 🎛️

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

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.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.add_stimulus_operator(ctx, field, {
    type = "stimulus_fourier",
    amplitude = 0.5,
    frequency = 220.0,
    shape = "square",
    duty = 0.25
})

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

---

Digamma Square Wave 📐

add_digamma_square_operator(ctx, field, opts)

Generate a deformable digamma waveform driver. Uses the digamma function to produce bandlimited square-like waves with controllable harmonics, optional field-driven warp modulation, and a tunable deformation shift.

Method Signature

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

Returns: Operator handle (userdata)

Note: Former add_digamma_square_warp_operator(...) behavior now lives on this operator through warp_field, warp_mix, warp_bias, and warp_mode.

Mathematical Formulation

Let

$$D(\varphi; H_{\text{mix}}, a) = 1 + \left(\cos\!\left(2\pi H_{\text{mix}}\cos\varphi\right) - \cos(2\pi a)\right) \left[ \psi^{(0)}\!\left(a + H_{\text{mix}}\cos\varphi\right) - \psi^{(0)}\!\left(1 - a + H_{\text{mix}}\cos\varphi\right) \right] \bigg/ \pi$$

where $\psi^{(0)}$ is the digamma function.

The phase is evaluated on the shared stimulus coordinate mapping:

$$\varphi(x, t) = k \cdot \xi(x, t) + \omega \cdot (t + t_0) + \phi$$

with base harmonic control $H =$ harmonics.

Without a warp field:

$$H_{\text{mix}} = H$$

With warp sample $w(x)$ from warp_field, the mix becomes:

$$H_{\text{mix}} = \begin{cases} H + m\,(w + b), & \text{sum} \\ H \cdot m\,(w + b), & \text{multiply} \\ (1-m)\,H + m\,(w + b), & \text{crossfade} \end{cases}$$

where $m$ is warp_mix, $b$ is warp_bias, and a is the deformation shift controlling the digamma pair offsets.

The output variants are:

$$u_{\text{default}}(x, t) = A \, D(\varphi; H_{\text{mix}}, a)$$ $$u_{\text{sawtooth}}(x, t) = A \, D(\varphi; H_{\text{mix}}, a)\,\sin\varphi$$ $$u_{\text{triangle}}(x, t) = A \, \left(D(\varphi; H_{\text{mix}}, a)\right)^2 \sin\varphi$$

Shape variants:

• default: Base digamma waveform
• sawtooth: Base waveform multiplied by $\sin\varphi$
• triangle: Squared base waveform multiplied by $\sin\varphi$

Parameters

Parameter	Type	Default	Range	Description
amplitude	double	0.5	≥0	Peak amplitude of the digamma-square driver
wavenumber	double	1.0	unbounded	Base spatial wavenumber
omega	double	1.0	unbounded	Base angular frequency
phase	double	0.0	[0, 2π]	Phase offset
time_offset	double	0.0	unbounded	Additional time shift
nominal_dt	double	0.0	≥0	Nominal timestep when fixed_clock = true
fixed_clock	boolean	false	—	Lock the driver to nominal_dt
harmonics	double	4.0	[0.25, 24]	Base harmonic mix factor
a	double	0.25	[0, 0.5]	Deformation shift controlling the digamma pair offsets
warp_field	field handle	nil	—	Optional field handle supplying per-sample warp modulation
warp_mix	double	1.0	unbounded	Warp gain, or crossfade weight when warp_mode = "crossfade"
warp_bias	double	0.0	unbounded	Bias added to the warp-field sample before mixing
warp_mode	enum	"sum"	see below	Harmonic/warp combine rule
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
scale_by_dt	boolean	false	—	Scale writes by dt instead of injecting dt-independently
use_wavevector	boolean	false	—	Use (kx, ky) instead of wavenumber + coordinate mapping
kx, ky	double	0.0	unbounded	Wavevector components used when use_wavevector = true

Shape options: default, sawtooth, triangle

Warp mode options: sum, multiply, crossfade

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

When warp_field is complex, the operator uses its real component for warp mixing. The a parameter is folded and clamped slightly away from 0 and 0.5 internally to avoid digamma poles and degenerate differences.

Plus shared coordinate mapping parameters.

Migration note: Former add_digamma_square_warp_operator(ctx, field, warp, opts) calls now become add_digamma_square_operator(ctx, field, { warp_field = warp, ... }).

Examples

-- Basic digamma square wave with deformation shift
ooc.add_digamma_square_operator(ctx, field, {
    amplitude = 0.3,
    wavenumber = 1.0,
    omega = 0.6,
    harmonics = 6.0,
    a = 0.28
})

-- Field-driven crossfade warping
ooc.add_digamma_square_operator(ctx, field, {
    amplitude = 0.4,
    wavenumber = 0.8,
    omega = 1.0,
    warp_field = warp,
    warp_mode = "crossfade",
    warp_mix = 0.5,
    harmonics = 8.0
})

-- Sawtooth variant with additive warp bias
ooc.add_digamma_square_operator(ctx, field, {
    amplitude = 0.5,
    wavenumber = 0.8,
    omega = 1.0,
    shape = "sawtooth",
    warp_field = warp,
    warp_mode = "sum",
    warp_mix = 0.3,
    warp_bias = 0.1
})

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

---

Lissajous 🎼

add_stimulus_operator(ctx, field, opts)

Generate a Gaussian ridge around a coupled Lissajous curve. This is useful for tracing multi-frequency trajectories, resonant loops, and implicit oscillatory masks.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_lissajous".

Mathematical Formulation

The operator forms two oscillators

$$\theta_x = k_x x - \omega_x t + \phi_x, \qquad \theta_y = k_y y - \omega_y t + \phi_y$$

and injects a Gaussian band around the implicit relation

$$\sin(\theta_x) = c\,\sin(\theta_y) + b$$

with width controlled by line_width.

Parameters

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_lissajous"
wavenumber_x	double	3.0	X oscillator wavenumber
wavenumber_y	double	2.0	Y oscillator wavenumber
omega_x	double	0.0	X oscillator angular frequency
omega_y	double	0.0	Y oscillator angular frequency
phase_x	double	0.0	X oscillator phase offset
phase_y	double	0.0	Y oscillator phase offset
coupling	double	1.0	Multiplier applied to the Y oscillator relation
bias	double	0.0	Additive offset in the implicit-curve relation
line_width	double	0.25	Gaussian ridge width

Plus shared coordinate mapping and timing parameters (amplitude, time_offset, rotation, scale_by_dt).

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_lissajous",
    amplitude = 0.8,
    wavenumber_x = 3.0,
    wavenumber_y = 2.0,
    line_width = 0.18
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_lissajous",
    amplitude = 0.5,
    omega_x = 0.2,
    omega_y = 0.3,
    coupling = 0.75
})