Stimulus: Spatial Patterns

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.

Checkerboard 🏁

add_stimulus_operator(ctx, field, opts)

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

Method Signature

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

Examples

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

-- Rectangular cells with complex phase
ooc.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.add_stimulus_operator(ctx, field, {
    type = "stimulus_checkerboard",
    amplitude = 0.8,
    period_x = 16,
    period_y = 1000
})

---

Moire 〽️

add_stimulus_operator(ctx, field, opts)

Generate a two-grating Moiré interference pattern by averaging two nearby gratings with slightly different wavenumbers or directions. Produces characteristic beat patterns whose spatial frequency equals the difference of the two grating frequencies.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_moire".

Mathematical Formulation

Let $\tau = t + \text{time\_offset}$.

Scalar mode (use_wavevector = false, with mapped coordinate $u=\xi(x,y,\tau)$):

$$\theta_a = k_a u - \omega_a \tau + \phi_a,\quad \theta_b = k_b u - \omega_b \tau + \phi_b$$ $$\Delta u = \frac{A}{2}\left[\cos(\theta_a) + \cos(\theta_b)\right]$$

Wavevector mode (use_wavevector = true):

$$\theta_a = k_{1x}x + k_{1y}y - \omega_a \tau + \phi_a,\quad \theta_b = k_{2x}x + k_{2y}y - \omega_b \tau + \phi_b$$ $$\Delta u = \frac{A}{2}\left[\cos(\theta_a) + \cos(\theta_b)\right]$$

Beat period (scalar mode, $k_b \approx k_a$):

$$\lambda_{\text{beat}} = \frac{2\pi}{|k_b - k_a|}$$

Parameters

For complex fields, the operator writes both cosine and sine components and applies rotation as a complex phase rotation.

When wavevector mode is active and (k1x,k1y) or (k2x,k2y) is exactly zero, runtime substitutes (wavenumber_a, 0) or (wavenumber_b, 0) respectively.

When coord_mode = "separable" (and use_wavevector = false), the operator evaluates one pattern on x and one on y, then combines them with coord_combine ("multiply" or "add").

With use_wavevector = true, the operator uses x,y directly for dot products; origin_*/spacing_* still apply, while coord_mode-specific mapping is bypassed.

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

-- Classic 1D Moiré beat pattern
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_moire",
    amplitude = 1.0,
    wavenumber_a = 2.2,
    wavenumber_b = 2.35
})

-- 2D Moiré with crossed wavevectors
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_moire",
    amplitude = 0.8,
    use_wavevector = true,
    k1x = 1.9, k1y = 0.7,
    k2x = 2.05, k2y = 0.76
})

-- Drifting Moiré (different frequencies)
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_moire",
    amplitude = 0.6,
    wavenumber_a = 2.0,
    wavenumber_b = 2.1,
    omega_a = 0.5,
    omega_b = 0.55
})

---

Positional Encoding 📡

add_stimulus_operator(ctx, field, opts)

Generate a NeRF-style positional encoding: a superposition of sinusoidal bands with geometrically growing wavenumbers. Provides rich multi-frequency structure useful for forcing spatial complexity and feature initialization.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_posenc".

Mathematical Formulation

Let $\tau = t + \text{time\_offset}$ and define:

$$\theta_l = k_0\,\gamma^l\,u - \omega \tau + \phi,\quad l=0,\dots,B-1$$

with encoded sum

$$E(u,\tau) = I\,u + \sum_{l=0}^{B-1} e^{i\theta_l}, \quad I=\begin{cases} 1,& \text{include\_identity=true}\\ 0,& \text{otherwise} \end{cases}$$

and injected write

$$\Delta u = \frac{A}{\sqrt{B+I}}\,E(u,\tau).$$

Scalar mode uses $u=\xi(x,y,\tau)$ from coordinate mapping.

Wavevector mode uses $u = k_x x + k_y y$ for the oscillatory bands. When include_identity = true in wavevector mode, the identity term uses $u_{\text{id}} = (k_x x + k_y y)/\|\mathbf{k}\|$ (fallback to $x$ if $\|\mathbf{k}\|=0$).

Frequency coverage: wavenumbers $k_0, \gamma k_0, \gamma^2 k_0, \ldots, \gamma^{B-1} k_0$

Parameters

For real fields, only the real component is written. For complex fields, both components are written and rotation is applied.

When coord_mode = "separable" (and use_wavevector = false), the operator evaluates one encoding on x and one on y, then combines them with coord_combine ("multiply" or "add").

With use_wavevector = true, the operator uses x,y directly for projection; origin_*/spacing_* still apply, while coord_mode-specific mapping is bypassed.

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

-- Standard 6-band positional encoding
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_posenc",
    amplitude = 0.8,
    base_wavenumber = 2.0,
    bands = 6,
    band_growth = 2.0
})

-- High-resolution 10-band encoding
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_posenc",
    amplitude = 0.5,
    base_wavenumber = 0.5,
    bands = 10,
    band_growth = 2.0
})

-- Temporal oscillation with golden-ratio-like growth
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_posenc",
    amplitude = 0.4,
    base_wavenumber = 1.0,
    bands = 8,
    band_growth = 1.618,
    omega = 0.3
})

-- Radial positional encoding
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_posenc",
    amplitude = 0.6,
    base_wavenumber = 1.5,
    bands = 6,
    coord_mode = "radial",
    coord_center_x = 128,
    coord_center_y = 128
})

---

Log Spectral Grid 🪟

add_stimulus_operator(ctx, field, opts)

Generate a structured spectral field using a polar frequency grid with logarithmically-spaced radial bins and uniformly-spaced angular bins. Provides deterministic or randomized-phase coverage of 2D k-space.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_log_spectral_grid".

Mathematical Formulation

The grid partitions k-space into $R \times \Theta$ bins. For each bin $(r, \theta)$, a mode is placed at the bin center $\mathbf{k}_{r,\theta}$:

$$u(\mathbf{x}, t) = A \sum_{r=0}^{R-1} \sum_{\theta=0}^{\Theta-1} w_r \cos\!\left(\mathbf{k}_{r,\theta} \cdot \mathbf{x} + \phi_{r,\theta} + \Omega t\right)$$

Radial bin centers (log spacing):

$$\bar{k}_r = k_{\min} \cdot \left(\frac{k_{\max}}{k_{\min}}\right)^{(r+0.5)/R}$$

Angular bin directions (with orientation offset $\alpha$):

$$\hat{\theta}_\theta = \alpha + \frac{2\pi \theta}{\Theta}$$

Per-shell amplitude weighting with spectral slope $\beta$: $w_r \propto \bar{k}_r^{-\beta/2}$

Phases $\phi_{r,\theta}$: random (seeded) when random_phase = true, else 0.

Parameters

Examples

-- Standard log spectral grid
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_log_spectral_grid",
    amplitude = 0.7,
    k_min = 0.2,
    k_max = 3.0,
    radial_bins = 7,
    angular_bins = 16
})

-- Deterministic grid (no random phases)
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_log_spectral_grid",
    amplitude = 0.5,
    k_min = 0.3,
    k_max = 2.0,
    radial_bins = 5,
    angular_bins = 8,
    random_phase = false
})

-- Rotating spectral grid
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_log_spectral_grid",
    amplitude = 0.6,
    k_min = 0.2,
    k_max = 3.0,
    radial_bins = 6,
    angular_bins = 12,
    orientation_rate = 0.2
})

-- Pink-noise weighted grid
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_log_spectral_grid",
    amplitude = 0.8,
    k_min = 0.1,
    k_max = 4.0,
    radial_bins = 8,
    angular_bins = 16,
    spectral_slope = 2.0,
    seed = 42
})

---

RD Seed 🧬

add_stimulus_operator(ctx, field, opts)

Generate one-shot reaction-diffusion seed templates for initializing RD systems. Produces spots, stripes, labyrinth, or rings patterns with controllable spatial scale and binary sharpness — applied once at the start of the simulation.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_rd_seed". Applied at time = 0 (uses_dt = false).

Mathematical Formulation

The seed pattern is synthesized by randomly placing $N$ primitive shapes (seed_count) and compositing them:

Spots:

$$f(\mathbf{x}) = \sum_{i=1}^{N} \exp\!\left(-\frac{|\mathbf{x} - \mathbf{c}_i|^2}{2 s^2}\right)$$

Stripes:

$$f(\mathbf{x}) = \sum_{i=1}^{N} \sin(\mathbf{k}_i \cdot \mathbf{x} + \phi_i)$$

Labyrinth: Perlin-noise-derived zero-crossings producing maze-like connected regions.

Rings: Concentric Gaussian annuli of randomly varying radii.

Each pattern is then passed through a logistic function:

$$u(\mathbf{x}) = A \cdot \sigma\!\left(s_h \cdot (f(\mathbf{x}) - \theta)\right) + b$$

where $s_h$ = seed_sharpness, $\theta$ = seed_threshold, $b$ = seed_bias.

Parameters

Seed pattern options: spots, stripes, labyrinth, rings

Plus coordinate mapping parameters.

Examples

-- Spots: classic Turing initial condition
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_rd_seed",
    amplitude = 0.9,
    seed_pattern = "spots",
    seed_count = 28,
    seed = 7
})

-- Labyrinth: maze-like initial topology
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_rd_seed",
    amplitude = 0.8,
    seed_pattern = "labyrinth",
    seed_count = 32,
    seed_scale = 8.0,
    seed = 42
})

-- Stripes with sharp edges
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_rd_seed",
    amplitude = 1.0,
    seed_pattern = "stripes",
    seed_count = 12,
    seed_sharpness = 20.0,
    seed_scale = 4.0,
    seed = 3
})

-- Concentric rings
ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_rd_seed",
    amplitude = 0.7,
    seed_pattern = "rings",
    seed_count = 8,
    seed_scale = 10.0,
    coord_mode = "radial",
    coord_center_x = 128,
    coord_center_y = 128,
    seed = 5
})

---

Log-Polar 🌀

add_stimulus_operator(ctx, field, opts)

Generate rings-and-spokes structure from the combination of log-radius and polar angle. This is useful for spiral masks, spoke wheels, and scale-aware angular patterns.

Experimental: Parameter names and coordinate interactions may change while the log-polar family settles.

Method Signature

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

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_log_polar".

Mathematical Formulation

The phase is built from log-radius and angle:

$$\phi(\mathbf{x}, t) = k_r \log(r + \varepsilon) + m\theta - \omega t + \phi_0$$

where $k_r$ is radial_frequency, $m$ is angular_frequency, and $\varepsilon$ is radius_floor.

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_log_polar",
    amplitude = 0.8,
    radial_frequency = 7.0,
    angular_frequency = 4.0
})

ooc.add_stimulus_operator(ctx, field, {
    type = "stimulus_log_polar",
    amplitude = 0.5,
    orientation_rate = 0.2,
    radius_floor = 0.1
})