Enabling the diagnostic

In the diag section of the input file, the PSZS diagnostic can be enabled and configured. Some recommended settings might be:

pszs_freq = 100
nsel_pszs = 'offline'
pszs_ntam = 32
pszs_nke = 16
pszs_nmu = 16

pszs_freq controls how frequently (every N timesteps) the PSZS diagnostic should be performed. Due to the nature of the PSZS in constants of motion, the diagnostic is expected not to be needed more frequently than the timescales set by (phase-space) transport.
nsel_pszs controls if the diagnostic is disabled (off), run online (online), or run offline (offline). In the case that it's run "offline" (recommended), only spline coefficients will be stored during the simulation, with post-processing required after the simulation (see below for more details).
pszs_ntam sets the number of points in the TAM (toroidal angular momentum) dimension.
pszs_nke sets the number of points in the KE (kinetic energy) dimension.
pszs_nmu sets the number of points in the mu (magnetic moment) dimension.

Note: During GPU simulations, the PSZS cannot be calculated on the GPU. Therefore the particle data must be copied from the GPU to the CPU before performing the PSZS deposition. This is slower, but if the pszs_freq is not to high, the cost is not too large. In such a case, OpenMP threads can be used to speed up the deposition on the CPU. (This feature is not yet merged into the master branch).

Run the code

When running the code with the PSZS diagnostic, there is some initial diagnostic information output in the standard output (orb5.out), initially when setting up the simulation, but also every time the PSZS data is computed. Running the diagnostic creates an additional output hdf5 file, matrix.h5.

This file contains the raw output from the code for the PSZS, and (in the case of the offline PSZS) everything needed for the post-processing calculation. The quantities stored in the output file depend on the value of nsel_pszs_type (default f0): we always have f = f0 + w, and we additionally have either f0 or w (default: f0).

Shown below is an example of the outputs for nsel_pszs = "offline", nsel_pszs_type = "f0", pszs_ntam = 16, pszs_nmu = 8, pszs_nke = 8:

$ h5ls -r matrix.h5/deuterium
/bsf03d                  Group
/bsf03d/data             Dataset {6/Inf, 1800}
/bsf03d/time             Dataset {6/Inf}
/bsf3d                   Group
/bsf3d/data              Dataset {6/Inf, 1800}
/bsf3d/time              Dataset {6/Inf}
/grids                   Group
/grids/b                 Dataset {17}
/grids/bstar             Dataset {17}
/grids/jpsi              Dataset {17}
/grids/js                Dataset {17}
/grids/ke                Dataset {9}
/grids/mu                Dataset {9}
/grids/tam               Dataset {17}
/matrices                Group
/size                    Group

Note: the names bs/f0/3d and bs/f/3d (slashes added for emphasis), which are arrays of length 1800=(17+1)*(9+1)*(9+1) per timepoint, are the /BS/plines coefficients of the RHSs corresponding to the 3d expressions of f0 and f respectively.

Shown below is an example of the outputs for nsel_pszs = "online", nsel_pszs_type = "f0", pszs_ntam = 16, pszs_nmu = 8, pszs_nke = 8:

$ h5ls -r matrix.h5/deuterium
/f03d                    Group
/f03d/coord1             Dataset {17}
/f03d/coord2             Dataset {9}
/f03d/coord3             Dataset {9}
/f03d/data               Dataset {6/Inf, 9, 9, 17}
/f03d/time               Dataset {6/Inf}
/f3d                     Group
/f3d/coord1              Dataset {17}
/f3d/coord2              Dataset {9}
/f3d/coord3              Dataset {9}
/f3d/data                Dataset {6/Inf, 9, 9, 17}
/f3d/time                Dataset {6/Inf}
/grids                   Group
/grids/b                 Dataset {17}
/grids/bstar             Dataset {17}
/grids/jpsi              Dataset {17}
/grids/js                Dataset {17}
/grids/ke                Dataset {9}
/grids/mu                Dataset {9}
/grids/tam               Dataset {17}
/matrices                Group
/size                    Group

Here we see that the deuterium/f3d and deuterium/f03d diagnostic objects contain /data, /time, /coord{1,2,3} which can be read and plotted just like standard ORB5 diagnostics.

Postprocessing (the offline version)

In the case of the "offline" version, we still have to perform another step. For this, we build an additional binary file, make pszs_offline, which builds bin/pszs_offline by symmetry with bin/orb5.

This additional binary can then be run after the simulation, and will then produce the same type of output as-produced by the "online" version of the code.

The pszs_offline file requires an input file named input_pszs3d, which requires the following:

&basic
  nspecies = 1
  species_name = "deuterium"
  label1 = "tam"
  label2 = "ke"
  label3 = "mu"
/

Running this file (only 1 MPI rank, but can use OpenMP threads) creates a file matrix_out.h5 which contains the "full" PSZS data

$ h5ls -r matrix_out.h5/deuterium
/f03d                    Group
/f03d/coord1             Dataset {17}
/f03d/coord2             Dataset {9}
/f03d/coord3             Dataset {9}
/f03d/df0d13d            Dataset {0/Inf, 9, 9, 17}
/f03d/df0d23d            Dataset {0/Inf, 9, 9, 17}
/f03d/df0d33d            Dataset {0/Inf, 9, 9, 17}
/f03d/f03d               Dataset {6/Inf, 9, 9, 17}
/f03d/time               Dataset {6/Inf}
/f3d                     Group
/f3d/coord1              Dataset {17}
/f3d/coord2              Dataset {9}
/f3d/coord3              Dataset {9}
/f3d/dfd13d              Dataset {0/Inf, 9, 9, 17}
/f3d/dfd23d              Dataset {0/Inf, 9, 9, 17}
/f3d/dfd33d              Dataset {0/Inf, 9, 9, 17}
/f3d/f3d                 Dataset {6/Inf, 9, 9, 17}
/f3d/time                Dataset {6/Inf}

Now we would be able to plot the 3D data from the PSZS (now stored in matrix_out.h5) in the same was as we can do for the online version.

Note: If we were to later continue the simulation with a restart, we could later run pszs_offline and it would only append the steps which were not already calculated. If zero steps are to be calculated, it will not spend time assembling and factorizing the matrix. The pszs_offline code should not be run while an ORB5 simulation is running.; Here (in contrast to the online version) we also create (empty) groups for the 3 derivatives (e.g. d f0 / d TAM) etc. These can be enabled in the input_pszs3d file, but are disabled by default.

Table of Contents

Enabling the diagnostic

Run the code

Postprocessing (the offline version)