GS2: A Guide for Beginners
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.
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:
Note: You may also use http rather than https (for example if required by local firewall policy) for checkout (co).
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 -o ls
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...
To use the older way of building GS2, go into the trunk folder of the source code and look at the folder Makefiles
Makefile.absoft Makefile.DARWIN Makefile.hector Makefile.kestrel Makefile.RS6000 Makefile.andes Makefile.davinci Makefile.hector_fe Makefile.kraken Makefile.simple Makefile.bass Makefile.dawson Makefile.hector_fftw3 Makefile.lahey Makefile.T3E Makefile.bassi Makefile.discovery Makefile.hoffman2 Makefile.mpixl Makefile.tungsten Makefile.BGP Makefile.franklin Makefile.homer Makefile.mrf Makefile.wave Makefile.bigben Makefile.fuj Makefile.hopper Makefile.nag Makefile.xl Makefile.BLUEGENE Makefile.G5 Makefile.intel Makefile.newhydra Makefile.XT4 Makefile.columbus Makefile.gcc-intel Makefile.ist Makefile.opensuse Makefile.XT5 Makefile.compaq Makefile.gnu-g95 Makefile.jacquard Makefile.pathscale Makefile.cray Makefile.gnu-gcc Makefile.jaguar Makefile.pgi Makefile.culham Makefile.gnu-gfortran Makefile.juropa Makefile.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 include Makefile.$(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.
You now need to correctly set up your environment for GS2. First you need to specify which system you are on:
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>module load intel ~/trunk>module load fftw2 ~/trunk>module load netcdf ~/trunk>module load mvapich2
You are now ready to build GS2. Type
make -I Makefiles
cross your fingers, and make yourself a cup of coffee.
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.
the command for running GS2 is simply:
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> gs2 run_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.
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
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.