WebGPU compute and rendering¶
Compute backend → GPU · WebGPU (approximate) runs surface calculations in WGSL. The device samples equilibrium splines, integrates each frequency with 8,192 Verlet steps, analyzes Floquet matrices, finds roots, and calculates local and period Alfvénicity. Frequencies run in parallel; theta steps remain sequential. Both scalar and coupled models support uniform and adaptive scans. Frequency samples = 0 requests adaptive sampling, capped at 4,097 GPU samples per surface. Radial zoom requests use the same GPU pipeline.
WebGPU needs a browser with a working adapter and a secure context (HTTPS or localhost). Its speed depends on the adapter and batch size; compare full run times against threaded WebAssembly on the target device.
Paired precision¶
GPU · WebGPU paired f32 (approximate) stores each number as a high and low
f32. Both halves pass through spline interpolation, integration, invariants,
root refinement, and Floquet exponents. Division, square root, logarithm, and
angle calculations retain compensation. This reduces roundoff at a higher
arithmetic and memory cost. It retains the f32 exponent range and the Verlet
discretization error.
Before use, the paired shaders check addition and multiplication in the
integrator, then division, square root, logarithm, and angle on buffer inputs.
An adapter that fails these checks uses WebAssembly. Paired scans never silently
select ordinary f32. Compare accuracy on the target adapter; paired arithmetic
does not provide native double precision or guarantee complete root searches.
Equilibrium sampling¶
The CPU constructs the equilibrium and exports each field's cell polynomials
with BSplineInterpolation's generate_polynomial_form() and
polynomial_coef(). WGSL evaluates the normalized bicubics with nested
Horner evaluation in both precisions. Axis fields first evaluate their angular
polynomials, then the radial polynomial in sqrt(psi / psi_min).
Scalar runs skip unused fields. Runs without Falessi amplitude weights also
skip the log-gradient field and its minimum and normalization passes.
Equilibrium construction starts on file selection and stays cached across
runs. The first GPU calculation builds the polynomial payload in a worker.
Later calculations reuse that payload and its resident GPU buffer. Changing
precision or replacing a scanner uploads a new packed buffer while reusing
the native double coefficients. Replacing the equilibrium rebuilds its payload.
The standard 256 × 256 equilibrium exports a 41.65 MB double payload,
which occupies 20.83 MB in f32 or 41.65 MB in paired f32 on the GPU. Export
checks cell counts and buffer limits before conversion; installation checks
validation, memory errors, disposal, and timeout before replacing the old
buffer. Native CPU readers keep their control-point splines.
Buffers and synchronization¶
Each surface then needs only its coordinates, settings, and toroidal targets. Coefficients, matrices, adaptive work lists, root brackets, eigenvectors, and period quadratures stay in GPU buffers. Workers notify the browser when work is ready. It batches up to four available surfaces across two reusable buffer sets without waiting for a display tick or a full batch. Each batch maps one final result buffer. There is no CPU round trip between theta steps, adaptive rounds, root iterations, or color integrations. Adaptive readback still includes the reserved sample capacity; it is not fully compact.
Accuracy and fallback¶
Refine coupled roots bisects sampled crossings on the GPU. Ambiguous turns, clusters of boundary hits, exhausted refinement, numerical overflow, and root capacity overflow recompute the affected surface in WebAssembly. Some difficult runs can therefore fall back entirely. The GPU search can still miss narrow gaps, tangencies, and close modes that its grid does not resolve; both GPU backends remain approximate. Increasing the frequency count can help.
File parsing, equilibrium construction, surface scheduling, branch grouping, exports, and selected Floquet solution calculations still use the CPU. A scalar zone-limit preflight also uses the native solver. Unsupported adapters and physical device errors release waiting workers and fall back to WebAssembly. The status message and export metadata identify the accepted backend.
Saved backend metadata¶
Downloads retain the requested and actual compute backends. Binary files store
compute_backend_requested, compute_backend, scan_precision, and
approximate under /run; mixed means that both backends supplied accepted
surfaces. JSON and Floquet text downloads also identify the backend.
Paired runs use compute_backend=webgpu-paired and
scan_precision=paired-f32; paired/CPU fallback uses mixed and retains the
requested backend. Changing the form after a run does not change these saved
settings. See output formats for the schemas.
Validation¶
The direct field-polynomial sampler passed native-reference checks on circular
and shaped equilibria with a 16 × 64 interpolation grid. Maximum scaled
coefficient differences were 3.46e-6 for f32 and 4.15e-13 for paired f32,
including knot sides, periodic seams, and the axis extension. The worker checks
also confirmed payload and GPU-buffer reuse, re-upload after precision changes,
new payloads for replacement files, and native fallback under a reduced buffer
limit. The shader and worker checks below cover these cases.
Run these commands from the repository root. Build the app with
./build_web.sh and the native references with:
cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
cmake --build build/release --target webgpu-reference webgpu-spline-reference -j
APP_URL below is the served app URL. To check actual shader execution
against analytic matrices and the native float/double integrator, run:
node test/web-webgpu-smoke.mjs APP_URL build/webgpu/browser \
http://localhost:9333 build/release/test/webgpu-reference
The check also exercises mixed-size batches, submission with the display loop
paused, approximate spectra, UI responsiveness, frozen exports, and concurrent
fallback. A software adapter can validate these paths but cannot establish
hardware speedup.
The script accepts a staged app directory after the reference program for a
remote asset bridge. For Chrome setups that keep all tabs visible,
--visible-only skips the hidden-tab checks and records the skip in runs.json.
To check every generated shader, spline interpolation at and beside knots, periodic seams, reused buffers across amplitude and coupling changes, boundary multiplicity, scalar gap labels, paired growing and complex spectra, and variable coupled period quadratures against native references, run:
cmake --build build/release --target webgpu-spline-reference
node test/webgpu-math-smoke.mjs build/webgpu/analysis \
http://localhost:9333 build/release/test/webgpu-spline-reference
node test/webgpu-resident-smoke.mjs APP_URL build/web build/webgpu/resident \
http://localhost:9333
To check upload-time construction, immediate Calculate, rapid file changes, invalid-file recovery, retained results, and one-worker operation, run:
node test/web-equilibrium-preparation-smoke.mjs APP_URL build/web \
build/webgpu/equilibrium-preparation http://localhost:9333
The Emscripten notification regression checks that a worker wake cannot reenter Wasm while the browser holds a solver lock:
cmake --build build/web --target webgpu-proxy-test
ctest --test-dir build/web -R '^webgpu(_proxy)?$' --output-on-failure
To compare both shaders with the same supplied double coefficients, frequencies, and timestep, including repeated waves, band edges, and tiny gaps:
node test/webgpu-precision-smoke.mjs build/webgpu/precision \
build/release/test/webgpu-reference http://localhost:9333
This check creates its own page through DevTools and does not need an HTTP server or port forward. It records matrix, Floquet spectrum, and sampled-root errors separately from runtime measurements.
Figure rendering¶
The continuum, stability diagram, Floquet spectrum, and both solution profiles automatically use WebGPU geometry when an adapter is available. Compute and figures share one device with separate resource ownership. Solver failures can fall back without disabling the figures; physical device loss redraws them with Canvas 2D. Canvas also draws text and handles interaction.
Accepted GPU scans and mode colors retain a compact GPU copy for display, up to 128 MiB. Figures can bind those buffers directly. CPU results upload raw coordinates once when they change. Vertex shaders transform coordinates, clip geometry, and select colors during redraws; zooming does not rebuild every point on the CPU. Dashed paths retain the geometry renderer's continuous dash distance. Paired scalar phase folding uses cached CPU records to preserve low bits. Extreme zoom ranges retain double-precision CPU coordinate mapping.
The renderer batches draws and reuses buffers and raster textures. The Broucke background runs in a fragment shader. Narrow or extreme axis ranges keep the CPU raster. Redraws submit commands without a GPU readback. Rendering does not change saved solver values or export metadata; antialiasing can differ at edges.
To compare composited GPU and Canvas 2D pixels, including gradients, dash phase, closed borders, transparent tiles, stability regions, and device-loss redraw:
node test/plot-gpu-smoke.mjs build/webgpu/plot-renderer http://localhost:9333
node test/web-diagnostic-zoom-smoke.mjs APP_URL build/webgpu/plot-zoom \
http://localhost:9333 build/web --webgpu
Pixel comparisons require Python and Pillow. The optional final directory serves staged app assets through DevTools when the browser has no HTTP port forward. The zoom check covers all five GPU figures, nested selections, mobile layout, fractional pixel ratios, and CPU redraw after device loss. See plot timing commands to measure drawing separately from solver work.
See measurements for dated solver and rendering results, setup costs, memory use, and limits on the speedup claims.