Reaction–Diffusion Pattern Simulator

rd-pattern is a deterministic command-line implementation of the two-dimensional Gray–Scott reaction–diffusion model. It simulates U/V concentration fields on the CPU and renders still images or PNG animation frame sequences without an image-processing dependency.

Build

dotnet restore
dotnet build -c Release --no-restore
dotnet test -c Release --no-build

Run the development build through dotnet run:

dotnet run --project src/ReactionDiffusion.Cli -- presets list

Commands

Render a still image and its Markdown report:

dotnet run --project src/ReactionDiffusion.Cli -- render \
  --preset coral \
  --width 1024 \
  --height 1024 \
  --steps 20000 \
  --output output/coral.png

Generate an animation frame sequence:

dotnet run --project src/ReactionDiffusion.Cli -- animate \
  --preset mitosis \
  --width 512 \
  --height 512 \
  --frames 120 \
  --warmup-steps 2000 \
  --steps-per-frame 40 \
  --output-dir output/mitosis

Inspect presets:

dotnet run --project src/ReactionDiffusion.Cli -- presets list
dotnet run --project src/ReactionDiffusion.Cli -- presets show worms

Use --overwrite to replace existing output, --no-report to suppress a report, --threads 1 for sequential execution, or --threads 0 for automatic parallelism. Run any command with --help for its complete option list.

Presets

Name	Feed	Kill	Seed	Recommended still steps	Palette
coral	0.0545	0.0620	random-spots	20000	ultraviolet
maze	0.0290	0.0570	center-square	18000	moss
mitosis	0.0367	0.0649	random-spots	20000	ember
spots	0.0350	0.0650	random-spots	18000	ocean
waves	0.0140	0.0540	center-square	16000	grayscale
worms	0.0780	0.0610	random-spots	16000	ultraviolet

Preset labels are descriptive application names, not universal scientific classifications. Explicit command-line options override preset values; omitted options retain the preset values.

Native AOT

Publish a self-contained Windows x64 executable:

dotnet publish src/ReactionDiffusion.Cli/ReactionDiffusion.Cli.csproj `
  -c Release -r win-x64 --self-contained true -p:PublishAot=true

For Linux, replace win-x64 with linux-x64. The executable is named rd-pattern (rd-pattern.exe on Windows).

Create a video with FFmpeg

The application writes frames and includes an FFmpeg example in animation-report.md; it never starts FFmpeg itself.

ffmpeg -framerate 60 -i "output/mitosis/frame-%06d.png" \
  -c:v libx264 -pix_fmt yuv420p "output/mitosis.mp4"

Architecture

• ReactionDiffusion.Core owns validated configuration, deterministic SplitMix64 seeding, contiguous double buffers, neighbor tables, the nine-point stencil, sequential/parallel stepping, metrics, and presets.
• ReactionDiffusion.Rendering maps the V field through fixed-range palettes, calculates image statistics, writes reports, and encodes RGBA PNG files with custom CRC-32 and zlib code.
• ReactionDiffusion.Cli explicitly builds the System.CommandLine tree, resolves defaults/presets/overrides, runs workflows, handles cancellation and exit codes, and protects output with same-directory temporary files.

Core is independent of Rendering and CLI; Rendering is independent of CLI. See the architecture guide and the mathematics.

Verification

Run scripts/verify.ps1 on Windows or scripts/verify.sh on Linux. The scripts restore, verify formatting, build, test, publish Native AOT, and run managed and AOT smoke renders.

Limitations

• The fixed-step explicit Euler solver is intentionally educational; arbitrary valid inputs are not guaranteed to be numerically stable, and concentrations are clamped to [0,1].
• Random spots that cross a grid edge are clipped, including with periodic simulation boundaries.
• Rendering uses only the V field, five built-in palettes, fixed scalar ranges, RGBA8 output, filter type 0, and a single PNG IDAT chunk.
• Animation output is a PNG sequence; video encoding, GUI, GPU acceleration, checkpoints, image-mask seeds, and configuration files are outside version 1.
• Large grids need substantial memory: four double[] simulation fields plus rendering and PNG buffers.

The full behavioral contract and developer test strategy are in PLAN.md and docs/TESTING.md.