README file for PREACT Module Prepared by C.Ludescher-Furth -- 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. FINAL INSTALLATION 7. RE-INITIALIZING REACTION TABLES 8. DOCUMENTATION ************ 1. CONTENTS: ************ This directory should contain the following files: README_Preact: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing the preact library libpreact.a and its test drivers testpreact and testf77layer. 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 adpak: Makefile Sources to build libadpak.a, an internally used library to calculate ionization and radiation rates. -- in subdirectory aladdinsub: Makefile Sources to build libaladdinsub.a, an internally used library for Aladdin format. -- in subdirectory comput: Makefile Sources to build libcomput.a, an internally used library with transformation/interpolation routines. -- in subdirectory cppsub: Makefile Sources to build libcppsub.a, a fortran-c++ wrapper -- in subdirectory fpreproc: Python scripts for fortran pre-processing. -- in subdirectory fpreact: Makefile Sources to build libfpreact.a, the f90 interface. -- in subdirectory include: ALCOM Common block for Aladdin cross-section database. ALPCOM Common block for Alpack standard Aladdin entry parsing. SIGTABL Common block for cross-section computation routines. SIGTABL_Z Common block for modified cross-section computation. ULOGICAL Common block for 'UREAD' logical function declarations. -- in subdirectory include/fpreproc: *.h files for source pre-processing. -- in subdirectory include/preact: *.h Interfaces for F77 reaction routines and Macros for reaction classes. -- in subdirectory portlib: Makefile Sources to build internally used portability library libportlib.a. -- in subdirectory preact: README: Copy of README_preact Makefile To compile libraries and programs ORNL6086.DAT Aladdin cross-section data. USERGUIDE Detailed description of code. Sources to build the library libpreact.a *.cpp Implementation of reaction classes *_z.f Modified sources from TRANSP comput and sigsub icode_preact.f Return code. Sources for programs: fpreact_test.f90 Test driver for F90 layer atop PREACT module. preact_change.cpp Changes the parameters of a reaction table. preact_init.cpp Initializes table parameters for each reaction. preact_list.cpp Lists table parameters for a particular reaction. testpreact.cpp Test driver for F77 layer atop PREACT module. testf77layer.f Test driver for PREACT module. preactinit Script clears and re-initializes reaction tables. fpreact_test.output Sample output from fpreact_test -- in subdirectory prefpp: Makefile Sources to build prefpp and postfpp, the Fortran pre- and post-processors. -- 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 sigsub: Makefile Sources to build libsigsub.a, an internally used library with cross-section routines for atomic and nuclear reactions. ************************** 2. UNPACKING INSTRUCTIONS: ************************** 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: ./adpak -- to calculate ionization and radiation rates ./aladdinsub -- ORNL Atomic Physics Data Center ./comput -- low level TRANSP routines ./cppsub -- fortran c++ wrapper ./fpreproc -- scripts for pre-processing of fortran ./include -- include files for sigsub and alladinsub ./include/preact -- *.h files for preact ./include/fpreproc -- *.h files for cpp ./portlib -- internally used portability library ./preact -- sources and Makefile ./prefpp -- Fortran pre/post processor ./r8slatec -- double precision "Fullerton" functions ./share -- include file Make.flags, Make.local.sample ./sigsub -- atomic/nuclear cross sections integration The makefile will create more sub directories, ${OBJ}/lib for the libraries ${OBJ}/obj/* for compiled objects and pre-processed sources ${OBJ}/test for the test programs and utilities ${PREACTDIR}/data for Aladdin cross-section data. ${PREACTDIR}/tables/* Directory structure for precomputed reaction tables. You must define the environment PREACTDIR. The data and tables are independent of architecture, so everyone can access the same tables. By default ${OBJ} is ./, 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/... Note: ${OBJ} is platform dependent, whereas ${PREACTDIR} is not. 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: ************************* >>> Note <<< To compile this code, you'll need gcc 3.X or a reasonable C++ compiler. Building libraries, proprams and tables --------------------------------------- Choose or create the root directory where you wish to build the Plasma Reaction Tables. Set the environment variable PREACTDIR to be the full pathname of the directory where the Tables will be stored. The Makefile will initialize the Tables after buiding the test programs. From the top directory (where you extracted the {tar,zip} file): > gmake -- to compile libraries, link all test programs and initialize tables > 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" 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 Note: By default the test programs, nubeam_test and nubeam_driver, are linked with lf95. If you encounter a problem, try linking with g++: > gmake USEFC=N Compiling on Alpha Linux: ------------------------- The Makefile assumes the Compaq compiler and specifies the " -assume no2underscores " option. Therefor 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. Therefor 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: preact_change Changes the parameters of a particular reaction table. preact_init Initializes table parameters for each reaction. preact_list Lists table parameters for a particular reaction. testpreact C++ test driver for PREACT module. testf77layer Test driver for F77 layer atop PREACT module. fpreact_test F90 test driver using the fpreact interface. fpreact_test.output Sample output of fpreact_test To run tests: ----------- (a) If PREACTDIR was defined during Step 4. go to (b). If you did not define PREACTDIR during step 4., you must now define it and manually initialize the Tables with cd /test preactinit (b) Test cd /test - to run the C++ test driver ./testpreact - to run the fortran test driver ./testf77layer Both programs perform identical tasks, creating/reading a subset of tables. The 1st time run, it will be slow, since the tables have to be created. The 2nd time should be quite fast, since it is only reading. - to run the fortran 90 test driver ./fpreact_test This program is similar to the other two. You can compare the output (when run the 2nd time) to fpreact_test.output. For details see USERGUIDE, included in this distribution. ********************** 6. FINAL INSTALLATION: ********************** There are two distinct parts to be installed: -> The Plasma Reaction Tables (in ascii format) in $PREACTDIR. -> The architecture dependent libraries and utilities in $PREFIX. (a) $PREACTDIR Choose or create the root directory where you wish to build the Plasma Reaction Tables. Set the environment variable PREACTDIR to be the full pathname of the directory where the Tables will be stored. For example, if you want to keep it in a subdirectory 'preact' of your home directory, then you should define PREACTDIR $HOME/preact. The tables will be created in: $PREACTDIR/data $PREACTDIR/tables/{cx,ii,fs}/*/* Note: The installation is not going to build all the tables, it is only creating a scelleton. The Tables will be created on demand. Therefore PREACTDIR must grant write access to all potential users. (b) $PREFIX Choose or create the root directory where you wish to install the libraries, executables and man page. Common locations would be $HOME/ or /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 executables in: $PREFIX/bin = $BINDIR scripts in: $PREFIX/etc = $ETCDIR 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 BINDIR=yyy MANDIR=zzz NOTE: ----- Users should link with: -L/lib -lpreact -lsigsub -laladdinsub -lpreact -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. ********************************** 7. RE-INITIALIZING REACTION TABLES ********************************** To initalize new tables, you can run the script preactinit. You need to provide the location of the Aladdin cross-section data, ORNL6086.DAT, that came with the package in the preact directory. 1. define $PREACTDIR (see Section 6. FINAL INSTALLATION) 2. run preactinit preactinit will run preact_init, so if both are in your PATH, type: > preactinit DATA If preact_init is not in your PATH, type > preactinit DATA $HOME/ntcc/preact PATH for options see also: > preact help Note: you can re-use ORNL6086.DAT from a previous installation, by specifying "DATA /data" ************************ 8. DOCUMENTATION: ************************ See USERGUIDE, part of this distribution. PREACT Home Page: http://w3.pppl.gov/NTCC/PREACT NTCC Home Page: http://w3.pppl.gov/NTCC ---------------------------------------------------------------------------- IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT: transp_support, Princeton University transp_support@pppl.gov