Wiki

GS2: A Guide for Beginners

Introduction

So, you've never run GS2 before? This is the place to start. On this page we cover the basics of how to get GS2 installed and running.

There are two different sorts of complexity in scientific computing; the complexity of the physical problem in hand, and the additional complexity brought about by the realities of software, including that of compiling, running and processing results. Most of the complexity of GS2 derives from the former; hard work by many people means that the second is much less of an issue. Now since the physical problem in hand, that of kinetic turbulence in various magnetic geometries, is incredibly complicated, this still means that to fully understand and use all the power of GS2 is a fiendishly tortuous undertaking. But do not be discouraged. In simple physical situations, GS2 is simple to use.

Installing GS2

Downloading GS2

There are no binary releases of GS2. Consequently, it is necessary to install it from source. An official release of GS2 is being prepared for March 2015: see here for updates and discussion. In the meantime, the best thing is to download the release candidate, which contains all the latest fixes and physics. Install Subversion if you don't already have it, and then issue this command in a suitable folder:

svnco``\ ```https://svn.code.sf.net/p/gyrokinetics/code/gs2/tags/6.0/release_candidate <https://svn.code.sf.net/p/gyrokinetics/code/gs2/tags/6.0/release_candidate>`__

Note: You may also use http rather than https (for example if required by local firewall policy) for checkout (co).

Building GS2

Dependencies

GS2 has the following dependencies, which should be installed before building. On most HPC systems all of these will be installed and you can skip this step.

FFTW2 or FFTW3 a popular open source package for performing fast Fourier transforms. Required for non-linear runs, possible to compile without these for linear-only simulations, though not recommended.
NetCDF a set of software libraries for data storage and retrieval. NB: as of April 2010 GS2 will not build from a NetCDF library that was built with shared libraries enabled. If you encounter problems with the NetCDF module when building GS2, try building a version of NetCDF without ``--enable-shared``. It is recommended that you use NetCDF-4, though version 3 should still work.
HDF - another set of libraries, needed if you want to install the parallel version of NetCDF.

If you are building GS2 on your own computer you will also need to install, if you intend to run it on more than one processor, an MPI implementation, such as open-mpi.

The Really Easy Way

If you are really lucky, your system will have been enabled for the new automated build system (see Build Scripts for more info). To find out if it has, go into the folder you have just downloaded and execute this command:

$./build_gs2-ols

This will show you a list of enabled systems. If your system is listed, all you have to do is execute:

$./build_gs2-s<yoursystem>

You can now move on to the section on running GS2.

If not, firstly, do ask us to enable your system via a support request. We cannot guarantee to respond immediately, but we will get back to you as soon as possible.

Secondly, your system may still be supported using the older non-automated build system. Carry on reading...

Makefiles

To use the older way of building GS2, go into the trunk folder of the source code and look at the folder Makefiles ~/trunk>ls Makefiles

Makefile.absoftMakefile.DARWINMakefile.hectorMakefile.kestrelMakefile.RS6000Makefile.andesMakefile.davinciMakefile.hector_feMakefile.krakenMakefile.simpleMakefile.bassMakefile.dawsonMakefile.hector_fftw3Makefile.laheyMakefile.T3E
Makefile.bassiMakefile.discoveryMakefile.hoffman2Makefile.mpixlMakefile.tungsten
Makefile.BGPMakefile.franklinMakefile.homerMakefile.mrfMakefile.wave
Makefile.bigbenMakefile.fujMakefile.hopperMakefile.nagMakefile.xl
Makefile.BLUEGENEMakefile.G5Makefile.intelMakefile.newhydraMakefile.XT4
Makefile.columbusMakefile.gcc-intelMakefile.istMakefile.opensuseMakefile.XT5
Makefile.compaqMakefile.gnu-g95Makefile.jacquardMakefile.pathscale
Makefile.crayMakefile.gnu-gccMakefile.jaguarMakefile.pgi
Makefile.culhamMakefile.gnu-gfortranMakefile.juropaMakefile.ranger

If a Makefile already exists for the system you are on then you are done: skip to the next step.

If not, it is usually pretty easy to make a new one for the system you are on starting with an existing Makefile. There are two kinds of Makefiles, Makefiles for different systems and Makefiles for different compilers. The Makefiles for different systems are usually fairly simple. They might specify which compiler is being used:

COMPILER=intel

includeMakefile.$(COMPILER)

and specify where to find the libraries, e.g:

FFT_LIB=-L$$FFTW_ROOT/lib-ldrfftw-ldfftw

Try to find a makefile for a system that is similar to yours and edit it.

Makefiles for different compilers are beyond the scope of this introduction.

Environment

You now need to correctly set up your environment for GS2. First you need to specify which system you are on:

~/trunk>exportGK_SYSTEM=yoursystemname

You may wish to add this command to your login script (e.g. .bashrc).

If you are on a system, for example Ranger, which uses modules to set up the build environment, you will need to load the requisite modules. e.g.

~/trunk>moduleloadintel
~/trunk>moduleloadfftw2
~/trunk>moduleloadnetcdf
~/trunk>moduleloadmvapich2

Building

You are now ready to build GS2. Type

make-IMakefiles

cross your fingers, and make yourself a cup of coffee.

Running GS2

Making an Input File

A GS2 input file is a series of namelists in which various parameters are specified:

&namelist
``        parameter1=value1 ! Fortran style comments are allowed``
``        parameter2=value2``
`` /``

Documentation for the various parameters is available here: GS2 Input Parameters. However, they are so many and varied that making your own input file from scratch is not advised if you're just starting out. It's much better to take an existing input file and tweak it to suit your own needs. A list of example input files is here: Example Input Files.

Take the input file, edit it as you need and save it as run_name.in, where run_name is a name you have chosen for this simulation.

Running GS2

the command for running GS2 is simply:

gs2run_name.in

This will run GS2 on one processor, which, for all but the lowest resolutions, will take a very long time. If you are on your own system with an MPI implementation installed, you'll probably want to issue a command like

mpirun-n<nprocs>gs2run_name.in

where nprocs is the number of processors. If you are running on an HPC system, you will need to consult their own manuals.

Analysing the Results

GS2 outputs a myriad collection of data and files. These are all dealt with on this page: GS2 Results and Diagnostics.

A Warning

We finish with a warning, which cannot be taken too seriously:

Just because GS2 outputs a result, it does not follow that the result is correct

There are 1001 tweaks and adjustments that can be made to the resolution, the geometry, the physical parameters and the diagnostics which may affect the final result. Like Charles Babbage's adding machine, if you put wrong numbers in, if the resolution is insufficient, you will not get right answers out. A rough guide to checking whether you have sufficient resolution is provided on this page: GS2 Results and Diagnostics. Please note that, unlike typical explicit algorithms, the implicit algorithm can return results which look reasonable even when the time step is too large. As such it is important to also check convergence in time step (usually only a linear problem).

There is also a program, ingen, which is built with GS2, which will check your input file for inconsistencies. Although documentation for this is currently sparse, try running

~/trunk>ingenrun_name.in

If you're just starting out using GS2, try to find some well-known result that you can reproduce, before going on to explore new territory.

Good luck!