λWAVES

A playable hydrogen shadow. The 140 exact eigenstates of hydrogen with n ≤ 7, reconstructed on the GPU as a wave field you can play like an instrument: tune amplitudes, phases and viewpoints, then watch the eigenmodes interfere and the cloud move. Small molecules are solved live (Hartree–Fock and Kohn–Sham LDA) or opened from a library of precomputed records.

Live: lambdawaves.magic-commons.com · a Magic Commons project · GPL-3.0-only · interface kit MIR

Status: 0.9.9-beta. What is verified and what is not is in shipping readiness; deployment is in DEPLOY.md.

What it is

The core is exact. λWAVES holds the hydrogen closed forms for n ≤ 7 — all 140 (n, l, m) states, with Condon–Shortley-phase complex spherical harmonics, and evolves them by the one operation a diagonal Hamiltonian permits: multiplying each coefficient by e^{-iE_n t}. For field-free hydrogen nothing is integrated, so nothing drifts. What does step in time is named where it runs: MOLECULES' RUN (real-time TDHF), MO-REGISTRY's DRIVE and SONG and the FLOW tracers integrate; INTER-SHELL STARK is an eigensolve over the 140 labels; VIBRATE moves the nuclei by a closed-form cos ωt and the density by one linear step. The node gate (tests/hydrogen.test.mjs) reads the radial norms within 3e-9 of 1 (its bound 1e-6, by quadrature) and the table-typed anchors within 3e-16 (its bound 1e-12).

The GPU does presentation: lab/field.js reconstructs ψ on an N³ rgba16float grid straight from the closed-form mode tables (no basis textures), and a ray-march presenter draws density, phase, Re ψ, Im ψ or a difference. Measured on an RTX 3070 (headless Firefox, 1920 × 994, batches of at least 2.5 s, 2026-09-24): presenting the default 1s + 2p_z at 96³ and 160 steps takes 3.25 ms per frame in the phase view and 2.10 ms for density, and reconstructing it 0.1 ms; reconstructing all 91 labels of the n ≤ 6 set took 1.43 ms at 96³ and 3.40 ms at 128³ (measured before n = 7 was added; the 140-label figure has not been re-measured). The grid is held to the CPU in each picture's own metric at 64³ (tests/field-law.browser-test.mjs, bounds in tests/helpers/field-law.mjs, read on that RTX 3070 in Firefox): hydrogen 1s + 2p_z against the closed form — |Δψ| RMS ≤ 3e-6, 99.8 % of voxels ≤ 2e-5, the worst voxel ≤ 2e-4; water (H₂O, STO-3G) against the f64 density of the same solve — |Δρ|/ρ RMS ≤ 1e-3, the worst voxel's |Δρ|/ρ ≤ 2e-3, the worst |Δρ| ≤ 3e-4 of ρmax. Every stored component lies within one rgba16float step of its f64 value plus the kernel's own f32 error.

Around that sits the instrument: a rack of windows (STATE, SPECTRUM, ORBIT, PLANE, KEPLER, VORTEX, MOLECULES, MO-REGISTRY, WIGNER, RADIATION, …), a transport with one clock, a modulation rack with drag-to-patch macros, a timeline, NODES, presets, projects, shareable state links, film rendering, FILE › EXPORT SHAPE (GLB · OBJ · STL, the density isosurface on screen) and EXPORT GRID (NPZ · Gaussian cube, ψ on the grid) — see docs/EXPORT.md — and an offline-capable PWA.

It requires a working WebGPU adapter in a secure context. Browser support varies by OS, GPU and driver; see the WebGPU compatibility reference.

Run it

tools/serve.sh          # https://127.0.0.1:8700/lab/   (or: npm run serve)
tools/serve-lan.sh      # the same, reachable from a tablet or phone on the local network

Requirements: Node 22+, Python 3 and OpenSSL (the local server makes its own self-signed certificate on first run), and a browser with WebGPU. The lab is a static tree of ES modules with no build step: what you edit is what the browser runs. For a first look, open FOLDERS (O) and choose a demo under DEMOS — WAVE DANCER PROTOTYPE, STAR LOOP, BENZENE π or WATER ESP — each opens ready to play.

Tests and gates

npm test (./test.sh node) runs every node suite — the mathematics against closed forms and PySCF fixtures, the file and state laws, and the PWA integrity check — plus the state-scope and hint checks; npm run test:browser (./test.sh browser) drives the real interface in headless Firefox with WebGPU against one owned HTTPS server (Firefox and geckodriver on PATH; LW_PORT and GD_PORT choose free ports, occupied ports are refused). The field's pixels are held by a digest gate, tools/perf/digest-lock.mjs, which compares each frame against two recorded fixtures in tests/fixtures/. After any edit under lab/, run node tests/pwa.test.mjs --write: the service worker derives its cache name from its precache hashes, and a stale hash would serve returning visitors the old bytes. ./test.sh legacy runs the historical gate in tests/legacy/, which asserts superseded behaviour and is not part of the release gate.

Requirements and limitations

Needs	A browser with WebGPU in a secure context (https or localhost): Chrome/Edge 113+, Firefox 141+, Safari 26 / iPadOS 26. There is no WebGL fallback: without WebGPU the page shows a notice instead of the lab.
Runs well on	A desktop GPU (measured on an RTX 3070: about 3 ms per frame at 96³) and an M-series iPad (the quality governor drops ray steps, then the grid, under load).
Physics	Exact hydrogen (n ≤ 7, 140 states), plus MOLECULES: Hartree–Fock in vendored Gaussian bases (STO-3G for H–Kr; 6-31+G* for H, C, N, O, F molecules up to 46 Cartesian AOs) — RHF for closed shells, UHF for the 7 open shells — and Kohn–Sham LDA (Slater + VWN5) up to benzene's 36 STO-3G AOs. 98 molecules: 61 solved live (59 enabled; CuH and ZnH₂ are listed and disabled, their RHF reference is not a minimum) and 37 opened from the library, which holds 38 records — 37 solved here and compared with PySCF, C₆₀'s energy PySCF's own (the table below). RPA and TDA spectra, and real-time TDHF. MO-REGISTRY plays orbital packets or many-electron TD-CIS states, drives them with a field, and shows their current. Nuclei are fixed except under VIBRATE (one harmonic normal mode); the wavefunction methods stop at single excitations, and LDA's correlation is the VWN5 functional's. Geometries are fixed: measured for the live molecules (each entry names its source; AlH₃'s is not a measurement), computed for 36 of the 38 records. Five early windows (QCD, H₂⁺, HELIUM, H₂, ELECTROSTATICS) were removed in 0.5.0; an older project that used one opens on a placeholder and says so (docs/LEGACY-WINDOWS.md). Every system λWAVES plays is a row of the catalogue on the MODEL sheet (186 rows, lab/catalogue.js), with its status — EXACT, NUMERICAL or UNCHECKED — and its oracle test.
Not yet verified	A device matrix beyond one desktop, the installed-PWA update on a real device, a real microphone for the AUDIO source, and a screen-reader pass — see shipping readiness. No independent code review has been made.

Against PySCF

A molecule's energy is NUMERICAL: checked against PySCF on the same atoms and the same basis decimals, never against experiment (tests/fixtures/oracles/README.md says what each fixture holds and which script in tools/oracles/ wrote it). A library record is written only if the app's solve is within 1e-8 Eh of PySCF's (tools/orbital-library.mjs). A live molecule is compared on the device; the node gate re-solves every enabled one in STO-3G and reads its agreement back from the STATUS line (tests/status.test.mjs), and holds a bound on these: every enabled closed shell up to 14 STO-3G AOs plus HBr, Br₂, C₂H₄ and C₆H₆ at max(1e-9, 3e-12·|E|) Eh (tests/molecules.test.mjs, tests/chem-sweep.test.mjs), every open shell at 1e-8 Eh (tests/uhf.test.mjs), the 6-31+G* molecules up to 27 AOs at 1e-9 Eh (tests/basis-631.test.mjs) and the LDA eight at 1e-6 Eh (tests/rks.test.mjs). The tables are written by node tools/pyscf-table.mjs.

38 library records — the app's solve beside PySCF's on the record's own atoms (PySCF 2.14.0, cart=True, the vendored Basis Set Exchange decimals, bohr; Δ = app − PySCF in Eh, as stored):

molecule	basis	AO	method	E (app), Eh	E (PySCF), Eh	Δ, Eh	geometry
C₆H₆ · benzene	STO-3G	36	RHF	-227.89100646418083	-227.89100646418058	-2.5579538487363607e-13	experimental
C₃H₇NO₂ · alanine	STO-3G	37	RHF	-317.67874534511134	-317.67874534511066	-6.821210263296962e-13	computed-reference
C₃H₇NO₃ · serine	STO-3G	42	RHF	-391.5289775312513	-391.5289775312844	3.3082869776990265e-11	optimised-here
C₃H₇NO₂S · cysteine	STO-3G	46	RHF	-710.8695451911605	-710.8695451913395	1.7905676941154525e-10	optimised-here
C₅H₉NO₂ · proline	STO-3G	49	RHF	-393.71065517305675	-393.71065517295614	-1.0061285138363019e-10	optimised-here
C₄H₉NO₃ · threonine	STO-3G	49	RHF	-430.07571912211637	-430.07571912251154	3.951754479203373e-10	computed-reference
C₅H₁₁NO₂ · valine	STO-3G	51	RHF	-394.85853402566505	-394.8585340256826	1.7564616427989677e-11	optimised-here
C₄H₇NO₄ · aspartic acid	STO-3G	52	RHF	-502.7860820160869	-502.78608201566465	-4.2223291529808193e-10	optimised-here
C₄H₈N₂O₃ · asparagine	STO-3G	53	RHF	-483.21790965638434	-483.2179096562219	-1.624584911041893e-10	computed-reference
C₆H₁₃NO₂ · isoleucine	STO-3G	58	RHF	-433.4053799418369	-433.40537994232943	4.925482244289014e-10	computed-reference
C₆H₁₃NO₂ · leucine	STO-3G	58	RHF	-433.4398947224981

61 molecules solved live — the app's energy is computed on your device and compared there (the STATUS line prints the agreement), so the table holds PySCF's (PySCF 2.14.0 RHF and PySCF 2.14.0 UHF in STO-3G, PySCF 2.14.0 in 6-31+G*, PySCF 2.14.0 RKS lda,vwn on the app's grid; "no oracle": the card offers it and no PySCF number is on file; "—": not offered):

molecule	AO (STO-3G)	method	STO-3G, Eh	6-31+G*, Eh	RKS LDA (STO-3G), Eh
H₂ · dihydrogen	2	RHF	-1.1167061373496687	-1.126740337407633	no oracle
LiH · lithium hydride	6	RHF	-7.862023874015301	—	no oracle
HF · hydrogen fluoride	6	RHF	-98.5707576634785	-100.01485739573144	-98.24584098961836
N₂ · dinitrogen	10	RHF	-107.49588788341214	-108.94572499706774	-107.14784546338231
CO · carbon monoxide	10	RHF	-111.22458955706387	-112.7415387235556	no oracle
F₂ · difluorine	10	RHF	-195.96746083720126	-198.68096270349432	no oracle
LiF · lithium fluoride	10	RHF	-105.36247144106767	—	no oracle
NaH · sodium hydride	10	RHF	-160.30218654395708	—	no oracle
HCl · hydrogen chloride	10	RHF	-455.1348097026879	—	no oracle
Cl₂ · dichlorine	18	RHF	-909.1116063077275	—	no oracle
NaCl · sodium chloride	18	RHF	-614.5241755564492	—	no oracle
O₂ · dioxygen	10	UHF	-147.6352300151407	no oracle	—
NO · nitric oxide	10	UHF	-127.53039956873471	no oracle	—
OH · hydroxyl radical	6	UHF	-74.3626375456123	no oracle	—
B₂ · diboron	10	UHF	-48.42116526893494	—	—
BeH₂ · beryllium dihydride

Accessibility

Every control is a real button or slider with a name, a value and arrow-key steps; windows are landmarks; the canvas is described in one sentence that changes only when the instrument's state changes. This was checked by a headless browser, not by a person using a screen reader. A photosensitivity notice stands before the first frame. A flash guard then holds the four routes that set the picture's brightness — EXPOSURE, GAMMA, STAGE and KNEE — to three flashes a second whenever a modulator drives them, and says so in METERS; it has no off switch. It is partial: HUE, a molecule's KICK, the register's morph and the camera are not held, so a patch on those can still flash. Please open an issue for anything unreachable or unreadable.

Privacy

λWAVES is a static site with no accounts and no analytics. Nothing you make is sent anywhere: projects, notes and settings live in your browser's localStorage, audio you drop on the TIMELINE in IndexedDB (mir-assets), and anything else in files you export yourself. After the page loads it asks its own origin for a new build at most every 30 minutes, and fetches the records, volumes, pictures, demos and measured lines you open, keeping them in Cache Storage for offline use. An image in an imported notebook is fetched from wherever the note points (SECURITY.md says what that host learns). The microphone is opened only when you add an AUDIO device to the modulation rack, its signal never leaves the page, and it is released when the last AUDIO device is removed; Web MIDI reconnects at launch only where a mapping was saved and the browser already grants it. Cloudflare serves the files and keeps its own ordinary server logs. SECURITY.md lists every request.

The documents

File	What it is
CHANGELOG.md	What changed between releases, newest first; generated by node tools/changelog.mjs.
CONTRIBUTING.md	The rules for a change, the gate, and where things live.
SECURITY.md	Every request the page makes, what stays on your device, and how to report a problem.
DEPLOY.md · RELEASING.md	Deployment to Cloudflare, and how a release is cut.
SHIPPING-READINESS.md · ACCEPTANCE-MATRIX.md	What is verified, what is not, and the evidence per device.
LEGAL-PROVENANCE.md	Every shipped component's origin, licence and copyright holder, and the authorship record.
docs/EXPORT.md	The shape and grid exports.

The interface kit

The interface — tokens, materials, widgets, gestures, window chrome and the modulation window — is MIR, Magic Commons' kit, adopted into lab/mir/ and lab/fonts/ from its own repository. λWAVES keeps only its own selectors in lab.css and skin.css. CONTRIBUTING.md gives the rule for those folders, and MIR-MANIFEST.json lists which bytes are the kit's.

AI disclosure

λWAVES was built with AI coding agents — principally Claude Code with Anthropic's Claude models, with OpenAI Codex and Google Gemini for parts of the code and the graphics — under the direction of its author, Joshua Hosain. Its claims rest on what can be checked — the physics against closed forms and PySCF, the node and browser suites, and the pixel gates — rather than on any claim of authorship. The authorship record (commit identities, attribution trailers, AI-generated assets) is in LEGAL-PROVENANCE.md.

Citing

CITATION.cff has the reference (GitHub shows it as "Cite this repository").

Branches

• main — the release. It moves only when a release is cut; see docs/release/RELEASING.md.
• dev — development.

Licence

GNU General Public License v3.0 only — Copyright 2026 Joshua Hosain. See LICENSE.

Third-party notices are in NOTICE: Spinwerad 0.3, Roboto 3.015, STIX Two Math 2.0.2, KaTeX 0.16.11 and its fonts, marked 12.0.2, the notebook's Spectral, Playfair Display and Alegreya SC; the Basis Set Exchange records and NIST's measured lines are credited there as data.

A reference, not a dependency: ChronusQ (Williams-Young et al., WIREs Comput. Mol. Sci. 10, e1436 (2020)) is the real-time electronic-structure package λWAVES' molecular propagation studied and cites. ChronusQ is released under GPL v2 and λWAVES under GPL-3.0-only, so it is read and cited, never merged: no ChronusQ code is in this tree (NOTICE).