CHAPTER 3: Installation of

 
• 3.1 What is required ?
• 3.2 Unpacking sciatran_v1.2.tar.gz
• 3.3 Generating the executable file SCIATRAN_*.exe
• 3.4 Running the program
• 3.5 Was the installation successfull?

3.1 What is required ?

SCIATRAN has been developed in FORTRAN 77 on IBM Risc 6000 workstations under AIX using the AIX XL FORTRAN Compiler/6000 and on SUN Ultra Sparc workstations under Solaris. SCIATRAN has also been tested on CRAY J916 under UNICOS, and on a DEC Alpha running OpenVMS AXP (TM) V6.1.

Installation of SCIATRAN on a UNIX system might be easy using UNIX unzip and tar commands and the GNU Make program.

1. users_guide_sciatran_v1.2.ps (A postscript version of this guide)
2. READ.ME.x file containing important ``last-minute'' information and a listing of all bugs found so far, if possible including links to software fixes or workaround solutions (x is an integer indicating the version number of the READ.ME file).
3. sciatran_v1.2.tar.gz (SCIATRAN as compressed (zip) tar file)
4. tar.gz_to_sciatran_v1.2.sh (unzip-untar UNIX ksh script)

sciatran_v1.2.tar.gz is a compressed tar file containing the entire SCIATRAN program (possible exception: large data base files which might be stored separately). This comprises several subdirectories with FORTRAN source files (*.f), a GNU-Makefile, UNIX Korn shell scripts (*.sh), user input files (*.inp) and several other files including all necessary input and test data for SCIATRAN.

3.2 Unpacking sciatran_v1.2.tar.gz

Invoking tar.gz_to_sciatran_v1.2.sh creates the SCIATRAN main directory VERSION1.2/ just below the current directory including all necessary subdirectories. Just type

Directory VERSION1.2/ should now have been created and should contain the following subdirectories:

Execute/	docu/	tests/
tools/	data/	lapack/
loadmaps/

3.3 Generating the executable file SCIATRAN_*.exe

In order to complete the installation process the following steps have to be performed:

1. Make ~/Execute/ to your current directory:
   cd VERSION1.2/Execute

2. Several NUMERICAL RECIPES subroutines and functions dealing with numerical algorithms, like matrix inversion etc., have NOT been included in this package due to copyright issues:

   The following NUMERICAL RECIPES Fortran 77 routines [34] have to be compiled in file gt_utilities_nr.f in directory ~/Execute/ (again: this file and the corresponding routines that are assumed to be contained in this file are not included in the SCIATRAN Version 1.2 package):

   SUBROUTINE GAULEG
   SUBROUTINE LUBKSB
   SUBROUTINE LUDCMP
   SUBROUTINE MPROVE
   FUNCTION DFRIDR
   FUNCTION PLGNDR

3. If GNU Make is available, compilation and linking of SCIATRAN could be done nearly automatically (provided the numerical libraries exist as well). Simply type:

   make (or "gmake": depending on your system )

   in subdirectory Execute/ in order to compile all subroutines and link them to the executable file (SCIATRAN_*.exe) in subdirectory Execute/.

   Note that by typing

   make debug=true

   an (non-optimised) executable compiled with the -g flag is created for source code debugging purposes (executable name SCIATRAN*_dbx.exe).

   If GNU Make is not available the information contained in the Makefile should allow the user to perform this exercise ``by hand'' or by making the GNU Makefile compatible with the local Make system.

4. After having successfully performed steps 1. to 3. ~/Execute/ should contain the executable file (SCIATRAN_IBM.exe or SCIATRAN_SUN.exe or SCIATRAN_CRAY.exe).
5. Six user input files are necessary to completely specify all SCIATRAN input parameters. These files are read by the SCIATRAN main program GT_IFACE which sets up all input parameters required for the main SCIATRAN subroutine GPP_MASTER. GT_IFACE is essentially the interface to the SCIATRAN core routine GPP_MASTER.

   Two user interface files have predefined filenames:

   control.inp and control2.inp.

   control.inp is the main user interface file. control2.inp contains only those input settings which are not supposed to change frequently, e.g., convergence critera. Both files have to be located in the current directory (usually Execute/). These ASCII files have to be edited manually in order to set several switches (e.g., trace gas selection, scattering mode), and to set various computational parameters, to specify the wavelength range of interest, etc.

   Four other input files are necessary (usually in subdirectory Execute/):

   • One deals with aerosol settings
     (see sample files: low_aer.inp for the LOWTRAN aerosol scheme or
     scia_aer.inp for the GOMETRAN/SCIATRAN aerosol scheme),
   • one with the internal altitude grids
     (see sample file: gt_net.inp),
   • one with trace gas absorption cross sections
     (see sample file: xsections.inp).
   • and one deals with ESFT data bases
     (see sample file: esft.inp).

   Filenames (incl. path, if required) of these three files have to be specified in control.inp. The structure of these files is identical with the structure of the ``control''-files, i.e., mainly key words followed by parameters that can be modified by the user (details see chapter 4).

   Before the program can be executed the user has to set the appropriate paths in control.inp (x-section files, altitude grid files, etc.; see corresponding key words, for example `` X-section path''. Please note that this has to be done also for all input files (control.*) necessary to run the predefined test sequences described below. Note that for convenience all paths and filenames are set in control.inp.

   The SCIATRAN internal altitude grids (``net'') stored in NET*.DAT files and the corresponding settings in gt_net.inp have been optimised and usually need not to be changed. However, how good these altitude grids are depends on several items. Therefore, the user has to check carefully if the predefined grids are appropriate for his/her specific application (diagnostic: spectral radiance jumps at net boundaries, i.e., at the specific wavelength where one net range finishes and the next net becomes valid, see gt_net.inp file). In general the distances between the atmospheric levels have to be ``sufficiently small'' (diagnostic: further decreasing the distanc between levels should not significantly change the results).

   Six control.* files are included. One file in Execute/ and five files for test purposes in directory tests/.

3.4 Running the program

After SCIATRAN has been sucessfully installed the program can be executed by typing, for example on SUN,

in ~/Execute/ after the required input settings have been selected in the user interface files (mainly control.inp and low_aer.inp or scia_aer.inp).

If a directory different from ~/Execute/ should be used to run SCIATRAN this is, of course, possible. Call SCIATRAN with the appropriate path or set a convenient alias or link.

Only the user interface files control.inp and control2.inp are locally required, that is, they have to be in the current directory. File control.inp should contain the (absolute or relative) paths to all other input files (trace gas absorption cross-section files etc.).

Important note concerning the memory requirements for SCIATRAN: It might be necessay to increase or to decrease certain constants which determine the maximum length of arrays used in SCIATRAN, e.g., the maximum number of spectral points or altitude levels. These constant are specified in the *.PARS files located in directory ~/Execute/.

Selecting smaller values might be necessary to significantly reduce the required memory. Note: especially max_gt_strms (maximum number of ``streams'', see annexed mathematical description), max_gt_layers (maximum number of altitude levels) and max_gt_specpts (maximum number of spectral points), which are specified in GOMETRAN.PARS, significantly determine the size of the required memory.

Once one of these parameters has been changed the program has to be recompiled and linked using the GNU-Makefile (type: make in directory ~/Execute/).

Note that even if max_gt_specpts is a rather small number it is possible to create output files containing much more spectral points without starting the program more than once. The program automatically splits the wavelength grid into packages of up to max_gt_specpts spectral points and processes one package after the other. This, however, requires to read all input data from scratch for each package to be processed.

3.5 Was the installation successfull?

In order to check if SCIATRAN has been correctly installed some reference input files have been defined and some reference output files created (on SUN !). All relevant test input and output files are located in directory /tests/.

1. Use control.ref as input file (save the original control.inp file, e.g., as
   control.ori):

   cp ../tests/control.ref control.inp

   Note that the paths specified in control.inp might have to be adjusted.

   Please note that this test run and also the test sequence described below will use the following user input files which already exist in Execute/ as well as in tests/:

   control2.inp
   low_aer.inp
   xsections.inp
   gt_net.inp
   esft.inp

2. Execute SCIATRAN:
   SCIATRAN_SUN.exe on SUN or
   SCIATRAN_IBM.exe on IBM or
   SCIATRAN_CRAY.exe on CRAY

3. Now the following files should have been created:

   intensity.dat

   radiance.dat

   weightfn.dat

   tg_amf.dat

   tg_vod.dat

   SCIATRAN_SCENARIO.OUT

   AEROSOL.OUT

   errors.log

4. The contents of these files should be essentially identical with the corresponding ~/tests/*.ref files (note that the numerical results may differ somewhat depending on the computer system used).

   A comparison can easily be made using the UNIX diff command. Type, for example

   diff intensity.dat ../tests/intensity.ref

5. To perform some more comprehensive tests the following Korn shell script can be used:

   ksh ../tools/sciatran_test.sh

   This script essentially copies the ~/tests/control.t0* files into the current directory (as control.inp!) and starts SCIATRAN.

   Please note again, that you have to adjust the paths specified in the ~/tests/control.t0* files.

   The script performs four tests based on the ~/tests/control.t0i (i = 1,..., 4) input files. After each execution of SCIATRAN the corresponding intensity.t0i reference files in ~/tests/ and the newly generated intensity.t0i files in ~/Execute/ are compared using the diff command. All output files are stored in the current directory (i.e.  ~/Execute/) and contain the extension of the corresponding test sequence (i.e.  ~/Execute/*.t0i).

   For all tests the basic scenario is the same. They only differ in wavelength settings, scattering mode selection, and w.r.t. clouds (clouds are only present in test number 4; this test is the most time consuming).