Skip to content

RESEARCH.md

Latest commit

 

History

History
116 lines (95 loc) · 6.53 KB

RESEARCH.md

File metadata and controls

116 lines (95 loc) · 6.53 KB
Raw

webgpu-dna — Research Protocol

Thesis

Electron track-structure radiobiology Monte Carlo runs in a browser tab on commodity GPU hardware, reproduces Geant4-DNA reference physics within published statistical uncertainties at every energy from 100 eV to 20 keV, and yields cross sections, ranges, radiolysis G-values, and DNA damage counts that can be cross-validated against tabulated G4EMLOW data, Karamitros 2011, the Geant4 11.4.1 dnaphysics ntuple, and the Tran 2024 ESA BioRad III chemistry review.

Every level below decomposes that thesis into falsifiable experiments.

Standards (apply to every experiment)

Reproducibility

  • Every experiment records the exact git commit SHA, timestamp (UTC ISO8601), Node version, OS platform, hostname, CPU count, and — when run on GPU — navigator.userAgent, adapter.info (vendor / architecture / device / description), and WebGPU device limits, alongside its numbers.
  • Every random input is driven by a named deterministic seed from experiments/lib/seeds.mjs. No Math.random() in an experiment path.
  • Every JSON artifact includes protocol, hypothesis, passBar, seed, warmup, trials so an outsider can re-run and compare.
  • Stage 1 experiments are CPU-only data checks (no GPU); from Level 2 onwards experiments run a real WGSL pipeline and capture adapter info.

Timing

  • All wall-clock measurements use performance.now() with forced GPU sync before and after (a mapped readback of a tiny buffer) — queue.submit is non-blocking.
  • First W = 5 samples per configuration are discarded (shader compile
    • warm-up).
  • Next T = 20 samples are retained.
  • Reported stats: median, p10, p90, p99, std, IQR. Never single-shot.
  • If std/median > 0.1 for any cell, the experiment flags it as NOISY and the author must investigate before publishing.

Correctness

  • Tabulated cross-section comparisons report relative error at every source energy (raw G4EMLOW grid). Pass bars are stated per-experiment; the universal floor is median rel_err < 1e-3 and scale ratio ∈ [0.95, 1.05] vs the raw data — this catches scale-factor regressions (e.g. the historical Champion 334× bug) before they reach a track.
  • Track-structure metrics use mean ± SEM over N primaries vs the Geant4 ntuple's mean for the same N, with a 2σ pass bar.
  • Chemistry G-values report value at t vs Karamitros 2011 / Tran 2024 references with explicit LET corrections documented per experiment.
  • DNA damage counts use Poisson-error pass bars on SSB / DSB per Gy per Da, vs Friedland 2011 / molecularDNA references.

Honest negative results

  • If an experiment fails its pass bar, the JSON is still committed with "status": "fail" and a short "diagnosis" string. Failures are the evidence. No rerunning until it passes.
  • experiments/results/<date>/<level>/<E#>.json is committed even when status = fail; the README index links it as a fail row.

The six levels

# Level Thesis fragment Experiments
1 Cross sections "WGSL tables agree with G4EMLOW within log-log subsampling noise" E1–E4
2 Track structure "CSDA, MFP, ions/primary, energy spectrum match Geant4 11.4.1 ntuple within 2σ at every energy in [100 eV, 20 keV]" E5–E8
3 Pre-chemistry "G(OH)_init, G(eaq)_init at 1 ps reproduce Geant4 chem6 with the documented mother-displacement convention" E9
4 Chemistry @ 1 μs "IRT G-values match Karamitros 2011 / Tran 2024 with explicit LET-deficit accounting at 10 keV" E10–E11
5 DNA damage "Direct + indirect SSB and DSB yields land within the published band of Friedland 2011 / molecularDNA on a comparable target geometry" E12–E14
6 Performance "Per-primary fused dispatch is bandwidth-limited and beats Geant4 single-thread by ≥ 10² on the same machine" E15–E16

Each level has its own protocol.md under experiments/level-N-<slug>/.

Status

Level Status Notes
0 — Env / infra In progress. B0 (browser-runner sanity) passing. Playwright + headless Chromium + WebGPU pipeline functional; B1 (webgpu-dna harness liveness) deferred.
1 — Cross sections Complete. E1, E2, E3, E4, E4b all passing. Born ionization + Emfietzoglou excitation + Champion elastic + Sanche vibrational total + per-mode fractions bit-match.
2 — Track structure In progress. E5 (CSDA + E-cons + ions @ 10 keV) and E6 (MFP across 6 energy bins) implemented and passing. E7/E8 deferred — need per-energy WebGPU dumps. Replaces ad-hoc validation/compare.py with structured validation/webgpu-results.json + research artifacts.
3 — Pre-chemistry Protocol only. Awaits Geant4 chem6 ntuple ingest.
4 — Chemistry In progress. E10 implemented (IRT vs Karamitros 2011 across 5 energies). E11 (GPU vs IRT) deferred — needs browser-runner infra.
5 — DNA damage Protocol only. Awaits Friedland 2011 / molecularDNA reference ingest.
6 — Performance Protocol only. Awaits same-machine Geant4 single-thread baseline.

References

Bench logs

All run artifacts live under experiments/results/<YYYY-MM-DD>/level-N/<E#>.json. The top-level experiments/results/README.md indexes them chronologically.