Leopoldo's KORC documentation

Introduction

The Kinetic Orbit Runaway electrons Code (KORC) is a full-orbit particle tracer that evolves relativistic electrons in both analytical and grid-based pre-computed electric and magnetic fields. KORC includes the effects of: the acceleration of the electrons due to the electric field, synchrotron radiation energy losses, and collisions with the background plasma containing high-Z impurities.

For details about the equations of motion of the relativistic electrons followed by KORC we refer the user to Carbajal et al. Phys. Plasmas 24, 042512 (2017) and Carbajal and del-Castillo-Negrete, Nuclear Fusion, submitted (2018). Also, for details about the KORC's synchrotron radiation synthetic diagnostic we refer the user to Carbajal and del-Castillo-Negrete, Plasma Phys. Controll. Fusion 59, 124001 (2017).

KORC is a modular Fortran 95 code that uses a hybrid MPI + open MP parallelization paradigm to exploit multi-core nodes systems, such as Cori and Edison NERSC systems (www.nersc.gov).

Installation

Getting started

To compile and run KORC you will need the following:

1. The HDF5 library for I/O.
2. The PSPLINES library for interpolating the pre-computed electric and magnetic fields as well as the plasma profiles.
3. The GNU compilers suite, or
4. The INTEL compilers suite.
5. The corresponding open MP library
6. The MPI or open MPI library
7. Git, for obtaining the latest version of KORC.

The HDF5 and PSPLINES libraries need to be installed BEFORE compiling KORC, or if these are already present in the system, they need to be loaded to your environment and their installation paths need to be added to the Makefile accordingly. We refer the user to the documentation of HDF5 and PSPLINES for the specifics about their installation.

If you are installing the HDF5 and PSPLINES libraries in your system, we recommend to perform a local installation. Then enter the absolute path of the folder containing the "lib" and "bin" folders of each library to the PSPLINE_INSTALL and HDF5_INSTALL variables of the Makefile.

Cloning and compiling KORC

To obtain the latest version of KORC you will need to clone the Github repository to the system where you want to run KORC. This can be done as follows:

1. Make sure you have all the needed external libraries and compilers in place.
2. Using the terminal of your system, cd to the directory where you want to save KORC.
3. Type the following in the terminal "git https://github.com/ORNL-Fusion/KORC.git". This will copy all the KORC files from the Github repository to your local system.
4. cd to the KORC-FO folder.
5. In the terminal type: "./compile.sh GNU" if you are using GNU compilers, or "./compile.sh INTEL" if you are using INTEL compilers.

Running KORC

If you are running KORC in a system that uses a resource manager such as TORQUE or SLURM, you will need to request the number of nodes and cores per node that you will need, this along with any other resources such as wall time, memory per node, etc. Decide the number of MPI processes (nmpi) and the number of open MP threads per MPI process (nomp) that you will use in your simulation. Then, on the terminal or in your batch file type the following: mpirun -np nmpi -x OMP_NUM_THREADS=nomp ./bin/KORC "full_path_to_input_file.korc" "full_path_to_the_outputs_folder" The above example assumes that you are using the open MPI wrapper mpirun to execute the binary "KORC" generated after compiling KORC. This wrapper can be replaced by any other wrapper that you might want to use. Notice that when using a different MPI wrapper the way to pass the number of MPI processes (nmpi) and the number of open MP threads per MPI (nomp) to KORC might vary.

Generating the KORC's input file

KORC uses...