Electron transport in gas mixtures: Magboltz 11.21 (S. Biagi), the reference Monte Carlo program for drift velocities, diffusion, mean energies and Townsend coefficients of electrons in gases, ported to Nim.
- The same input decks and the same printout as Magboltz, all 61 gases (and the 19 empty slots of Magboltz), all field geometries, the gas at 0 K or with thermal motion, Penning transfers, the Townsend analyses.
- Faster than Magboltz and than Magboltz++, on one thread and more so on many, on NVIDIA GPUs and in a web page (WebAssembly, WebGPU): https://scinim.github.io/NimBoltz/.
- A library: a gas mixture and the fields in, the results out as values with errors and units.
- 61 defects of Magboltz 11.21 fixed, each reported with a reproduction (see Defects of Magboltz and the Magboltz fork).
| Mode | How | What |
|---|---|---|
| Default | many independent electrons, exact bounds of the collision frequency, all cores: Magboltz’s results within errors | |
| Magboltz, bit for bit | NIMBOLTZ_FORTRAN=1 | one electron, Magboltz’s methods and random numbers, one thread: Magboltz’s printout, number for number |
The default mode gives the same physics with other estimators: the drift run follows many electrons (“walkers”) instead of one long trajectory, and every free flight uses an exact upper bound of the collision frequency over short time windows instead of Magboltz’s coarse one, so far fewer null collisions are drawn. Its results agree with Magboltz’s within the errors, and its errors are honest: Magboltz underestimates some of its own (diffusion by 2–5 times, attachment in CCl₄ and SF₆ by up to 16 times).
The bit-for-bit mode is there to cross-check: with the same deck it prints what Magboltz 11.21 prints (with the defects below fixed in both), digit for digit, which the regression tests check on 96 decks.
Nim 2.4 or later, and the packages of NimBoltz.nimble (among them
Unchained from its branch rational-powers, not released yet):
nimble install -d # the dependencies
nim c -d:release -o:nimboltz-mb src/nimboltz/magboltz_main.nim
./nimboltz-mb < deck.in > deck.out # a Magboltz deck, Magboltz's printout
NIMBOLTZ_FORTRAN=1 ./nimboltz-mb < deck.in # Magboltz 11.21, bit for bit| Variable | Effect |
|---|---|
NIMBOLTZ_FORTRAN=1 | Magboltz bit for bit (see above) |
NIMBOLTZ_THREADS=n | n threads instead of all cores |
NIMBOLTZ_SEED=n | another seed (Magboltz’s is 54217137) |
NIMBOLTZ_WALKERS=cpu[:n] | n walkers on the CPU threads (default: 100 per thread) |
NIMBOLTZ_WALKERS=gpu[:n] | the drift on an NVIDIA GPU in double precision (float64); n walkers, default 16384 |
NIMBOLTZ_WALKERS=gpu32[:n] | the same in single precision (float32): 4–10 times as fast, same results within errors |
NIMBOLTZ_RNG=… | xoshiro (default: xoshiro256+, on GPUs xoshiro128) or ranmar (RM48), walkers |
NIMBOLTZ_TIMING=1 | the time of each step of a deck on stderr |
NIMBOLTZ_GPU_AVALANCHES=1 | with gpu: the Townsend avalanches on the GPU too (experimental, slower yet) |
gpu and gpu32 need a GPU build (-d:nimboltzGpu, see GPUs and the web).
In single precision the walkers keep positions, velocities, energies and
the collision tables in float32 and draw their random numbers from
xoshiro128+; the sums over them stay in float64 on the CPU.
import nimboltz/api
let r = simulate(Setup(mixture: @[(argon, 90.0), (carbonDioxide, 10.0)],
efield: 500.0.V•cm⁻¹, collisions: 4_000_000))
echo r.velocity.z # 41.1 ± 0.122 MicroMeter•NanoSecond⁻¹
echo r.spread(r.transverse) # √(2D/v), per √cmA Setup is one Magboltz deck (gases and shares, temperature, pressure,
E, B and its angle, collisions, Penning transfers, thermal motion);
Setup.fortran selects the bit-for-bit mode. Results has the drift
velocity, the diffusion tensor, the mean energy, the Townsend and
attachment coefficients and the results of the Townsend analyses, each
with its error, plus the collision frequencies by process and the energy
distribution. See src/nimboltz/api.nim.
Whole decks of the regression set (tests/regress/decks, 4·10⁷
collisions, Townsend analyses where Magboltz runs them) on a Ryzen 9
5950X. One thread each, 15 decks side by side, in CPU seconds; and, under
“32 threads”, the default mode on all 32 threads of the machine, one deck
at a time, in seconds of wall time (Magboltz and Magboltz++ have one
thread only):
| deck | default | 32 threads | Magboltz++ | bit for bit | Magboltz 11.21 |
|---|---|---|---|---|---|
| Ar/CO₂ 90/10, 0 K (arco2_nob_t0) | 8.9 | 1.6 | 13.9 | 22.5 | 28.0 |
| Ar/CO₂ 90/10, B ⊥ E (arco2_bperp_t0) | 11.0 | 1.5 | 13.5 | 32.2 | 38.7 |
| CO₂, thermal (pure_co2_t1) | 10.3 | 1.4 | 16.4 | 17.4 | 20.5 |
| CF₄ (gas01) | 15.8 | 1.9 | 98.3 | 147.1 | 191.2 |
| H₂ (gas21) | 11.7 | 1.7 | 71.5 | 40.5 | 51.0 |
| air, Townsend (hi_air_t0) | 203.2 | 11.7 | 414.8 | 890.0 | 992.5 |
| Ne/CO₂, Townsend (penning_neco2_t0) | 30.9 | 3.2 | 42.7 | 46.0 | 52.0 |
Over 90 decks (six left out where the programs do not run the same thing: Magboltz++ stops early, or MB-58 changes the physics) the default mode is 2.3 times as fast as Magboltz++ (geometric mean; median 1.8, slowest deck 1.08: pure argon), 2.7 times as fast as the bit-for-bit mode and 3.2 times as fast as Magboltz 11.21 (gfortran -O2); in total 28 CPU minutes against 89, 92 and 113. Magboltz++ skips the Townsend analyses below |α − η| = 25 /cm; its times above are of a build with Magboltz’s limit (5). On all cores (the default) the walkers and the avalanches run in parallel; about 1 s of each deck on 32 threads is the setup (the tables of cross sections and ELIMIT), which runs on one thread. The avalanches of the Townsend analyses go electron by electron in waves over all threads (each electron with its own random numbers, so the results don’t depend on the number of threads): the analyses of hi_air_t0 take 11 s on 32 threads, against 203 s for the whole deck on one; all 96 decks of the regression set take 4.5 minutes on 32 threads.
The drift alone (MONTE) with ten times the collisions, 4·10⁸, in seconds
of wall time: on one thread (5 decks side by side), on 32 threads and on
an NVIDIA RTX 3090 in double precision (float64, NIMBOLTZ_WALKERS=gpu)
and in single precision (float32, NIMBOLTZ_WALKERS=gpu32):
| deck | 1 thread | 32 threads | GPU, float64 (gpu) | GPU, float32 (gpu32) |
|---|---|---|---|---|
| arco2_nob_t0 | 63.0 | 3.1 | 1.11 | 0.29 |
| arco2_bperp_t0 | 85.5 | 4.2 | 1.95 | 0.28 |
| pure_co2_t1 | 76.2 | 3.9 | 1.65 | 0.41 |
| gas01 | 113.0 | 5.9 | 3.27 | 0.54 |
| gas21 | 84.0 | 4.5 | 2.87 | 0.42 |
The RTX 3090, like other consumer GPUs, does float64 at 1/64 of its float32 rate. Both precisions give the same results within the errors: on these 5 decks and the 7 above, CPU, float64 and float32 agree with χ²/n between 0.02 and 1.4 and no quantity beyond |z| = 2.4.
On the decks above (4·10⁷ collisions) the GPU gains little: starting CUDA and compiling the kernels (NVRTC) takes 0.5–3 s, the tables take their second on the CPU, and the GPU runs at least 16384 walkers, i.e. 3–6 times the collisions asked for (with smaller errors). The Townsend analyses run on the CPU threads (see below for the GPU).
Where the time goes: Magboltz’s free flight takes 5–10 null collisions
per real one; the walkers bound the collision frequency exactly over
short windows of time (~0.1 null collisions per real one), draw angles
without trigonometric functions, and take their random numbers from
xoshiro256+ (Ranmar’s in the bit-for-bit mode). See docs/DESIGN.md.
- NVIDIA GPUs: build with
-d:nimboltzGpu --path:<tattletale>(Crucible, the Nim-to-GPU compiler of tattletale) and run withNIMBOLTZ_WALKERS=gpu(orgpu32in single precision: on an RTX 3090 1.0–1.8 G collisions/s, double precision 0.12–0.48). Each walker has a small generator of its own (xoshiro128** in double precision, xoshiro128+ in single) and its fields in arrays of their own. WithNIMBOLTZ_GPU_AVALANCHES=1the Townsend avalanches run on the GPU too: correct, but still 10–50 times slower than 32 CPU threads (experimental). - A web page (
web/), https://scinim.github.io/NimBoltz/: NimBoltz compiled to WebAssembly, on all cores of the browser’s machine and on its GPU through WebGPU, always in single precision (float32: WGSL has no float64), likegpu32. Seeweb/README.md.
tests/regress: the bit-for-bit mode against the Fortran program, 96 decks (all geometries, thermal motion, Penning transfers, analyses), byte for byte.tests/stat: the default mode against the Fortran program, every printed result within its errors, the errors measured over several seeds where Magboltz’s are too small.tests/gasengine,tests/gasdump: the collision tables of all gases against Magboltz’s.tests/unit,tests/ensemble,tests/gpu,tests/wasm: the library, the walkers, CPU against GPU walkers.
The CI (.github/workflows/ci.yml) runs the unit tests and a deck in
both modes (the bit-for-bit one against Magboltz’s printout), builds the
web page with WebGPU and puts it on GitHub Pages.
How it is built and why: docs/DESIGN.md.
Porting Magboltz line by line, comparing every table bit for bit and then
comparing with Magboltz++ found 61 defects in Magboltz 11.21 (MB-01 to
MB-61): wrong array indices, typos in constants, levels skipped or
counted twice, a mass off by 81 amu, energy lost twice, uninitialised
values, 32-bit overflows. Each is fixed by its evident intent in NimBoltz
and on the branch fixes of the Magboltz fork
https://github.com/SciNim/Magboltz, one commit each, with a report
(bugs/README.md: what, where, its effect on results, a
reproduction), and 15 open questions where the intent is not clear
(bugs/QUESTIONS.md). Where Magboltz has a defect, NimBoltz’s results
are those of the fixed Magboltz.
The first NimBoltz wrote Magboltz decks and ran the Fortran program on
them, several in parallel; it is still here (nimboltz.nim):
import nimboltz
let gases = initGases([("argon", 97.7), ("isobutane", 2.3)])
let mb = initMagboltz(gases, 1050.mbar, 300.K, 60.kV•cm⁻¹, nMax = 10,
usePenning = true, gasMotionThermal = true)
runMagboltz(mb) # or runMagboltz([mb1, mb2, ...]) in parallelIt needs magboltz on the PATH:
wget https://magboltz.web.cern.ch/magboltz/magboltz-11.21.f
gfortran -O3 -o magboltz magboltz-11.21.fThe tests compare with the Fortran program too (MAGBOLTZ_SRC, default
~~/src/Magboltz/magboltz-11.21.f~): the branch fixes of the fork,
git clone -b fixes https://github.com/SciNim/Magboltz ~/src/MagboltzMagboltz’s gas numbers, as in the decks, and their names in the library
(nimboltz/gases.Gas):
| 1 | cf4 | 21 | hydrogen | 41 | deuteratedMethane |
| 2 | argon | 22 | deuterium | 42 | boronTrifluoride |
| 3 | helium4 | 23 | carbonMonoxide | 43 | c2h2f4 |
| 4 | helium3 | 24 | methylal | 44 | trimethylamine |
| 5 | neon | 25 | dimethylEther | 45 | c3f4h2 |
| 6 | krypton | 26 | reidStep | 46 | nPropanol |
| 7 | xenon | 27 | maxwell | 47 | paraHydrogen |
| 8 | methane | 28 | reidRamp | 48 | orthoDeuterium |
| 9 | ethane | 29 | hexafluoroethane | 49 | c4f7n |
| 10 | propane | 30 | sulphurHexafluoride | 50 | fluoroform |
| 11 | isobutane | 31 | ammonia | 51 | bromotrifluoromethane |
| 12 | carbonDioxide | 32 | propene | 52 | perfluoropropane |
| 13 | neopentane | 33 | cyclopropane | 53 | ozone |
| 14 | water | 34 | methanol | 54 | mercuryDimer |
| 15 | oxygen | 35 | ethanol | 55 | hydrogenSulphide |
| 16 | nitrogen | 36 | isopropanol | 56 | nButane |
| 17 | nitricOxide | 37 | cesium | 57 | nPentane |
| 18 | nitrousOxide | 38 | fluorine | 58 | nitrogenPhelps |
| 19 | ethylene | 39 | carbonDisulphide | 59 | germane |
| 20 | acetylene | 40 | carbonylSulphide | 60 | silane |
| 61 | carbonTetrachloride |
26 to 28 are model gases; 62 to 80 are empty, as in Magboltz.