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.
71## Tests
73- `npm run test:node` — f64 solver correctness in Node: exact single-mode
74 linear recurrence, exact uniform-state reaction ODE, and the linearized
75 Turing-mode 2×2 IMEX recurrence (all at ~1e-12).
76- `npm run test:gpu` — builds and drives headless Chrome: GPU-vs-CPU transform
77 and solver cross-checks, plus a 100-step stability run.
78- `node scripts/longrun-node.ts` — CPU run to t = 100 confirming pattern
79 saturation.
e7bcd70Add soak, live-check and solver-only soak toolingJeremy Magland 80- `node scripts/soak.mjs [steps] [lmax] [backend]` — drive the demo for many
81 steps, sampling JS heap and catching crashes. A 900-step run at lmax 63 on
82 software WebGPU (SwiftShader) completes with a flat ~4 MB heap.
2dedc35turing-sphere: reaction-diffusion on the sphere, spectral solver on WebGPUJeremy Magland 83- `node scripts/screenshot.mjs out.png [light|dark] [minSteps]` — screenshot
84 the demo after a number of steps.
e7bcd70Add soak, live-check and solver-only soak toolingJeremy Magland 85- `node scripts/check-live.mjs [url]` — smoke-check a deployed URL in a real
86 browser: load, press Run, confirm the solver advances.
87- `test.html?soak=<steps>&lmax=<n>` — solver-only soak with no rendering.
89### A note on canvas resizing
91Early long runs killed the browser after ~700–800 steps. The cause was the
92colorbar's min/max labels changing width as their digit count changed, which
93reflowed the panel, fired the `ResizeObserver`, and called
94`renderer.setSize()` — reallocating the WebGL drawing buffer. Assigning
95`canvas.width` also blanks the canvas even when the value is unchanged, so the
96same bug caused visible flicker. Fixed by giving the colorbar column a fixed
97width and making `SphereScene.resize()` return early on no-op resizes.
99## Development
101```
102npm install
103npm run dev # local dev server
104npm run build # type-check + production build to dist/
105```
107Deployed to GitHub Pages by `.github/workflows/deploy.yml` on push to `main`.
109## License
111CECILL-2.1 (inherited from SHTNS via shtns-webgpu, whose sources are vendored).