boss-bench
The Benchmark of Stellarator Simulations (the BoSS) is a database of stellarator configurations paired with physics simulations: ideal-MHD equilibria and the collisionless guiding-center orbits of fusion-born alpha particles. This package accompanies the BoSS benchmark paper.
boss-bench loads the data and computes the benchmark metrics exactly as they are
defined in the paper.
Documentation | Data | Models
Installation
boss-bench needs Python 3.9 or newer.
pip install boss-bench
From source:
git clone https://github.com/mishapadidar/boss_bench.git
cd boss_bench
pip install .
Downloading the data
The package works on local files, so download the data before using it. The data is
distributed through Globus as HDF5 files of two kinds, each
split into train and test:
confinementfiles hold up to3000configurations each, with15000traced alpha particles per configuration,5000born on each of the surfacess0 = 0.1, 0.25, 0.5.trajectoryfiles hold up to40configurations each, with6000full orbits per configuration.
Open the Globus link, log in with your institution, Google or ORCID account, select the files and click Download. For large transfers, use Transfer or Sync to... to send them to your own Globus endpoint, such as a cluster or a laptop running Globus Connect Personal.
Put the downloaded files in one folder, for example BoSS/; any layout inside it works.
The examples below use that folder.
Loading the data
Row i of every per-configuration field belongs to configuration i.
import h5py
import boss_bench as bb
files = bb.list_files("BoSS", "confinement", "test") # files under the download folder
with h5py.File(files[0], "r") as f:
record = bb.load_record(f, 0) # every field of configuration 0 (or give its uuid)
data = bb.load(files, ["nfp", "aspect_ratio"]) # fields stacked over files
with h5py.File(bb.list_files("BoSS", "trajectory", "test")[0], "r") as f:
orbit = bb.load_trajectory(f, 0, 5) # orbit 5 of configuration 0: t, s, theta, zeta, vpar
record = bb.load_record(f, 0)
xyz = bb.to_xyz(record, orbit["s"], orbit["theta"], orbit["zeta"]) # its Cartesian positions [m]
Particle losses and heat flux
A particle is lost if confinement_time < t_max. Each quantity is computed over
the particles born on one surface s0:
ct, t_max, s_init = record["confinement_time"], record["t_max"], record["s_init"]
bb.loss_fraction(ct, t_max, s_init, s0=0.1) # fraction lost
bb.energy_loss(ct, t_max, s_init, s0=0.1) # mean of 3.5 MeV * exp(-2 ct / t_max)
bb.normalized_energy_loss(ct, t_max, s_init, s0=0.1) # the same, rescaled to [0, 1]
bb.mean_confinement_time(ct, t_max, s_init, s0=0.1) # mean of the confinement times [s]
# where the lost particles strike the boundary, and their energies
zeta_end, theta_end = record["zeta_end"], record["theta_end"]
zeta, theta, energy, n_launched = bb.lost_particles(ct, t_max, s_init, zeta_end, theta_end, s0=0.1)
# heat flux per bin; only the boundary geometry is read from the record
q = bb.binned_heat_flux(zeta, theta, energy, n_launched, record, resolution=32)
Benchmarks
Each benchmark takes your predictions and returns the paper's metrics.
Surrogate models. A prediction is a per-configuration quantity on the test split,
compared with its true value, such as bb.loss_fraction or bb.normalized_energy_loss
at s0 = 0.1.
Heat flux. A prediction for each test configuration and birth surface s0 is a
tuple (zeta, theta, energy, loss_fraction): the Boozer angles and energies of the
predicted strike points of the lost particles on the plasma boundary (arrays of any
length), and the predicted loss fraction. With predictions a dict from
(uuid, s0) to these tuples,
paths = bb.list_files("BoSS", "confinement", "test")
bb.heat_flux_metrics(paths, predictions)
The per-sample metrics are also available on their own, with their formulas in the
documentation: bb.heat_flux_error(prediction, record, s0) and
bb.energy_distance(prediction, record, s0).
Trajectories. A prediction for each test configuration is a tuple (z, t_loss)
covering all its orbits: z holds the predicted states at lead times 10, 100 and
999 us, of shape (n_orbits, 3, 5), in the embedded form of bb.embed_state, and
t_loss the predicted loss times, of shape (n_orbits,) (NaN if not lost). With
predictions a dict from uuid to these tuples,
paths = bb.list_files("BoSS", "trajectory", "test")
bb.trajectory_metrics(paths, predictions)
Each nRMSE in the report is followed by its breakdown by channel group (pol_x, pol_y,
phi, lambda), whose mean it is. The metrics are also available on their own, with
their formulas in the documentation: bb.nrmse (with by_group=True for the breakdown),
bb.loss_fraction_mae and bb.confinement_time_w1.
Inverse design. Evaluate each design with VMEC and particle tracing at ARIES-CS scale, then score the set:
bb.design_metrics(loss_fraction, mirror_ratio, mirror_target, aspect_ratio, aspect_target)
Plotting
predictions is optional, and maps each birth surface s0 to a predicted
(zeta, theta, energy, loss_fraction), drawn next to the truth.
bb.plot_device(record) # plasma boundary colored by |B|
bb.plot_modB_boozer(record, s=0.5) # |B| on a flux surface in Boozer coordinates
bb.plot_loss_fraction_curves(record) # fraction lost vs time, per birth surface
bb.plot_strike_points(record, predictions) # strike points and density of lost particles, per s0
bb.plot_heat_flux(record, predictions) # heat flux over one field period, per s0
bb.plot_rollouts(z_true, z_pred) # trajectories vs lead time, per channel
Trained models
Three models from the paper are available on Hugging Face, in PyTorch and ONNX:
loss_fraction: a neural surrogate which predicts the loss fraction of the alpha particles born ons0 = 0.1from the plasma boundary and profiles, without a VMEC run.heat_flux: a flow matching model which samples the locations at which lost fast ions strike the boundary.inverse_design: a flow matching model which generates plasma boundaries with a desired loss fraction, shape, field and profiles.
The PyTorch models need pip install "boss-bench[models]". models.download saves a
model from Hugging Face in a folder, and the model's load reads it. The models read the
BoSS fields by name, from one record or from a batch of configurations:
from boss_bench import models
from boss_bench.models import HeatFluxModel, InverseDesignModel, LossFractionModel
surrogate = LossFractionModel.load(models.download("loss_fraction", "BoSS-models/loss_fraction"))
surrogate.predict(record) # loss fraction at s0 = 0.1
heat_flux = HeatFluxModel.load(models.download("heat_flux", "BoSS-models/heat_flux"))
prediction = heat_flux.sample(record, s0=0.1) # (zeta, theta, energy, loss_fraction)
bb.heat_flux_error(prediction, record, s0=0.1)
generator = InverseDesignModel.load(models.download("inverse_design", "BoSS-models/inverse_design"))
conditions = {name: record[name] for name in models.inverse_design.CONDITIONS if name != "loss_fraction"}
boundary_xyz = generator.sample({**conditions, "loss_fraction": 0.01}) # laid out as record["boundary_xyz"]
Calling surrogate on PyTorch tensors gives the loss fraction with gradients, for
example with respect to the boundary. Gradients are available in PyTorch only; the ONNX
files give the predictions without them.
Downloading from Hugging Face directly
Each model is a folder of the Hugging Face repository, holding config.json, the PyTorch
weights model.safetensors and the ONNX files. The ONNX files run without PyTorch, for
example with ONNX Runtime; examples/onnx_models.py shows how. models.download(name, path, onnx=True) also downloads them, but needs PyTorch installed. Without it, use the
Hugging Face command line (pip install huggingface_hub):
# one model
hf download mishapadidar/boss --include "heat_flux/*" --local-dir BoSS-models
# the ONNX files only
hf download mishapadidar/boss --include "*/config.json" --include "*.onnx" --local-dir BoSS-models
# everything
hf download mishapadidar/boss --local-dir BoSS-models
Each model then sits in its own folder, e.g. BoSS-models/heat_flux, which the model's
load reads, e.g. HeatFluxModel.load("BoSS-models/heat_flux"). Single files can also be downloaded from the Files and versions tab of the
repository.
Examples
The examples/ folder has five short scripts. Download the data first, then run each
as python <script> DATA_DIR, where DATA_DIR is a directory containing the downloaded
files (it is searched recursively):
explore_configuration.pyloads a configuration and plots its shape,|B|, loss fraction curves, and true against predicted strike points and heat flux.DATA_DIRmust contain at least one confinement data file from the test split.heat_flux_benchmark.pyscores made-up heat-flux predictions on a small batch of test configurations.DATA_DIRmust contain at least one confinement data file from the test split.trajectory_rollouts.pyloads the orbits of one configuration, plots made-up predictions against them and scores them.DATA_DIRmust contain at least one trajectory data file from the test split.trained_models.pyruns the three trained models on test configurations: it scores the loss-fraction surrogate and the heat-flux model, and plots boundaries generated with a lower loss fraction than a test configuration's.DATA_DIRmust contain at least one confinement data file from the test split. It takes the models folder as a second argument, by defaultBoSS-models.onnx_models.pyruns the loss-fraction surrogate and the heat-flux model with ONNX Runtime, without PyTorch. It takes the same arguments, with the ONNX files downloaded into the models folder first (see above).
Tests
The tests run on small synthetic files with known answers, so they need no download:
pip install ".[test]"
pytest
License
Copyright 2026 The Simons Foundation.
The code and the trained models are released under the Apache License 2.0. The data is released under the CC BY 4.0 license.
Metadata
Release files for boss-bench 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| boss_bench-1.0.0.tar.gz | 55.5 kB | Without provenance | Details for boss_bench-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| boss_bench-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for boss_bench-1.0.0-py3-none-any.whl |
Total release size: 104.3 kB
Release files / boss_bench-1.0.0.tar.gz
| Download URL | boss_bench-1.0.0.tar.gz |
|---|---|
| Size | 55.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
366dd3c4d708b2f486cd2eb753b9417a1beaca6edef59e9fb1e7307887fa73e0
|
|
BLAKE2b-256 checksum How to use checksums |
17d34cf2897ccac3e44f56c057d69faff66f22eacd21c1633f59a3ed9849e4e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.11
|
Release files / boss_bench-1.0.0-py3-none-any.whl
| Download URL | boss_bench-1.0.0-py3-none-any.whl |
|---|---|
| Size | 48.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
414c991245da719dd4acad9f098ba7e1be29e6ccf85bccc51ef200293c8dbf9c
|
|
BLAKE2b-256 checksum How to use checksums |
8f76664878345e461f32d7f6a1460d4b2c0ce06f0a42387e4d1c6d6cb5df049b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.11
|
Security for boss-bench 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.