Skip to main content

boss-bench

PyPI Python License: Apache 2.0 Data Models

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:

  • confinement files hold up to 3000 configurations each, with 15000 traced alpha particles per configuration, 5000 born on each of the surfaces s0 = 0.1, 0.25, 0.5.
  • trajectory files hold up to 40 configurations each, with 6000 full 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 on s0 = 0.1 from 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.py loads a configuration and plots its shape, |B|, loss fraction curves, and true against predicted strike points and heat flux. DATA_DIR must contain at least one confinement data file from the test split.
  • heat_flux_benchmark.py scores made-up heat-flux predictions on a small batch of test configurations. DATA_DIR must contain at least one confinement data file from the test split.
  • trajectory_rollouts.py loads the orbits of one configuration, plots made-up predictions against them and scores them. DATA_DIR must contain at least one trajectory data file from the test split.
  • trained_models.py runs 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_DIR must contain at least one confinement data file from the test split. It takes the models folder as a second argument, by default BoSS-models.
  • onnx_models.py runs 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)

Source distribution for boss-bench 1.0.0
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)

Table of built distributions (wheels) for boss-bench 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page