This is the README file for the GENE application benchmark,
distributed with the DEISA Benchmark Suite:
http://www.deisa.eu/science/benchmarking/

Last modified by the DEISA Benchmark Team on 2008-08-25.



-----------
GENE readme
-----------



Contents
--------

1. General description
2. Code structure
3. Parallelization
4. Building
5. Execution
6. Data

1. General description
======================

The gyrokinetic plasma turbulence code GENE (this acronym stands for
Gyrokinetic Electromagnetic Numerical Experiment) is a software package
dedicated to solving the nonlinear gyrokinetic equations in a flux-tube domain.
Alternatively, it can be operated in a linear mode, thus calculating the
properties (like complex frequencies, parallel mode structures
and quasilinear transport coefficients) of the microinstabilities
driving the turbulence.
Gene has been developed by a team of people (the Gene Development Team,
led by F. Jenko) over the last several years.

For further documentation of the code see: doc/gene.tex

2.  Code structure
==================

Each particle species is described by a time-dependent distribution function
in a five-dimensional phase space.
This results in 6 dimensional arrays, which have the following coordinates:
x y z	three space coordinates
v	parallel velocity
w	perpendicular velocity
spec	species of particles

GENE is written completely in FORTRAN90. 
It also contains preprocessing directives.
Most of the source files are described here:

- redef.h
	Include file containing some compilation parameters.
- par_mod.F90
	Module for definition of global datastructures
- gene.F90
	The main program containing the timeloop
- time_scheme.F90
	The subroutine 'electro_magnetic', which calculates one timestep.
- rhsc2.F90
	Module that includes CalFullRhs.F90, block1.F90 and block2.F90.
	This strange code structure has historical reasons.
	It would no longer be necessry.
- CalFullRhs.F90
	Called by 'electro_magnetic'.
	Calculates the right hand side of the gyrokinetic Vlasov equation.
- block1.F90 block2.F90
	Called by 'CalFullRhs'
- comm.F90
	Communication subroutines
- diag.F90
	Diagnostic subroutines (Output)
- fourier_essl.F90 fourier_acml.F90 fourier_mkl.F90 fourier_fftw.F90
	Interfaces to different fourier-libraries
- init_cond.F90
	Subroutines creating different initial conditions
- init_physical.F90
	Initialization of physical variables and arrays.
- checkpoint.F90
	Checkpointing subroutines
	

3. Parallelization
==================

Parallelization is done by domain decomposition of 5 coordinates using MPI.
y, z	2 space coordinates
v	parallel velocity
w	perpendicular velocity
spec	species of particles


4. Building
===========

The source code (fortran-90) resides in directory src.
The compilation of GENE will be done by JuBE.
Compilation will be done automatically if a new executable for the
benchmark runs is needed.
On LOUHI: To make the BLAS library available 'module load blas' is necessary.



5.  Running the code
====================

There are template input files prepared (input directory) for 3 sizes
of benchmark runs:
	128GB, 256GB and 512GB of total memory needed.
These files only differ in the lattice size, physical parameters are identical.
These datasets are created especially for the benchmark runs and don't
relate to real simulations.
JuBE generates for each benchmark run a run directory and generates from
a template input file the input file 'parameters' and stores it in the
run directory.
A job submit script is created as well and is submitted.


6. Data
=======

The only input file is 'parameters'. It has the format of a f90 namelist.

The following output files are stored in the run directory.

nrg.dat		The content of this file is used to verify the correctness
		of the benchmark run.
s_alpha.dat	not used in benchmark runs.

stdout		is redirected by JuBE.
		It contains logging information,
		especially the result of the time measurement.
 
--------------------------------------------------------------------------