Compiling WRF and WPS¶
This page provides guidance for compiling WRF and WPS following the steps below. It is recommended to follow the steps in order for a successful compile.
Note
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¶
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.
Note
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.
Create a new/clean directory called TESTS.
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 required 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, libpng (if using GRIB2 input for a real-data case, prior to WPSv4.4)
From a terminal window, create a new directory called LIBRARIES, then click the links in the above list to download each library. Place the downloads in the LIBRARIES directory.
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=/path_to_directory/Build_WRF/LIBRARIES
export CC=gcc
export CXX=g++
export FC=gfortran
export FCFLAGS=-m64
export F77=gfortran
export FFLAGS=-m64
export JASPERLIB=$dir/grib2/lib
export JASPERINC=$dir/grib2/include
export LDFLAGS=-L$dir/grib2/lib
export CPPFLAGS=-I$dir/grib2/include
Environment Settings for an Intel Compiler
export dir=/path_to_directory/Build_WRF/LIBRARIES
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 JASPERLIB=$dir/grib2/lib
export JASPERINC=$dir/grib2/include
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.
Install netCDF-c¶
From inside the LIBRARIES directory, issue the following commands:
tar xzvf netcdf-c-4.7.2.tar.gz #or just .tar if no .gz present
cd netcdf-c-4.7.2
./configure --prefix=$dir/netcdf --disable-dap --disable-netcdf-4 --disable-shared
make
make install
setenv PATH $dir/netcdf/bin:$PATH
setenv NETCDF $dir/netcdf
cd ..
Install netCDF-fortran¶
From inside the LIBRARIES directory, issue the following commands:
setenv LIBS "-lnetcdf -lz"
tar xzvf netcdf-fortran-4.5.2.tar.gz #or just .tar if no .gz present
cd netcdf-fortran-4.5.2
./configure --prefix=$dir/netcdf --disable-dap --disable-netcdf-4 --disable-shared
make
make install
setenv PATH $dir/netcdf/bin:$PATH
setenv NETCDF $dir/netcdf
cd ..
Install MPI¶
If planning to use more than a single processor when running WRF, it is necessary to install an MPI library. From inside the LIBRARIES directory, issue the following commands:
tar xzvf mpich-3.0.4.tar.gz #or just .tar if no .gz present
cd mpich-3.0.4
./configure --prefix=$dir/mpich
make
make install
setenv PATH $dir/mpich/bin:$PATH
cd ..
Note
The following three libraries (zlib, libpng, and jasper) 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 zlib¶
From inside the LIBRARIES directory, issue the following commands:
tar xzvf zlib-1.2.7.tar.gz #or just .tar if no .gz present
cd zlib-1.2.7
./configure --prefix=$dir/grib2
make
make install
cd ..
Install libpng¶
From inside the LIBRARIES directory, issue the following commands:
tar xzvf libpng-1.2.50.tar.gz #or just .tar if no .gz present
cd libpng-1.2.50
./configure --prefix=$dir/grib2
make
make install
cd ..
Install jasper¶
From inside the LIBRARIES directory, issue the following commands:
tar xzvf jasper-1.900.1.tar.gz #or just .tar if no .gz present
cd jasper-1.900.1
./configure --prefix=$dir/grib2
make
make install
cd ..
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. Download the library compatibility tests and unpack the file in the TESTS directory, then follow the instructions below to run the tests.
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.
First, obtain the WRF source code. After doing so, you should have a WRF directory. Note that if you downloaded a packaged file, it will need to be unpacked (e.g.,
tar -xf wrf-packaged-file). Move into the WRF directory:cd WRF
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.
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.
Obtain the WPS source code. After doing so, you should have a WPS directory. Note that if you downloaded a packaged file, it will need to be unpacked (e.g.,
tar -xf wrf-packaged-file). Move into the WPS directory:cd WPS
Run the configuration to specify the computing environment and compiler.
Attention
If building a version of WPS prior to v4.4, simply issue
./configureinstead 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).
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
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.
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.
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.
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.
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.
Ensure that the compiler (and version) used to install WRF is the same one used to install WPS.
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,
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.
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