|
|
IV. Step by Step Installation and Testing Instructions.The reader is assumed to have some programming ability-- especially if building the code for the first time on a new type of system or under a new fortran compiler. It is assumed that the TRANSP environment has been defined (as per the preceding section), and that a copy of the TRANSP sources has been obtained. If so, TRANSP can be built and tested by using the recipe that follows. 1. Select WORKSTATION_TYPEIf you were able to set WORKSTATION_TYPE to one of the known machine types given in the previous section, skip ahead to step 2. IF YOUR MACHINE IS NOT ONE OF THE KNOWN MACHINES in the list given in the previous section as possible definitions for the WORKSTATION_TYPE environment variable... you may have to fix various scripts in order to get the code to compile and load correctly. WARNING -- you may be starting down a long and winding road, if you are setting out to bring up TRANSP on a new type of machine. That is, the code and scripts will have to be ported to the new machine type. Please consult with Doug, dmccune@pppl.gov, for advice. The reason the environment variable WORKSTATION_TYPE is needed is that different workstations have different versions of system software (f77, cc, ld, ps, ... ) which required different control switches to work properly, in the context of a TRANSP build. As an example of machine dependence, the script codesys/csh/tcomp is used for all code compilations -- to set up compiler switch settings as needed by your workstation's C and Fortran compilers. Note: in 1999, tcomp invokes a subprocedure, "Default_options", to get the system-dependent compiler switch settings. NB dmc 17 Jun 1993 -- the following scripts also contain workstation dependent code (list may not be complete):
all triggered by testing the environment variable WORKSTATION_TYPE which should be defined at login time. There may be others. Search the codesys/csh directory for occurrences of the string WORKSTATION_TYPE. In trying to build the system on your machine you may have to iterate on these changes. When you have a set of valid customizations for your machine, (if you have a cvs installation of transp) please cvs commit your changes so that others with your machine type might benefit in the future. Please also send Email to dmccune@pppl.gov so that we may credit your accomplishment of bringing up TRANSP on a new type of workstation (and update this document). Note: transp includes a program "errfilter" which is used to filter messages from a cvs update job to produce a report suitable for mailing. This program contains workstation-dependent code. If you are running a cvs installed transp and you want to receive regular updates from PPPL, you may want to modify this program to improve the editing of update reports on your machine. However -- this activity need not be done on day 1. 1b. Test the compiler settings.The command below runs a quick ( but not exhaustive ) test of the environment, displaying the compiler options selected. If this does not create the file $TMPDIR/test_for.o, then seek help ; nothing else is likely to work. %tcomp -v $CODESYSDIR/source/tcomp_testlib/test_for.for $TMPDIR/test_for.o %csh/tcomp -I- option_string = -v tcomp% -I- running on LINUX tcomp% -I- FORTRAN_VARIANT = Fujitsu tcomp% -I- cppargs = -undef -D__LINUX -D__F90 -D__FUJITSU -D__UNIX -D__NOMDSPLUS -I/u/pshare/transp_versions/Fuji_90_04/codesys -D__NODLINES tcomp% -I- f90opt = ff95 -c -O -f1444,2004,2006,2008 -X9 -Kfast -Kfap -Am -Nallextput -I/u/pshare/transp_versions/Fuji_90_04/codesys -I/usr/local/include -I/home/pshare/transp_versions/Fuji_90_04/codesys/obj/tcomp_testlib -I/home/pshare/transp_versions/Fuji_90_04/codesys/mod%tcomp -v $CODESYSDIR/source/tcomp_testlib/test_f.f $TMPDIR/test_f.o The standard compiler options for all supported systems are defined in $CODESYSDIR/source/System_options. These may be overridden if required, by creating a file $CONFIGDIR/User_options :- #... config/User_options - sourced from tcomp # set JET user options # jconboy@jet.uk 19Sep2000 #---------------------------------------------------------------------------------- # set cppargs_f90 = "$cppargs_f90 -D__JET" # end User_Options 1c. Local makefile switchesSome transp executables are built with a makefile distributed as $CODESYSDIR/source/<name>/<name>.mk , rather than a makefile constructed by the code generators. These makefiles access flags defined in $CODESYSDIR/source/misc/makeflags.mk, which may be overridden by local definitions from $CONFIGDIR/Make.local - eg
The settings of all flags may be displayed :- >make -f source/misc/flagtest.mk flagtest ------------------------------ flagtest results: FORTRAN_TYPE = 95 FORTRAN_VARIANT = LaheyFujitsu ...general: LIBROOT = /home/pshare/transp_versions/La_95_02/usr.local PREFIX = LIBDIR = /lib BINDIR = /bin ETCDIR = /etc INCLDIR = /include MODDIR = /mod MANDIR = /man LLOC = ...fortran: FC = lf95 FC90 = lf95 .... Check these definitions before attempting to build the codes. 2 Single precision nag library.This is no longer required 3. Basic TRANSP kernel -- makefile generator and portlib.To build this part of the code, ensure that the environment variable LOADER_TRAILER is undefined, or an empty string, then enter the command % make_begin Makefiles needed to build this "kernel" were supplied by the "install.csh" script when the TRANSP source code was originally downloaded. After running make_begin, you should find >ls $TRANSPROOT/codesys/exe cinclud errfilter finclud ftxtrac moduse nfilter sfilter >ls $TRANSPROOT/codesys/lib generic_dummy.a mclib.a portlib.a vaxonly.a If errors occur at this stage do not continue. Seek help from a PPPL TRANSP expert. 4a. External LibrariesBefore starting to build the transp codes, the auxilliary libraries not part of the core transp distribution should be obtained. Note that libraries containing fortran code must be compiled with the same fortran compiler as will be used for the transp codes..
Note that the location of sglib is built into application makefiles as $TRANSPROOT/other/libsg.a The environment variables $F90_INC, $C_INC, $CXX_INC are availabe to indicate the location of module and include files for external packages - use of these variables at JET is shown here. If any of the libraries is built as shared object ( .so ) then their location should be added to the library search path ( eg to $LD_LIBRARY_PATH for Fujitsu fortran ) 4b. SG scientific graphics library.Build and test this library in accordance with instructions in codesys/sglib/README paying attention in particular to the definition of the environment variable TERMINAL_TYPE. SG must be working in order to use interactive TRANSP support software. For more information on SG, contact Douglas McCune at PPPL (dmccune@pppl.gov). When testing of sglib is complete, use the command % make_sglib to make a clean copy of sglib and cleanup the sglib source directory. [ If make_sglib can't be found, you will have to "rehash" first ( a csh builtin command).] make_sglib is a shell script in $CODESYSDIR/csh. It delivers the completed sglib to $LOCAL/other/sglib.a, where it is expected to be found by subsequent code build procedures. 5. Build transp codesYou are now ready to generate the make files and compile the TRANSP code. Note again that with the advent of XTRANSPIN, one must use the GNU "make". This job will require many hours to execute -- depending on the speed of your system and compiler software. For us it takes about 3 hours on a modern DEC ALPHA workstation. [ Before running make_it_all, you may optionally run the script $SC/prebuild - this will attemt to build the executable tcomp_test, which is written to use most of the external libraries, & can detect many problems with the transp environment. See source/doc/prebuild.doc for more information. ] % make_it_all >& $LOGDIR/make_it_all.log & will compile the entire TRANSP code (and all related software), with a record of the results stored in the indicated file. The make_it_all script is in the file $CODESYSDIR/csh/make_it_all in the same directory as many other executable c shell scripts. When the job completes, the log file should be studied carefully for errors. On our system, compiler warnings about "statement function never used" or "no path to this statement" appear occasionally, because of stubs of debug code and the like that appear in the sources. Certain other warning messages may be ignorable. However, other errors are not normal. All compiler and loader errors should be fixed before proceeding. The linkcheck procedure reports how many library and code builds were attempted, and how many failed ; search the log output for the string %linkcheck to find these messages. You should inform us of source code changes to make the code more portable. (If you have an cvs installation you may install portability improvements yourself and cvs commit these back to the pppl repository; for information on this see $CODESYSDIR/doc/transp_share.doc). Note -- if make_it_all has just completed, you may want to issue the command % rehash to make sure that all executable programs in $LOCAL/exe are made available to you as commands. Then, if the program errfilter has been upgraded to support your brand of workstation, then the command % errfilter <$LOGDIR/make_it_all.log | more will give a quick way to review your compiler errors. The errfilter program should filter out "normal" compiler output, letting through only error messages. (In this example, messages from the make file generators cmsmms and makelink also get through). To relink an individual program (rplot, for example) use the command % uplink rplot This will recompile any modified sources, rebuild any modified subroutine libraries, and relink rplot if any source has been updated (i.e. uplink runs a make on just the rplot program itself). If based on $LOGDIR/make_it_all.log you think that the make file generator ran successfully, but there is an error compiling and loading programs (e.g. because nag or sglib were not built), then the command % linkcheck will run makes on *all* libraries and programs, but without regenerating any make files. When all programs have been linked, testing of the TRANSP system becomes possible. [6. Build the TRANSP atomic / nuclear physics database.][this section has changed -- dmc 29 Jun 2001]. The environment variable PREACTDIR needs to be defined at login time; typically one should use "setenv PREACTDIR $TRANSPROOT/preact" No other action is required. The `make_all_tables' script does not have to be run; the new `preact' module installed in TRANSP will create reaction rate table data as needed. The module binaries were built and the preact data system initialized in `make_it_all'. 7. Running the Ufiles SG demo.The TRANSP export package includes sample tokamak data (TFTR shot 37065, 1988). Canned examinations of some of this data are available by doing % cd $TRANSPROOT% cd data/TFTR/test -- move to the directory containing the test data% ugraf1 @ugraf1.demo -- plot the surface voltage% ugraf2 @ugraf2.demo -- plot the ECE electron temperature More extensive explorations of the Ufile data can be made by using ugraf1 and ugraf2 interactively. (If you have problems here you may want to check again that SGLIB is working -- step 3 above). A hardcopy manual describing Ufiles is available from D. McCune at PPPL. 8. Running the rplot demo on 37065Y01-- one of TRANSP's regression test datasets. The output files for this TRANSP run are included with the data downloaded during the transp installation process.
Another set of plots can be produced with:
("rplot.demo" and "mctest.tmi" are scripts which drive the command line interactive fortran program rplot). For a more extensive investigation of the output, run rplot interactively. 9. Running the TRANSP test case 37065Z01.The TRANSP export package contains everything needed to create a small, fast TRANSP run. To make this run, do the following:
On 2005 commodity hardware the run requires less than an hour to complete. When the run completes, a sampling of plots from the run can be produced as follows:
The plots should closely resemble those of 37065Y01 (cf step 8) but will not be identical due to the use of Monte Carlo simulation with modest statistics. 10. (Optional) -- additional test runs.The TRANSP distribution now includes "regression" test cases. The reference cases, along with suggested rplot scripts for examination of output, can be found in $CONFIGDIR/regression.dat; each field in this file contains records of the form: <tok> <yy> <runid> <script-name>. For example, TFTR 88 37065Y01 mctest.tmi refers to TRANSP run $RESULTDIR/TFTR.88/37065Y01* and the rplot driver script $RESULTDIR/TFTR.88/mctest.tmi ... one can rerun the run by using "activate" as described in the previous steps, selecting a new runid for the rerun case. Then, rplot <runid> @mctest will produce a series of plots, which are expected to be quite similar but not necessarily identical to the sequence from rplot <original-runid> @mctest Suggestions for additional regression tests can be sent by email to transp@pppl.gov. Note: ALL regression tests can be run, sequentially, by entering the command: run_all_tests (this will take several HOURS to complete execution). |