boss_bench

boss_bench.models.loss_fraction#

Loss-fraction surrogate: predict the loss fraction from the boundary and profiles, without VMEC.

class boss_bench.models.loss_fraction.LossFractionModel(*args, **kwargs)[source]#

A trained neural loss-fraction surrogate: predict the alpha-particle loss fraction without VMEC.

The model predicts the fraction of the alpha particles born on \(s = 0.1\) that are lost within 0.1 s, as confinement.loss_fraction computes it from the traced particles. Its inputs are fields of the configuration that need no VMEC run:

  • boundary_xyz: points on 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. The model uses the cylindrical coordinates \(R = \sqrt{x^2 + y^2}\) and \(Z = z\) of the points; the toroidal angle is set by their place in the grid.

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

  • toroidal_current: the enclosed toroidal current profile [A], shape (15,), on the same grid.

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

  • nfp: the number of field periods, from 1 to 6.

Before encoding, the poloidal index of the boundary is reordered as in training. It is shifted so that index 0 is the point of largest \(R\) of the cross section \(\phi = 0\), and reversed if \(Z\) decreases along \(\theta\) there; the same shift applies to every cross section. When two grid points tie for the largest \(R\), the first is taken. Ties are common on the 41-point grid: about 70% of the test configurations have one. Near a tie, the prediction is not smooth in the boundary: a tiny change of the boundary can switch the reordering and change the prediction by a few hundredths, occasionally more. To optimize the boundary with gradients, call the model with reorder_theta=False on a boundary built in this order, with \(\theta = 0\) at the outboard point of \(\phi = 0\) and \(Z\) increasing with \(\theta\) there; the order then stays fixed and the prediction is smooth in the boundary.

Load the model with load and predict with predict. Calling the model on PyTorch tensors gives the prediction with gradients, for example with respect to the boundary. Gradients are available in PyTorch only: the ONNX export gives the prediction without them.

Example

Predict the loss fraction of a test configuration:

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

path = models.download("loss_fraction", "BoSS-models/loss_fraction")
model = LossFractionModel.load(path)
with h5py.File(bb.list_files("BoSS", "confinement", "test")[0], "r") as f:
    record = bb.load_record(f, 0)
model.predict(record)
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("loss_fraction", path).

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

Returns:

the model, ready to predict.

Return type:

LossFractionModel

Raises:

ValueError – if the folder holds another model.

predict(data)#

Predict the loss fraction of one configuration or a batch of them.

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, pressure, toroidal_current, volume_avg_modB and nfp are read.

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, or nfp is out of range.

forward(boundary_xyz, pressure, toroidal_current, volume_avg_modB, nfp, reorder_theta=True)[source]#

Predict the loss fraction of a batch of configurations, with gradients.

This is predict on PyTorch tensors, without the input checks, and differentiable with respect to every float input. Gradients are available in PyTorch only, not in the ONNX export.

Parameters:
  • boundary_xyz (torch.Tensor) – boundary points [m], shape (n, 41 * 41 * 3) or (n, 41, 41, 3), as the field boundary_xyz.

  • pressure (torch.Tensor) – pressure profiles [Pa], shape (n, 15).

  • toroidal_current (torch.Tensor) – toroidal current profiles [A], shape (n, 15).

  • volume_avg_modB (torch.Tensor) – volume-averaged field strengths [T], shape (n,).

  • nfp (torch.Tensor) – numbers of field periods, shape (n,).

  • reorder_theta (bool) – whether to reorder the poloidal index of the boundary as in training (see the class docstring). With False, the boundary is used in its own order, which must then already be the training order.

Returns:

the loss fractions, shape (n,).

Return type:

torch.Tensor