README file for PlasmaState Module Prepared by C.Ludescher-Furth -- transp_support@pppl.gov 10/08/07 **************** REVISION HISTORY **************** date Description Oct 08, 2007 -- Created May 05, 2008 -- Added geq2ps, ps2geq and ps_nbline May 13, 2008 -- Added jsocdf2ps ps2xplasma ---------------------------------------------------------------- Index: 1. CONTENTS 2. UNPACKING INSTRUCTIONS 3. DESTINATIONS 4. BUILDING INSTRUCTIONS 5. TESTING INSTRUCTIONS 6. DOCUMENTATION 7. FINAL INSTALLATION ************ 1. CONTENTS: ************ The directory into which plasma_state{zip,tar.gz} was extracted, should contain the following files: README_PlasmaState: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing the plasma_state libraries. Makefile: NOTE, "GNU make" must be used (usually in /usr/gnu/bin or /usr/local/bin). Main Makefile to envoke Makefile(s) in subdirectories. -- in subdirectory fpreproc: Python scripts for fortran pre-processing. -- in subdirectory include/fpreproc: *.h files for source pre-processing. -- in subdirectory plasma_state_test: Makefile Sources to build plasma_state_test README: Copy of README_PlasmaState Makefile Input file for test: g104403.nstx: equilibrium data Refernce output files for test: ref_output, ref_debug3 -- in subdirectory cstate: Makefile Sources to build cstate qktest.ind script for testing -- in subdirectory update_state: Makefile Sources to build update_state -- in subdirectory jsocdf2ps: Makefile Sources to build jsocdf2ps -- in subroutine geq2ps Makefile Sources to build geq2ps -- in subroutine ps2geq Makefile Sources to build ps2geq cur_state.cdf: sample plasma state file -- in subdirectory ps_nbline_driver: Makefile Sources to build ps_nbline_driver tftr_nbline.cdf: sample plasma state file -- in subdirectory ps2xplasma: Makefile Sources to build ps2xplasma -- in subdirectory share: Make.flags: Include file for Makefile, to setup Flags, etc. Make.local.sample: Include file for Makefile, to setup non-conventional, site specific locations. For Test Program cstate: in subdirectories cstate_lib, xplasma_debug, trgraf, elvislib, ureadsub, sglib sources and Makefiles to build these libraries. ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip plasma_state.tar.gz > tar xvf plasma_state.tar or, for zip archives: > unzip plasma_state.zip **************** 3. DESTINATIONS: **************** Or where do the files go? (this refers to building and testing; see FINAL INSTALLATION for end result) When you extract the tar file you get sub directories: ./ccps_lib ./cstate_lib ./fpreproc -- scripts for pre-processing of fortran ./include/fpreproc -- *.h files for cpp ./plasma_state -- ./plasma_state_kernel -- ./ps_nbline -- ./ps_xplasma2 -- ./ps2plasma -- ./share -- include file Make.flags, Make.local.sample For Programs: ./ccps_test ./cstate ./jsocdf2ps ./geq2ps ./plasma_state_test ./ps2geq ./ps2xplasma ./ps_nbline_driver ./update_state The makefile will create more sub directories, lib: for the library, libplasma_state.a mod: for the f90 modules obj/*: for compiled objects and pre-processed sources test: for the test programs and the sample output files. By default these directories are created in ./, which is determined by Make.flags. e.g.: if you are running Linux, and the tar file resides in $HOME/foo, the directories would be in $HOME/foo/LINUX/... You can overwrite the destination by defining OBJ, as an environment variable (e.g. export OBJ=/dir1/dir2), or with make (e.g. "make all OBJ=."). If OBJ is defined, the destinations will be $OBJ/lib and $OBJ/test. If OBJ is defined as "." then, in the example above, the destination would be $HOME/foo/lib. The rationale behind is to facilitate building for various platforms. Note: If you define OBJ as option to gmake, you have to consistently do so; e.g: gmake clean OBJ=., gmake install OBJ=. ************************* 4. BUILDING INSTRUCTIONS: ************************* Required Compilers: =================== Fortran 90 or 95 C Required Libraries: =================== libpspline.a -> NTCC module PSPLINE transp libraries -> NTCC module PS_TranspSubs (available with PlasmaState) Note: if you have NUBEAM, you don't need PS_TranspSubs lapack - Linear Algebra PACKage netCDF - network Common Data Form Optional Libraries: =================== readline, history, termcap for Command Line Editing Note: if not all three libraries are installed you must define NO_EDITLIBS e.g.: gmake NO_EDITLIBS=Y Check with your systems administrator where these libraries and modules are. lapack, blas, netCDF --------------------------- lapack, blas, netCDF are assumed to be in /usr/local/lib, if not, you can specify the location with LIBROOT, e.g.: "gmake LIBROOT=/usr/contrib". If netCDF is in a separate location, specify NETCDF_DIR e.g.: "gmake NETCDF_DIR=/usr/local/my-netcdf LIBROOT=/my-libroot". Alternatively you can modify Make.local.sample and rename it to Make.local. pspline, xplasma and preact --------------------------- If your site already has pspline, xplasma and preact libraries installed, specify their location (library and modules) with PREFIX, e.g. "gmake PREFIX=/usr/ntcc" At PPPL these libraries are in $NTCCHOME/lib. Note: If you don't have all required NTCC libraries, you may download them together into the same work directory. The Makefile will build them all in one step. Building libraries and programs -------------------------------- > gmake -- to compile library and link all test programs > gmake checklibs -- tells you what the makefile will do (without any action); it says which libraries it will make and which ones it already found and where. > gmake clean -- to remove objects > gmake realclean -- to remove objects and library > gmake show_makeflags -- to see what flags, definitions Make will use Compiling on Linux: ------------------- By default the Makefile will select LaheyFujitsu. To select a different compiler define FORTRAN_VARIANT to "Portland" "PathScale" " GCC" "NagWare" "Fujitsu" "Intel" or "Absoft" e.g.: setenv FORTRAN_VARIANT Portland (csh) FORTRAN_VARIANT=Portland; export FORTRAN_VARIANT (sh) Alternatively, FORTRAN_VARIANT can be passed directly to the gmake command, as in: gmake FORTRAN_VARIANT=Portland Note: some test programs are linked with g++; to find the Fortran libraries, you need to define FLIBROOT e.g. export FLIBROOT=/usr/pppl/lf64x/lf6480 To use vastf90: > gmake VAST90=y To use NAG90: > gmake NAG90=y Note: By default the test programs, plasma_state_test and plasma_state_driver, are linked with lf95. If you encounter a problem, try linking with g++: > gmake USEFC=N Compiling on Alpha Linux: ------------------------- The Makefile assumes the Compaq compiler and specifies the " -assume no2underscores " option. Therefore the calling user software must also be compiled with this option, or you should edit share/Make.flags to remove the option. Compiling on SUN: ----------------- The Makefile specifies the -dalign option. Therefore the calling user software must also be compiled with this option, or you should edit share/Make.flags to remove the option. ************************ 5. TESTING INSTRUCTIONS: ************************ directory $OBJ/test -or- /test will contain plasma_state_test and cstate: To run tests / programs: ======================== cd plasma_state_test ..//test/plasma_state_test cd cstate ..//test/cstate @qktest.ind Write g-eqdsk file from plasma state "cur_state" into "foo" cd ps2geq ../LINUX/test/ps2geq cur_state.cdf foo.geq will write ./g104403.nstc -- "g104403.nstx" is the file name stored in the state itself, in data element eqdsk_file. Load plasma state from sample g-eqdsk file into "gps.cdf" cd geq2ps ../LINUX/test/geq2ps g104403.nstx gps.cdf -tok:NSTX -shot:104403 For ps_nbline_driver: cd /ps_nbline_driver Arguments are: "-ps:" -- plasma state file; "-seed:" -- random number seed in form of a character string "-n: " -- sample size e.g.: ../LINUX/test/ps_nbline_driver -ps:tftr_nbline.cdf -seed:abc -n:20 See: README_ps_nbline update_state ------------ This program applies a state update file or list of update files to an existing state, to create a new state. For help: /test/update_state ************************ 6. DOCUMENTATION: ************************ PLASMA_STATE Home Page: http://w3.pppl.gov/NTCC/PlasmaState NTCC Home Page: http://w3.pppl.gov/NTCC ********************** 7. FINAL INSTALLATION: ********************** Choose or create the root directory in which you wish to install the software. A common location would be /usr/ntcc, but installation can occur in any directory where you have appropriate permissions. You define your choice of root directory via PREFIX. The default for PREFIX is /usr/ntcc. The assumptions are: libraries in: $PREFIX/lib = $LIBDIR f90 modules in: $PREFIX/mod = $MODDIR man pages in: $PREFIX/man/man3 = $MANDIR/man3 To install the software, return to the top directory (the directory, where you downloaded the tar files) and type > gmake install to install into /usr/ntcc/... > gmake install PREFIX=/dir1/dir2/ to install into /dir1/dir2/... If you want things elsewhere, you can overwrite the default with > gmake install LIBDIR=/xxx MODDIR=yyy MANDIR=zzz NOTE: ----- To link a program, you need all plasma_state, xplasma, pspline libraries. e,g: -L/lib \ -lplasma_state -lps_xplasma2 -lplasma_state_kernel \ -lxplasma2 -lgeqdsk_mds -lmdstransp -lvaxonly -lnscrunch \ -lfluxav -lr8bloat -lpspline -lezcdf \ -llsode -llsode_linpack -lcomput -lportlib Make sure users know what is. After you have installed the software, you can delete the entire tree with > cd .. > rm -r foo assuming the previous example. ---------------------------------------------------------------------------- IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT: transp_support, Princeton University transp_support@pppl.gov