README file for NTCC Module TrRead Prepared by C.Ludescher -- transp_support@pppl.gov 08/03/00 **************** REVISION HISTORY **************** date Description Aug. 03, 2000 -- 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_TrRead: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing the trread library libtrread.a and its test driver trread_test. Makefile: NOTE: "GNU make" must be used (usually in /usr/gnu/bin or /usr/local/bin). You also need python for pre-processing. 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 trread: Copy of README Makefile Sources to build the library libtrread.a *.f, *.F, *.F90 Sources for programs: cdfcon.F -- creates CDF file from transp run trread_test.f -- for testing Sample input/output files for test: 11114p04.cdf, 11114p04tr.dat expected_trread_test.msg, expected_trread_test.output -- in subdirectories rp_kernel, rplot_io: Makefile Sources to build librp_kernel.a and librplot_io, internally used libraries to handle RPLOT i/o. -- in subdirectory mdstransp: Makefile Sources to build libmdstransp.a, an internally used library with trans-Mdsplus interfaces. -- in subdirectory smlib: Makefile Sources to build libsmlib.a, an internally used library with math routines. -- in subdirectory xdatmgr: Makefile Sources to build libxdatmgr.a, an internally used library for memory management. -- in subdirectory vaxonly: Makefile Sources to build vaxonly.a, an internally used library with miscellaneous routines. -- in subdirectory comput: Makefile Sources to build libcomput.a, an internally used library with transformation/interpolation routines. -- in subdirectory interp_sub: Makefile Sources to build libinterp_sub.a, an internally used library with interpolation routines. -- in subdirectory portlib: Makefile Sources to build internally used library libportlib.a. -- in subdirectory fpreproc: Python scripts for fortran pre-processing: -- in subdirectory include/fpreproc: *.h files for source pre-processing. -- in subdirectories rplot_sub, ureadsub, trgraf, sgdummy: Makefile Sources to build libraries needed by cdfcon. ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip trread.tar.gz > tar xvf trread.tar or, for zip archives: > unzip trread.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: ./trread -- sources and Makefile ./share -- include file Make.flags, Make.local.sample ./portlib -- internally used library ./include/fpreproc -- *.h files for cpp ./fpreproc -- scripts for pre-processing of fortran ./rp_kernel -- RPLOT i/o ./rplot_io -- RPLOT i/o ./mdstransp -- MDSplus interface ./smlib -- math algorithms ./interp_sub -- interpolation routines ./comput -- transformation/interpolation routines ./xdatmgr -- memory management ./vaxonly -- miscellaneous ./rplot_sub -- for cdfcon ./ureadsub -- " ./trgraf -- " ./sgdummy -- " The makefile will create more sub directories, lib: for the libraries mod: for fortran 90 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: =================== Python -- for pre-processing Fortran 90 C Required Library: =================== netCDF -- for cdfcon and test program Note: Ignore complaints about ezcdf - you probably don't need it. Check with your systems administrator where the library. Default is /usr/local/lib. You can define non-standard locations via NETCDF_DIR and MDSPLUS_DIR. 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 Fujitsu f95. To select a different compiler define FORTRAN_VARIANT to "Portland" "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 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: trread_test : Test driver for trread 11114p04.cdf : transp run output 11114p04tr.dat : transp namelist expected_trread_test.msgs : sample of output messages expected_trread_test.output : sample of output To run test: ----------- cd /test ./trread_test.csh This will produce trread_test.output and trread_test.msgs and compare it. Due to architecture differences you might prefer running ./trread_test and do the compare manually. For details see http://w3.pppl.gov/~pshare/help/trread.htm ************************ 6. DOCUMENTATION: ************************ TrRead Home Page: http://w3.pppl.gov/NTCC/TrRead TrRead HELP http://w3.pppl.gov/~pshare/help/trread.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 executacles in: $PREFIX/bib = $BINDIR man pages in: $PREFIX/man/man{1,3} = $MANDIR/man{1,3} 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 MANDIR=zzz NOTE: ----- Users should link with: -L/lib -ltrread -lrp_kernel -lrplot_io -lxdatmgr -lmdstransp -linterp_sub -lsmlib -lcomput -lvaxonly -lportlib $MDSLIB. 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