Program TERRAIN is the first program you need to run in the suite of MM5 system programs. This program lets you design your mesoscale model configuration: where to place your grid, the grid size, what resolution data to use to generate terrain elevation, landuse category, and other datasets if you will be running MM5 with the land-surface model option. All fields generated by the Terrain program are constant fields for the model. To learn more about how the TERRAIN program works, please read Chapter 4 of the Tutorial Notes.

Where to Start?

To start, let's first create an MM5V3 directory:

mkdir MM5V3
cd MM5V3

and you will be working inside this directory. Then let's download the Terrain program tar file from NCAR's ftp site, and you should be doing this under MM5V3 directory. Once you have it on your machine, type the following to unzip and untar it:

gunzip TERRAIN.TAR.gz
tar -xvf TERRAIN.TAR

After this, you should see a program directory TERRAIN/ created in your working directory. cd to this directory:

cd TERRAIN

and you should see the following files and subdirectories listed:

ls -l

-rwxr-xr-x   1 mesouser system      2537 Mar 10 15:54 CHANGES
drwxr-xr-x   2 mesouser system      8192 Feb  2 11:56 Data
-rwxr-xr-x   1 mesouser system      5311 Mar 10 17:41 Makefile
-rwxr-xr-x   1 mesouser system     11325 Feb  5 16:02 README
drwxr-xr-x   2 mesouser system      8192 Feb  2 11:56 Templates
-rwxr-xr-x   1 mesouser system      2812 Jul 31  1999 con.tbl
-rwxr-xr-x   1 mesouser system      3062 Jul 31  1999 confi.tbl
-rwxr-xr-x   1 mesouser system      3322 Jul 31  1999 confiP.tbl
-rwxr-xr-x   1 mesouser system      3257 Jul 31  1999 confiT.tbl
-rwxr-xr-x   1 mesouser system     36832 Jul 31  1999 ezids
-rwxr-xr-x   1 mesouser system      4432 Jul 31  1999 lsco.tbl
-rwxr-xr-x   1 mesouser system      3980 Jul 31  1999 luco.tbl
-rwxr-xr-x   1 mesouser system      4432 Jul 31  1999 lvc1.tbl
-rwxr-xr-x   1 mesouser system      5336 Jul 31  1999 lvc2.tbl
-rwxr-xr-x   1 mesouser system      4432 Jul 31  1999 lvco.tbl
-rwxr-xr-x   1 mesouser system      1941 Feb  2 11:56 map.tbl
-rwxr-xr-x   1 mesouser system      2427 Jul 31  1999 maparea.tbl
-rwxr-xr-x   1 mesouser system      2428 Feb  2 11:56 mapfi.tbl
-rwxr-xr-x   1 mesouser system     67116 Jul 31  1999 psids
-rwxr-xr-x   1 mesouser system     39396 Jul 31  1999 raobsta.ieee
drwxr-xr-x   2 mesouser system      8192 Feb  2 11:56 src

Read the README file in the directory.

NCAR Graphics:

Next, find out whether you have NCAR Graphics installed on your machine. Terrain program does not require NCAR Graphics to run. But with NCAR Graphics, a plot file will be created to help you vitualize your domain configuration. The basic library that several MM5 programs requires has become free for downloading. Please see the NCAR Graphics site for information.

Typically NCAR Graphics is installed in /usr/local/ncarg, but depending on your system administrator, it may be installed somewhere else. If you have it, make sure that you either type

setenv NCARG_ROOT /usr/local/ncarg

before you run MM5 programs (TERRAIN, RAWINS, and GRAPH), or include it in your .cshrc file if you are running C-shell.

If you don't have NCAR Graphics, you should first edit the Makefile in the TERRAIN directory: set NCARGRAPHICS = NONCARG, and remove the libraries listed after LOCAL_LIBRARIES for your appropriate machine. For example, if you didn't have NCAR Graphics on your COMPAQ Alpha workstation, you would change this line:

   "LOCAL_LIBRARIES= -L/usr/local/ncarg/lib -lncarg -lncarg_gks -lncarg_c -lX11 -lm" ) ; \

to

   "LOCAL_LIBRARIES= " ) ; \

Now you are ready to work with Terrain.

How to Run TERRAIN?

1. Type to create terrain.deck:

make terrain.deck

If it is successful, the last message printed will say:

Making terrain deck for [your machine - whateven it may be]

2. Edit terrain.deck  on your machine until you hit "END OF USER MODIFICATION".  The deck you see here is an example for Compaq machine.

The default deck has everything selected to do the SOC case. You can check the parameters defined in the deck against what is described in the Notes (Chapter 15). Also click on the example terrain.deck to see highlighted parameters that need to be considered and changed if you start to configure your own case. Some of the more commomly used variables have clickable links with additional informaiton. Other namelist variables can be left as they are unless there is special need to change them.

If you don't have NCAR Graphics on your machine, see Notes below.

For complete references to all script variables and namelist variables, please see section 4.7 - 4.9 in Chapter 4 of the Tutorial Notes.

3. Type the following to compile and run Terrain program:

terrain.deck >& log &

The terrain.deck will first compile and output from the compilation is redirected to a file called 'make.terrain.out'. You should check this file to see if compilation is carried out successfully. If the compilation is successful, you should get four executables created in the src/ directory:

-rwxr-xr-x   1 mesouser users        32768 May 16 12:38 src/rdnml
-rwxr-xr-x   1 mesouser users        90112 May 16 12:38 src/data_area.exe
-rwxr-xr-x   1 mesouser users        40960 May 16 12:38 src/rdem.exe
-rwxr-xr-x   1 mesouser users    1990656 May 16 12:38 src/terrain.exe

These executables are used for:

rdnml:                      read namelist and figure out what data to obtain from ftp site.
data_area.exe:         used only if you choose 30 sec elevation data. It figures out which tiles to get
                               from USGS ftp site
rdem.exe:                 used only if you choose 30 sec elevation data. It reformats the titled USGS
                               data for TERRAIN.
terrain.exe                this is the main executable for terrain program.

The deck will then go to NCAR's ftp site to get the basic set of input data to your local machine under directory Data/. The ftp is carried out by using the file ftp.csh in Data/ directory. If you set NTYPE = 6 in terrain.deck, another ftp script: ftp30s.csh will also be used to get additional data.

Next, the deck will run the TERRAIN program. If everything is successful, you should see these files in the directory:

-rw-r--r--   1 mesouser users     900000 Mar 17 11:15 TER.PLT
-rw-r--r--   1 mesouser users     170912 Mar 17 11:15 TERRAIN_DOMAIN1
-rw-r--r--   1 mesouser users     210980 Mar 17 11:15 TERRAIN_DOMAIN2
-rw-r--r--   1 mesouser users      18149 Mar 17 11:15 terrain.print.out

where terrain.print.out is log file of all print statements generated by Terrain program, TERRAIN_DOMAINx are binary output files that are going to be used by other MM5 programs, and TER.PLT is a plot file generated by NCAR Graphics. In the SOC case, there are two domains (MAXNES=2) so you will get two binary output files, and 13 frames in the plot file. The example uses USGS 24-category landuse data.

Always check the end of terrain.print.out file to see if this line appears:

  == NORMAL TERMINATION OF TERRAIN PROGRAM ==

This is a good indication that the Terrain program has successfully run. Check to see how big the sizes of binary files are - they shouldn't have 0 size.

To view TER.PLT generated by Terrain, type

idt TER.PLT &

(See man page on idt if necessary: man idt)

If you've seen these files generated in your TERRAIN directory, and you've checked your plot file to see if they compare OK with our example TER.PLT, then your attempt to run the first program in MM5 modeling system suite is a success! You can now move to the next program: REGRID.

1. TERRAIN program requires recompilation if your domain configuration and/or requirement for input data exceed what is currently in the deck (see the highlighted PARAMTER statements inside the example deck).

2. If you don't have NCAR Graphics on your machine, you should edit Makefile in the TERRAIN directory before you type 'terrain.deck' to compile and run. In Makefile, set NCARGRAPHICS to NONCARG near to top, and you may also need to remove anything in the LOCAL_LIBRARIES line under appropriate machine names.

If you don't have NCAR Graphics, it will be hard to imagine where you have placed your domains. You should find some other way to view your domain setup by reading and plotting the binary output files.

3. You can use program GRAPH to plot binary output from TERRAIN.

4. If you have NCAR Graphics, always check the plot file carefully to see if terrain, and landuse are produced correctly.

5. If you choose to use the 30 sec data option: NTYPE=6, another data directory will be created: Data30s/. The job deck will, based on the domain configuration, compute the area over which 30 sec data are required and go to the USGS ftp site to get them. An example of this directory is shown here.

6. For a brief  introduction to the TERRAIN program, you can also view the bi-annual tutorial slides.

Trouble Shooting:

1. If your job fails to produce those binary and plot files, check terrain.print.out for any clues. Also check the file 'make.terrain.out' to see if the compilation is successful.

2. If you have NCAR Graphics, but either the compilation failed or no plot file is generated, check to see if you have set NCARG_ROOT in your .cshrc. Also check if the location of NCAR Graphics library is as it is assumed in the Makefile. For example, on a Compaq machine, the NCAR Graphics library is assumed to be in /usr/local/ncarg:

LOCAL_LIBRARIES= -L/usr/local/ncarg/lib -lncarg -lncarg_gks -lncarg_c -lX11 -lm

If you have successfully run program TERRAIN, you can now go to the next program: REGRID.

If you have questions, ask mesouser.