			GRYFFIN help file

GRYFFIN is a 3-D, nonlinear, toroidal gyrofluid code for studying
ion-temperature-gradient turbulence in tokamak plasmas.  This code is a
collaborative effort: Bill Dorland developed the original slab version
(itg), Mike Beer extended to toroidal geometry and toroidal drift terms
(itgc- with the c denoting use of Cowley's coordinates), and other
contributions from Greg Hammett and Bill and Mike.  Phil Snyder added
electromagnetic extensions to include A_parallel, and a perturbative
electron treatment for the m_e/m_i << 1 limit.  (The code evolved from
earlier codes by Satoshi Hamaguchi and by Wonchull Park, but the changes
have been quite extensive, particularly the change from convolutions to
fast Fourier transforms and from a cosine/sine representation to complex
notation, so that virtually nothing remains from the Hamaguchi/Park
versions.)  Citable references at the end.

**************************************************
# Setup instructions for a new user:

# Assuming you have access to the afs distributed file system, you do:

cd ~ # move to a directory where you want to create the gryffin directory.
setenv CVSROOT /afs/pppl.gov/u/qpliu/cvsroot
setenv CVSEDITOR "emacs"
cvs checkout gryffin  # to get the most recent version, or
cvs checkout -D "1999-03-03 07:00 GMT" gryffin  # for a specific version
cd ~/gryffin/run
ln -s ../src gfbin
cd ~/gryffin/doc  # peruse documentation, including history file.

# To compile the main itgc code, and the various utilities, do;

cd ~/gryffin/src
make         # (using gnu make)

# To run the code, do:

cd ~/gryffin/run
cp ../test/lintest0.in .
cp gfbin/post.in .
gfbin/itgc lintest0     # run the main code
                 # should probably do this as a batch job for long runs
mpprun -np 4 gfbin/itgc lintest0     # run on 4 processors with mpi
gfbin/postc lintest0	# run the postprocessor
ictrans lintest0.m	# plot the results
			# (assumes setenv GRAPHCAP X11 done at login)
			# or use idt, ctrans, or gplotm as alternatives...

****************************************************************
Useful utilities:

res2nc   # converts *.res restart/results file to *.nc netcdf format
nc2res   # inverse
nc2nc    # useful for debuging

compare file1.nc file2.nc  # compares two files with default error tolerances
compare file1.nc file2.nc 1.e-7 1.e-19  # relative and absolute err tolerances

This utility is useful because roundoff errors in FFTs for example might be
locally large at some values of k, but are small compared to the RMS
magnitude of the field.  It can also be useful because netcdf files are
written in the local binary format:  "diff file1.nc file2.nc" might report
difference if file1.nc was written on a T3E and file2.nc was written on an
Origin-2000, while "compare" will show that they are actually equivalent.
You can also use the netcdf utility "ncdump" to convert to ASCII and also
find they are equivalent.  See todo.txt for cases where round-off errors
can still look large.

****************************************************************

# In the future, to get an updated version of gryffin, do:

cd ~/gryffin
cvs -n -q update  # to get a list of files that have been changed, without
		  # making any changes to your ~/gryffin working directory
cvs diff src/filename.f90  # to see what changes you've made to a file
			   # since checkout
cvs diff -D now src/filename.f90  # to see differences with current version
cvs update   # when you are ready, do this to actually change your working
	     # directory 

# When you are ready to put changed versions of a file into CVS:

cd ~/gryffin/src
cvs -n -q update # see what changes need to be 
cvs diff filename.f90  # review changes that you've made
cvs commit filename.f90  # commit them to the CVS library.

Don't forget to add comments to the ~/gryffin/doc/history file!

**************************************************

When running on a DEC Alpha, you may need to first type:

	uac p noprint
	limit stacksize unlimited

*****************************
A suite of test cases for the Gryffin code are in hpss in

	ftp://archive.nersc.gov/nersc/gc3/u1768/testsuite

****************************************************************************

Look in itg.cmn and itg.par for how various variables are defined.

****************************************************************************

c In the original slab itg code:
c
c	Label	Direction	index	Max	Max
c					Used	Possible
c
c	x	radial position	l	ldb	lz
c	y	poloidal mode	m	md	mz
c	z	toroidal mode	n	nd	nz
c
c The main representation in the slab code was finite difference in x
c and Fourier modes in y and z (m and n).
c
c The main representation in the toroidal code using Cowley's field-line
c coordinates is finite difference along the field line and Fourier modes
c in the radial and poloidal direction.  For this reason, l now indexes
c the along-the-field-line coordinate, m labels the poloidal mode number,
c and n labels the radial mode number.
c
c In the present toroidal itgc code:
c
c	Label	Direction	index	Max	Max
c					Used	Possible
c
c	x	parallel pos.	l	ldb	lz
c	y	poloidal mode	m	md	mz
c	z	radial mode	n	nd	nz
c
c Many of the comments in the code have not been updated since the 
c change to toroidal geometry, leading to some confusion.  For example,
c comments may refer to l as an index in the x "radial" direction, when
c it is really an index in the parallel position, along the field line.

***************************************************************************

c
c FOURIER TRANSFORM CONVENTIONS FOR THE ITG CODE
c
c The ITGC code solves gyrofluid equations using a pseudo-spectral
c method, doing parts of the calculation in k-space and part in x-space,
c wherever is easiest for the term at hand.
c The "home" representation for most field variables is in (kx,ky,z)
c space, i.e., a spectral representation for the radial (x) and poloidal 
c (y) directions, and a finite grid for the along-the-field coordinate z.
c The standard complex Fourier transform is:
c
c	wfield(x,y,z) = Sum_mn w(x,m,n) exp( + i m y / y0 - i n z / z0)
c
c where w(x,m,n) are complex coefficients, and the sum is over positive
c and negative m and n.  The reality condition is 
c	w(x,-m,-n) = conjg(w(x,m,n)) 
c In the original code we got from Hamaguchi, he instead separates this
c into the cosine and sine parts: 
c
c	wfield(x,y,z) = Sum_mn wc(x,m,n) cos( m y / y0 - n z /z0)
c			      +ws(x,m,n) sin( m y / y0 - n z /z0)
c
c where the sum is only over m>=0, though both signs of n.
c (Caution, the m=0 modes are not all independent, the (m=0,-n) mode
c is still related to the (m=0,+n) mode.)
c
c The complex coefficient W(m,n)=Wr(m,n) + I*Wi(m,n) is related to
c the cosine/sine coefficients by (note the sometimes factor of 2):
c
c If (m .ne. 0) then
c	Wr(m,n) =  Wc(m,n)/2
c	Wi(m,n) = -Ws(m,n)/2
c endif
c If (m .eq. 0) then
c	Wr(m,n) =  Wc(m,n)
c 	Wi(m,n) = -Ws(m,n)
c endif
c
c The code would certainly be simpler, clearer, and more concise
c if it had used complex notation rather than sine and cosine
c parts.  We are moving in that direction.
c

****************************************************************************

PUBLISHED REFERENCES FOR THE ITG CODE

William Douglass Dorland, "Gyrofluid Models of Plasma Turbulence",
Princeton Ph.D. Thesis, November 1993.
Contains the derivation of the original slab gyrofluid equations, and a
description of the numerical methods used in the code.

W. Dorland, G. W. Hammett, Phys. Fluids~B {\bf 5}, 512 (1993).
Derivation of the original slab gyrofluid equations.

R. E. Waltz, R. R. Dominguez, and G. W. Hammett, Phys. Fluids~B {\bf 4},
3138 (1992)
Derivation of the original 3+1 toroidal gyrofluid equations.

M.A. Beer, S.C. Cowley, G.W. Hammett, in progress.
Development of field-line-following coordinates for efficient toroidal
simulations.

M.A. Beer et.al.
Extension to higher accuracy toroidal equations.

G.~W.~Hammett, M.~A.~Beer, W.~Dorland, S.~C.~Cowley, and S.~A.~Smith,
"Developments in the Gyrofluid Approach to Tokamak Turbulence Simulations"
Plasma Phys. Cont. Fusion {\bf 35}, 973 (1993). 
Review paper on early results from the toroidal code.

S.A. Smith and G.W. Hammett, "Some nonlinear aspects of fluid moment
closures that model Landau damping", to be submitted when I get a little
time...

G.W. Hammett, W. Dorland, F.W. Perkins, "Fluid models of phase mixing,
Landau damping, and nonlinear gyrokinetic dynamics", Phys. Fluids B {\bf
4}, 2052 (1992).
Review of the main concepts involved in gyro-Landau fluid equations
(conceptually clearer than the PRL below), including a review of related
work by other on modelling Landau damping in fluid equations.

G.W. Hammett, F.W. Perkins, "Fluid Moment Models for Landau Damping with
Applications to the Ion-Temperature-Gradient Instability", Phys. Rev. Lett.
{\bf 64}, 3019 (1990).
Our initial paper on the Landau-fluid approach.
