INSTRUCTIONS FOR WRF PRE-PROCESSORS MM52WRF
-------------------------------------------

27 Nov 2000

1. Introduction

1.1 What is the MM52WRF package for?

Since many of the early users of the WRF system will be interested in 
comparing results between the WRF model and other more established
mesoscale models, the MM5 group at NCAR is providing a program to allow
similar input data sets.  Users with traditional V3 format model input
(MMINPUT_DOMAIN1, LOWBDY_DOMAIN1) may drive the mm52wrf program to 
generate data that is acceptable to the WRF package.  Due to different 
physics options, staggerings, vertical levels, etc., the forecasts
will certainly not be easy to duplicate (OK, not even possible to 
replicate each other), but this should go a long ways towards supporting
the start of the camparison studies with real data.

1.2 Who is this MM52WRF program targeted to?

This README file assumes that users are familiar with the MM5 
pre-processing system and can generate the required files: MMINPUT_DOMAIN1, 
LOWBDY_DOMAIN1.  With these files readily available, the user needs only 
to build the mm52wrf executable, modify the namelist, and run the 
mm52wrf program.  If after running this program you say, "Gee, that sure
felt like an MM5 pre-processor", then we succeeded.

2. Building the MM52WRF executable

2.1 What have (haven't) we tried so far?

Tests have been conducted only on Compaq machines with Alpha chips, with
Tru64 Unix and the Compaq f90 compiler.  The MM5 system Makefiles used in
most of the pre-processors has been employed with this program.  Users
with a modicum of experience with the MM5 system should be comfortable
making required modifications identical to those that may have been 
necessary for running REGRID, LITTLE_R, INTERPF, or NESTDOWN.  If those
packages worked "right out of the box", you should expect the same 
level of ease of use with the MM52WRF program.  However, you would 
expect us to put such patently condescending drivel in out build
instructions, right?

2.2 Get the tar file

The MM52WRF package is maintained by the NCAR MesoUser as a Unix-based
gzip'ed tar file located on the NCAR anonymous ftp site (again, 
identical to the distribution method that handles the rest of the MM5 
system).

2.2.1 I got a browser, where's the file.

With a browser, the MM52WRF.TAR.gz file is available from
<a href="ftp://ftp.ucar.edu/mesouser/MM5V3/MM52WRF.TAR.gz">the NCAR ftp 
site</a>.  

2.2.2 I don't trust all this new technology stuff.

Users may also directly pull the file down from the NCAR 
anonymous ftp location.  Since this is an *anonymous* ftp site, please 
log in with username <b>ftp</b> (easier than anonymous) and your 
<b>complete email address</b> as your password.

ftp ftp.ucar.edu
user: <b>ftp</b>
passwd:<b>your email address</b>
cd mesouser/MM5V3
bin
get MM52WRF.TAR.gz
quit

2.3 Unzip and untar

After successfully retrieving the file, two things need to be done
in this order: 1) unzip it, and 2) untar it.

2.3.1 Uncompress the file

The file is compressed with the *gzip* utility.  To uncompress the
file:
# gunzip MM52WRF.TAR.gz

After this, the file MM52WRF.TAR has replaced the compressed file
MM52WRF.TAR.gz in the working directory.

2.3.2 Untar the file

Typical of the MM5 system, the tar file contains the entire directory
structure required for the MM52WRF package.  The tar file creates a
directory MM52WRF, and places all of the associated files underneath.

# tar -xvf MM52WRF.TAR
a MM52WRF
a MM52WRF/macros_mm52wrf 1 Blocks
a MM52WRF/mm52wrf symbolic link to src/mm52wrf
a MM52WRF/README 1 Blocks
a MM52WRF/src
a MM52WRF/src/Makefile 4 Blocks
a MM52WRF/src/module_util.F 7 Blocks
a MM52WRF/src/module_dm.F 2 Blocks
a MM52WRF/src/proc_namelist.F 1 Blocks
a MM52WRF/src/module_namelist_info.F 6 Blocks
a MM52WRF/src/mm52wrf.F 11 Blocks
a MM52WRF/src/module_mm5_input.F 37 Blocks
a MM52WRF/src/module_header_space.F 5 Blocks
a MM52WRF/src/module_diags.F 65 Blocks
a MM52WRF/src/module_interp.F 10 Blocks
a MM52WRF/src/module_date_time.F 42 Blocks
a MM52WRF/src/proc_mm5_header.F 1 Blocks
a MM52WRF/src/module_constants.F 1 Blocks
a MM52WRF/Makefile 16 Blocks
a MM52WRF/namelist.input 1 Blocks
a MM52WRF/configure.rules 1 Blocks

2.4 I have the source code, now what?

Change you working directory to the MM52WRF location.  If you just 
unzipped and untared the above files, just cd MM52WRF.  Once in this
directory, a Makefile has been designed to work with Compaq, SGI,
IBM, and Sun machines.  If you have one of these candidate machines,
you should be able to just type "make".  If this last command was
successful, you should have a brand, spanking new executable named
mm52wrf in the directory.  Well, OK, you really have a link to the
executable in the src directory.  

2.4.1 Sample output from the make command

# make
uname -a > .tmpfile
OSF1 headache2 V4.0 1229 alpha
Compiling for Compaq
/bin/rm -f module_date_time.o
/usr/bin/cpp -I. -C -P -DDEC module_date_time.F > module_date_time.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_date_time.f
/bin/rm -f module_date_time.f
/bin/rm -f module_constants.o
/usr/bin/cpp -I. -C -P -DDEC module_constants.F > module_constants.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_constants.f
/bin/rm -f module_constants.f
/bin/rm -f module_header_space.o
/usr/bin/cpp -I. -C -P -DDEC module_header_space.F > module_header_space.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_header_space.f
/bin/rm -f module_header_space.f
/bin/rm -f module_util.o
/usr/bin/cpp -I. -C -P -DDEC module_util.F > module_util.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_util.f
/bin/rm -f module_util.f
/bin/rm -f module_mm5_input.o
/usr/bin/cpp -I. -C -P -DDEC module_mm5_input.F > module_mm5_input.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_mm5_input.f
/bin/rm -f module_mm5_input.f
/bin/rm -f module_diags.o
/usr/bin/cpp -I. -C -P -DDEC module_diags.F > module_diags.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_diags.f
/bin/rm -f module_diags.f
/bin/rm -f module_dm.o
/usr/bin/cpp -I. -C -P -DDEC module_dm.F > module_dm.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_dm.f
/bin/rm -f module_dm.f
/bin/rm -f module_interp.o
/usr/bin/cpp -I. -C -P -DDEC module_interp.F > module_interp.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_interp.f
/bin/rm -f module_interp.f
/bin/rm -f module_namelist_info.o
/usr/bin/cpp -I. -C -P -DDEC module_namelist_info.F > module_namelist_info.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u module_namelist_info.f
/bin/rm -f module_namelist_info.f
/bin/rm -f mm52wrf.o
/usr/bin/cpp -I. -C -P -DDEC mm52wrf.F > mm52wrf.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u mm52wrf.f
/bin/rm -f mm52wrf.f
/bin/rm -f proc_mm5_header.o
/usr/bin/cpp -I. -C -P -DDEC proc_mm5_header.F > proc_mm5_header.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u proc_mm5_header.f
/bin/rm -f proc_mm5_header.f
/bin/rm -f proc_namelist.o
/usr/bin/cpp -I. -C -P -DDEC proc_namelist.F > proc_namelist.f
f90 -c -automatic -convert big_endian -fast -fpe -free -O4 -std -u proc_namelist.f
/bin/rm -f proc_namelist.f
f90 -o mm52wrf -fast -O4 mm52wrf.o  proc_mm5_header.o proc_namelist.o module_constants.o module_date_time.o  module_diags.o module_dm.o  module_header_space.o module_interp.o  module_mm5_input.o  module_namelist_info.o module_util.o 
( /bin/rm -f mm52wrf ; ln -s src/mm52wrf . )


3 The MM52WRF namelist file, namelist.input

3.1 Where was that namelist file located?

The namelist file that controls the MM52WRF program is in the top
MM52WRF directory, and is named namelist.input.  This is a text file 
that is modified with an editor (such as vi or emacs).  

3.2 What does the namelist file do?

The namelist.input file for the MM52WRF program provides two kinds 
of necessary information to the executable.  It lets the program
know what input files to read and how to build the WRF vertical
levels.

The MM52WRF program inputs MM5 V3 data that is suitable for use to
drive the MM5 program, specifically the model input and the lower
boundary file.  These are input as character strings in the 
first namelist record.  As with the other MM5 system pre-processors,
directory structure is permitted.

&record0
 mm5_file_name               = '../MMINPUT_DOMAIN1-soc'
 lowbdy_file_name            = '../LOWBDY_DOMAIN1-soc' /

The second type of information required deals with the new vertical
levels which the user MUST choose prior to running the WRF program.
While the specific variables that are required are automatically
diagnosed, and the horizontal staggerings are set a priori, the 
vertical levels are an option to which the user must attend.  In this
current release, the only method for assigning the vertical levels
is to decide the thickness and number of levels.

Perhaps a bit of info on the vertical levels is in order.  The
new WRF coordinate levels are called zeta levels.  They are a 
terrain following coordinate defined as:

                 z(i,j,k) - zsfc(i,j)
   zetafull(k) = -------------------- * zetatop
                 zetatop - zsfc(i,j) 

This gives a value of 0.0 as the lowest level (i.e., at ground level) 
and a value of zetatop at the model lid.  NOTE THAT THIS IS OPPOSITE 
OF THE MM5 CONVENTION!  Additionally, the user is selecting levels 
that are scaled by the top height (with units in m).  

&record1
 dzetaw                      = 400.
 numzeta                     = 48 /  ! this is half layers, not full

If the input data does not extend "high" enough, a print statement
from the MM52WRF program will inform the user that either the 
thickness of each layer or the number of total layers needs to
be decreased.  To allow some tuning, the minimum value of the 
height (on all three staggerings) for the top MM5 level is printed
to allow the user some direct information in computing the dzetaw
(thickness of each layer in m) and the numzeta (number of half
layers - same sort of idea with MM5 half sigma layers).  In the
above example, dzetaw= 400 and numzeta = 48 would yield 
zetatop=19,200 m.  

3.3 More namelist options later?

It is possible at a later date that the namelist options will be 
increased to permit the use of a stretched vertical coordinate.  This
would more closely emulate the MM5 vertical staggering, with closely
packed levels in the boundary layer and levels in the free atmosphere
spaced approximately linearly in pressure.

All of the time periods in the MM5 input data sets are processed.
There is no mechanism to cull only requested time periods from the
MM5 files.  As the time to generate each time period is fairly small
when compared to the other collateral damage when running WRF, this
will probably not be an option.  Specific periods from a long series of
times that are contained in the MMINPUT_DOMAIN1 file may be chosen in 
the WRF pre-processors, since each time period which is output from the 
MM52WRF program is contained in a separate file.

4. Running the MM52WRF program

4.1  I hope this is easy to run

Just type "mm52wrf".  If you have built the executable, the program 
should start processing.  If the "." directory is not in your
path, then you may need to type "./mm52wrf".  But what are you doing
without the "." in your path, anyways?

4.2  Easy to fix errors

4.2.1 File not found

# mm52wrf
The MM5 input file, ./MMINPUT_DOMAIN1-soc, does not exist.

Guess what, the MM5 input file does not exist, at least not where you
said the MM52WRF program could find it.  Just check the spelling
and directories.  You can get the same sort of message from the
LOWBDY file, also.

4.2.2  The slash is missing

# mm52wrf
Found an extra big header flag.  We are going to skip the big header.
Found the end of time flag, all data input for this time period.
Found an extra big header flag.  We are going to skip the big header.
Found the end of time flag, all data input for this time period.
 processing data at 1993-03-13_00:00:00.0000
forrtl: error (73): floating divide by zero
Abort (core dumped)

If you leave off that last "/" character at the end of either of the 
namelist records, WHO KNOWS WHAT YOU'LL SEE!  If you get an error
about I/O, or improper namelist values or even the ridiculous
floating divide by zero above (!), just make sure that your namelist
is f90 compliant.

4.2.3 The famous level mismatch scenario

# mm52wrf
Found an extra big header flag.  We are going to skip the big header.
Found the end of time flag, all data input for this time period.
Found an extra big header flag.  We are going to skip the big header.
Found the end of time flag, all data input for this time period.
 processing data at 1993-03-13_00:00:00.0000
TROUBLES with chosen levels.
The maximum allowable WRF height is 19218. m.
With your namelist options of thickness and # or levels, we get a maximum height of ****** m.
Lower_the_effective_max_height

In this case, the program is just trying to let you know that you
need to reduce the number of vertical levels that you are requesting,
the level thicknesses, or BOTH.  

4.3  What print output do I expect if this works?

Here's the output from two time periods of data that is supposed to look 
all the world just like the MM5 SOC case.  This data set was specially
prepared to push the PTOP as high as possible to get the zetatop in
WRF as high as possible.  Other than that, this is just a regular MM5
input data set.

# mm52wrf
Found an extra big header flag.  We are going to skip the big header.
Found the end of time flag, all data input for this time period.
Found an extra big header flag.  We are going to skip the big header.
Found the end of time flag, all data input for this time period.
 processing data at 1993-03-13_00:00:00.0000
Minimum height from MM5 top level is = 19218. m.
 domain size: x=          41   y=          35   z=          49
Found the end of time flag, all data input for this time period.
Found the end of time flag, all data input for this time period.
 processing data at 1993-03-13_12:00:00.0000
 domain size: x=          41   y=          35   z=          49
END-OF-FILE detected in MM5.  Stopping fairly gracefully.
EOF_inMM5_input

4.4  What output files should I see?

The output files from the WRF2MM5 program are named IDENTICALLY to the
files prepared by the WRF standard initialization (SI).  The file name
is in three pieces.  The first piece is the string "wrf_input.".  The
second component is currently "d01.", where this will eventually refer
to the specific domain (i.e., as in domain #1 rigth now).  Since WRF 
only handles a coarse grid right now, this is not an issue for 
generalization, yet.  The third component of the file name is the date
string associated with the file.  Every file contains only a single
time period, so there is no ambiguity concerning which time period is
referenced by the file name date.  The date is in the standard MM5 V3
format: YYYY-MM-DD_HH:mm:ss, where DD is day of the month NOT day
of the year.

# ls -sl wrf_*
2984 -rw-r--r--   1 gill     users    3055416 Nov 27 14:13 wrf_input.d01.1993-03-13_00:00:00
2984 -rw-r--r--   1 gill     users    3054976 Nov 27 14:13 wrf_input.d01.1993-03-13_12:00:00

In the  above example, two time periods were processed.  This represents
all of the time periods found in the MMINPUT_DOMAIN1 file chosen in the
namelist.input

5. Hey, I have problems.  What can I do?

The MM52WRF package is maintained and supported by the NCAR MesoUser
(mesouser@ucar.edu).  Any questions about the MM52WRF package, or any
other MM5-related package, should be directed to mesouser@ucar.edu.
Questions specifically about the WRF system should be sent to 
wrfhelp@wrf-model.org.  Right now, the only overlap between these
two email aliases should be the MM52WRF program.
