Precomputed tables
Some of the physics needs tools that will not run in a browser. Those parts are computed ahead of time, checked in, and tracked by hash.
Why there are tables
Two pieces of the model depend on heavy tools.
- The radiation belts and the field geometry need the IRBEM library, which is Fortran: the AP8 and AE8 models, the reference magnetic field and the L parameter.
- Shielding needs Geant4, a particle-transport code that takes about half an hour of computing per wall thickness.
Neither can run in a browser, and neither needs to run more than once. So their results are computed by the Python reference engine and stored as tables. The browser model does everything else itself.
The tables
| File | What it holds | Produced by | Tools | Size |
|---|---|---|---|---|
data/orbit_data.json | Orbit-averaged AP8/AE8 trapped proton and electron spectra (solar minimum and maximum, with and without the low-orbit proton correction), and the sampling of McIlwain L and magnetic latitude along each of 68 orbits: 13 altitudes by 5 inclinations, plus GEO, Molniya and GTO. | engine/scripts/build_orbit_data.py | SpacePy 0.7 (IRBEM: AP8/AE8, IGRF) | 512 kB |
data/shield_data.json | Geant4 response matrices of a spherical aluminum shell at 0.3, 1, 3, 10 and 30 g/cm², packed for the browser (5 output bins per decade, 0.06 dex steps), with water stopping powers and the neutron and photon dose coefficients. | engine/scripts/build_shield_data.py | NumPy | 361 kB |
data/trapped.json | AP8/AE8 equatorial flux against L, and its dependence on B/B0, in three energy bands per species and for solar minimum and maximum. It places the radiation-belt tracers and the local readouts of the 3D explorer. | engine/scripts/build_trapped_data.py | SpacePy 0.7 (IRBEM: AP8/AE8, IGRF) | 54 kB |
engine/spacerad/data/phi_usoskin2017_monthly.csv | Monthly solar modulation potential, 1951 to 2016, in MV. | Transcribed from Usoskin et al. (2017), Table 2 (reference usoskin_2017). | none | 4 kB |
engine/spacerad/data/shield/Al_0.3gcm2.npz | Response matrices of a spherical aluminum shell of 0.3 g/cm²: what an isotropic field outside becomes inside, by incident species and energy. | engine/scripts/build_shield_matrices.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 284 kB |
engine/spacerad/data/shield/Al_10gcm2.npz | Response matrices of a spherical aluminum shell of 10 g/cm²: what an isotropic field outside becomes inside, by incident species and energy. | engine/scripts/build_shield_matrices.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 333 kB |
engine/spacerad/data/shield/Al_1gcm2.npz | Response matrices of a spherical aluminum shell of 1 g/cm²: what an isotropic field outside becomes inside, by incident species and energy. | engine/scripts/build_shield_matrices.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 320 kB |
engine/spacerad/data/shield/Al_30gcm2.npz | Response matrices of a spherical aluminum shell of 30 g/cm²: what an isotropic field outside becomes inside, by incident species and energy. | engine/scripts/build_shield_matrices.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 321 kB |
engine/spacerad/data/shield/Al_3gcm2.npz | Response matrices of a spherical aluminum shell of 3 g/cm²: what an isotropic field outside becomes inside, by incident species and energy. | engine/scripts/build_shield_matrices.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 335 kB |
engine/spacerad/data/shield/neutral_dose.npz | Mean dose and dose equivalent in a water sphere of 15 cm radius per unit fluence of neutrons and photons. | engine/scripts/build_neutral_dose.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 5 kB |
engine/spacerad/data/shield/stopping.npz | Stopping powers of water and silicon by particle species, from Geant4: the basis of the charged-particle dose estimate. | engine/scripts/build_shield_matrices.py | Geant4 11.4.1 (QBBC physics list, 0.1 mm production cut) through geant4_pybind 0.1.3 | 78 kB |
Each table has a recorded SHA-256. A check fails if a table no longer matches its record, which catches both a rebuild that was not written down and an edit by hand.
What the browser cannot do, as a result
- Earth orbits come from a grid: 13 altitudes from 300 to 20 200 km by 5 inclinations, plus geostationary, Molniya and geostationary transfer. The Python engine handles any orbit.
- Wall thickness comes from five values. The dose panel interpolates between them; the spectrum explorer offers the five.
- Trapped particles on the grid carry the interpolation error of the tables, a few percent.
Rebuilding
From the repository root, with the Python engine installed:
python engine/scripts/build_orbit_data.py about 2 minutes; needs SpacePy (IRBEM)
python engine/scripts/build_trapped_data.py needs SpacePy (IRBEM)
python engine/scripts/build_shield_data.py repacks the Geant4 matrices for the browser
node tools/data-manifest.mjs --write records the new hashes
python engine/scripts/build_parity_fixture.py refreshes the reference values for the parity tests
npm test
The Geant4 matrices themselves are rebuilt with engine/scripts/build_shield_matrices.py; the
engine's Geant4 notes explain the setup.
Two engines, one answer
The Python engine is the reference: it is the one compared with measurements on the validation page. The browser model is a port of it, held to it by tests that compare integral fluxes and doses for a set of scenarios, to 5 % in free space and 6 % behind a wall.