Clone wiki

gkw / Documentation

Summary: Quick start documentation of the code

Manual and input documentation

Which version?

Repository (clone or download)

In the GKW development model there are two perpetual public branches of GKW (see git docs):

  • master: points to a recent, stable, and well tested version of the code, recommended for users. Master is the default branch for any new clone and points to incremental tagged versions available as direct downloads.
  • develop: latest working version, where all new work is merged, prior to becoming master. Recommended for developers. Must pass standard test cases, but changes often.

Compared to the tarball released with the original 2009 paper, recent GKW versions additionally contain:

  • Centrifugal effects
  • Magnetic Islands
  • Compressional magnetic field
  • Circular geometry (X. Lappillonne PoP 09)
  • Miller geometry
  • Improved collision operator (full momentum and energy conservation)
  • Global version
  • HDF5
  • Eigenvalue solver
  • Expanded documentation (including CHEASE)
  • Improved build with per-host config (inc. HECToR and HPC-FF)
  • Scripts (Matlab, PBS batches, tests, VTK)
  • OpenMP hybrid scheme
  • Better performance of both nonlinear and linear terms
  • Reduced memory footprint
  • Extra diagnostics
  • Full auto-parallelize over all directions
  • Improved restart handling
  • Improved ExB shear options
  • Minor bug fixes
  • And more, it is still evolving...

Most new features are documented in the manual (which you can also compile from the latex).

Tarball

The GKW download tarball is a clean and simplified version of the code that implements the features as described in the 2009 CPC paper. This version is rather outdated now, but should be sufficient for some simple runs. If you encounter a bug, or need collisions, we would suggest first that you try a recent tagged version available here, described above.

The downloaded GKW tarball has a very simple POSIX makefile which is well commented, follow the instructions there.

Compiling

This is the quick start documentation on how to compile the code -- see the manual for more comprehensive details.

For recent GKW from from the repository, the build process is configured on a per-host basis using configuration files in ./config. You should not need to edit the ./trunk/GNUmakefile or any file in ./src

Ideally you will have GNU make (available on most machines) and should run 'make' from the ./trunk directory (usually the top level one you check out).

The compilation is configured for Julich HPC-FF and HECToR already, and should compile directly (though you may need to load the correct modules).

To setup on a new machine, run

make config-file

then edit the commented example file created (and preferably remove most of it if checking it into the repository). You may need to provide the location of the MPI and FFTW3 libraries and the FFTW3 include files. You will need to provide the executable name of your Fortran compiler. Precision and optimizations flags will vary between compilers and may also need to be adjusted. You can also compare with other example files from ./config. The default values in the template are very basic, (without using MPI or FFTs), and may compile on many machines, but will only be useful for small linear runs.

The configuration file directories are based on the hostname, and the default settings for a machine are set in ./config/hostname/default.mk. If no folder matches, the first letters (at least 3) are used for a match (which works for most machines with many login nodes). Rename your folder to only the first matching letters of the hostname to use this feature. Note that everything set within ./config/global_defaults.mk is included into every configuration as default values. Per user and per compiler settings can also be configured, for details see the makefile 'GNUmakefile' and the full GKW manual. When ready to compile (or to test if the config works), it should be sufficient to just type

make

All switches can be passed directly to make, overriding the template file, but this is generally not recommended; to ensure that the code is built as you expect it to be, all changes should usually be made via the configuration files. Options such as switching the compiler, turning on debug flags, or using a different config file can be useful for debugging and testing code. Here are some examples:

make CONFIG=config/templates/template_INTEL.mk or make HOSTNAME=xaps * To attempt to build with an existing config files

make COMPILER=intel * To use a specific compiler file for the local machine

make DEBUG=on * To turn on debugging flags

make FC=mpif90 MPI=mpi FFTLIB=FFT_FFTW3 * To compile with MPI and FFTW

make REAL_PRECISION=real_precision_default * To compile in single precision

N.B. again, the passing of variables to make as shown above is potentially dangerous (and generally discouraged), and can lead to unexpected results if you are not careful; you should run make clean when rebuilding the code while passing variables to make. Read the makefiles and documentation.

The alternative simpler POSIX build process can still be used by editing ./src/makefile and building in ./src. If the machine does not have GNU make you will need to use this option.

Manual

The full GKW manual for the latest version of the code is available as a PDF. This manual is also in latex form with the source in the /doc folder:

cd /doc; make

The code reference generated automatically with Doxygen can also provide useful information on the code structure.

Updated