   HOW TO COMPILE AND RUN WRF3DVAR VERSION 2.0

   Before Starting

   Before you compile wrf3dvar code on your computer,
   please check to see if you have netCDF installed.
   wrf3dvar I/O makes use of netCDF data format. If your
   netCDF is installed in some odd places (e.g. not
   in your /usr/local/), then you need to know the
   paths to netCDF library, and to its include/
   directory.

   If you don't have netCDF on your computer, you
   need to install it first. You may download netCDF
   source code or pre-built binary, and find
   installation instruction on the Unidata Web page.

   Quick Reference

   1. configure 

   Go to wrf3dvar (top) directory.

   Type './configure', and you will see a list of
   choices available for your computer. These
   choices range from compiling for a single
   processor job, or distributed-memory parallization
   options for multiple processors. Enter a number.

   A configure.3dvar file will be created.

   Type 'compile -h', and you'll see the following:

     Usage:
       compile 3dvar              compile 3dvar
       compile -h                 help message

   If you want to clean directories of all object
   files and executables, type 'clean'.

   Type 'clean -a' to remove all built files,
   including configure.3dvar.

   Detailed instructions for compiling
   -----------------------------------

   The top-level directory of the wrf3dvar distribution
   contains a configure script (Bourne Shell:
   /bin/sh) and a compile script (Csh: /bin/csh).
   The configuration mechanism also makes use of
   Perl scripts in the arch directory
   (arch/Config_3dvar.pl). The compile mechanism makes use
   of the UNIX make utility. The arch directory
   contains a file of configuration templates for a
   number of different architectures and
   configuration options called configure.defaults.
   The templates in configure.defaults_3dvar are used to
   create the file configure.3dvar when the configure
   script is run. Once it has been created, the
   configure.3dvar file may be edited as needed to
   change compiler options, etc.

   A clean script (Csh: /bin/csh) is also provided.
   Specifying clean without any argument removes
   from the src directory the .o and other
   intermediate files generated by a compile. The
   configure.3dvar file is left alone. Specifying
   clean -a will also remove the configure.3dvar file
   and clean up libraries in the external
   subdirectory. Clean -a returns the code to it's
   distribution state and changes to configure.wrf
   will be lost with 'clean -a'. (Note: it does not
   clean out data files or executables in the run or
   test subdirectories).

   1. Generate configuration:

   In the top-level directory, type "./configure" .
   Assuming that the configure script can locate a
   suitable version of Perl (5.004 or higher), the
   templates in arch/configure.defaults_3dvar are scanned
   and a list of options are presented and the user
   is prompted for a choice:

       % ./configure
       checking for perl5... no
       checking for perl... found /usr/local/bin/perl (perl)
       Will use NETCDF in dir: /usr/local/netcdf
       -----------------------------------------------------------
Please select from among the following supported platforms.

   1.  Compaq OSF1 alpha          (single-threaded)
   2.  Compaq OSF1 alpha DM       (RSL, MPICH, RSL IO)
   3.  Compaq OSF1 alpha    (single-threaded, no NetCDF)
   4.  Compaq OSF1 alpha DM  (RSL, MPICH, RSL IO, no NetCDF)
   5.  Compaq OSF1 alpha DM       (RSL, DECMPI, RSL IO)

Enter selection [1-5] : 

   The user enters the choice as an integer and
   presses return. If an invalid choice is made, the
   choices and prompts are redisplayed. To exit the
   configure script at this point use the shell
   interrupt character (for example, Control-C).
   Once a choice is selected, the script generates a
   configure.3dvar file in the top level wrf3dvar directory
   and exits.

   The configure.3dvar file may be edited to change
   compile options. Note that wrf3dvar is run-time
   configurable with respect to domain size, numbers
   of processors, and options and these are set by
   modifying the namelist.input file at the
   beginning of a run. There is no need to edit
   configure.3dvar for these considerations.

   For machines not listed among the choices, edit
   the file arch/configure.defaults_3dvar and add a
   section for the target computer. Please consider
   sending these new settings back to the wrf3dvar 
   developers for inclusion in subsequent releases
   of the code.

   The configure script will also attempt to locate
   netCDF libraries and include files on the compile
   host. This can be overridden by setting the
   environment variable NETCDF to the correct path
   on your system. If this is not set, and if the
   configure script cannot find NETCDF on its own,
   it will ask the user to provide the paths to the
   library and include directories for netCDF.
   Failing all of this, it will attempt to compile
   the code without NetCDF; however, actually
   running the code will be problematic since
   currently only netCDF I/O is implemented.

   2. Compile the code

   Invoke the compile script such as './compile 3dvar'.

   The compile mechanism then invokes the Registry
   mechanism: the c programs in tools/ directory are
   used to generate the files in the inc directory
   from the tables contained in the file
   Registry/Registry_3dvar. The compile mechanism then
   builds the code in a few source directories,
   generating .o files and some other intermediate
   files (e.g. .f). One of the source files in
   frame/ directory does not appear in the
   distribution and is automatically generated by
   the Registry mechanism:
   frame/module_state_description.F . To force the
   Registry mechanism to be run again by the next
   compile command, remove
   frame/module_state_description.F .

   The result of a successful compile will be the
   executable file da_3dvar.exe in the main/ directory.

   2.a. Note on non-standard F90/F95 elements of
   current wrf3dvar prototype.

   2.a.i. The compiler must allow at least 50
   continuation lines (possibly more if
   -DDEREF_KLUDGE is specified on ARCHFLAGS -- see
   below).

   2.a.ii. The compiler must allow the INTEGER*1
   extension to specify 1-byte integers. It may be
   possible to substitute a KIND= parameter if the
   *1 extension is not available.

   2.a.iii. The compiler must allow multiple calls
   to a subroutine to use actual arguments of
   different types between calls that the compiler
   can see in the same subroutine or module (the NAg
   F95 compiler generates errors for this unless the
   -mismatch_all flag is set.)

   2.b. Note for debugging: Line numbers reported by
   an interactive debugger such as dbx will
   correspond to lines in the intermediate .f files,
   not necessarily to the lines in the .F files in
   the src directory.

   2.c. Note on ARCHFLAGS = -DDEREF_KLUDGE. F90
   compilers are allowed generate copies of
   f90-style assumed-shape arrays when passed as
   actual arguments to an external subroutine (one
   for which the Fortran compiler does not have
   access to an interface definition). Certain F90
   compilers generate this copy even if the entire
   array is being passed (there is no array
   subsetting going on). This copying can be quite
   costly. -DDEREF_KLUDGE instructs the Registry
   mechanism to generate additional index
   information when it constructs lists of actual
   arguments to the solve routine so that the
   compiler will think it is only passing the first
   element of the array and thus avoid the copy.
   However, on some other compilers this is also an
   error. The solution to this problem is imperfect
   at present.

   Instructions for running

   1. Edit namelist.input, namelist.3dvar

   The default namelists are in the run directory.

   2. Files

   The following files need to appear in the
   run directory.

     DA_Run_3DVAR.csh         wrf3dvar run script
     namelist.input           run time configuration ready for real case
     namelist.3dvar           namelist file 3dvar used parameters
     LANDUSE.TBL              input data for surface land-use categories

   3. Run the wrf3dvar model

   Execute da_3dvar.exe. The standard output and error
   output can be redirected using da_3dvar.exe > print.out
   or da_3dvar.exe >& print.out. As the model runs it will
   generate the following files:

       wrf_3dvar_output    model output files

   For MPI runs:

   Typically da_3dvar.exe will be run using some form of
   the mpirun command. For example,

       mpirun -np 16 da_3dvar.exe

   will run wrf3dvar on 16 distributed-memory
   processors. Consult your system documentation and
   support staff.

   As the model runs it will generate the following
   files:

       rsl.out.*            standard output from each processor
       rsl.error.*          standard error from each processor
       show_domain_0000     an ascii file showing the decomposition
       wrf_3dvar_output     model output file

   Each processor will write the files rsl.out.* and
   rsl.error.*, where * is the processor number.

                   --------------------------------------
                          Last updated: 5/17/2004
