README file for Kdsaw Module Prepared by C.Ludescher-Furth -- transp_support@pppl.gov 02/01/02 **************** REVISION HISTORY **************** date Description Feb 01, 2002 -- Created Oct 27, 2004 -- Diagnostic Output Option Nov 14, 2005 -- Porcelli Mixing Upgrade ---------------------------------------------------------------- DOUBLE/SINGLE PRECISION VERSION Standard REAL*8 and Single Precision versions are distributed in kdsaw.{tar.gz,zip}". NOTE, REAL soubroutines are post_fixed with "_r4". Index: 1. CONTENTS 2. UNPACKING INSTRUCTIONS 3. DESTINATIONS 4. BUILDING INSTRUCTIONS 5. TESTING INSTRUCTIONS 6. DOCUMENTATION 7. FINAL INSTALLATION 8. DIAGNOSTIC OUTPUT ************ 1. CONTENTS: ************ This directory should contain the following files: README_Kdsaw: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing the kdsaw library libkdsaw.a and its test driver kdsaw_test. 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 invoke Makefiles in all subdirectories. UserGuide_Kdsaw: User guide ./share/Make.flags: Include file for Makefile, to setup Flags, etc. ./kdsaw: README: -- A copy of README_Kdsaw from above. UserGuide: -- A copy of UserGuide_Kdsaw from above. Makefile -- to build libkdsaw and test programs Sources to build the library libkdsaw.a kdsaw_test.f90 -- source for basic test driver kdsaw_test.output -- sample output file for respective test case ************************** 2. UNPACKING INSTRUCTIONS: ************************** for tarfiles: > gunzip kdsaw.tar.gz > tar xvf kdsaw.tar or, for zip archives: > unzip kdsaw.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: ./kdsaw -- sources and Makefile ./share -- include file Make.flags The makefile will create more sub directories, lib: for the library, libkdsaw.a mod: for the f90 module obj/kdsaw: for compiled objects test: for the test program and the sample output file. 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/{lib,mod,obj,test}. You can overwrite the destination by defining OBJ, as an environment variable (e.g. export OBJ=/dir1/dir2), or with make (e.g. "gmake OBJ=."). If OBJ is defined, the destinations will be $OBJ/{lib,mod,obj,test}. If OBJ is defined as "." then, in the example above, the destination would be $HOME/foo/{lib,mod,obj,test}. 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=. Alternatively you can modify share/Make.local.sample and rename it to share/Make.local. ************************* 4. BUILDING INSTRUCTIONS: ************************* > gmake -- to compile library and link test program > gmake clean -- to remove objects > gmake realclean -- to remove objects and library > gmake show_makeflags -- displays what compiler/flags would be used Compiling on Linux: ------------------- By default the Makefile will select Fujitsu. To select a different compiler define FORTRAN_VARIANT to "Portland" "NagWare" "LaheyFujitsu" or "Absoft" e.g.: setenv FORTRAN_VARIANT LaheyFujits (csh) FORTRAN_VARIANT=LaheyFujitsu; 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: ************************ To verify functioning of the software: -------------------------------------- There is no input required. Run kdsaw_test and compare it's output with kdsaw_test.output: e.g.: > cd /test or > cd $OBJ/test > ./kdsaw_test > foo > diff foo kdsaw_test.output ************************ 6. DOCUMENTATION: ************************ KDSAW Home Page: http://w3.pppl.gov/NTCC/KDSAW ********************** 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 PREFIX=/dir1/dir2/ to install into /dir1/dir2/... > gmake install to install into /usr/ntcc/... or, if PREFIX is defined in share/Make.local If you want things elsewhere, you can overwrite the default with > gmake install LIBDIR=/xxx MODDIR=yyy MANDIR=/zzz NOTE: ----- The library is installed as libkdsaw.a Users should link with -L/lib -lkdsaw 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. ---------------------------------------------------------------------------- ********************* 8. DIAGNOSTIC OUTPUT: ********************* If you need extra diagnostic output for your particular problem, you can compile kdsaw_init and kdsaw_deln, to produce a netcdf output file. do: > cd kdsaw > gmake realclean > gmake USE_CDF=Y Note: you need to download the ezcdf module for this feature. http://w3.pppl.gov/NTCC/EZcdf ------------------------------------------------------------------------ IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT: transp_support, Princeton University transp_support@pppl.gov