GPEC User Agreement¶
- Date
2016.03.18
GPEC development is funded by the US Department of Energy (DoE) through the Princeton Plasma Physics Laboratory (PPPL), and distribution is subject to DoE and PPPL requirements and restrictions.
The scientific results from the use of GPEC are intended for publication and sharing in the open scientific community.
In order to acquire access to the code sources and/or executables, the user must agree to the following:
The user will not rename, modify or redistribute the code, in whole or in part, to 3rd parties without consent of the authors, although the code may be imbedded unmodified and shared within a larger software project.
If modifications or improvements are needed, these will be developed in collaboration with the authors, so that they may be redistributed through the GPEC git versioning distributions to the benefit of all GPEC users.
The user will include the proper code name(s) and appropriate references in published results and presentations. The user will email a draft of any article/report/presentation/etc. using GPEC results to the authors prior to publishing.
New users are encouraged to send their agreement (pdf) to lead developers Jong-Kyu Park <jpark@pppl.gov> and Nikolas Logan <nlogan@pppl.gov> to initiate collaboration and obtain code support.
Installations¶
Public¶
Public installations are available at PPPL (portal.pppl.gov), GA (iris.gat.com), and NFRI (ukstar). Public installations are regularly cloned and kept up to date with the official releases.
The default gpec module at each institution tracks the latest release. Public installations of the “development” (beta) branch are also available if you should happen to need a new feature right away.
On any of the above clusters, use the module system to obtain the appropriate gpec environment. For example, use:
module avail
to see the available releases or simply,:
module load gpec
to load the current default. This will load the necessary compiler modules and add the appropriate directories to your path, such that you can simply call the executables (i.e. dcon, gpec, etc.).
Note
For PPPL Users
On the Princeton portal.pppl.gov computers, users must first execute module use /p/gpec/modules. It is recommended this be included in a .bashrc or similar file.
Loading the gpec module sets the $GPECHOME environment variable. This is helpful for find the path to source code, including such helpful things as the examples at $GPECHOME/docs/examples.
Modules for any past minor release versions installed are retained on the cluster, so you can always go back to re-run old work. The latest development branch is also available using,:
module load gpec/0.0
but this should be used with the understanding that many of it’s features are in beta testing and no guaranties are made for its stability. We ask that users always contact a developer if/when thinking of using a beta feature.
Personal¶
Personal copies of GPEC should be cloned from the Github repository, as the make process uses git commands assuming the installation is a git repository. The repository remains private for now, so only those with access will be able to install/update the package. Contact nlogan@pppl.gov for access.
The global makefile can be found in the install directory. This essentially enters and makes each individual subdirectory. Each subdirectory’s makefile references the DEFAULTS.inc file, also in install. Compiled using this install makefile, the executables will then be available in their individual subdirectories as well as collected in the bin directory.
Compiling should use intel compilers with the -qopenmp flag for parallel kinetic calculations in the gpec executable. An example make command might be,:
make FFLAGS="-qopenmp" 2>&1 | tee make.log
where the logging part is merely a useful suggestion. Appropriate compiler details for the major fusion clusters on which public installations are maintained is recorded in the $GPECHOME/install/DEFAULTS.inc file annotations.
Running using OMFIT¶
OMFIT is a framework for integrated modeling. It contains a GPEC module for preparing, running, and analyzing GPEC runs that is highly recommended for pure users (non-developers). OMFIT is the recommended way to run GPEC for new users. Public releases of OMFIT are available on most major fusion clusters, or it can be downloaded to your personal computer.
Using OMFIT guides users through a clean workflow, providing many powerful tools to facilitate the necessary preparation of inputs. It provides the interface, for example, with EFIT and profile fitting tools on many machines. It also enables users to submit GPEC jobs remotely, quickly visualize outputs, perform powerful python post-processing, and share projects with others.
A complete description of the OMFIT GPEC module can be found on the module documentation page and a thorough discussion of the workflow, inputs, outputs, and post-processing can be found in the corresponding google doc tutorial.
Manual Run Process¶
This section outlines the basic run process with reference to some of the most common input-output manipulation in GPEC runs. This is not meant to be a complete coverage of the many options and capabilities available to the user during this process. For a complete list of the input and output control variables please see the Inputs section.
Note
The use of $GPECHOME and executable commands such as dcon, gpec or pentrc assumes the appropriate environement variables have been set. The easiest way to do this is to use the module commands associated with one of the public installations.
To run GPEC, a user should first navigate to a directory in which they wish to run and write outputs. Once in the run-directory the user needs (at a minimum) the dcon, equil, vac, and gpec namelist files, which can be copied from $GPECHOME/input for example. The user can then follow these simple steps to complete a GPEC run:
Edit the dcon.in file
DCON will only run for a single toroidal mode number. Set the toroidal mode number for the entire run here using the crucial parameter nn. GPEC outputs for multiple toroidal mode numbers can be added together in the post-processing.
Edit the equil.in file
Specify the specific plasma shot of interest by setting the initial equilibrium file (ex: EFIT output g-file).
Set the range of normalized flux to be included in the calculation.
$GPECHOME/bin/dcon
This creates the euler.bin file, which provides a orthonormal basis of force balance states for GPEC.
Once this is created, you can various effects on this equilibrium by changing the 3D field input in gpec.in without having to run DCON again.
Edit the gpec.in file
Specify the 3D error field input file to be used in GPEC to perturb the 2D equilibrium.
This must match the psihigh variable used in equil.in.
Set the flags to specify the desired outputs.
$GPECHOME/bin/gpec
That’s it! Now go look at your output files.
Note that GPEC takes 2-3 inputs depending on whether kinetic effects are included. All calculations require a file containing the 2D plasma equilibrium, which is specified in equil.in prior to the DCON run. The most common equilibrium source is “efit”, in which case a two dimensional EFIT output g-file is used to specify the original axi-symmetric equilibrium. This equilibrium data and file format are widely used across multiple machines, but many alternative formats are also supported by GPEC. It is worth noting that significant differences between kinetic EFIT equilibria and the more simple non-kinetic EFITs has been noted. Obtaining the best 2D equilibrium data possible is encouraged for detailed calculations.
If kinetic effect are being included (via kin_flag in DCON or eny use of PENTRC), the kinetic profiles are also required. The OMFIT tutorial details the necessary profiles and ascii file format required. Whenever possible, it is encouraged to use profiles consistent with the 2D equilibrium (especially if it is a kinetic EFIT).
The final input is the 3D “error field” data. The input data can be again read from a file, and accepts a small number of select formats. These files must specify the external field on the surface of the GPEC plasma boundary defined by the psihigh variable in equil.in. This means that the data must be pre-processed using knowledge of both the non-axisymmetric external field (applied and/or intrinsic), the same equilibrium used in the GPEC corresponding calculation, and the exact magnetic surface used in that calculation. This requirement of coordination by the user is an easy pitfall for the un-wary. If utilizing this method, be sure that all work is consistent! To avoid the pitfalls associated with the above method a in-house Biot-Savart module that contains various coil geometries has been added as of GPEC 2.00. Using the coil_flag in gpec.in will result in the reading of yet another input file “coil.in” and the fields from the coils/currents specified therein will be calculated on the appropriate surface. Finally, the harmonic_flag allows users to apply a set amplitude harmonic on the boundary. All the 3D field input may be used (or not) in any combination, and the total boundary condition will be a sum of those used.
Manual Examples¶
The GPEC repository contains a number of examples intended to provide both consistent regression testing and a useful reseource for users looking to manually run straightforward examples. These examples are located in $GPECHOME/docs/examples, and contain all the necessary inputs and namelists to run the appropriate suite of codes. Ideal and kinetic examples use dcon, gpec, and pentrc. Resistive examples contain the necessary inputs to run dcon, rdcon, rmatch and gpec.
Example console commands and output are given below.