README file for Xplasma Module Prepared by C.Ludescher-Furth -- transp_support@pppl.gov 06/26/00 **************** REVISION HISTORY **************** date Description June 26, 2000 -- Created Feb. 08, 2001 -- Support of EFIT output June 21, 2001 -- Added geqxpl2 sample program Mar. 14, 2006 -- Added xplasma_fsp_test example Sep. 08, 2006 -- New xplasma2 ---------------------------------------------------------------- Index: 1. CONTENTS 2. UNPACKING INSTRUCTIONS 3. DESTINATIONS 4. BUILDING INSTRUCTIONS 5. TESTING INSTRUCTIONS 6. DOCUMENTATION 7. FINAL INSTALLATION ************ 1. CONTENTS: ************ This directory should contain the following files: README_Xplasma: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing the libxplasma2, old_xplasma, xplasma_debug libraries, and the test drivers xplasma2_test, test_xplasma, xplasma_fsp_test and geqxpl{2} and the utility plot_xplasma. 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 xplasma: Copy of README Makefile Sources to build the library libxplasma.a *.f, *.F, *.F90 Sources for programs: test_xplasma.f90, plot_xplasma.f, geqxpl[2}.for xplasma_fsp_test.f90 xplasma2_test.f90 Sample input/output files for test: *.ind, *.treq_data script_output.ps, g*.nstx 104276D02_4s710_xplasma.cdf -- in subdirectory comput: Makefile Sources to build libcomput.a, an internally used library with transformation/interpolation routines. -- in subdirectory fluxav: Makefile Sources to build libfluxav.a, an internally used library for flux zone / flux surface averages and integrals. -- in subdirectory fpreproc: Python scripts for fortran pre-processing. -- in subdirectory generic_dummy: Makefile Sources to build libgeneric_dummy.a, an internally used library with dummy routines for optional hdf, sglib, mdsplus. -- in subdirectory include/fpreproc: *.h files for source pre-processing. -- in subdirectory mclib: Makefile Sources to build libmclib.a, an internally used library for string manipulation. -- in subdirectory r8bloat: Makefile Sources to build libr8bloat.a, an internally used library with miscelanious math routines. -- in subdirectory smlib: Makefile Sources to build libsmlib.a, an internally used library with math routines. -- in subdirectory tridiag: Makefile Sources to build libtridiag.a, an internally used library for solving tridiagonal systems. -- in subdirectory portlib: Makefile Sources to build internally used library libportlib.a. -- for the test and the visualization programs: subdirectories sglib, trgraf, ureadsub, vaxonly, lsode, lsode_linpack, mdstransp, nscrunch containing sources and Makefiles to build these libraries. ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip xplasma.tar.gz > tar xvf xplasma.tar or, for zip archives: > unzip xplasma.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: ./xplasma2 -- sources and Makefile ./old_xplasma -- sources and Makefile ./xplasma_debug -- sources and Makefile ./cdf_dummy -- dummy routines for netcdf ./comput -- transformation/interpolation routines ./fluxav -- flux zone / flux surface averages and integrals ./fpreproc -- scripts for pre-processing of fortran ./hdf_dummy -- Dummy routines for hdf ./geqdsk_mds -- ./include/fpreproc -- *.h files for cpp ./lsode -- REAL*8 version of netlib odepack ./lsode_linpack -- linpack routines used by lsode ./mclib -- string manipulation ./mds_dummy -- Dummy routines for mdsplus ./mdstransp -- fortran/c interface for mdsplus ./nscrunch -- moment representation of nested flux surfaces ./portlib -- internally used library ./r8bloat -- miscelanious math routines ./share -- include file Make.flags, Make.local.sample ./smlib -- math algorithms ./tridiag -- for solving tridiagonal systems ./vaxonly -- Low level code for machine dependence for test_xplasma and visualization program: ./elvislib -- interface for trgraf ./sglib -- graphics ./trgraf -- display routines ./ureadsub -- interactive command interface The makefile will create more sub directories, lib: for the libraries 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: =================== libpspline.a -> NTCC module PSPLINE lapack blas netCDF Optional Libraries: =================== MDSplus for geqxpl option readline, history, termcap for Command Line Editing Note: if these libraries are "partionally" installed, not all three are available, you must define NO_EDITLIBS e.g.: gmake NO_EDITLIBS=Y Check with your systems administrator where these libraries and modules are. lapack, blas and netCDF ----------------------- lapack, blas and 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 ------- If your site already has pspline installed, specify the location (library and modules) with PREFIX, e.g. "gmake PREFIX=/usr/ntcc" At PPPL ntcc libraries are in /usr/ntcc. Note: If you don't have all required NTCC libraries, you may download them together into the same root directory. The Makefile will build them all in one step. 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 Fujitsu f95. To select a different compiler define FORTRAN_VARIANT to "Portland" "PathScale" " GCC" "NagWare" "Fujitsu" 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 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 " -fast " option which includes -dalign. 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: xplasma2_test : Quick test of xplasma test_xplasma : Test driver for xplasma script.ind : controlling input script for test_xplasma jet.ind : input script for script.ind nstx.ind : input script for script.ind plotall.ind script_output.ps : output from "test_xplasma @script" geqxpl : Test for EFIT output nstx_geqdsk.ind : controlling input script for geqxpl g104403.nstx : a G-EQDSK file geqxpl_output.ps : output from "geqxpl @nstx_geqxpl" geqxpl2 : Example to create an xplasma from a geqdsk file g103875.nstx : a G-EQDSK file xplasma_fsp_test : Examples for F77 interface calls 104276D02_4s710_xplasma.cdf : input for xplasma_fsp_test plot_xplasma : visialization utility To run tests: ------------- define environment variable TERMINAL_TYPE = XTERM (e.g. export TERMINAL_TYPE=XTERM) cd /test ./xplasma2_test No input required. ./test_xplasma @script This will produce a canned sequence of plots. This is the same set of plots as are stored in script_output.ps ./geqxpl @nstx_geqdsk This will also produce a canned sequence of plots. This is the same set of plots as are stored in geqxpl_output.ps ./geqxpl2 This will start an interactive session. ./xplasma_fsp_test This will read the includes netCDF file and print the example results. (no graphics). For details see README or http://w3.pppl.gov/~pshare/help/xplasma.htm ************************ 6. DOCUMENTATION: ************************ XPLASMA Home Page: http://w3.pppl.gov/NTCC/Xplasma XPLASMA HELP http://w3.pppl.gov/~pshare/help/xplasma.htm 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 utility in: $PREFIX/bin = $BINDIR 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 BINDIR=zzz NOTE: ----- The library is installed as libxplasma.a Users should link with -L/lib -lxplasma -lfluxav -lezcdf \ -lmclib -lsmlib -ltrgraf -lureadsub -lvaxonly \ -ltridiag -lr8bloat -lcomput -lpspline -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