boss_bench

boss_bench.heat_flux

boss_bench.heat_flux#

Heat-flux benchmark: predict where lost alpha particles strike the plasma boundary.

boss_bench.heat_flux.lost_particles(record, s0)[source]#

Compute the strike points (zeta, theta) and energies energy of the lost particles born on one surface.

For the \(k\) lost particles born on s0, zeta and theta are the Boozer angles where they strike the boundary, in \([0, 2\pi)\) [rad], and energy is their energy [MeV], each of shape (k,). A particle lost at time \(t_\text{loss}\) carries the energy \(E = 3.5\,\text{MeV}\; e^{-2 t_\text{loss} / t_\text{slowing}}\), where the slowing-down time is approximated by \(t_\text{slowing} \approx t_\text{max} = 0.1\) s. n_launched is the number of particles born on s0.

Parameters:

  • record (dict) – the configuration’s fields from data.load_record, including confinement_time, t_max, s_init, zeta_end and theta_end.

  • s0 (float) – the birth surface.

Returns:

zeta, theta, energy, n_launched, the strike points, their energies, and the number of particles launched.

Return type:

tuple

Raises:

ValueError – if the confinement times or the strike points contain NaN or inf.

boss_bench.heat_flux.binned_heat_flux(zeta, theta, energy, n_launched, record, resolution=32)[source]#

Compute the heat flux on the plasma boundary [MeV/m² per launched particle], binned over one field period.

The strike points of all \(n_\text{fp}\) field periods are first folded into one. With \(m\) = resolution, \(Q_{ij}\) is the heat flux in the bin \([\zeta_i, \zeta_{i+1}) \times [\theta_j, \theta_{j+1})\), where \(\zeta_i = 2\pi i / (m\, n_\text{fp})\) and \(\theta_j = 2\pi j / m\) for \(i, j = 0, \dots, m - 1\):

\[Q_{ij} = \frac{1}{N\, n_\text{fp}\, A_{ij}} \sum_k E_k,\]

where the sum runs over the strike points in the bin, with energies \(E_k\), \(A_{ij}\) is the boundary area of the bin, and \(N\) is the number of particles launched.

To estimate the absolute heat flux per unit time [W/m²], multiply \(Q\) by a birth rate [1/s] and by \(1.602 \times 10^{-13}\) J/MeV.

Parameters:

  • zeta (np.ndarray) – Boozer toroidal angles of the strike points [rad], shape (k,).

  • theta (np.ndarray) – Boozer poloidal angles of the strike points [rad], shape (k,).

  • energy (np.ndarray) – energies of the strike points [MeV], shape (k,).

  • n_launched (int) – the number of particles launched.

  • record (dict) – the configuration’s fields from data.load_record, including R_boozer, Z_boozer, nu_boozer, s1d and nfp.

  • resolution (int) – the number of bins per angle.

Returns:

Q, the heat flux \(Q_{ij}\) [MeV/m² per launched particle], shape (resolution, resolution).

Return type:

np.ndarray

Raises:

ValueError – if an input contains NaN or inf.

boss_bench.heat_flux.heat_flux_metrics(paths, predictions)[source]#

Score heat-flux predictions with the metrics of the paper.

A sample is the point cloud of strike points of the lost particles born on one surface s0 of one configuration, so each configuration gives three samples, one per birth surface. Each predicted sample is compared with the true one by the heat-flux error on 16 × 16 and 32 × 32 grids (heat_flux_error), the energy distance between the two point clouds (energy_distance), and the absolute error of the loss fraction.

Over all samples, the function reports the median energy distance ED_median (over samples with at least 10 lost particles); the median and mean heat-flux errors HF_16_median, HF_16_mean, HF_32_median and HF_32_mean; the median and mean absolute error of the loss fraction loss_fraction_median_abs_error and loss_fraction_mean_abs_error; and the number of samples scored n_samples. Only the fields it needs are read from disk.

Parameters:

  • paths (list of str) – the confinement files holding the predicted samples, usually data.list_files(data_dir, "confinement", "test").

  • predictions (dict) – maps (uuid, s0) of each sample to the tuple (zeta, theta, energy, loss_fraction): the Boozer angles [rad] and energies [MeV] of any number of predicted strike points, arrays of shape (k,), and the predicted loss fraction, a float.

Returns:

ED_median, HF_16_median, HF_16_mean, HF_32_median, HF_32_mean, loss_fraction_median_abs_error, loss_fraction_mean_abs_error, n_samples, the metrics above and the number of samples scored.

Return type:

dict

Raises:

  • KeyError – if a predicted sample is not in the files.

  • ValueError – if a prediction contains NaN or inf, or has no strike points for a sample with at least 10 lost particles.

boss_bench.heat_flux.heat_flux_error(prediction, record, s0, resolution=32)[source]#

Compute the heat-flux error of a prediction for one sample.

With \(Q\) and \(\hat Q\) the true and predicted heat flux from binned_heat_flux on \(m \times m\) bins of areas \(A_b\), relative to a uniform loss of every particle at the birth energy \(E_\alpha = 3.5\) MeV over the boundary area \(S\),

\[\mathrm{HF}_m^2 = \frac{n_\text{fp} \sum_b A_b \left(\hat Q_b - Q_b\right)^2}{E_\alpha^2 / S}.\]

The predicted strike points are scaled so that their total is the predicted loss fraction.

Parameters:

  • prediction (tuple) – the tuple (zeta, theta, energy, loss_fraction): the Boozer angles [rad] and energies [MeV] of any number of predicted strike points, arrays of shape (k,), and the predicted loss fraction, a float.

  • record (dict) – the configuration’s fields from data.load_record on a confinement file.

  • s0 (float) – the birth surface.

  • resolution (int) – the number of bins per angle, \(m\).

Returns:

\(\mathrm{HF}_m\).

Return type:

float

Raises:

ValueError – if a prediction contains NaN or inf.

boss_bench.heat_flux.energy_distance(prediction, record, s0)[source]#

Compute the energy distance between predicted and true strike points, for one sample.

With \(X\) and \(Y\) the predicted and true strike points as positions on the boundary,

\[\mathrm{ED} = \left| \frac{2\,\mathbb{E}\|X - Y\| - \mathbb{E}\|X - X'\| - \mathbb{E}\|Y - Y'\|}{\mathbb{E}\|Y - Y'\|} \right|^{1/2},\]

where the self terms average over pairs of distinct points. It is defined for samples with at least 10 lost particles.

Parameters:

  • prediction (tuple) – (zeta, theta), the Boozer angles [rad] of any number of predicted strike points, arrays of shape (k,). Further entries, such as the energies and loss fraction of the tuple passed to heat_flux_error, are ignored.

  • record (dict) – the configuration’s fields from data.load_record on a confinement file.

  • s0 (float) – the birth surface.

Returns:

\(\mathrm{ED}\), or NaN if fewer than 10 particles born on s0 are lost.

Return type:

float

Raises:

ValueError – if a prediction contains NaN or inf, or has no strike points while at least 10 particles are lost.