boss_bench

Overview

Overview#

boss-bench is the Python package of the BoSS. It loads the data and computes the benchmark metrics exactly as they are defined in the paper. It depends only on NumPy, SciPy, h5py and Matplotlib, and needs Python 3.9 or newer. Install it with

pip install boss-bench

or from source:

git clone https://github.com/mishapadidar/boss_bench.git
cd boss_bench
pip install .

Then import it as

import boss_bench as bb

The package works on local files, so download the data first.

What’s in the package#

Each module has its own page, with every function and the formula of every metric.

boss_bench.data

Finds the downloaded files and reads them: one configuration at a time with load_record(), or chosen fields of many configurations at once.

boss_bench.confinement

Computes the loss metrics of the particles born on one surface: the loss fraction, the energy loss and its normalized form, and the mean confinement time, e.g. loss_fraction().

boss_bench.heat_flux

Finds where lost particles strike the plasma boundary and turns their energy into a heat flux on the boundary. It also scores predictions for the heat-flux benchmark, with heat_flux_metrics().

boss_bench.trajectory

Provides convenience functions to load trajectory data for one particle or one device, and to convert orbits to Cartesian coordinates. It also computes the prediction-error metrics of the trajectory benchmark, with trajectory_metrics().

boss_bench.design

Scores generated designs for the inverse-design benchmark, with design_metrics().

boss_bench.plotting

Plots a configuration, its particle losses and heat flux, and its orbits, alone or next to a model’s predictions.

Benchmarks#

Each benchmark scores a model’s predictions on the test split with the metrics of the paper:

  • Surrogate models: predict a quantity of each configuration, such as its loss_fraction() or normalized_energy_loss() at \(s_0 = 0.1\).

  • Heat flux: predict the loss fraction and the strike points of the lost particles, for each configuration and birth surface; scored by heat_flux_metrics().

  • Trajectories: predict each orbit from its first sample; scored by trajectory_metrics().

  • Inverse design: generate designs and evaluate them with VMEC and particle tracing; scored by design_metrics().

Tutorials#

To see the package in use, work through the tutorials: