boss_bench

Source code for boss_bench.models.loss_fraction

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

import numpy as np
import torch
from torch import nn

from ._common import as_batch, load_trained

FIELDS = ("boundary_xyz", "pressure", "toroidal_current", "volume_avg_modB", "nfp")
N_GRID = 41  # boundary points per angle
N_PROFILE = 15  # radial points of the profiles
N_NFP = 12  # rows of the nfp embedding, for nfp from 1
NFP_MAX = 6  # the training data covers nfp from 1 to 6, with one configuration of nfp 12
BATCH_SIZE = 256  # configurations evaluated at once


[docs] class LossFractionModel(nn.Module): r"""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 :math:`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 :math:`(\phi, \theta, xyz)`: Cartesian points of the boundary surface on 41 toroidal angles :math:`\phi` uniformly spaced in :math:`[0, 2\pi / n_\text{fp})` and 41 poloidal angles :math:`\theta` uniformly spaced in :math:`[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 :math:`R = \sqrt{x^2 + y^2}` and :math:`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 :math:`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 :math:`R` of the cross section :math:`\phi = 0`, and reversed if :math:`Z` decreases along :math:`\theta` there; the same shift applies to every cross section. When two grid points tie for the largest :math:`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 :math:`\theta = 0` at the outboard point of :math:`\phi = 0` and :math:`Z` increasing with :math:`\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) """ def __init__(self): super().__init__() conv_channels, surf_dim, profile_dim, scalar_dim, hidden_dim = (32, 64, 128, 256, 512), 512, 32, 16, 2048 self.surface_encoder = _PeriodicConvEncoder(2, conv_channels, surf_dim) self.pressure_encoder = nn.Linear(N_PROFILE, profile_dim) self.current_encoder = nn.Linear(N_PROFILE, profile_dim) self.modB_encoder = nn.Linear(1, scalar_dim) self.nfp_embedding = nn.Embedding(N_NFP, scalar_dim) self.mlp = nn.Sequential( nn.Linear(surf_dim + 2 * profile_dim + 2 * scalar_dim, hidden_dim), nn.GELU(), nn.Linear(hidden_dim, hidden_dim), nn.GELU(), nn.Linear(hidden_dim, hidden_dim), nn.GELU(), nn.Linear(hidden_dim, 1), nn.Sigmoid(), ) # each input is scaled by (x - low) / (high - low), with its range over the training set for name in ("R", "Z", "pressure", "current", "modB"): self.register_buffer(f"{name}_range", torch.tensor([0.0, 1.0], dtype=torch.float64))
[docs] @classmethod def load(cls, path, device="cpu"): """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. Args: 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: LossFractionModel: the model, ready to predict. Raises: ValueError: if the folder holds another model. """ return load_trained(cls(), "loss_fraction", path, device)
@torch.no_grad() def predict(self, data): """Predict the loss fraction of one configuration or a batch of them. Args: 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: float or np.ndarray: the loss fraction, shape ``(n,)`` for a batch. Raises: KeyError: if a field is missing from ``data``. ValueError: if a field contains NaN or inf, or ``nfp`` is out of range. """ batch, single = as_batch(data, FIELDS) if np.any((batch["nfp"] < 1) | (batch["nfp"] > NFP_MAX)): raise ValueError(f"nfp must be between 1 and {NFP_MAX}") device = self.R_range.device out = [] for a in range(0, len(batch["nfp"]), BATCH_SIZE): rows = {name: torch.as_tensor(x[a:a + BATCH_SIZE], device=device) for name, x in batch.items()} out.append(self(**rows).cpu().numpy()) out = np.concatenate(out).astype(float) return float(out[0]) if single else out
[docs] def forward(self, boundary_xyz, pressure, toroidal_current, volume_avg_modB, nfp, reorder_theta=True): """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. Args: 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: torch.Tensor: the loss fractions, shape ``(n,)``. """ # in float64, so that the reordering does not depend on the input precision xyz = boundary_xyz.double().reshape(-1, N_GRID, N_GRID, 3) if reorder_theta: xyz = _reorder_theta(xyz) R = torch.sqrt(xyz[..., 0] ** 2 + xyz[..., 1] ** 2) surface = torch.stack([_scale(R, self.R_range), _scale(xyz[..., 2], self.Z_range)], dim=1) encodings = [ # in the order of training self.current_encoder(_scale(toroidal_current, self.current_range).float()), self.nfp_embedding(nfp.long() - 1), self.pressure_encoder(_scale(pressure, self.pressure_range).float()), self.surface_encoder(surface.float()), self.modB_encoder(_scale(volume_avg_modB, self.modB_range).float()[:, None]), ] return self.mlp(torch.cat(encodings, dim=-1))[:, 0]
class _PeriodicConvEncoder(nn.Module): """Encode an image periodic in both axes by stride-2 convolutions and a global average. Args: in_channels (int): channels of the image. conv_channels (tuple of int): output channels of each convolution. out_dim (int): width of the encoding. """ def __init__(self, in_channels, conv_channels, out_dim): super().__init__() blocks = [] for c in conv_channels: blocks += [nn.Conv2d(in_channels, c, 3, stride=2, padding=1, padding_mode="circular"), nn.BatchNorm2d(c), nn.GELU()] in_channels = c self.conv = nn.Sequential(*blocks) self.proj = nn.Linear(in_channels, out_dim) def forward(self, x): """Encode images of shape ``(n, in_channels, h, w)`` to shape ``(n, out_dim)``.""" return self.proj(self.conv(x).mean(dim=(-2, -1))) def _reorder_theta(xyz): r"""Shift the poloidal angle of boundaries to start outboard and increase with :math:`Z`. The same shift of the poloidal index is applied to every cross section. It puts the point of largest :math:`R` of the cross section :math:`\phi = 0` at index 0, then, if :math:`Z` decreases along :math:`\theta` there, reverses the direction of :math:`\theta`. Args: xyz (torch.Tensor): boundary points, shape ``(n, n_phi, n_theta, 3)``. Returns: torch.Tensor: the reordered points, the same shape. """ n_theta = xyz.shape[2] j = torch.arange(n_theta, device=xyz.device) shift = torch.argmax(torch.sqrt(xyz[:, 0, :, 0] ** 2 + xyz[:, 0, :, 1] ** 2), dim=1)[:, None] z = xyz[:, 0, :, 2] after = torch.gather(z, 1, (shift + 1) % n_theta)[:, 0] before = torch.gather(z, 1, (shift - 1) % n_theta)[:, 0] index = torch.where((after < before)[:, None], -j, j) # -j reverses the direction index = (index + shift) % n_theta return torch.gather(xyz, 2, index[:, None, :, None].expand_as(xyz)) def _scale(x, value_range): """Scale x by (x - low) / (high - low), for value_range = (low, high).""" return (x - value_range[0]) / (value_range[1] - value_range[0])