Skip to content
SciNimPublic

About

A library to interface with Magboltz (Boltzmann transport equation solver for gas mixtures)

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

NimBoltz

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).

Two modes

ModeHowWhat
Defaultmany independent electrons, exact bounds of the collision frequency, all cores: Magboltz’s results within errors
Magboltz, bit for bitNIMBOLTZ_FORTRAN=1one 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.

Building and running

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
VariableEffect
NIMBOLTZ_FORTRAN=1Magboltz bit for bit (see above)
NIMBOLTZ_THREADS=nn threads instead of all cores
NIMBOLTZ_SEED=nanother 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=1the time of each step of a deck on stderr
NIMBOLTZ_GPU_AVALANCHES=1with 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.

As a library

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 √cm

A 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.

Speed

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):

deckdefault32 threadsMagboltz++bit for bitMagboltz 11.21
Ar/CO₂ 90/10, 0 K (arco2_nob_t0)8.91.613.922.528.0
Ar/CO₂ 90/10, B ⊥ E (arco2_bperp_t0)11.01.513.532.238.7
CO₂, thermal (pure_co2_t1)10.31.416.417.420.5
CF₄ (gas01)15.81.998.3147.1191.2
H₂ (gas21)11.71.771.540.551.0
air, Townsend (hi_air_t0)203.211.7414.8890.0992.5
Ne/CO₂, Townsend (penning_neco2_t0)30.93.242.746.052.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):

deck1 thread32 threadsGPU, float64 (gpu)GPU, float32 (gpu32)
arco2_nob_t063.03.11.110.29
arco2_bperp_t085.54.21.950.28
pure_co2_t176.23.91.650.41
gas01113.05.93.270.54
gas2184.04.52.870.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.

GPUs and the web

  • NVIDIA GPUs: build with -d:nimboltzGpu --path:<tattletale> (Crucible, the Nim-to-GPU compiler of tattletale) and run with NIMBOLTZ_WALKERS=gpu (or gpu32 in 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. With NIMBOLTZ_GPU_AVALANCHES=1 the 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), like gpu32. See web/README.md.

Agreement with Magboltz

  • 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.

Defects of Magboltz

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 Magboltz interfacer

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 parallel

It needs magboltz on the PATH:

wget https://magboltz.web.cern.ch/magboltz/magboltz-11.21.f
gfortran -O3 -o magboltz magboltz-11.21.f

The 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/Magboltz

Gases

Magboltz’s gas numbers, as in the decks, and their names in the library (nimboltz/gases.Gas):

1cf421hydrogen41deuteratedMethane
2argon22deuterium42boronTrifluoride
3helium423carbonMonoxide43c2h2f4
4helium324methylal44trimethylamine
5neon25dimethylEther45c3f4h2
6krypton26reidStep46nPropanol
7xenon27maxwell47paraHydrogen
8methane28reidRamp48orthoDeuterium
9ethane29hexafluoroethane49c4f7n
10propane30sulphurHexafluoride50fluoroform
11isobutane31ammonia51bromotrifluoromethane
12carbonDioxide32propene52perfluoropropane
13neopentane33cyclopropane53ozone
14water34methanol54mercuryDimer
15oxygen35ethanol55hydrogenSulphide
16nitrogen36isopropanol56nButane
17nitricOxide37cesium57nPentane
18nitrousOxide38fluorine58nitrogenPhelps
19ethylene39carbonDisulphide59germane
20acetylene40carbonylSulphide60silane
61carbonTetrachloride

26 to 28 are model gases; 62 to 80 are empty, as in Magboltz.

About

A library to interface with Magboltz (Boltzmann transport equation solver for gas mixtures)

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages