After you have successfully prepared input data for the model, you are ready to run the MM5 model. You should not be here if you have not successfully run the INTERPF program.

MM5 requires output files from INTERPF: MMINPUT_DOMAIN1, BDYOUT_DOMAIN1, and LOWBDY_DOMAIN1. If you are doing 4DDA and would choose to do 3 hourly surface analysis nudging, you would also need output file from RAWINS: SFCFDDA_DOMAIN1.

To learn more about MM5, please read Chapter 8 of the Tutorial Notes.

Where to Start?

First, go back to MM5V3 directory and download the MM5 program tar file from NCAR's ftp site. Once you have it on your machine, type the following to unzip and untar it:

gunzip MM5.TAR.gz
tar -xvf MM5.TAR

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

cd MM5

and you should see the following files and subdirectories listed:

ls -l

-rwxr-xr-x   1 mesouser system     15594 Mar 16 16:05 CHANGES
drwxr-xr-x   2 mesouser system      8192 Mar 16 16:02 Diff
-rwxr-xr--   1 mesouser system      4094 Sep 21  1999 Makefile
-rwxr-xr--   1 mesouser system      8261 Jan 28 11:48 README
-rwxr-xr-x   1 mesouser system     18505 Jan 26 10:15 README.MPP
drwxr-xr-x   2 mesouser system      8192 Mar 16 16:02 Run
drwxr-xr-x   3 mesouser system      8192 Mar 16 16:02 Templates
drwxr-xr-x   2 mesouser system      8192 Mar 16 16:02 Util
-rwxr-xr-x   1 mesouser system     24784 Mar 24 13:44 configure.user
-rwxr-xr-x   1 mesouser system      5746 Jan 26 10:15 configure.user.linux
drwxr-xr-x   8 mesouser system      8192 Mar 16 16:03 domain
drwxr-xr-x   3 mesouser system      8192 Mar 16 16:02 dynamics
drwxr-xr-x   5 mesouser system      8192 Mar 16 16:02 fdda
drwxr-xr-x   2 mesouser system      8192 Mar 16 16:02 include
drwxr-xr-x   3 mesouser system      8192 Mar 16 16:02 memory
drwxr-xr-x   8 mesouser system      8192 Mar 16 16:02 physics
drwxr-xr-x   2 mesouser system      8192 Mar 16 16:02 pick

Read the README file in the directory.

Now cd to directory Run/, and download the test data input2mm5.tar.gz from the ftp site. You can also use the data you generated from successfully running pre-processing programs. After you gunzip and untar the file from ftp site, you should see the following files:

-rw-r--r--   1 mesouser system   2678936 Aug  3  1999 BDYOUT_DOMAIN1
-rw-r--r--   1 mesouser system    123552 Aug  3  1999 LOWBDY_DOMAIN1
-rw-r--r--   1 mesouser system   3599748 Aug  3  1999 MMINPUT_DOMAIN1
-rw-r--r--   1 mesouser system   6288756 Aug  3  1999 MMINPUT_DOMAIN2
-rw-r--r--   1 mesouser system    138376 Nov 19 16:05 TERRAIN_DOMAIN2

If you use the data you produce, you may not see files MMINPUT_DOMAIN2 and TERRAIN_DOMAIN2. Only one of these two files is required to start the nest in MM5 (see IOVERW option in mm5.deck). For this exercise, we will choose to use TERRAIN_DOMAIN2 as an input to MM5 to start the nest. So move or link TERRAIN_DOMAIN2 from the TERRAIN/ directory to this directory, e.g.,

ln -s ../../TERRAIN/TERRAIN_DOMAIN2 TERRAIN_DOMAIN2

Go back to the top MM5 directory: cd ..

Now you are ready to work with MM5.

How to Run MM5?

1. Edit the configure.user file. This file contains basic compile options for a number of computer vendors (such as Compaq, Cray, IBM, HP, SGI and Sun) and model domain/physics configuration parameters. First find the appropriate compiler options in section 3 for your machine, uncomment the lines (i.e., remove # in the first column). (In our example we choose to run on a DEC Alpha machine). If you work on a Linux PC, copy configure.user.linux to configure.user. Do not select the compile options (just yet) for a MPI platform (i.e., compiler options from section 7) - we will do the exercise first on a single processor or multiple processor/single node machine. Then find sections 5 and 6 in configure.user file, and edit all parameters that are relevant for the SOC case. Check the file you edit against the example configure.user here.

For your future reference, the variables highlighted in magenta are the ones you must change each time you configure a different domain or a different physics-option run. If you are doing a 4DDA run, then change variables highlighted in green. Variables highlighted in blue are less used, and may not work in all cases and/or with all physics options.

When editting the configure.user file or mm5.deck, and when you are seeing a line with 10 values, it means that each value will be applied to different domains. If we are running a model with only two domains (such as in this example), only the values in the first two columns are used during the run time and they are applied to domain 1 and 2 respectively.

2. Type the following to compile MM5:

make >& make.out &

This will compile MM5. If it is successful, you should see mm5.exe created in the Run/ directory. Also check the output from make, make.out, to see if there are any compilation errors.

3. Now type the following to create a deck to run MM5:

make mm5.deck

If it is successful, you should see this among other things printed on your screen:

Making mm5.deck for (your platform)

Then edit the deck to define at least these namelist variables:
 
 

TIMAX:	Model integration length in minutes
TISTEP:	Time step in seconds for model integration
TAPFRQ:	How frequently do you want to model to write out output (history file)
NESTIX:	The Y-dimension of MM5 domains
NESTJX:	The X-dimension of MM5 domains - if you have more than one domain, you need to fill all corresponding columns.
NESTI:	The starting grid location in Y-direction of the nest in its mother domain
NESTJ:	The starting grid location in X-direction of the nest in its mother domain
IOVERW:	Nest initialization option: use 1 if you use MMINPUT_DOMAIN2; use 2 if you use TERRAIN_DOMIAN2 as the input. If you choose 0, MM5 will interpolate nested input files from the coarse domain data.

As you may have noticed, the deck has been set up to run the SOC case. But check on the highlighted namelists as these would be the ones you need to modify every time you work with a different domain, and perhaps different physics. Other namelist variables may be left as they are unless you have special purpose to change them. For a complete listing of namelist variables in the deck and their explanations, refer to section 8.12 of Chapter 8 in Tutorial Notes.

Now you are ready to run MM5.

4. Type the following to run MM5:

mm5.deck &

The deck first creates a namelist called mmlif in the Run/ directory, and then starts to execute the mm5 executable.

The default simulation length is 12 hours. So it will take a while to complete a model run. On a 500 MHz Compaq Alpha machine, 12 hour run of the SOC case using the default physics takes about 15 minutes. If the run is successful, you should see these additional files generated in the Run/ directory:

-rw-r--r--   1 mesouser system    6905620 Mar 27 10:42 MMOUT_DOMAIN1
-rw-r--r--   1 mesouser system   12136720 Mar 27 10:42 MMOUT_DOMAIN2
-rw-r--r--   1 mesouser system    6971700 Mar 27 10:42 SAVE_DOMAIN1
-rw-r--r--   1 mesouser system    6971700 Mar 27 10:42 SAVE_DOMAIN2
-rw-r--r--   1 mesouser system      29578 Mar 27 10:42 mm5.print.out

where MMOUT_DOMAINx are binary history output files from the model that are written at interval specified by TAPFRQ, and SAVE_DOMAINx are binary files for the purpose of restarts.  mm5.print.out is a log file of all print statements generated by MM5, and this is the file you should take a closer look if an MM5 job fails. Check this file to see if the last output at hour 12 is written:

      --- MODEL OUTPUT IS WRITTEN AT TIME =     720.00 MINUTES FOR DOMAIN  1
      --- MODEL OUTPUT IS WRITTEN AT TIME =     720.00 MINUTES FOR DOMAIN  2
      +++ REWINDING SAVE FILE FOR DOMAIN  1
      +++ RESTART FILE IS WRITTEN AT TIME =     720.00 MINUTES FOR DOMAIN  1. IXTIMR =   720
      +++ REWINDING SAVE FILE FOR DOMAIN  2
      +++ RESTART FILE IS WRITTEN AT TIME =     720.00 MINUTES FOR DOMAIN  2. IXTIMR =   720
99999

If you want to do a restart run, the IXTIMR value would be the one to fill in for the restart job deck.

Miscellanies:

Restart run -

A restart run is a run that starts from the SAVE files (which are snapshots of the MM5 run) created from a previous MM5 run. The results at the end of a restart run should be identical to a single run that covers the entire period. For example, you can do a 24-h run in a single model run, or a run for 12-h, then restarts and run for another 12-h.

In addition to the common namelist variables to be considered, a restart run requires the specification of these variables: IFREST and IXTIMR. Set IFREST = .TRUE., and find the value of IXTIMR from the end of mm5.print.out file from the previous run (see the example restart MM5 deck).

You also need to rename SAVE_DOMAINx files to RESTART_DOMAINx before you start a restart run.

The output file from a restart run is such that it adds a suffix to the output file name. For example, the output name for domain 1 would be MMOUT_DOMAIN1_01 from a restart run.

Some clarification about time variables in the namelist is in order here in the context of a restart run. It is important to remember that these time variables are relative to the beginning of a MM5 run. For example, variable TIMAX is the total length of the model integration, not just how long a restart run is. In the above example, when you restart at hour 12, and run for another 12 h, TIMAX is equal to 24 h or 1440 min. The same rule applies to starting and ending times for a nest: XSTNES and XENNES.

One-way nest run -

A one-way nest run is considered the same as a regular MM5 run. So no matter what domain ID you are getting from running NESTDOWN (one way to create one-way nest initial and boundary condition files), MM5 expects to see the input files for the first domain named as X_DOMAIN1.

FDDA run -

There are two ways to nudge the model, Analysis or Grid nudging and Station or Observational nudging. The model can use these individually or combined.

To use grid nudging, set FDDAGD in the configure.user file equal to 1, and add the FDDA options to mm5.deck.  When doing 3D analysis nudging, no additional  input files are required. MM5 makes use of the same MMINPUT file (or a copy of this file to MMINPUT2).  If surface FDDA is required, a user must set F4D = TRUE in RAWINS / LITTLE_R, which enables the job to create a separate surface analysis file (SFCFDDA_DOMAINx), which is needed as additional input to the MM5 run.

To use observational nudging, set FDDAOBS in configure.user equal to1, and add the FDDA options to mm5.deck. In this case an additional file MM5OBS_DOMAINx is needed as input to the mm5 run. There is no standard software available to create this input file. The file is a binary file, which contain 9 real numbers per record (in order of increasing time). Note that if you use observation nudging on any domain in a nested run, the observation file is the same for all domains. Just make copies of MM5OBS_DOMAIN1 to MM5OBS_DOMAIN2, MM5OBS_DOMAIN3, etc.. However, if you are making a one-way run, you will need to recalculate the X/Y (RJO/RIO) values of the observations, as these values always refer to the first domain MM5 is seeing.

MPP MM5 run -

After you are able to make at least one MM5 run on a single processor machine, you may try on machines with multiple processors and multiple nodes. To learn about MPP MM5, please visit the MPP MM5 page.
Also view the lecture slide from the bi-annual tutorial, regarding the MM5 MPP code.
 

For a brief introduction to the MM5 program, refer to the lecture slides from the bi-annual tutorial (Equations ; Physics ; Code ; Running MM5)
 

Trouble Shooting:

1. On a number of machines (e.g. Compaq Alpha, SGI), if you get a 'segmentation fault' right away, it may be a good indication that there isn't enough memory to run the job. Sometimes, typing 'unlimit' before you run MM5 helps.

If you have run MM5 successfully, and if you have NCAR Graphics, you can now run GRAPH to look at model output.

If you have questions, ask mesouser.