Chapter 2

File structure and initial configuration

This section describes the directory file system for the portable version of the NCEP RSM. The purpose of the directories is explained with its files. A step by step procedure to configure the system is illustrated for installation and initial setup. After you obtain the system from the description in the chapter 1. We can start to explore what you should have in your unix file system.

2.1 Current file directory structures

Let's assume that the disk directory you do un-tar your entire system is called /disk/f97, for simplicity, we call it $DISK. Under $DISK, you should have three directories so far, one is $DISK/common, another one is $DISK/[machine], the other one called $DISK/input. The directories under can be described as

We follow the syntax of the unix file system, a name with a '/' indicates it is a directory. Where [machine] can be replaced by dec, hp, sgi etc. The common/ contains all the machine independent files, the [machine]/ contains all machine dependent files and some of them have to be initialized, the input/ directory will put any input data you want, such as example for daily data, or others.

After you configure the initial system and run an experiment, the script will create some additional directories

where [experiment_name] can be g2n97, or g2r97 etc under $DISK/[machine], [any] can be any routine name etc. The run/ is the place your experimental product, dirrun/ contains running time input and output etc, exec/ contains all the program files, executable files, and their make files, rmtn/ contains the mountain related data for this experiment, output/ is the place contains all the necessary output files for you to do display and further computation. The tmp/ is a VERY temporary place, it exists when you do the compilation, it can be deleted any time afterwards. We assume that you have a larger disk space for tmp/ instead of using system tmp/, which is usually fixed size and cannot be easily expanded.

In summary, there are 3 main directory levels. Under the directory $DISK there are five subdirectories, the common/ with machine-independent file system, the [machine]/ with machine-dependent file system, the input/ with all initial input data etc, run/ with all experimental related output file system, and the tmp/ with all temporary files for compilation.

2.2 Contents in each directory

This section will describe the purposes and contains of each directory we have illustrated in the previous section one by one, especially the last level of the file system.

$DISK/common/co2gen/

This is a place contains all the formatted co2 data for prepared by $DISK/[machine]/condata/makeco2const.s. Inside this directory, there should have files called:

CO2CNEW         : main program
CONSTANT       : definition of constants
DCLFCST          : definition of dimension
DCLFULL          : definition of precision
DCLS18              : example of definition with 18 layers
DCLS28              : example of definition with 8 layers
DCLSIGL           : definition of how many layers
MDLDSIG          : definition of all the sigma layer depth
MODLS18          : example of the definition of 18 sigma depth
MODLS28          : example of the definition of 8 sigma depth
cns_350_490670
cns_350_490850   : the three co2 concentration values dataset
cns_350_670850

$DISK/common/definition/

This directory contains all the necessary definition for compilation used by all the experiments. There are several groups, the first group for definition of model dimension, its form is DC?????, for example DC12628, DC6228, DC12618, and DC6218, the second group is for input dimension of model change resolution, its form is DCI?????, say DCI12628, DCI12618, DCI8018 etc, the third group is for output dimension of model change resolution, it has form as DC?????O, say DC12618O, DC6228O, DC4012O etc, the forth group is for definition of the computed dimension using any of the first to third group, it has form as DCL?????, say DCLFCST, DCLRBLN etc, the fifth group is the model sigma depth definition, it has form as MODLS??.

$DISK/common/docblock97/

This directory contains most of the NCEP type of documentation block, all the filenames start with DB are for global and model physics and those start with DR are for regional routines' documentation block. These files basically contain the information of who created and/or modified a routine, what are the dimension and meaning of the passing arguments, how to call this routine, and what routines called by this one. Some have very useful information, some don't.

$DISK/common/fmtdata/

This directory contains all the compressed formatted data used for model integration, they are used by the initial configuration to be read by the scripts in $DISK/dec/condata to create binary data for later use in model. They are

mtnvar.126.fmt.Z   : mountain variance for T126.
mtnvar.62.fmt.Z     : mountain variance for T62
navy10.fmt.Z          :10 min by 10 min boxes of terrain height.
topo05.fmt.Z           : 5 min by 5 min topography.
tune1.fmt.Z             : cloud tuning data

$DISK/common/include/

      This directory contains lists of include files for computation used for all the experiment directory. They are
INCCHGR     : file list for global change resolution
INCGSMF     : file list for global forecast
INCMSMF    : file list for regional non-hydrostatic forecast
INCPCRS      : file list for lot cross section
INCPOSTP    : file list for postprocessor in pressure
INCPOSTS    : file list for postprocessor in sigma
INCPPRS       : file list for plot pressure field
INCPSIG       : file list for plot field on sigma surface
INCRBLN     : file list for regional blending
INCRINP       : file list for regional input
INCRLOC     : file list for regional movable relocation
INCRMAP    : file list for regional mapping location
INCRMTN    : file list for regional model terrain
INCRSMF     : file list for regional hydrostatic forecast

$DISK/common/script/

      This directory contains all general script for computation, prepare input, run model, post output for all the experiment directories. They are
PCMPL        : script for any selected compilation
PGCHGR     : script for global regional input resolution
PGFCST      : script for global forecast
PRFCST      : script for regional forecast
PRINP         : script for regional input processor
PRMAP       : script for regional domain mapping
PRMTN       : script for regional terrain related files
PRPLOT      : script for regional plotting
PRPOST      : script for regional postprocessor

$DISK/common/source97/

This directory contains all the necessary FORTRAN source codes for all the experiments, including global model, regional hydrostatic and non-hydrostatic model, model physics, model preprocessors for global change resolution or regional input, and postprocessors for NCAR graphics and GRIB packed file outputs. For some convenience, all main program is started from MAIN????, all regional model codes are started from RS????, all groups of subroutines have form as *SUBS, all groups of common block have form as *COM*, and all group of input/output have form as *IO*.

      We give you some examples here:
MAINSMF         : main program for global spectral model
MAINRSMF      : main program for regional spectral model
MAINPPRS       : main program to plot pressure fields by NCAR graphics
MAINCHGR      : main program to change global resolution
MAINRINP        : main program to prepare regional input
TIO                    : routines for global sigma file IO
FIXIO                : routine for global surface file IO
RSREGIO          : routines for regional IO
COMFIBM         : major common block for global model
RSCOMF           : major common block for regional model
LUPASUBS        : group routines for GLOOPA

$DISK/[machine]/

Next are the groups of directories in $DISK/[machine], remember that [machine] can be either sgi, dec, hp, or ibm etc as mentioned.

$DISK/[machine]/c2n97/

      This directory contains an example for running non-hydrostatic RSM (referred to as n) by using coarse regional grid (referred to as c) as input and base fields. Inside of this directory, there are three files
DCLSYS     : definition of the experiment for dimension and options
LOCRSM    : define the location of the regional domain and its resolution
runc2n         : script to do compilation, prepare terrain, input and run forecast

$DISK/[machine]/c2r97/

      This directory contains an example for running RSM (referred to as r) by using a coarse regional grid (referred to as c) as input and base fields. Inside of this directory, there are three files
DCLSYS     : definition of the experiment for dimension and options
LOCRSM    : define the location of the regional domain and its resolution
runc2n         : script to do compilation, prepare terrain, input and run forecast

$DISK/[machine]/condata/

      This directory contains all the scripts to make constant binary data by using $DISK/common/fmtdata/ and $DISK/common/co2gen/  formatted data set. The files in here are:
makeco2con.s       : script to make binary files called co2con.28 or co2con.18 in                               this directory
makefile.co2con    : make file for makeco2con.s
unfmtmtnvar.s      : script to make binary files called mtnvar.126 and                                mtnvar.62 in this directory
unfmttune.s          : script to make binary file called tune1

All the binary files will be used for model integration.

$DISK/[machine]/etc/

      This directory contains all necessary utilities, including a related source code preprocessor, dataset format and unformatted, checking date or forecast hour inside a given binary file. These utilities are used for
1. source code preprocess
    fortprep.f           : FORTRAN code to do source code preprocessor
    makefortprep.s  : script to make executable fortprep.x
2. format and unformat, for example:
    fmtrsig.s               : script to format regional sigma file
    unfmtsig126.s       : script to unformat T126 sigma file
    unfmtsig126to62.s : script to unformat and change T126 to T62 sigma file
3. date check:
    makeDATE.s      : script to make DATE.x
    date.s                  : script to show date on a given file
    fhour.s                : script to show forecast hour from a file
    validate.s            : script to compute validate date
                                 from date and forecast hour

$DISK/[machine]/g2n97/

      This directory contains an example for running non-hydrostatic RSM (referred to as n) by using global system (referred to as g) as input and base fields. Inside of this directory, there are three files
DCLSYS     : definition of the experiment for dimension and options
LOCRSM    : define the location of the regional domain and its resolution
runc2n         : script to do compilation, prepare terrain, input and run forecast

$DISK/[machine]/g2r97/

      This directory contains an example for running hydrostatic RSM (referred to as r) by using global system (referred to as g) as input and base fields. Inside of this directory, there are three files:
DCLSYS     : definition of the experiment for dimension and options
LOCRSM    : define the location of the regional domain and its resolution
runc2n         : script to do compilation, prepare terrain, input and run forecast

$DISK/[machine]/grads[machine]/

This directory contains all the GrADS utilities obtained from ftp://cola.iges.org or ftp://grads.iges.org, which is a free graphic package which can display on any machine. A useful feature is that it can read a GRIB packed file, which we generated from out system here. However, its executable utilities are machine dependent, you have to get one related to your system. We have provided an old version of GrADS, which works well. And we have collected code for different platforms, including ibm, dec, hp, sun, sgi and linux. Some environments may have to re-configure this code.

$DISK/[machine]/grib[machine]/

This directory contains all the necessary files for the user to pack and unpack GRIB datasets. GRIB has been proposed by WMO to be a standard data format for the world community. A library of object code has to be used to create it at the initial setup for its use later in model postprocessor. This directory is a machine dependent directory. You can obtain it from ftp://nic.fb4.noaa.gov/pub/info where you can get GRIB unpack utility related different machine, and you need one more group of routines called w3pack.f from any of the grib[machine]/ directory if it has this w3pack.f which is machine independent.

$DISK/[machine]/gsm97/

      This directory contains an example for running the global model. Inside of this directory, there are three files
DCLSYS     : definition of the experiment for dimension and options
rungsm         : script to do compilation, prepare terrain, input and run forecast

$DIEK/[machine]/n2n97/

      This directory contains an example for running the non-hydrostatic RSM (referred to as n) by using coarse regional grid which is non-hydrostatic system (refer as n) for input and base fields. Inside of this directory, there are three files:
DCLSYS     : definition of the experiment for dimension and options
LOCRSM    : define the location of the regional domain and its resolution
runn2n         : script to do compilation, prepare terrain, input and run forecast

2.3 Initial configuration for utility

The first major step is to do the initial configuration and this should be done from the $DISK/[machine]/etc/. Without this setup of some of the utilities in this directory, you cannot proceed to other configurations, and cannot do experimental test later. Do this in the following order:
(1) Change directory to $DISK/[machine]/etc/, for example

unix % cd /disk/f97/dec/etc/

(2) Make executable for preprocessor the FORTRAN source code as

unix % makefortprep.s

      Then you should have fortprep.x if you do ls -l.
(3) Make sure and change all the FORTRAN compiler option is what you want in all script files by using any editor, say vi. What we need for model are 8 bytes in real floating number and 4 bytes in integer number, so for example, the compile options we know it works are
      -r8 -i4      for Dec alpha, SUN and SGI.
      -Zp -Wd"-e8 -das" -Wf"-dmz -o aggress"     for Cray
      -qrealsize=8          for IBM
      +autodblpad           for HP
and the ln -s should use ftn# instead of fort.# in HP machine, and others use fort.# instead of ftn# for ln -s.

2.4 Initial configuration for constant

The second major step is to do the initial configuration in the directory called $DISK/[machine]/condata/. Do this in the following order:
(1) Change directory to $DISK/[machine]/condata/, for example

unix % cd /disk/f97/dec/condata/

(2) Make sure and change all the FORTRAN compiler option is what you want in file called makefile.co2con by using any editor, say vi. For more clear, let look it as following

SHELL= /bin/sh
SDIR= ../../common/co2gen
LIBS=
co2cnew.x: co2cnew.f
         f77 -r8 -O4 -Olimit 5000 -o co2cnew.x co2cnew.f $(LIBS)
co2cnew.f:
         echo ' %INCLUDE DCLSIGL; %INCLUDE DCLFULL;' >mrinput
         echo ' %INCLUDE CONSTANT; %INCLUDE CO2CNEW;'>>mrinput
         >mrpaths
         >mroutput
         >mrthree
         echo $(SDIR)/ >>mrpaths
         echo mrinput >>mrthree
         echo mroutput >>mrthree
         echo mrpaths >>mrthree
         ../etc/fortprep.x <mrthree
         cp mroutput co2cnew.f
         rm mrinput mrpaths mroutput mrthree

This is an example from dec, you have to make sure f77 is what you want, compiler option is right (-i4 is default, so not shown here), the path to SDIR and fortprep.x are correct. Please follow the file directory structure along the lines already suggested. The paths in this file are OK.

(3) Make sure the directories in the script makeco2con.s are right. They should be

#! /bin/sh
dirhome=`pwd`
dirco2c=$dirhome/../../common/co2gen
echo "How many vertical layers you want? (28/18)"
read   LEVS
cp    $dirco2c/DCLS$LEVS        $dirco2c/DCLSIGL
cp    $dirco2c/MODLS$LEVS    $dirco2c/MDLDSIG
make   -f   makefile.co2con
co2con=$dirhome/co2con.$LEVS
co2file1=$dirhome/../../common/co2gen/cns_350_490850
co2file2=$dirhome/../../common/co2gen/cns_350_490670
co2file3=$dirhome/../../common/co2gen/cns_350_670850
rm   -f   fort.*   $co2con
ln   -s   co2out        fort.16
ln   -s   $co2file1    fort.61
ln   -s   $co2file2    fort.62
ln   -s   $co2file3    fort.63
ln   -s   $co2con      fort.66
echo 350.   |   $dirhome/co2cnew.x
cat co2out
rm   -f   fort.*   co2cnew.x   co2cnew.f   co2cnew.o   co2out

You must make sure path of dirco2c, all co2files and fort unit etc are right. For example, HP machine uses ftn# instead of fort.#.

(4) After you make (2) and (3), then run the script

unix % makeco2con.s

and answer the question whether you want 28 layers or 18 layers.

(5) Again, be certain the path, compiler option and FORTRAN unit assignment by either ftn# or fort.# are OK in files unfmttune.s and unfmtmtnvar.s. Then do

unix % unfmttune.s
unix % unfmtmtnvar.s

2.5 Initial configuration for library

The third major step for the initial configuration is in the directory called $DISK/[machine]/grib[machine]/. In this directory, we are going to create a library called w3lib.a. Without setting up w3lib.a in this directory, you cannot use the postprocessor in any experiments. Again, if you don't have this directory, you can get one for your machine from ftp://nic.fb4.noaa.gov/pub/info. Copy w3pack.f from other machine version of $DISK/[other-machine]/grib[other-machine]/ because w3pack.f should be machine independent as mentioned before.

Do the following, in the suggested order, to build this w3lib.a:

(1) Change directory to $DISK/[machine]/grib[machine]/, for example

unix % cd /disk/f97/dec/gribdec/

(2) This directory is originally obtained from ftp://nic.fb4.noaa.gov/pub/info as mentioned before, so the compile option should be OK. However, you can check into two necessary scripts, one is compw3l.sh, which tells how it does the compilation, and another on is compallg.sh which lists all the necessary file to be compiled. AGAIN, make sure that w3pack is included in the list inside the file called compallg.sh. Then build the library, w3lib.a by

unix % compallg.sh

Use 'ls -l w3lib.a' to see whether you got it or not. Due to the compile option used here, there are 4 bytes for real and integer variables, so all the postprocessor compilation option in $DISK/common/script/PCMPL should use default 4 bytes for real and integer wherever it links with the w3lib.a library.

2.6 Initial configuration for display

The last major step of the initial configuration is in $DISK/[machine]/grads[machine]/. Without setting up some of the environment configuration, you cannot use GrADS utilities. Again, if you don't have this directory, you can get one from ftp://grads.iges.org and then make one here. Do this in the following order.
(1) Change directory to $DISK/[machine]/grads[machine]/, for example

unix % cd /disk/f97/dec/radsdec/

Inside this directory, you should have, at least, two groups of files. The first group includes the data files:

font0.dat
font1.dat
font2.dat
font3.dat
font4.dat
font5.dat
himap.dat
memap.dat
nmap.dat
stroke.dat
wmap.dat
xyplot.dat

Another group of executable files are:

grads
gribmap
gribscan
gxps
gxtran
stnmap

You may get something like grads.151.hp instead of grads. If so, you can make a symbolic link it to grads etc, and leave grads.151.hp untouched, so you know which version and machine-dependent executable code you have in this directory. To make the link, you do the following:

unix % ln -s   grads.151.hp        grads
unix % ln -s   gribmap.151.hp   gribmap
unix % ln -s   gribscan.151.hp   gribscan
unix % ln -s   gxps151.hp            gxps
unix % ln -s   gxtran.151.hp       gxtran
unix % ln -s   stnmap151.hp     stnmap

(2) The last step for this setup environment is to have a path to GrADS. If you are using /bin/sh as your shell, you should put the following in your .profile as

PATH=$PATH:$DISK/[machine]/grads[machine]
GADDIR=$DISK/[machine]/grads[machine]

If you are using /bin/csh as your default shell, you should put following in your .cshrc as

setenv PATH $PATH:$DISK/[machine]/grads[machine]
setenv GADDIR $DISK/[machine]/grads[machine]

For example in /bin/sh for .profile you put

               PATH=$PATH:/disk2/f97/dec/gradsdec
               GADDIR=/disk2/f97/dec/gradsdec

and if /bin/csh for .cshrc, you put

               setenv   PATH   $PATH:disk2/f97/dec/gradsdec
               setenv   GADDIR    /disk2/f97/dec/gradsdec

After you have done this, you can try to see if it works. Log out then log in again, and then do

unix % grads

you should be able to see the grads window in your monitor, if not, you have to set your environment DISPLAY on your ip address monitor, for example,
in /bin/sh, you do

unix $ DISPLAY=140.90.123.321:0

again, where 'unix$' is the prompt from /bin/sh. For /bin/csh, you do

unix % setenv DISPLAY 140.90.123.321:0

then try grads again. If you got it, you have finished your initial configuration.

webmaster: Hann-Ming Henry Juang
henry.juang@noaa.gov