README file for Nubeam Module Prepared by C.Ludescher-Furth -- transp_support@pppl.gov 03/25/02 **************** REVISION HISTORY **************** date Description Mar 25, 2002 -- Created Oct 01, 2003 -- Added nubeam_driver Jan 11, 2009 -- replaced nubeam_driver with (mpi_}nubeam_comp_exec for parallel build define MPI_ENABLE=1 ---------------------------------------------------------------- Index: 1. CONTENTS 2. UNPACKING INSTRUCTIONS 3. DESTINATIONS 4. BUILDING INSTRUCTIONS 5. TESTING INSTRUCTIONS 6. DOCUMENTATION 7. FINAL INSTALLATION ************ 1. CONTENTS: ************ The directory into which nubeam{zip,tar.gz} was extracted, should contain the following files: README_Nubeam: This file. Brief descriptions of the other files, and instructions for compiling, testing and installing the nubeam library libnubeam.a and its test drivers test_nubeam and geqxpl{2} and the utility plot_nubeam. 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 fpreproc: Python scripts for fortran pre-processing. -- in subdirectory include/fpreproc: *.h files for source pre-processing. -- in subdirectory kdsaw: Makefile Sources to build kdsaw.a, an internally used library for the ideal Kadomtsev Sawtooth Model. -- in subdirectory nbdebug: Makefile Sources to build nbdebug.a, a library for nubeam_test -- in subdirectory nubeam: README: Copy of README_nubeam UserGuide Makefile, Make2 Sources to build the library libnubeam.a Source for test program: nubeam_test.f90 Sample input/output files for nubeam_test: *.ind, sample_run_*, *.cdf Sample input/output files for nubeam_driver: *.CDF, nubeam*.dat, nubeam*.ref -- in subdirectory nubeam_comp_exec: README, README_PPL Makefile, Make2 Sources to build nubeam_comp_exec and mpi_nubeam_comp_exec Sample input/output files scripts for testing -- in subdirectory nubeam_comp_sub: Makefile Sources to build nubeam_comp_sub.a, library for nubeam_comp_exec -- in subdirectory portlib: Makefile, Make2 Sources to build internally used library libportlib.a. -- in subdirectory prefpp: Makefile Sources to build prefpp and postfpp, the Fortran pre- and post-processors. -- in subdirectory r8slatec: Makefile Sources to build libr8slatec.a, an internally used library with double precision "Fullerton" functions. -- in subdirectory random: Makefile Sources to build librandom.a, an internally used library to generate random numbers. -- 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 xstraln: Makefile Sources to build libxstraln.a, an internally used library for straight line tracker. And for Test Program: -- in subdirectory trgraf: Makefile and sources to build libtrgraf.a, a display library. -- in subdirectory ureadsub Makefile and sources to build libureadsub.a, an input interface. ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip nubeam.tar.gz > tar xvf nubeam.tar or, for zip archives: > unzip nubeam.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: ./cdf_dummy -- dummy netcdf library ./elvislib -- interface for trgraf ./fpreproc -- scripts for pre-processing of fortran ./frantic -- 1d neutral gas transport calculation ./get_fbm_kernel -- for get_fbm ./get_fbm_xplasma -- get distribution functions ./hdf_dummy -- dummy hdf library ./include/fpreproc -- *.h files for cpp ./interp_sub -- linear or bilinear interpolation of gridded data ./kdsaw -- Kadomtsev Sawtooth Model ./mds_sub -- interface to mdsplus ./nbdebug -- routines for nubeam_test ./nubeam -- Monte Carlo package of fast ion species in tokamaks ./nubeam_comp_exec -- nubeam driver and test samples ./nubeam_comp_sub -- routines for nubeam_comp_exec ./plasma_state -- representation of fusion plasma MHD equilibrium ./plasma_state_kernel - for plasma_state ./plot_fpreact -- data plotting routines ./portlib -- portability routines ./ps_xplasma2 -- plasma state / xplasma interface ./r8slatec -- Fullerton functions ./random -- random number generator ./rfxqlo -- Fokker Planck / wave solver interface ./rfxqlo_helper -- ./share -- include file Make.flags, Make.local.sample ./sglib -- graphical library for test programs ./trgraf -- display routines for test program ./ureadsub -- input routines for test program ./xstraln -- xplasma based straight line tracker The makefile will create more sub directories, lib: for the library, libnubeam.a 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 Compilers: =================== Fortran 90 or 95 C and C++ >>>>> you need gcc 3.X or a reasonable C++ standard Required Libraries: =================== libxplasma.a -> NTCC module Xplasma libpspline.a -> NTCC module PSPLINE libpreact.a -> NTCC module PREACT lapack - Linear Algebra PACKage blas - Basic Linear Algebra Subprograms netCDF - network Common Data Form fftw - fast fourier transforms For nubeam_driver: trread.a -> NTCC module TRREAD Optional Libraries: =================== readline, history, termcap for Command Line Editing Note: if not all three libraries are installed you must define NO_EDITLIBS e.g.: gmake NO_EDITLIBS=Y Check with your systems administrator where these libraries and modules are. lapack, blas, fftw, netCDF --------------------------- lapack, blas, fftw 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, xplasma and preact --------------------------- If your site already has pspline, xplasma and preact libraries installed, specify their location (library and modules) with PREFIX, e.g. "gmake PREFIX=/usr/ntcc" At PPPL these libraries are in $NTCCHOME Note: If you don't have all required NTCC libraries, you may download them together into the same work directory. The Makefile will build them all in one step. Building libraries and programs -------------------------------- > 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 To compile the MPI version, define environment MPI_ENABLE e.g.: setenv MPI_ENABLE 1 Compiling on Linux: ------------------- By default the Makefile will select LaheyFujitsu. To select a different compiler define FORTRAN_VARIANT to "Portland" "PathScale" " GCC" "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 Note: some test programs are linked with g++; to find the Fortran libraries, you need to define FLIBROOT e.g. export FLIBROOT=/usr/pppl/lf64x/lf6480 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. 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. ************************ 5. TESTING INSTRUCTIONS: ************************ directory $OBJ/test -or- /test will contain the following nubeam related files: For nubeam_test: ---------------- sample_run.csh : script to run nubeam_test nubeam_test : test driver for nubeam sample_run.ind : controlling input script for nubeam_test sample_run_output.ps : output from "nubeam_test @sample_run" in PS format sample_run_output.txt: output from "nubeam_test @sample_run" in text format sample_run_alpha.txt : output from "nubeam_test @sample_run" from a Alpha Linux machine in text format For {mpi_}nubeam_comp_exec --------------------------- See nubeam_comp_exec/README and README_PPL To run tests: ============= define environment variable TERMINAL_TYPE = XTERM (e.g. export TERMINAL_TYPE=XTERM) Also, the location of the fusion reaction tables, PREACTDIR, must be defined and the tables must be initialized. See http://w3.pppl.gov/NTCC/PREACT or preact/USERGUIDE and REDAME (included in the preact module). cd /test nubeam_test ----------- ./nubeam_test @sample_run This will produce a canned sequence of plots. This is the same set of plots that is stored in sample_run_output.ps (e.g., running ghostview on sample_run_output.ps should produce identical plots.) You can also run: ./sample_run.csh This will produce the PS file,foo.ps and a text file foo.txt. foo.ps can be compared with sample_run_output.ps, and foo.txt with sample_run_output.txt. For instructions on how to use the library routines in your own code see UserGuide on the web http://w3.pppl.gov/NTCC/NUBEAM or http://w3.pppl.gov/~pshare/help/nubeam.htm ************************ 6. DOCUMENTATION: ************************ NUBEAM Home Page: http://w3.pppl.gov/NTCC/Nubeam 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 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 MANDIR=zzz NOTE: ----- To link a program, you need all nubeam, xplasma, pspline and preact libraries. e,g: -L/lib -lnubeam -lkdsaw -lxstraln -lfpreact -lpreact \ -lsigsub -laladdinsub -lxplasma -lfluxav -lmclib -lsmlib -ltridiag \ -lr8bloat -lpspline -lezcdf \ -lcomput -lvaxonly -lr8slatec -lrandom -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