2dedc35turing-sphere: reaction-diffusion on the sphere, spectral solver on WebGPUJeremy Magland 1# turing-sphere
3Reaction–diffusion systems (Turing patterns) solved **live in the browser on the
4surface of a sphere**, using a spectral spherical-harmonic method with the
5transforms running on the GPU via WebGPU.
7**Live demo:** <https://concept-collection.github.io/turing-sphere/>
9## What it does
11It solves the N-species system
13```
14d(u_k)/dt = D_k*lap_s(u_k) + f_k(t, x, y, z, u_1, ..., u_N), k = 1, ..., N
15```
17on the unit sphere, where `lap_s` is the Laplace–Beltrami operator. Diffusion is
18treated implicitly in spherical-harmonic coefficient space, where `lap_s` is
19diagonal with eigenvalues `-l(l+1)`; reaction is treated explicitly on the grid.
20The two are combined with a first-order IMEX Euler step — the entire time loop is
22```
23V_k = synth(U_k) # spectral -> grid
24R_k = analys(f_k(t, x, y, z, V_1..V_N)) # reaction on grid -> spectral
25U_k = (U_k + dt*R_k) / (1 + dt*D_k*l(l+1))
26```
28You watch the patterns emerge in real time on orbitable 3D spheres (one per
29species, cameras synced), with pause/resume, re-seeding, live parameter editing,
30and colormap selection.
32Three presets are included:
34- **Schnakenberg** — Turing spots (unstable band 14 ≤ l ≤ 40, peak l = 24)
35- **Brusselator** — stripes and spots from a stiffer reaction
36- **Allen–Cahn** — a single species whose interfaces form and coarsen
38## Provenance
40This is the browser port of a MATLAB reference implementation
41(`SphericalReactionDiffusion.m`, "websph"), which defines the solver through a
42four-member porting boundary: `coeffs2vals`, `vals2coeffs`, `grid.lat`,
43`grid.lon`. Profiling of the MATLAB version shows the transforms are ~96% of
44compute, so this port swaps in:
46- **Transforms:** [shtns-webgpu](https://github.com/concept-collection/shtns-webgpu) —
47 fp32 spherical harmonic transforms in WGSL compute shaders, modeled on
48 [SHTNS](https://nschaeff.bitbucket.io/shtns/). Its source is vendored under
49 [`src/sht/`](src/sht/) (CECILL-2.1), including the f64 CPU reference
50 transform used for testing and as a no-WebGPU fallback.
51- **Rendering:** three.js spheres with per-vertex colormaps, adapted from the
52 `SphereEmbedding` view in
53 [figpack](https://github.com/flatironinstitute/figpack)'s experimental
54 extension package ([`src/render/`](src/render/)).
55- **Solver:** [`src/solver/simulation.ts`](src/solver/simulation.ts), a direct
56 TypeScript port of the MATLAB IMEX loop, in f64 on the coefficients with the
57 transforms in fp32 on the GPU.
59## Numerics
61- Grid: Gauss–Legendre × equispaced-phi, dealiased for the cubic reactions with
62 the `(pdeg+1)` rule from the reference implementation:
63 `nlat ≥ ((pdeg+1)·lmax+1)/2`, `nphi ≥ (pdeg+1)·lmax+1` (rounded up to a power
64 of two for the GPU FFT path). At the default lmax 63 that is a 128×256 grid.
65- Spectral layout: SHTNS conventions — orthonormal + Condon–Shortley, complex
66 coefficients for m ≥ 0, m-major ordering.
67- fp32 transforms introduce ~1e-6 relative error per step (verified against the
68 f64 CPU path); for pattern formation from 1e-2 seeded noise this is
69 inconsequential.
15a77e2Add a desktop WebGPU benchmark and show its command in the appJeremy Magland 71## Desktop vs browser
73How much does running this in a browser cost? [`scripts/bench.ts`](scripts/bench.ts)
74answers that by running the *same* code — same `Simulation`, same WGSL
75transforms, same parameters — from Node on desktop WebGPU (Google Dawn), and
76the app prints the command line that reproduces whatever it is currently
77simulating:
79```
80node scripts/bench.ts --preset schnak-spots --lmax 63 --backend webgpu --steps 2000 \
81 --seed 1 --a 0.1 --b 0.9 --D1 0.0004 --D2 0.008 --dt 0.05
82```
84Copy it from under the stats line, run it, and compare the `ms/step` it reports
85with the app's. Both sides go through the one shared
86[`src/bench/runSpec.ts`](src/bench/runSpec.ts) — the app formats a run into that
87command, the benchmark parses it back — so there is no second copy of the
88defaults for the two runs to drift apart on. Node runs the TypeScript sources
89directly, so `src/` is literally the same code in both places, down to the
90device request in `requestShtDevice()` (Dawn is installed under `navigator.gpu`
91and the WebGPU globals, and the rest runs unchanged).
e5b7827Fix CI: do not omit optional dependenciesJeremy Magland 93Desktop WebGPU comes from the `webgpu` package (prebuilt Dawn, ~70 MB), listed
94as an optional dependency so that a platform it has no binaries for fails the
95install of that package alone rather than the whole tree. `npm install` picks it
96up; without it, only `--backend cpu` runs and the benchmark says so. Other
97flags: `--steps`, `--warmup`, `--json`, `--help`; `DAWN_FLAGS='backend=vulkan'`
98(`;`-separated) passes Dawn options through, e.g. to pick a backend or to
99compare against Dawn's own software adapter.
101What the comparison does and does not control for:
103- the benchmark is **solver only**; the app's `ms/step` excludes `draw()` but is
104 still measured on a page that renders two spheres between steps. For a browser
105 number with no rendering at all, open `test.html?soak=2000&lmax=63`.
106- each step is four transforms, each ending in a buffer readback, so both sides
107 are dominated by submit-and-map latency rather than arithmetic — this measures
108 a driver round-trip more than it measures a GPU.
109- the browser adds its own GPU-process boundary and, for a page that is not
110 cross-origin isolated, coarser timers.
2dedc35turing-sphere: reaction-diffusion on the sphere, spectral solver on WebGPUJeremy Magland 112## Tests
15a77e2Add a desktop WebGPU benchmark and show its command in the appJeremy Magland 114- `npm run bench -- --help` — the desktop benchmark above (see
115 [Desktop vs browser](#desktop-vs-browser)).
2dedc35turing-sphere: reaction-diffusion on the sphere, spectral solver on WebGPUJeremy Magland 116- `npm run test:node` — f64 solver correctness in Node: exact single-mode
117 linear recurrence, exact uniform-state reaction ODE, and the linearized
118 Turing-mode 2×2 IMEX recurrence (all at ~1e-12).
119- `npm run test:gpu` — builds and drives headless Chrome: GPU-vs-CPU transform
120 and solver cross-checks, plus a 100-step stability run.
121- `node scripts/longrun-node.ts` — CPU run to t = 100 confirming pattern
122 saturation.
e7bcd70Add soak, live-check and solver-only soak toolingJeremy Magland 123- `node scripts/soak.mjs [steps] [lmax] [backend]` — drive the demo for many
124 steps, sampling JS heap and catching crashes. A 900-step run at lmax 63 on
125 software WebGPU (SwiftShader) completes with a flat ~4 MB heap.
2dedc35turing-sphere: reaction-diffusion on the sphere, spectral solver on WebGPUJeremy Magland 126- `node scripts/screenshot.mjs out.png [light|dark] [minSteps]` — screenshot
127 the demo after a number of steps.
e7bcd70Add soak, live-check and solver-only soak toolingJeremy Magland 128- `node scripts/check-live.mjs [url]` — smoke-check a deployed URL in a real
129 browser: load, press Run, confirm the solver advances.
130- `test.html?soak=<steps>&lmax=<n>` — solver-only soak with no rendering.
132### A note on canvas resizing
134Early long runs killed the browser after ~700–800 steps. The cause was the
135colorbar's min/max labels changing width as their digit count changed, which
136reflowed the panel, fired the `ResizeObserver`, and called
137`renderer.setSize()` — reallocating the WebGL drawing buffer. Assigning
138`canvas.width` also blanks the canvas even when the value is unchanged, so the
139same bug caused visible flicker. Fixed by giving the colorbar column a fixed
140width and making `SphereScene.resize()` return early on no-op resizes.
142## Development
144```
145npm install
146npm run dev # local dev server
147npm run build # type-check + production build to dist/
148```
150Deployed to GitHub Pages by `.github/workflows/deploy.yml` on push to `main`.
152## License
154CECILL-2.1 (inherited from SHTNS via shtns-webgpu, whose sources are vendored).