EduSim

GPU-powered interactive science simulations, running in the browser on WebGPU. Built with Next.js 16 (App Router, Turbopack), React 19, Tailwind 4 and vgpu.

Simulation	Subject	GPU technique
Wave Interference & Diffraction	Physics	Fragment shader; Huygens–Fresnel slits as phasor sums
N-Body Orbital Mechanics	Physics	Tiled all-pairs gravity compute shader (up to 16 384 bodies), leapfrog integrator, instanced rendering
Double Pendulum Chaos	Physics	One RK4 compute kernel for every view: a 32-bit GPU crowd of up to 10 000 pendulums against a 64-bit CPU pair, and a flip-time fractal of up to 1024² pendulums (one per pixel)
Axons & Nerves	Biology	Hodgkin–Huxley cables, one GPU invocation per fibre solving its tridiagonal system implicitly (Thomas algorithm); a nerve of up to 1 000 fibres and its compound action potential
Hodgkin–Huxley Neuron	Biology	Compute shader integrates the ODEs; fragment shader plots the traces
Cellular Automata	Computer Science	Ping-pong compute shader over grids up to 2048²; a reduction shader counts and fingerprints every generation; pan/zoom renderer
How AI Learns	Computer Science	A neural network trained on the GPU: forward, backpropagation, gradient and momentum-SGD kernels over the whole mini-batch (deterministic, no atomics); a live decision map and every neuron's own map; real handwritten digits (MNIST) with a draw pad
How AI Writes	Computer Science	A character-level language model (neural bigram, MLP or a small GPT) trained on the GPU with AdamW, a whole step in one command buffer; it writes as it learns, shows its attention, races exact count tables, and plays Shannon's guessing game against you

The catalog in src/lib/subjects.ts lists many more planned simulations (marked "Coming Soon"). See docs/ROADMAP.md for the improvement plan.

Getting started

pnpm install
pnpm dev          # http://localhost:3000

You need a browser with WebGPU (recent Chrome, Edge or Safari). Without it, simulation pages show an explanatory message instead of a blank canvas.

This repo uses a newer Next.js than most training data covers — see AGENTS.md and read node_modules/next/dist/docs/ before changing framework-level code.

Scripts

Command	What it does
pnpm lint	ESLint
pnpm typecheck	next typegen (route types) + tsc --noEmit
pnpm test	Vitest: pure logic and headless-GPU tests of every shader
pnpm test:lm-slow	The How AI Writes challenge claims that need real training (names, temperature, the sonnet, the copying game), on the headless GPU: about an hour on the software renderer, so not part of pnpm test
pnpm check:wgsl	Validates every .wgsl file against a real WebGPU device (next build does not)
pnpm build	Production build (all simulation routes are statically generated)
pnpm smoke	Browser smoke test of a running server (BASE_URL=http://localhost:3000)
pnpm e2e	Full browser suite (94 scenarios: every sim, URL state, measurement tools, challenges, shortcuts, no-WebGPU, phone) against BASE_URL. Works on pnpm start, pnpm dev with E2E_DEV=1 (React strict mode; skips size budgets) and a static export. E2E_GREP=<regex> runs only the scenarios whose name matches; E2E_CHROMIUM=<path> uses another Chromium build
pnpm smoke:local	Builds, serves on a spare port, runs the smoke test, stops the server
pnpm export	Fully static offline build in out/ — serve with any static file server, no Node or internet
pnpm verify	lint → typecheck → test → check:wgsl → build

Git hooks

pnpm install enables .githooks/pre-push, which runs pnpm verify before every push so a broken build never reaches GitHub (GitHub Actions may be unavailable). Bypass in an emergency with git push --no-verify.

Running the GPU tests without a GPU

pnpm test and pnpm check:wgsl need a WebGPU adapter. On a machine without one (containers, CI):

npx vgpu install-software-renderer   # one-off: downloads a CPU Vulkan renderer
REQUIRE_GPU=1 pnpm test              # REQUIRE_GPU makes a missing adapter a failure instead of a skip

Project layout

src/
  app/
    page.tsx                    landing page, grouped by subject
    [subject]/[sim]/page.tsx    the single simulation route (generateStaticParams, 404 for the rest)
  components/                   SimLayout, ParameterSlider, SimCard, GpuStatusOverlay
  lib/
    subjects.ts                 simulation catalog (single source of truth)
    gpu/runtime.ts              WebGPU lifecycle: init, surface, clock, safe teardown
    gpu/useGpuSim.ts            React hook wrapping the runtime
  simulations/
    loaders.tsx                 sim id -> lazily loaded, client-only component
    <subject>/<sim>/
      sim.ts                    creates the GPU resources and the frame loop; returns a handle
      controls.tsx              React UI built on SimLayout + useGpuSim
      *.wgsl                    shaders, loaded through vgpu's bundler loader

This is the beginning of the README. Read the rest at the original. Read the full README ↗