Compiling WRF and WPS


This page provides guidance for compiling WRF and WPS using either a GNU/gfortran/gcc compiler or an intel compiler. Follow the steps in order for a successful compile.


Important

WRF User Support staff cannot help with errors that occur during system environment tests or during the process of installing libraries. If such errors should arise, please contact a systems administrator at your institution to assist. You may also find it useful to do a web search for the errors.



System Environment Tests

Regardless of whether you plan to build WRF and WPS with a GNU compiler or an intel compiler, the following are required software for installing and running WRF and WPS. To run the below tests, open a terminal/Unix window to issue the commands. These are automatically included on Linux and Macs, and can be installed on Windows machines (see Installing a Terminal Window on Windows Machines).




Fortran, C, and gcc compilers

Even if planning to compile the code with a compiler other than GNU, a fortran compiler must still be available because much of the WRF/WPS source code is written in Fortran programming language. To test whether these are installed, open a terminal/unix environment window and enter the following commands. If an installation is found, a path will be given as the output to each command. This path points to the location of the installation.

which gfortran

which cpp

which gcc


Fortran compilers are free of charge. It is recommended to use one of the most recent versions of gfortran for installing the WRF/WPS code. There are often compatibility issues with newer WRF code and older compilers (and vice versa). To check the version, issue the following command:

gcc --version


The following simple tests will verify that the fortran compiler is built properly, and that it is compatible with the C compiler.

Important

If any of these tests fail, please contact a systems administrator at your institution for help, as these are specific to the particular environment. WRF Support staff do not have the resources to support these types of errors.


  1. Create a new/clean directory called tests.

  2. Download the Fortran+C packaged file. Place it in the tests directory and then unpack it (tar -xf Fortran_C_tests.tar).




Test #1 - Fixed Format Fortran Test

Issue the following two commands from within the tests directory.

gfortran TEST_1_fortran_only_fixed.f

a.out

If successful, the following message should print to the screen:

SUCCESS test 1 fortran only fixed format



Test #2: Free Format Fortran

Issue the following two commands from within the tests directory.

gfortran TEST_2_fortran_only_free.f90

./a.out

If successful, the following message should print to the screen:

Assume Fortran 2003: has FLUSH, ALLOCATABLE, derived type, and ISO C Binding
SUCCESS test 2 fortran only free format



Test #3: C

Issue the following two commands from within the tests directory.

gcc TEST_3_c_only.c

./a.out

If successful, the following message should print to the screen:

SUCCESS test 3 c only



Test #4: Fortran Calling a C Function

gcc and gfortran have different defaults, so they are forced to both always use 64 bit [-m64] when combining them. Issue the following two commands from within the tests directory.

gcc -c -m64 TEST_4_fortran+c_c.c

gfortran -c -m64 TEST_4_fortran+c_f.f90

gfortran -m64 TEST_4_fortran+c_f.o TEST_4_fortran+c_c.o

./a.out

If successful, the following message should print to the screen:

C function called by Fortran
Values are xx = 2.00 and ii = 1
SUCCESS test 4 fortran calling c




Required Scripting Programs

The WRF build system includes scripts at the top level for the user interface, and therefore having the following is necessary:

  • perl 5.04 or later

  • csh

  • sh


To test whether these scripting languages are working properly on the system, the following tests can be run. The files for running these tests are included in the tar file that was unpacked for the above tests.



Test #5: csh

Issue the following two commands from within the tests directory.

./TEST_csh.csh

If successful, the following message should print to the screen:

SUCCESS csh test



Test #6: perl

Issue the following two commands from within the tests directory.

./TEST_perl.pl

If successful, the following message should print to the screen:

SUCCESS perl test



Test #7: sh

Issue the following two commands from within the tests directory.

./TEST_sh.sh

If successful, the following message should print to the screen:

SUCCESS sh test




Required UNIX Commands

Many UNIX commands are included in WRF source code, regardless of which shell environment is used. The following standard UNIX commands are mandatory:

ar

awk

cat

cd

cp

cut

expr

file

grep

gzip

head

hostname

ln

ls

make

mkdir

mv

nm

printf

rm

sed

sleep

sort

tar

touch

tr

uname

wc

which

m4





Install Libraries

The following libraries are used for installing and running WRF and WPS. Note that all libraries must be installed with the same compilers as will be used to install WRF and WPS.

  • netCDF-c and netCDF-fortran (version 3 or 4)

  • MPI or OpenMP libraries (if planning to use parallel processing - e.g., distributed-memory)

  • jasper, zlib, and libpng (if using GRIB2 input for a real-data case, prior to WPSv4.4)

  • HDF5 - Optional for file compression



  1. From your terminal window, set the following environment variables. Note that there are settings available for using a gfortran (GNU) compiler or an Intel compiler. Issue the settings for the compiler that will be used to install WRF.

    Note

    The syntax used here is for a bash shell. If using csh, see csh Commands for Setting Environment Variables.


    Environment Settings for a gfortran/GNU Compiler

    export dir=/full-path-to-libs-directory/libs
export dir=/full-path-to-libs-directory/libs
export PATH=.:/$dir/netcdf/bin:/$dir/bin:${PATH}
export LD_LIBRARY_PATH=/$dir/lib:/$dir/netcdf/lib:/$dir/grib2/lib
export JASPERLIB=/$dir/grib2/lib
export JASPERINC=/$dir/grib2/include
export NETCDF=/$dir/netcdf
export CC=gcc
export CXX=g++
export FC=gfortran
export FCFLAGS=-m64
export F77=gfortran
export FFLAGS=-m64
export LDFLAGS=-L$dir/grib2/lib
export CPPFLAGS=-I$dir/grib2/include

    Environment Settings for an Intel Compiler

    export dir=/full-path-to-libs-directory/libs
export PATH=.:/$dir/netcdf/bin:/$dir/bin:${PATH}
export LD_LIBRARY_PATH=/$dir/lib:/$dir/netcdf/lib:/$dir/grib2/lib
export JASPERLIB=/$dir/grib2/lib
export JASPERINC=/$dir/grib2/include
export NETCDF=/$dir/netcdf
export CC=icc
export CXX=icpc
export CFLAGS='-O3 -xHost -ip -no-prec-div -static-intel'
export CXXFLAGS='-O3 -xHost -ip -no-prec-div -static-intel'
export F77=ifort
export FC=ifort
export F90=ifort
export FFLAGS='-O3 -xHost -ip -no-prec-div -static-intel'
export CPP='icc -E'
export CXXCPP='icpc -E'
export LDFLAGS=-L$dir/grib2/lib
export CPPFLAGS=-I$dir/grib2/include

    Tip

    Setting the environment variables in the command line means they are now set until the terminal session is closed. You may opt to add these to your environment start-up files (e.g., .bashrc, .cshrc to see these files, issue ls - a in the user’s home directory) so the settings are saved and used each time a new terminal session begins.



  2. Make a directory for installing the libraries, and then move into that directory:

    mkdir libs

cd libs



Install mpich

If planning to use more than a single processor when running WRF, it is necessary to install an MPI library. From inside the libs directory, issue the following commands:

wget https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/mpich-3.0.4.tar.gz

tar -xf mpich-3.0.4.tar.gz

cd mpich-3.0.4

./configure --prefix=$dir

make 2>&1

make install

cd ..

rm -rf mpich*



Install zlib

From inside the libs directory, issue the following commands:

wget https://www2.mmm.ucar.edu/people/duda/files/mpas/sources/zlib-1.2.11.tar.gz

tar xzvf zlib-1.2.11.tar.gz

cd zlib-1.2.11

./configure --prefix=$dir/grib2

make -j 4

make install

cd ..

rm -rf zlib*



Install HDF5

From inside the libs directory, issue the following commands:

wget https://www2.mmm.ucar.edu/people/duda/files/mpas/sources/hdf5-1.10.5.tar.bz2

tar -xf hdf5-1.10.5.tar.bz2

cd hdf5-1.10.5

./configure --prefix=$dir --with-zlib=$dir/grib2 --enable-fortran --enable-shared

make -j 4

make install

cd ..

rm -rf hdf5*



Install netCDF-c

From inside the libs directory, issue the following commands:

wget https://github.com/Unidata/netcdf-c/archive/v4.7.2.tar.gz

tar -xf v4.7.2.tar.gz

cd netcdf-c-4.7.2

./configure --enable-shared --enable-netcdf4 --disable-filter-testing --disable-dap --prefix=$dir/netcdf

make -j 4

make install

cd ..

rm -rf v4.7.2.tar.gz netcdf-c*



Install netCDF-fortran

From inside the libs directory, issue the following commands:

Note

If you are using a csh environment, replace the LIBS setting below with setenv LIBS "-lnetcdf -lhdf5_hl -lhdf5 -lz"


export LIBS="-lnetcdf -lhdf5_hl -lhdf5 -lz"

wget https://github.com/Unidata/netcdf-fortran/archive/v4.5.2.tar.gz

tar -xf v4.5.2.tar.gz

cd netcdf-fortran-4.5.2

./configure --enable-shared --prefix=$DIR/netcdf

make -j 4

make install

cd ..

rm -rf netcdf-fortran* v4.5.2.tar.gz



Note

The libpng and jasper libraries are only need to be installed for versions of WPS prior to V4.4 and using GRIB2 meteorological input data. Starting with V4.4, a configuration option is available that installs these libraries internally with the compile, and is discussed later in the WPS compile section. If using WPSV4.4+, skip the final three library installations.


Install libpng

From inside the libs directory, issue the following commands:

wget https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/libpng-1.2.50.tar.gz

tar xzvf libpng-1.2.50.tar.gz

cd libpng-1.2.50

./configure --prefix=$DIR/grib2

make -j 4

make install

cd ..

rm -rf libpng*



Install jasper

From inside the libs directory, issue the following commands:

wget https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/jasper-1.900.1.tar.gz

tar xzvf jasper-1.900.1.tar.gz

cd jasper-1.900.1

./configure --prefix=$DIR/grib2

make -j 4

make install

cd ..

rm -rf jasper*





Library Compatibility Tests

The instructions in this section will verify that the libraries are able to work with the compilers that are to be used for the WPS and WRF builds.

  1. Move out of the libs directory and create another new directory called tests, then move into that directory

    cd ..

mkdir tests

cd tests

  2. Download the library compatibility tests and unpack the file.

    wget https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/Fortran_C_NETCDF_MPI_tests.tar

tar -xf Fortran_C_NETCDF_MPI_tests.tar


Test #1: Fortran + C + netCDF

This test requires the include file from the netCDF package be in this directory. From the tests directory, copy the file “here”:

cp ${NETCDF}/include/netcdf.inc .

Compile the Fortran and C codes for the purpose of this test (the -c option specifies no executable is to be built). Issue the following commands:

gfortran -c 01_fortran+c+netcdf_f.f

gcc -c 01_fortran+c+netcdf_c.c

gfortran 01_fortran+c+netcdf_f.o 01_fortran+c+netcdf_c.o -L${NETCDF}/lib -lnetcdff -lnetcdf

./a.out

If successful, the following message should print to the screen:

C function called by Fortran
Values are xx = 2.00 and ii = 1
SUCCESS test 1 fortran + c + netcdf




Test #2: Fortran + C + netCDF + MPI

From the tests directory, issue the following commands:

mpif90 -c 02_fortran+c+netcdf+mpi_f.f

mpicc -c 02_fortran+c+netcdf+mpi_c.c

mpif90 02_fortran+c+netcdf+mpi_f.o  02_fortran+c+netcdf+mpi_c.o  -L${NETCDF}/lib -lnetcdff -lnetcdf
mpirun ./a.out

If successful, the following message should print to the screen:

C function called by Fortran
Values are xx = 2.00 and ii = 1
status = 2
SUCCESS test 2 fortran + c + netcdf + mpi





Compiling WRF

Assuming all the above tests were successful, WRF can now be compiled. Follow the steps below to compile WRF.

Note

The below commands use git to obtain the code. If that command does not work for you, you can download the WRF code - scroll to the bottom of the latest release notes and follow directions to choose the correct file to download, then unpack the file.


  1. Obtain the WRF code and then move into the WRF directory.

    git clone --recurse-submodule https://github.com/wrf-model/WRF.git

cd WRF

  2. Run the WRF configuration to specify your computing environment and compiler.


    ./configure

    Numerous options will print to the screen. Choose the option for the compiler that will be used to build WRF, along with the type of processing that will be used. The options are

    • serial : single processor

    • smpar : shared-memory (OpenMP)

    • dmpar : distributed memory (MPI) RECOMMENDED

    • dm+sm : distributed-memory with shared-memory (e.g., MPI across nodes, with OpenMP within a node) - not recommended for beginners


    After choosing the compiler and processing type, choose the type of nesting that will be used. The options are:

    • no nest : typically only used for 1d or 2d idealized cases - only available for serial processing

    • basic : the most common type of nesting - a parent domain with one or more nested domains

    • preset moves : used for a moving nest in which each move must be specified in the namelist - not typically recommended

    • vortex-following : option to use a moving nest to track a tropical cyclone


    Serial computing only uses a single processor, which can only be used for small simulations (and are only recommended for learning and teaching purposes). For real research applications, domains should be a bit larger, and therefore parallel processing is recommended - specifically the dmpar option, which has been tested the most, and has shown the best results.

  3. When issuing the compile command, the case type will also need to be included. The options are

    • em_real (3d real-data case)

    • em_quarter_ss (3d idealized case)

    • em_b_wave (3d idealized case)

    • em_convrad (3d idealized case)

    • em_les ((3d idealized case)

    • em_heldsuarez (3d idealized case)

    • em_tropical_cyclone (3d idealized case)

    • em_hill2d_x (2d idealized case)

    • em_squall2d_x (2d idealized case)

    • em_squall2d_y (2d idealized case)

    • em_grav2d_x (2d idealized case)

    • em_seabreeze2d_x (2d idealized case)

    • em_scm_xy (1d idealized case)


    Issue the compile command, using the desired case. For e.g.,


    ./compile em_real >& compile.log

Depending on the computing environment and the compiler, the build can take anywhere between about 20-60 minutes. To see the progress, issue tail -f compile.log. When the compile is complete, there should be a “success” message printed at the end of the compile log and the following executables should be available in the WRF/main directory.


Compile for a real-data case

wrf.exe (model executable)
real.exe (real-data initialization)
ndown.exe (one-way nesting)
tc.exe (tc-bogusing)


Compile for an idealized case

wrf.exe (model executable)
ideal.exe (ideal case initialization)


The executables are linked from the main directory, to both the WRF/run and the WRF/test/em_* directories, and can be run from either location.






Compiling WPS

Note

WPS is only installed for real-data cases. If an idealized case was built, this step can be skipped.



Assuming WRF was successfully built, the WPS program can now be compiled. WPS will not build if the WRF compile was not successful. Follow the steps below to compile WPS.


Note

The below commands use git to obtain the code. If that command does not work for you, you can download the WPS code - scroll to the bottom of the latest release notes and follow directions to choose the correct file to download, then unpack the file.

  1. Obtain the WPS code and then move into the WPS directory.

    git clone https://github.com/wrf-model/WPS.git

cd WPS

  2. Run the configuration to specify the computing environment and compiler.


    Attention

    If building a version of WPS prior to v4.4, simply issue ./configure instead of the below command.



    ./configure --build-grib2-libs

    The –build-grib2-libs command instructs the compiler to build the zlib, libpng, and jasper libraries (required for GRIB2 data processing) internally. A list of compiler options and processing types (serial or parallel) should print to the screen. Unless the simulations will use thousands x thousands of grid spaces, there is no need to compile for parallel processing - even if WRF was compiled for parallel processing. Choose the option that matches the compiler used for building WRF (note that the option number will likely be different than that of WRF).


  3. Because the metgrid.exe and geogrid.exe builds rely on the WRF model’s I/O libraries, the following environment variable should be set. The path should point to the location and name of the WRF directory.


    export WRF_DIR=path-to-wrf-directory/wrf-directory

  4. Issue the compile command.


    ./compile >& compile.log

    WPS should compile much faster than WRF. If the compilation is successful, there should be 3 executables in the WPS top-level directory, that are linked to their corresponding src/ directories:

    • geogrid.exe -> geogrid/src/geogrid.exe

    • ungrib.exe -> ungrib/src/ungrib.exe

    • metgrid.exe -> metgrid/src/metgrid.exe




Troubleshooting


Failed WRF Compile

If the WRF model did not successfully compile, follow these steps for troubleshooting.

  1. Open the compile log and search for the word “Error” (with a capital “E”). Typically the first error in the file is the culprit, and all additional errors are likely related to the first error.

  2. If the error message is not clear, try searching to see if others have had a similar error, and if there is an available solution. This can be done via a general web search, or within the WRF & MPAS-A User Support Forum.

  3. If there error cannot be solved after following the first two steps, post a new thread on the WRF & MPAS-A User Support Forum and someone will respond to the inquiry. Be sure to attach the compile log and the configure.wrf file for support staff to view.



Failed WPS Compile

If the geogrid and metgrid program did not compile, follow these steps for troubleshooting.

  1. Ensure that WRF compiled successfully. Because geogrid and metgrid rely on the I/O libraries from WRF, it is essential that WRF is properly installed prior to building WPS.

  2. Ensure that the compiler (and version) used to install WRF is the same one used to install WPS.

  3. Ensure that the netCDF (and version) used to install WRF is the same one used to install WPS.


If unbrib failed to compile, and if using V4.4+ and installing GRIB2 libraries manually, go back to the Compiling WPS step and follow the instructions to build the libraries internally. If using an older version of WPS, consider upgrading to a newer version. It is okay to use a different version of WPS and WRF, as long as they are both V4 or greater. If this is not an option, look in the configure.wps file and ensure the paths for COMPRESSION_LIBS and COMPRESSION_INC are set correctly.


If the above steps are not helpful for correcting installation issues,

  1. If the error message is not clear, try searching to see if others have had a similar error, and if there is an available solution. This can be done via a general web search, or within the WRF & MPAS-A User Support Forum.

  2. If there error cannot be solved after following the first two steps, post a new thread on the WRF & MPAS-A User Support Forum and someone will respond to the inquiry. Be sure to attach the compile log and the configure.wps file for support staff to view.



Recompiling WRF and/or WPS

Once the issues are resolved, the code may be recompiled. Prior to doing so, the code needs to be cleaned (./clean -a) and reconfigured before compiling.




Next Steps

Prior to running a real-data simualation, the next steps are to