boss_bench

boss_bench.models.heat_flux#

Heat-flux model: sample where the lost alpha particles strike the plasma boundary.

class boss_bench.models.heat_flux.HeatFluxModel(*args, **kwargs)[source]#

The IID baseline of the paper’s heat-flux task: sample where the lost alpha particles strike the boundary.

For the alpha particles born on one surface \(s_0\) = 0.1, 0.25 or 0.5, the model predicts the loss fraction, and samples the strike points of the lost particles on the boundary: their Boozer angles \((\zeta, \theta)\) and energies, as heat_flux.lost_particles computes them from the traced particles. Each strike point is drawn independently by a conditional flow-matching model, as many as the predicted number of lost particles. A sample is a prediction for heat_flux.heat_flux_metrics.

The inputs are the birth surface \(s_0\) and these fields of the configuration:

  • boundary_xyz: the plasma boundary over one field period [m], shape (41 * 41 * 3,) as stored, or (41, 41, 3). Reshaped to (41, 41, 3), it is indexed \((\phi, \theta, xyz)\): Cartesian points of the boundary surface on 41 toroidal angles \(\phi\) uniformly spaced in \([0, 2\pi / n_\text{fp})\) and 41 poloidal angles \(\theta\) uniformly spaced in \([0, 2\pi)\), endpoints excluded. This is the layout of gamma() of a simsopt SurfaceRZFourier with these quadrature points.

  • nfp: the number of field periods.

  • d_pressure_d_s: the radial derivative of the pressure [Pa], shape (15,), on the radial grid s1d, 15 points from \(s = 10^{-4}\) to 1.

  • iota: the rotational transform of the VMEC equilibrium, shape (15,), on the same grid.

  • volume_avg_modB: the volume-averaged field strength [T].

  • minor_radius: the effective minor radius of the boundary [m].

Load the model with load, and predict with sample and predict_loss_fraction. The predictions are not differentiable.

Example

Sample the strike points of the particles born on \(s_0 = 0.1\) in a test configuration, and compare their heat flux with the truth:

import h5py
import boss_bench as bb
from boss_bench import models
from boss_bench.models import HeatFluxModel

path = models.download("heat_flux", "BoSS-models/heat_flux")
model = HeatFluxModel.load(path)
with h5py.File(bb.list_files("BoSS", "confinement", "test")[0], "r") as f:
    record = bb.load_record(f, 0)
prediction = model.sample(record, s0=0.1, seed=0)
bb.heat_flux_error(prediction, record, s0=0.1)
classmethod load(path, device='cpu')[source]#

Load the trained model, from its PyTorch weights.

This loads model.safetensors. The ONNX export of the model, from the same Hugging Face folder, is not loaded here: run it with ONNX Runtime instead.

Parameters:
  • path (str) – the model’s folder, holding config.json and model.safetensors, e.g. from models.download("heat_flux", path).

  • device (str or torch.device) – the device to put the model on.

Returns:

the model, ready to predict.

Return type:

HeatFluxModel

Raises:

ValueError – if the folder holds another model.

predict_loss_fraction(data, s0=0.1)#

Predict the loss fraction of the particles born on one surface, for one or several configurations.

Parameters:
  • data (dict) – the fields of one configuration, as from data.load_record, or of several, with one row per configuration, as from data.load. Only boundary_xyz, nfp, d_pressure_d_s, iota, volume_avg_modB and minor_radius are read.

  • s0 (float) – the birth surface, 0.1, 0.25 or 0.5.

Returns:

the loss fraction, shape (n,) for a batch.

Return type:

float or np.ndarray

Raises:
  • KeyError – if a field is missing from data.

  • ValueError – if a field contains NaN or inf.

sample(data, s0=0.1, seed=None)#

Sample the strike points of the lost particles born on one surface, for one or several configurations.

For each configuration, the number of strike points is the predicted number of lost particles of the 5,000 launched, \(\max(1, \operatorname{round}(5000 \hat f))\), with \(\hat f\) the predicted loss fraction.

Parameters:
  • data (dict) – the fields of one configuration, as from data.load_record, or of several, with one row per configuration, as from data.load. Only boundary_xyz, nfp, d_pressure_d_s, iota, volume_avg_modB and minor_radius are read.

  • s0 (float) – the birth surface, 0.1, 0.25 or 0.5.

  • seed (int, optional) – the random seed. By default, a random one.

Returns:

zeta, theta, energy, loss_fraction, the Boozer angles [rad] and energies [MeV] of the strike points, arrays of shape (k,), and the predicted loss fraction, a float; one tuple per configuration for a batch.

Return type:

tuple or list of tuple

Raises:
  • KeyError – if a field is missing from data.

  • ValueError – if a field contains NaN or inf.