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

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.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

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.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

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_morlet_field"
amplitude	double	0.0	unbounded	Overall amplitude (0.0 writes nothing)
scales	integer	4	1..64	Number of Morlet scales $S$ (clamped to 64)
base_wavenumber	double	1.0	unbounded	Carrier wavenumber at scale 0 (rad/unit)
scale_growth	double	2.0	nonzero	Geometric growth of carrier wavenumber $\gamma_k$ (absolute value used; zero falls back to default)
sigma_base	double	0.75	(0, 8]	Gaussian envelope width at scale 0
sigma_growth	double	1.5	nonzero	Geometric growth of envelope width $\gamma_\sigma$ (absolute value used; zero falls back to default)
center_u	double	0.0	unbounded	Wavelet center along local u coordinate
center_v	double	0.0	unbounded	Wavelet center along local v coordinate
velocity_u	double	0.0	unbounded	Center drift velocity along u (units/s)
velocity_v	double	0.0	unbounded	Center drift velocity along v (units/s)
orientation	double	0.0	unbounded	Wavelet orientation angle (radians)
orientation_rate	double	0.0	unbounded	Orientation drift rate (rad/s)
omega	double	0.0	unbounded	Temporal angular frequency (rad/s)
phase	double	0.0	unbounded	Global phase offset (radians)
time_offset	double	0.0	unbounded	Additional time shift
rotation	double	0.0	unbounded	Complex phase rotation on output (radians)
zero_mean	boolean	true	—	Apply Morlet zero-mean correction
scale_by_dt	boolean	false	—	Scale writes by dt
use_wavevector	boolean	false	—	Evaluate in (kx,ky) wavevector frame (also auto-enabled if nonzero kx or ky is provided)
kx, ky	double	0.0	unbounded	Wavevector components; if wavevector mode is active and both are zero, runtime uses (1, 0)

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

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_steerable_wavelet"
amplitude	double	—	unbounded	Overall amplitude (required)
wavelet_family	enum	"simoncelli"	see below	Steerable wavelet family
order	integer	1	≥1	Steering order (angular harmonic)
scales	integer	4	≥1	Number of radial scales $S$
base_wavenumber	double	1.0	unbounded	Base radial wavenumber at scale 0 (rad/unit)
scale_growth	double	2.0	(0, 8]	Geometric growth factor between scales
radial_bandwidth	double	0.65	[0.05, 4]	Log-radius Gaussian bandwidth
angular_sharpness	double	1.0	[0.1, 16]	Angular envelope sharpness
orientation	double	0.0	unbounded	Steering orientation angle (radians)
orientation_rate	double	0.0	unbounded	Angular steering drift rate (rad/s)
omega	double	0.0	unbounded	Temporal angular frequency (rad/s)
phase	double	0.0	unbounded	Global phase offset across scales (radians)
time_offset	double	0.0	unbounded	Additional time shift
rotation	double	0.0	unbounded	Complex phase rotation on output (radians)
scale_by_dt	boolean	false	—	Scale writes by dt
use_wavevector	boolean	false	—	Evaluate in (kx,ky) wavevector frame
kx, ky	double	0.0	unbounded	Wavevector components (when use_wavevector = true)

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_heat_kernel"
diffusivity	double	0.0	Heat diffusivity controlling spread rate
sigma_x	double	1.0	Initial width along X/local U
sigma_y	double	1.0	Initial width along Y/local V
preserve_mass	boolean	false	Preserve integrated mass as the kernel broadens

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_optical_vortex"
charge	integer	1	Topological charge controlling phase winding
waist_x	double	0.75	Beam waist along local U
waist_y	double	0.75	Beam waist along local V
center_u, center_v	double	0.0	Beam center in the local frame
velocity_u, velocity_v	double	0.0	Beam-center drift velocity
orientation	double	0.0	Beam orientation angle
orientation_rate	double	0.0	Beam orientation drift rate

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_airy_beam"
scale_u, scale_v	double	0.45	Airy scaling along the local frame axes
apodization_u, apodization_v	double	0.12	Finite-energy taper along each local axis
center_u, center_v	double	0.0	Beam center in the local frame
velocity_u, velocity_v	double	0.0	Beam-center drift velocity
orientation	double	0.0	Beam orientation angle
orientation_rate	double	0.0	Beam orientation drift rate
carrier_u, carrier_v	double	0.0	Carrier tilt applied along the local axes

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_zone_plate"
radial_chirp	double	18.0	Quadratic radial chirp controlling ring spacing
scale_u, scale_v	double	1.0	Radial scaling along the local frame
aperture_u, aperture_v	double	1.6	Gaussian aperture width along the local axes
center_u, center_v	double	0.0	Plate center in the local frame
velocity_u, velocity_v	double	0.0	Plate-center drift velocity
orientation	double	0.0	Plate orientation angle
orientation_rate	double	0.0	Plate orientation drift rate

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_bessel_beam"
order	integer	0	Cylindrical Bessel order
radial_wavenumber	double	8.0	Radial wavenumber applied to $J_n(k_r \rho)$
scale_u, scale_v	double	1.0	Radial scaling along the local frame axes
center_u, center_v	double	0.0	Beam center in the local frame
velocity_u, velocity_v	double	0.0	Beam-center drift velocity
orientation	double	0.0	Beam orientation angle
orientation_rate	double	0.0	Beam orientation drift rate

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_hermite_gaussian_beam"
mode_u, mode_v	integer	0	Hermite mode indices along the local axes
waist_u, waist_v	double	0.75	Beam waist along the local axes
center_u, center_v	double	0.0	Beam center in the local frame
velocity_u, velocity_v	double	0.0	Beam-center drift velocity
orientation	double	0.0	Beam orientation angle
orientation_rate	double	0.0	Beam orientation drift rate
carrier_u, carrier_v	double	0.0	Carrier tilt along the local axes

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_traveling_wave_packet"
sigma_u, sigma_v	double	0.75	Packet width along the local axes
center_u, center_v	double	0.0	Packet center in the local frame
velocity_u, velocity_v	double	0.0	Packet-center drift velocity
orientation	double	0.0	Packet orientation angle
orientation_rate	double	0.0	Packet orientation drift rate
carrier_u, carrier_v	double	0.0	Carrier wavenumber along the local axes

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

Parameter	Type	Default	Description
type	string	—	Must be "stimulus_cylindrical_wave_emitter"
radial_wavenumber	double	8.0	Radial wavenumber of the outgoing phase front
attenuation	double	0.0	Exponential attenuation factor
softening_radius	double	0.1	Core radius used to regularize the source singularity
center_u, center_v	double	0.0	Emitter center in the local frame
velocity_u, velocity_v	double	0.0	Emitter-center drift velocity

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
})