Stimulus: Beam & Wavelet Families

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.

Gaussian Pulse 💥

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

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

Plus timing parameters.

Examples

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

-- Moving pulse
ooc.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.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
})

---

Gabor Kernel 📦

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

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

Plus timing parameters.

Examples

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

-- Moving Gabor pulse
ooc.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.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
})

---

Morlet Wavelet Field 🌊

add_stimulus_operator(ctx, field, opts)

Generate a multi-scale Morlet wavelet packet field: a superposition of Gaussian-windowed complex sinusoids at geometrically-spaced spatial scales. Supports drifting center position, orientation control, and explicit coordinate mapping.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_morlet_field".

Mathematical Formulation

Each scale $s$ contributes a complex Morlet atom at effective time $\tau = t + \text{time\_offset}$:

$$\psi_s(\mathbf{x}, \tau) = \exp\!\left(-\frac{u_r^2 + v_r^2}{2\sigma_s^2}\right)\cdot \exp\!\left(i\left(k_s u_r - \omega \tau + \phi\right)\right)$$

where rotated local coordinates are

$$\begin{bmatrix}u_r\\v_r\end{bmatrix} = R_{\theta(\tau)} \left(\begin{bmatrix}u\\v\end{bmatrix} -\begin{bmatrix}c_u + v_u\tau\\c_v + v_v\tau\end{bmatrix}\right), \quad \theta(\tau)=\text{orientation}+\text{orientation\_rate}\cdot\tau.$$

with per-scale definitions:

• $k_s = k_0 \cdot \gamma_k^s$ (base_wavenumber × scale_growth$^s$)
• $\sigma_s = \sigma_0 \cdot \gamma_\sigma^s$ (sigma_base × sigma_growth$^s$)

When zero_mean = true, the implementation subtracts the standard Morlet correction from the real carrier term only:

$$\Re\!\left[e^{i\left(k_su_r-\omega\tau+\phi\right)}\right] \rightarrow \cos\!\left(k_su_r-\omega\tau+\phi\right) - \exp\!\left(-\frac{(\sigma_s k_s)^2}{2}\right)$$

The injected write is normalized by scale count:

$$\Delta u(\mathbf{x}, t) = \frac{A}{\sqrt{S}}\sum_{s=0}^{S-1}\psi_s^{(0)}(\mathbf{x}, t)$$

For real fields, only $\Re[\Delta u]$ is added. For complex fields, both real and imaginary parts are added, then rotation is applied.

Parameters

Plus coordinate mapping parameters (coord_mode, coord_axis, coord_combine, coord_angle, origin_x/y, spacing_x/y, coord_center_x/y, coord_velocity_x/y, spiral params).

Examples

-- Basic 5-scale Morlet wavelet field
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_morlet_field",
    amplitude = 0.8,
    scales = 5,
    base_wavenumber = 1.2,
    sigma_base = 0.75
})

-- Oriented and drifting Morlet
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_morlet_field",
    amplitude = 0.6,
    scales = 4,
    base_wavenumber = 1.0,
    orientation = math.pi / 4,
    velocity_u = 0.5
})

-- Slowly rotating wavelet field
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_morlet_field",
    amplitude = 0.5,
    scales = 6,
    base_wavenumber = 0.8,
    scale_growth = 1.8,
    sigma_base = 0.9,
    orientation_rate = 0.15
})

-- High-sigma broad envelope with temporal oscillation
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_morlet_field",
    amplitude = 0.4,
    scales = 3,
    base_wavenumber = 2.0,
    sigma_base = 1.5,
    sigma_growth = 1.2,
    omega = 0.5
})

---

Steerable Wavelet 🔭

add_stimulus_operator(ctx, field, opts)

Generate a multi-scale steerable wavelet stimulus using Simoncelli or Riesz wavelet families. Provides direction-selective, multi-resolution spatial structure with controllable angular bandwidth and orientation.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_steerable_wavelet".

Mathematical Formulation

Each scale $s$ contributes a steerable filter response at orientation $\alpha$:

Simoncelli family (raised cosine in log-polar frequency):

$$H_s(k, \theta) = L(k/k_s) \cdot B(\theta - \alpha)^n$$

Riesz family (order-$n$ Riesz transform):

$$H_s^{(n)}(k, \theta) = L(k/k_s) \cdot e^{in\theta}$$

where:

• $L(\cdot)$ is the log-radius Gaussian with bandwidth radial_bandwidth
• $B(\cdot)^n$ is the angular envelope raised to order
• $k_s = k_0 \cdot \gamma^s$ is the per-scale wavenumber
• $\alpha = \text{orientation} + \text{orientation\_rate} \cdot t$

The spatial-domain output is the sum over $S$ scales:

$$u(\mathbf{x}, t) = A \sum_{s=0}^{S-1} \mathcal{F}^{-1}\!\left[H_s \cdot \hat{f}\right](\mathbf{x})$$

evaluated at each pixel by direct synthesis (not via FFT).

Parameters

Wavelet family options: simoncelli, riesz

Plus coordinate mapping parameters.

Examples

-- Basic Simoncelli steerable wavelet
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_steerable_wavelet",
    amplitude = 0.7,
    wavelet_family = "simoncelli",
    scales = 4,
    order = 2
})

-- Riesz family with high steering order
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_steerable_wavelet",
    amplitude = 0.6,
    wavelet_family = "riesz",
    order = 3,
    scales = 5,
    orientation = math.pi / 6
})

-- Slowly rotating steerable wavelet
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_steerable_wavelet",
    amplitude = 0.5,
    wavelet_family = "simoncelli",
    scales = 4,
    order = 2,
    orientation_rate = 0.2,
    angular_sharpness = 2.0
})

-- Narrow-band single-scale Riesz
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_steerable_wavelet",
    amplitude = 0.4,
    wavelet_family = "riesz",
    scales = 1,
    base_wavenumber = 1.5,
    radial_bandwidth = 0.3,
    order = 4
})

---

Heat Kernel ♨️

add_stimulus_operator(ctx, field, opts)

Inject a diffusing Gaussian heat kernel whose width grows over time according to the heat equation. This is useful for thermal diffusion demos, broadening pulses, and soft sources that spread as the simulation advances.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_heat_kernel".

Mathematical Formulation

The kernel broadens over time as

$$\sigma_{\mathrm{eff}}(t)^2 = \sigma_0^2 + 2D \max(t + t_0, 0)$$

and the injected profile is

$$u(\mathbf{x}, t) = A \exp\!\left(-\frac{|\mathbf{x} - \mathbf{c}(t)|^2}{2\sigma_{\mathrm{eff}}(t)^2}\right)$$

with optional mass preservation multiplying by $\sigma_0 / \sigma_{\mathrm{eff}}(t)$.

Parameters

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

Examples

-- Diffusing thermal packet
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_heat_kernel",
    amplitude = 0.5,
    diffusivity = 0.15,
    sigma_x = 8.0
})

-- Mass-preserving anisotropic spread
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_heat_kernel",
    amplitude = 0.4,
    diffusivity = 0.08,
    sigma_x = 4.0,
    sigma_y = 12.0,
    preserve_mass = true
})

---

Optical Vortex 🌀

add_stimulus_operator(ctx, field, opts)

Generate an optical vortex beam with a phase singularity and topological charge. This is useful for orbital-angular-momentum demos, dark-core beam patterns, and rotational phase structure.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_optical_vortex".

Mathematical Formulation

In a local beam frame,

$$u(\mathbf{x}, t) = A\,\rho^{|l|} e^{-\rho^2/2} e^{i(l\theta - \omega t + \phi)}$$

where $l$ is the integer charge, $\rho$ is the normalized radial coordinate set by waist_x and waist_y, and $\theta$ is the local polar angle.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_optical_vortex",
    amplitude = 0.6,
    charge = 1,
    waist_x = 0.8
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_optical_vortex",
    amplitude = 0.4,
    charge = 2,
    orientation = math.pi / 6
})

---

Airy Beam 🪶

add_stimulus_operator(ctx, field, opts)

Generate a finite-energy separable Airy beam with configurable apodization and carrier tilt. This is useful for self-bending beam demos and accelerating-wave patterns.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_airy_beam".

Mathematical Formulation

The beam uses separable Airy envelopes with finite-energy tapers:

$$u(\mathbf{x}, t) = A\,\mathrm{Ai}\!\left(\frac{u}{s_u}\right)\mathrm{Ai}\!\left(\frac{v}{s_v}\right) \exp\!\left(a_u \frac{u}{s_u} + a_v \frac{v}{s_v}\right) e^{i(k_u u + k_v v - \omega t + \phi)}$$

where scale_u/v set $s_u, s_v$ and apodization_u/v set $a_u, a_v$.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_airy_beam",
    amplitude = 0.5,
    scale_u = 0.4,
    apodization_u = 0.12
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_airy_beam",
    amplitude = 0.35,
    carrier_u = 2.0,
    carrier_v = -1.0,
    orientation = math.pi / 8
})

---

Zone Plate 🎯

add_stimulus_operator(ctx, field, opts)

Generate a Fresnel-style zone plate with quadratic radial phase and Gaussian aperture. This is useful for diffraction-inspired rings, focusing masks, and radial chirp patterns.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_zone_plate".

Mathematical Formulation

In the local plate frame,

$$u(\mathbf{x}, t) = A \exp\!\left(-\frac{1}{2}\left[\left(\frac{u}{a_u}\right)^2 + \left(\frac{v}{a_v}\right)^2\right]\right) e^{i(\kappa \rho^2 - \omega t + \phi)}$$

where $\kappa$ is radial_chirp and $\rho^2 = (u/s_u)^2 + (v/s_v)^2$.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_zone_plate",
    amplitude = 0.7,
    radial_chirp = 24.0,
    aperture_u = 1.3
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_zone_plate",
    amplitude = 0.5,
    scale_u = 0.75,
    scale_v = 1.25,
    orientation = math.pi / 6
})

---

Bessel Beam 🧵

add_stimulus_operator(ctx, field, opts)

Generate an integer-order cylindrical Bessel beam with configurable radial wavenumber. This is useful for non-diffracting beam demos, cylindrical modes, and ringed phase fronts.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_bessel_beam".

Mathematical Formulation

In the local beam frame,

$$u(\mathbf{x}, t) = A\,J_n(k_r \rho)\,e^{i(n\theta - \omega t + \phi)}$$

where order sets the integer $n$, radial_wavenumber sets $k_r$, and $\rho$ is the scaled radial coordinate.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_bessel_beam",
    amplitude = 0.5,
    order = 0,
    radial_wavenumber = 10.0
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_bessel_beam",
    amplitude = 0.35,
    order = 2,
    orientation_rate = 0.1
})

---

Hermite-Gaussian Beam 🔬

add_stimulus_operator(ctx, field, opts)

Generate separable Hermite-Gaussian transverse modes inside a Gaussian envelope. This is useful for cavity-mode demos, paraxial beam families, and mode-superposition studies.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_hermite_gaussian_beam".

Mathematical Formulation

$$u(\mathbf{x}, t) = A\,H_m\!\left(\frac{\sqrt{2}\,u}{w_u}\right) H_n\!\left(\frac{\sqrt{2}\,v}{w_v}\right) \exp\!\left(-\frac{u^2}{w_u^2} - \frac{v^2}{w_v^2}\right) e^{i(k_u u + k_v v - \omega t + \phi)}$$

where mode_u/v set the Hermite indices and waist_u/v set the beam waists.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_hermite_gaussian_beam",
    amplitude = 0.6,
    mode_u = 1,
    mode_v = 0,
    waist_u = 0.75
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_hermite_gaussian_beam",
    amplitude = 0.45,
    mode_u = 2,
    mode_v = 1,
    carrier_u = 1.5
})

---

Traveling Wave Packet 📦

add_stimulus_operator(ctx, field, opts)

Generate a Gaussian-envelope traveling wave packet with configurable carrier and drift. This is useful for localized transport, dispersive-packet demos, and moving coherent structures.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_traveling_wave_packet".

Mathematical Formulation

The packet envelope is

$$G(u, v) = \exp\!\left(-\frac{1}{2}\left[\left(\frac{u}{\sigma_u}\right)^2 + \left(\frac{v}{\sigma_v}\right)^2\right]\right)$$

and the injected field is

$$u(\mathbf{x}, t) = A\,G(u,v)\,e^{i(k_u u + k_v v - \omega t + \phi)}$$

with the packet center drifting through the local frame over time.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_traveling_wave_packet",
    amplitude = 0.6,
    sigma_u = 0.7,
    carrier_u = 3.6,
    velocity_u = 0.12
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_traveling_wave_packet",
    amplitude = 0.4,
    sigma_v = 1.2,
    carrier_v = 2.0,
    orientation = math.pi / 4
})

---

Cylindrical Wave Emitter 📡

add_stimulus_operator(ctx, field, opts)

Generate a regularized cylindrical wave radiating from a moving point source. This is useful for 2D wave-emitter demos, soft singular sources, and outgoing radial phase fronts.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_cylindrical_wave_emitter".

Mathematical Formulation

With softened radius

$$r_a = \sqrt{\rho^2 + a^2}$$

the emitted field is

$$u(\mathbf{x}, t) = A \frac{e^{-\alpha r_a}}{\sqrt{r_a}} e^{i(k_r r_a - \omega t + \phi)}$$

where softening_radius supplies $a$, attenuation supplies $\alpha$, and radial_wavenumber supplies $k_r$.

Parameters

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

Examples

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_cylindrical_wave_emitter",
    amplitude = 0.7,
    radial_wavenumber = 9.0,
    attenuation = 0.2
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_cylindrical_wave_emitter",
    amplitude = 0.4,
    softening_radius = 0.2,
    velocity_u = 0.05
})