white-noise-atlas

A small numerics project walking from Donsker's invariance principle up to the stochastic heat equation on the torus, with a C++ native core for the hot kernels. Python package, deterministic tests, reproducible gallery.

One realisation of the 2D SHE with a Fourier-space cutoff on a 128x128 torus.

What's inside

Four movements, each with its own figure in gallery/ and analytic tests:

1. Donsker invariance. Rescaled random walks from four step families (Gaussian, Rademacher, uniform, centred exponential) converge in law to Brownian motion. Terminal variance, kurtosis, arcsine occupation, and quadratic variation are checked against closed-form targets.
2. White noise on the torus. Grid and spectral samplers, Hermitian symmetry, and the Wiener isometry against a panel of smooth test functions.
3. Stochastic heat equation. Exponential-Euler in Fourier space, exact flow per mode, mollified in 2D with an explicit UV cutoff.
4. Regularity and round-trip. Spatial and temporal structure functions against their truncated closed forms, in 1D and 2D; BM-like spatial increments of the stationary 1D field.

Every test uses a Gaussian Monte Carlo band sized from the sample count rather than snapshot comparisons.

Quick start

pip install -e ".[dev]"         # builds the C++ core (needs libomp on macOS)
pytest                          # 36 tests, deterministic, ~15s
white-noise-atlas all           # regenerates everything in gallery/

The CLI exposes one subcommand per movement (donsker, white-noise, she-1d, she-2d, regularity, benchmark) plus all. Each calls the matching examples/NN_*.py script.

Gallery

Donsker overlay
White noise covariance
1D SHE space-time
Spectrum decay
Structure function
Round-trip to BM
Benchmark

Performance notes

The native core wins where parallelism amortises per-call overhead: 2D SHE steps (~1.4x-6x vs NumPy, N=64-256), and the structure-function accumulator (~3x, M=2000 rows). The 1D step has a small mode array per call, so below N=2048 the NumPy path is faster; SHE1D.solve dispatches accordingly. Raw numbers live in gallery/benchmark.json.

Layout

src/white_noise_atlas/
    _numerics.py        # Hermitian samplers, mode grids
    _native_fallback.py # NumPy mirrors of the C++ kernels
    donsker.py          # Movement 1
    white_noise.py      # Movement 2
    she.py              # Movement 3
    regularity.py       # Movement 4
    viz.py              # matplotlib helpers
    cli.py              # entry point
src/cxx/                # she_step, structure_function, pybind11 bindings
examples/               # one script per gallery figure
tests/                  # 36 analytic tests
gallery/                # generated PNGs, the hero GIF, benchmark.json

See DECISIONS.md for the non-obvious choices and REFERENCES.md for the sources behind each movement.

Development

ruff check .            # lint
pytest -x               # fail fast
pytest -k parity        # C++/NumPy bit-exact parity (1e-10 tol)

License

MIT