README file for NTCC Module xtranspin Prepared by C.Ludescher-Furth -- transp_support@pppl.gov **************** REVISION HISTORY **************** date Description Oct. 14, 2004 -- Created ---------------------------------------------------------------- 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_xtranspin: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing xtranspin. Makefile: NOTE: "GNU make" must be used (usually in /usr/gnu/bin or /usr/local/bin). You also need "gcc" for pre-processing (exept on CRAY). 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 transpin Makefile -- in subdirectory transpin/uil: Makefile Sources to build the motif interfaces for xtranspin -- in subdirectory transpin/nml: Makefile Sources to build the I/O interface for xtranspin -- in subdirectory transpin/src: Makefile Sources to build the program xtranspin -- in subdirectory etc: configuration file for I/O interface -- in subdirectory splitn: Makefile Sources to build libsplitn.a, routines to read the TRANSP Namelist. -- in subdirectory portlib: Makefile Sources to build internally used library libportlib.a. -- in subdirectory fpreproc: python scripts for pre-processing of fortran -- in subdirectory include/fpreproc: *.h files for source pre-processing. -- in subdirectories ureadsub, sgdummy: Makefile Sources to build libraries needed by splitn. -- in subdirectories trnocom, vaxonly: Makefile Sources to build routines internally used to determine tokamak and year. -- in subdirectory {cdf,hdf}_dummy: Makefile Sources to build dummy routines for optional cdf hdf libraries. ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip xtranspin.tar.gz > tar xvf xtranspin.tar or, for zip archives: > unzip xtranspin.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: ./share -- include file Make.flags, Make.local.sample ./transpin -- Makefile ./transpin/etc -- configuration files needed at run time ./transpin/nml -- xtranspin's interface to splitn ./transpin/src -- c code for each sub menu ./transpin/uil -- uil code for each sub menu ./include/fpreproc -- *.h files for cpp ./fpreproc -- python scripts for pre-processing fortran ./cdf_dummy -- Dummy routines for netcdf ./portlib -- internally used library ./sgdummy -- Dummy routines for sglib ./splitn -- routines to read TRANSP Namelist ./trnocom -- miscellanious (e.g. to verfy Tokamak) ./ureadsub -- interactive I/O command interface ./vaxonly -- miscellaneous The makefile will create more sub directories, lib: for the libraries obj/*: for compiled objects and pre-processed sources uid: compiled motif interface 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: =================== Python -- for pre-processing Fortran 90 C uil -- openmotif Required Libraries: =================== Motif 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 Compiling on Linux: ------------------- By default the Makefile will select Lahey Fujitsu f95. To select a different compiler define FORTRAN_VARIANT to "Portland" "NagWare" "Pathscale" "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 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: -------- To link Xtranspin, Fortran Libraris need to be included. 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: xtranspin To test xtranspin: --------------- 1. Define Environment Variables: - TRANSP_LOCATION /etc - XTRANSPIN /transpin - UIDPATH //uid e.g.: on Linux, if downloaded into $HOME/ntcc # setenv TRANSP_LOCATION $HOME/ntcc/etc # setenv XTRANSPIN $HOME/ntcc/transpin # setenv UIDPATH $HOME/ntcc/LINUX/uid/%U:$UIDPATH Note: After you have installed the package, you must change the Environment accordingly. 2. cp transpin/XTranspin ~/. This is the Motif resource file, which you can customize 3. cd /test ./xtranspin & to get an interactive menu click under the "Help" pulldownmenu on the upper write corner for instructions. ************************ 6. DOCUMENTATION: ************************ NTCC Home Page: http://w3.pppl.gov/NTCC/client TRANSP Home Page http://w3.pppl.gov/transp Help Documents and Manuals - Transp Help - set up TRANSP runs and use RPLOT ********************** 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: xtranspin in: $PREFIX/bin = $BINDIR uid in: $PREFIX/uid = $UIDDIR configuration files in: $PREFIX/etc = $ETCDIR xtr_* directories in: $XTRANSPIN/ 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 BINDIR=/xxx ETCDIR=/yyy UIDDIR=zzz 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