README file for TR_Client Module Prepared by C.Ludescher-Furth -- transp_support@pppl.gov 01/29/03 **************** REVISION HISTORY **************** date Description Jan 29, 2003 -- Created ---------------------------------------------------------------- Index: 1. CONTENTS 2. UNPACKING INSTRUCTIONS 3. DESTINATIONS 4. BUILDING INSTRUCTIONS 5. RUNNING INSTRUCTIONS 6. DOCUMENTATION 7. FINAL INSTALLATION ************ 1. CONTENTS: ************ Note: See README_TrStart and README_rplot for details on tr_start and rplot. See Notes_mdsplot on how to install mdsplot. This directory should contain the following files: README_TrClient: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing scruncher, scrunch2, nbfile, adisplay and get_fbm. README_TrStart: Brief descriptions of tr_start related files and instructions for compiling, testing and installing the tr_start scripts, executables and data files. README_rplot: Brief descriptions of rplot related files and instructions for compiling, testing and installing rplot. Notes_mdsplot: Brief descriptions of mdsplot and how to install it. 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 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. -- in subdirectory client: Copy of README UserGuide: Description of scripts and programs. Makefile Sources for programs: nbfile, nblist, scruncher, scrunch2, mdsplot, adisplay, get_fbm -- in subdirectory nblistsub: Makefile Sources to build libnblistsub.a, a library to handle input to nbfile. -- in subdirectory momsub: Makefile Sources to build libmomsub.a, a library to convert magnetics into TRANSP form for scruncher. -- in subdirectory scrunch: Makefile Sources to build libscrunch.a, a library to map plasma boundary into TRANSP usable form for scruncher. -- in subdirectory scr2lib: Makefile Sources to build libscr2lib.a, a library to convert EFIT into TRANSP usable form for scrunch2. -- in subdirectory tftrg1: Makefile Sources to build libtftrg1.a, a library used by nbfile. -- in subdirectory tr_tdi PPPL customized tdi functions ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip tr_client.tar.gz > tar xvf tr_client.tar or, for zip archives: > unzip tr_client.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: for tr_start: ./tr_start -- sources, scripts and Makefile for software to start a TRANSP run ./share -- include file Make.flags, Make.local.sample ./include -- shared include files for TRANSP libraries ./include/fpreproc -- *.h files for cpp ./fpreproc -- python scripts for pre-processing of fortran ./mds_sub -- ufiles/mdsplus interface ./mdstransp -- MDSplus interface ./portlib -- routines for porting ./sgdummy -- dummy routines for sglib ./uflib -- to read standard ufiles ./ufhdf -- to read ufiles of netCDF / HDF format ./ureadsub -- I/O routines ./vaxonly -- miscellaneous ./TFTR/test -- Ufiles for testing ./*_dummy -- dummy routines for netcdf, hdf for rplot: ./rplot -- sources and Makefile ./rp_kernel -- RPLOT i/o ./rplot_io -- RPLOT i/o ./rplot_sub -- RPLOT ./smlib -- math algorithms ./interp_sub -- interpolation routines ./comput -- transformation/interpolation routines ./xdatmgr -- memory management ./trgraf -- for cdfcon ./sgdummy -- " for scruncher, scrunch2 ./scrunch -- map plasma boundary into TRANSP usable form ./momsub -- converting magnetics analysis into TRANSP form ./scrlib2 -- convert EFIT into TRANSP usable form for nbfile ./nblistsub -- prepare neutral beam info ./tftrg1 -- TFTR specific data access routines for adisplay, get_fbm ./aclib -- ascii encoding of floating point ./hpsort -- heap sort ./i3encod -- ascii encode/decode of floatimg point ./zm_swb -- ULTRA random number generator for mdsplot ./tr_tdi -- PPPL customized MDSplus tdi functions The makefile will create more sub directories, lib: for the library, libtr_start.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 Libraries: =================== MDSplus For scruncher, scrunch2 pspline -- NTCC Module xplasma -- NTCC Module trxplib -- NTCC Module (scrunch2 only) Optional Libraries: =================== readline, history, termcap for Command Line Editing Note: if these libraries are "partionally" installed you must define NO_EDITLIBS e.g.: gmake NO_EDITLIBS=Y Check with your systems administrator where these libraries and modules are. MDSplus ------- MdsLib is assumed to be in /usr/local/mdsplus/lib, otherwise define MDSPLUS_DIR. If it's not installed properly, modify MDSLIB in share/Make.local If you don't have MDSplus, build the code with "make NO_MDSPLUS=1" -or- define environment variable NO_MDSPLUS Building libraries and proprams -------------------------------- > 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 "Intel", "Portland", "NagWare", "Fujitsu" or "Absoft" e.g.: setenv FORTRAN_VARIANT Portland (csh) export FORTRAN_VARIANT=Portland (bash) Alternatively, FORTRAN_VARIANT can be passed directly to the gmake command, as in: gmake FORTRAN_VARIANT=Portland To use vastf90: > gmake VAST90=y To use NAG90: > gmake NAG90=y 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. Linking: -------- Some C programs need to link with Fortran Libraries. The Makefile is looking in -L$(FLIBROOT)/lib. Define FLIBROOT or F90HOME to point to your fortran installation, e.g: export FLIBROOT=/usr/pppl/pgi/6.1-2/linux86/6.1 ************************ 5. TESTING INSTRUCTIONS: ************************ directory $OBJ/test -or- /test will contain: Scripts, executables and a sample Namelist. For testing (prior to final installation) I. Define environment variable MDS_TRANSP_SERVER If you don't use Mdsplus, define MDS_TRANSP_SERVER=NONE. II. Creating the Pulse and writing the Input using the sample NameList 37065A01TR.DAT: 1. Define Environment Variables: - DATADIR where = the directory where you downloaded the {tar,zip}file - TRANSP_LOCATION /etc - PATH add //test to your PATH e.g.: on Linux, if downloaded into $HOME/ntcc # setenv DATADIR $HOME/ntcc # setenv TRANSP_LOCATION $HOME/ntcc/etc # setenv PATH $HOME/ntcc/LINUX/test:$PATH Note: After you have installed the package, you must change the Environment accordingly. 2. mkdir cp $DATADIR/TFTR/test/37065Z01TR.DAT . 3. tr_start 37065Z01 To start the run. III. Submitting the run to PPPL 1.A. If you use mdsplus: tr_send 37065Z01 1.B. If you don't use mdsplus tr_send_pppl.pl 37065Z01 TFTR NOMDSPLUS IV. Running mdsplot See Notes_mdsplot See http://w3.pppl.gov/transp for details. ************************ 6. DOCUMENTATION: ************************ UserGuide: http://w3.pppl.gov/transp/production.html#Tools TR_Client Home Page: http://w3.pppl.gov/NTCC/TR_Client TRANSP Home Page http://w3.pppl.gov/transp NTCC Home Page: http://w3.pppl.gov/NTCC ********************** 7. FINAL INSTALLATION: ********************** Note: Unless you run your own TRANSP Production System, you do NOT need mdsplot. 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: programs in: $PREFIX/bin = $BINDIR scripts in: $PREFIX/etc = $ETCDIR libraries in: $PREFIX/lib = $LIBDIR f90 modules: $PREFIX/mod = $MODDIR man pages in: $PREFIX/man/man3 = $MANDIR/man3 For mdsplot: tdi functions in: $TDIDIR You must define TDIDIR to a directory that is in your MDSplus Server's MDS_PATH. 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/... For mdsplot: > gmake install PREFIX=/dir1/dir2/ TDIDIR=/my/mdsplus/tdi If you want things elsewhere, you can overwrite the default with > gmake install ETCDIR=/xxx BINDIR=zzz NOTE: ----- Add {bin,etc} to you PATH. 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