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 initialize before running the code, do: setenv gfbin ~/gryffin/src # Directory of nmlstrip and gyrofluid binaries. alias itgc=$gfbin/itgc alias postc=$gfbin/postc # To run the code, do: cd ~/gryffin/run cp ../test/lintest0.in . cp gfbin/post.in . 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 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.