GORILLA

Guiding-center ORbit Integration with Local Linearization Approach

GORILLA computes guiding-center orbits for charged particles of given mass, charge and energy in toroidal fusion devices with three-dimensional field geometry. This guiding-center orbit code is designed to be used in scientific plasma physics simulations in the field of magnetic confinement fusion.

Summary

The guiding-center orbits are traced via a quasi-geometric integration method described in Ref. [1]. There, high order interpolation of electromagnetic fields in space is replaced by a special linear interpolation, leading to locally linear Hamiltonian equations of motion with piecewise constant coefficients. The underlying formulation treats the motion in the piecewise linear fields exactly. This further leads to conservation of total energy, magnetic moment and phase space volume. Furthermore, the approach reduces computational effort and noise sensitivity. Guiding-center orbits are computed without taking collisions into account.

Due to its formulation in general curvilinear coordinates, GORILLA is not limited by the field topology. That means that the computation domain of GORILLA covers both the closed field line region (i.e. the plasma core) and the open field line region (i.e. the scrape-off layer).

For various simulations in magnetic confinement fusion, direct modeling of guiding-center particle orbits is utilized, e.g. global kinetic computations of quasi-steady plasma parameters or fast alpha particle loss estimation for stellarator optimization. In such complex simulations a simple interface for the guiding-center orbit integration part is needed. Namely, the initial condition in five-dimensional phase space is provided (i.e. guiding-center position, parallel and perpendicular velocity) and the main interest is in the condition after a prescribed time step while the integration process itself is irrelevant. Such a pure “orbit time step routine” acting as an interface with a plasma physics simulation is provided (orbit_timestep_gorilla). However, the integration process itself can be of high interest as well, thus, a program allowing the detailed analysis of guiding-center orbits, the time evolution of their respective invariants of motion and Poincaré plots is at disposal as well (gorilla_plot). Both applications are realized for demonstration in the program (test_gorilla_main).

License

The code is free to use and modify under the MIT License and links to Runge-Kutta-Fehlberg routines in SRC/contrib/rkf45.f90 from https://people.sc.fsu.edu/~jburkardt/f_src/rkf45/rkf45.html under the GNU LGPL License.

Magnetic field input

The magnetic field can be provided by magnetohydrodynamics (MHD) equilibria with nested magnetic flux surfaces either in 2D (e.g. EFIT) or in 3D (e.g. VMEC). Supported equilibria are in the g-file or NetCDF format, respectively. For both equilibria formats, test files for the limited purpose of computing guiding-center orbits are provided. The g-file test equilibrium (g_file_for_test) was provided by the ASDEX Upgrade Team for testing purposes and corresponds to the axisymmetric tokamak field configuration of ASDEX Upgrade (shot 26884 at 4300 ms) described in Ref. [3]. The VMEC NetCDF test equlibrium (netcdf_file_for_test.nc) was provided by Michael Drevlak for testing purposes and corresponds to the stellarator field configuration described in Ref. [4], namely, a quasi-isodynamic reactor-scale device with five toroidal field periods and a major radius of 25 m. The g-file test equilibrium in WEST geometry (g_file_for_test_WEST) was provided by the SOLEDGE3X-EIRENE Team for testing purposes and corresponds to the axisymmetric tokamak field configuration of WEST for the code SOLEDGE3X-EIRENE (shot 54903 at 8 s) described in Ref. [5].

Documentation

A detailed description of the working principle of GORILLA can be found in DOCUMENTATION/GORILLA_DOC.pdf. The following supplemental material is available in DOCUMENTATION/SUPPLEMENTAL_MATERIAL:

• arXiv preprint of Ref. [1]
• Master's thesis of M. Eder (preliminary work with some detailed explanations referenced in GORILLA_DOC.pdf)
• Master's thesis of L. Bauer (preliminary work with some detailed explanations referenced in GORILLA_DOC.pdf)
• Bachelor's thesis of D. Forstenlechner (unit testing with pFUnit)

Building

GORILLA can be built with make or cmake.

Supported compilers

• GNU Fortan

Required libraries

• NetCDF
• LAPACK/BLAS

To install requirements on Ubuntu Linux use

sudo apt install wget unzip git gfortran make cmake liblapack-dev libnetcdff-dev

To install requirements on macOS, install Homebrew, then

brew install wget unzip git gcc make cmake netcdf netcdf-fortran libomp

Additional tools

• pFUnit
• lcov

To install pFUnit, follow the instructions on the linked github project page.

To install lcov on Ubuntu Linux use

sudo apt install lcov

To install lcov on macOS use

brew install lcov

Include external library

N. Flocke, “Algorithm 954: An Accurate and Efficient Cubic and Quartic Equation Solver for Physical Applications” https://doi.org/10.1145/2699468

• Download supplemental material 954.zip from above webpage.

wget -O 954.zip "https://dl.acm.org/action/downloadSupplement?doi=10.1145%2F2699468&file=954.zip&download=true"

• Copy 954/F90/Src/Polynomial234RootSolvers.f90 to GORILLA/SRC/contrib/ and overwrite existing file. (Existing file with identical name is a placeholder which is necessary for compilation.)

unzip 954.zip
cp 954/F90/Src/Polynomial234RootSolvers.f90 SRC/contrib/

• GORILLA can be run without this external library. The computation of guiding-center orbits is then limited to the numerical Runge-Kutta option of GORILLA.

Building with make

cd /path/to/GORILLA
make

This will produce test_gorilla_main.x required to run the code. To specify the location of NetCDF includes and libraries, one has to set the NCINC and NCLIB variable during make.

Building with cmake

To build GORILLA with cmake, use build.sh.

cd /path/to/GORILLA
./build.sh

This will produce test_gorilla_main.x in the folder BUILD/SRC/ required to run the code.

To get additional tests and code coverage, build GORILLA with build_coverage.sh. This requires the additional tools and a correct set PFUNIT_DIR. See the pFUnit github project page for additional information.

Usage

GORILLA currently runs on a single node with OpenMP shared memory parallelization with one particle per thread and background fields residing in main memory.

The main executable is test_gorilla_main.x. As an input it takes ....

... the following input files which can be found in the folder INPUT/

• tetra_grid.inp (Input file for settings of the tetrahedronal grid used in GORLLA)
• gorilla.inp (Input file for settings of GORILLA)
• gorilla_plot.inp (Input file for the program for the analysis of guiding-center orbits)
• field_divB0.inp (Input file for loading g-file equilibria - Do not change this file.)
• preload_for_SYNCH.inp (Input file for splining magnetic field data of g-file equilibria - Do not change this file.)

... and the MHD equilibrium files which can be found in the folder MHD_EQUILIBRIA/

• netcdf_file_for_test.nc: VMEC NetCDF equlibrium (File name can be specified in tetra_grid.inp.)
• g_file_for_test or g_file_for_test_WEST: g-file equilibrium (File name can be specified in tetra_grid.inp.)

For compability with WEST geometry of SOLEDGE3X-EIRENE, additional input files describing the original 2D mesh are needed. Those can be found in MHD_EQUILIBRIA/MESH_SOLEDGE3X_EIRENE

• knots_for_test.dat: coordinates ($R$, $Z$) of the vertices making up the 2D grid (File name can be specified in tetra_grid.inp.)
• triangles_for_test.dat: association of above mentioned vertices to triangles (triples of vertices) covering the 2D plane (File name can be specified in tetra_grid.inp.)

To produce these files (including the g-file equilibrium) oneself from files provided by SOLEDGE3X-EIRENE, a set of prepocessing MATLAB scripts are at disposal in REPROCESSING/SOLEDGE3X_EIRENE/MESH and REPROCESSING/SOLEDGE3X_EIRENE/MHD_EQUILIBRIUM respectively.

Tutorial

A tutorial for running GORILLA and plotting Poincaré cuts, full guiding-center orbits and the appropriate time evolution of invariants of motion is realized redundantly in both MATLAB and Python.

Step-by-step plotting tutorial in MATLAB

• MATLAB Live Script with the name plotting_tutorial.mlx is at disposal in MATLAB as a step-by-step tutorial for all plotting features of GORILLA.

Step-by-step plotting tutorial in Python

• Jupyter Notebook with the name plotting_tutorial.ipynb is at disposal in PYTHON as a step-by-step tutorial for all plotting features of GORILLA.

For the Jupyter Notebook as well as the Python scripts