Compiling WRF and WPS

This page explains how to compile WRF and WPS using either GNU (gfortran/gcc) or Intel compilers. Follow the steps in order for a successful build.

Important

WRF User Support cannot help with errors during system environment tests or library installation. If these occur, contact a systems administrator at your institution; a web search for the error message may also help.

System Environment Tests

Whether building WRF and WPS with GNU or Intel compilers, the software below is required for installation and use. To run the tests, open a terminal/Unix window and issue the commands. These tools are included by default on Linux and Macs, and can be installed on Windows (see Installing a Terminal Window on Windows Machines).

Fortran, C, and gcc compilers

Even when compiling with a non-GNU compiler, a Fortran compiler must still be available, since much of the WRF/WPS source code is written in Fortran. To check, open a terminal/Unix window and enter the following commands. If a compiler is installed, each command prints the path to its installation.

which gfortran

which cpp

which gcc

Fortran compilers are free of charge. Use a recent version of gfortran to install WRF/WPS, since compatibility issues are common between newer WRF code and older compilers (and vice versa). To check the version, run:

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, contact a systems administrator at your institution — the issue is specific to your environment, and WRF Support staff don’t have the resources to help with these errors.

Create a new directory called tests.
Download the Fortran+C packaged file. Place it in the tests directory and unpack it by issuing tar -xf Fortran_C_tests.tar.

Note

Run all the below tests in the tests/ directory.

Test #1 - Fixed Format Fortran Test

Issue the following commands from within the tests/ directory:

gfortran TEST_1_fortran_only_fixed.f

./a.out

If successful, the following message prints to the screen:

SUCCESS test 1 fortran only fixed format

Test #2: Free Format Fortran

Issue the following commands:

gfortran TEST_2_fortran_only_free.f90

./a.out

If successful, the following prints 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 commands:

gcc TEST_3_c_only.c

./a.out

If successful, the following prints to the screen:

SUCCESS test 3 c only

Test #4: Fortran Calling a C Function

To ensure gcc and gfortran are compatible when combined, both are forced to use 64-bit (-m64). Run the following commands:

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 prints 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 relies on top-level scripts for its user interface, therefore the following are required:

perl 5.04 or later
csh
sh

The tar file unpacked for the earlier tests also includes the files needed to check that these scripting languages work properly. Run the following tests:

Test #5: csh

Issue the following from within the tests/ directory.

./TEST_csh.csh

If successful, the following prints to the screen:

SUCCESS csh test

Test #6: perl

Issue the following commands:

./TEST_perl.pl

If successful, the following prints to the screen:

SUCCESS perl test

Test #7: sh

Issue the following commands:

./TEST_sh.sh

If successful, the following prints to the screen:

SUCCESS sh test

Required UNIX Commands

The WRF source code relies on many UNIX commands, regardless of the shell environment used. The following standard 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. All libraries must be built with the same compilers that will be used to install WRF and WPS.

netCDF-c and netCDF-fortran
MPI or OpenMP - for parallel processing (e.g., distributed-memory)
jasper, zlib, and libpng (for GRIB2 input for real-data cases (prior to WPSv4.4)
HDF5 - optional, for file compression

From your terminal window, set the following environment variables. Settings are provided for both gfortran (GNU) compiler and Intel compilers; use the set that matches 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 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

Environment variables set on the command line last only until the terminal session closes. To make them persistent, add them to your shell start-up file (e.g., .bashrc or .cshrc) so they are applied each time a new session begins. To see these files, run ls -a in your home directory.

Create a directory called libs, where you’ll install the libraries. Then move there:
```
mkdir libs

cd libs
```

Install mpich

For running WRF with more than a single processor the MPI library is required. 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

Issue the following commands in the libs/ directory:

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

Issue the following commands in the libs/ directory:

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

Issue the following commands in the libs/ directory:

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

Issue the following commands in the libs/ directory:

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 needed for WPS versions prior to V4.4 when using GRIB2 meteorological input data. Starting with V4.4, a configuration option installs these libraries internally during the compile (covered in the WPS compile section). If using WPS V4.4 or later, skip the final three library installations.

Install libpng

Issue the following commands in the libs/ directory:

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

Issue the following commands in the libs/ directory:

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 verify that the libraries work with the compilers that will be used to build WPS and WRF.

Move back up a directory and create a new directory called tests, then move there.
```
cd ..

mkdir tests

cd tests
```

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 to be in this directory. From the tests directory, copy it here:

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

Compile the Fortran and C test codes (the -c option means no executable is built). Run 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 prints 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 prints 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.

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

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

cd WRF

Run the WRF configuration to specify your computing environment and compiler.
```
./configure
```
Numerous options print to the screen. Choose the one matching the compiler that will be used to build WRF and the type of processing to 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
Next choose the type of nesting to use. The options are:
- no nest : typically only used for 1d or 2d idealized cases - only available for serial processing
- basic : the most common type: a parent domain with one or more nested domains
- preset moves : a moving nest in which each move is specified in the namelist - not typically recommended
- vortex-following : a moving nest that tracks a tropical cyclone
Serial computing uses a single processor, so it suits only small simulations and is recommended just for learning and teaching. For research applications with larger domains, use parallel processing, specifically dmpar, which is the most thoroughly tested and has shown the best results.
When issuing the compile command, the case type must also 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
```

The build can take roughly 20–60 minutes, depending on the computing environment and compiler. To monitor progress, run tail -f compile.log. When the compile finishes, a “success” message appears at the end of the compile log, and the following executables should be 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 required for real-data cases. Skip this step if you built an idealized case.

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

Note

The commands below use git to obtain the WPS code. If git isn’t available, download the code instead: scroll to the bottom of the latest release notes, follow the directions to choose the correct file, then unpack it.

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

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

cd WPS

Run the configuration to specify the computing environment and compiler.

Note

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 option builds the zlib, libpng, and jasper libraries (required for GRIB2 data processing) internally. A list of compiler options and processing types (serial or parallel) prints to the screen.
- Choose the option matching the compiler used to build WRF (the option number will likely differ from WRF’s).
- Parallel processing is unnecessary unless simulations will use thousands × thousands of grid points, even if WRF was compiled for parallel processing.
Because the metgrid.exe and geogrid.exe builds rely on WRF’s I/O libraries, set the following environment variable. The path points 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 compiles much faster than WRF. If successful, three executables are added to the WPS top-level directory, 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 WRF did not compile successfully, follow these troubleshooting steps:

Check the compile log. Search for “Error” (capital “E”). The first error is typically the culprit; later errors are usually related to it.
Search for a solution. If the message is unclear, check whether others have hit the same error, via a general web search or the WRF & MPAS-A User Support Forum.
Post to the forum. If the error remains unresolved, start a new thread on the WRF & MPAS-A User Support Forum, attaching the compile log and configure.wrf file for support staff to review.

Failed WPS Compile

If the geogrid and metgrid programs failed to compile, check the following:

Confirm WRF compiled successfully. geogrid and metgrid rely on the WRF’s I/O libraries, so WRF must be installed before building WPS.
Use the same compiler (and version) for WPS as was used for WRF.
Use the same netCDF (and version) for WPS as was used for WRF.

If ungrib did not compile:

WPS V4.4+ with manually installed GRIB2 libraries: return to the Compiling WPS step and build the libraries internally instead.
Older WPS versions: consider upgrading. WPS and WRF versions may differ, provided both are V4 or later.
If upgrading isn’t an option: check that the COMPRESSION_LIBS and COMPRESSION_INC paths in configure.wps are set correctly.

If the above steps don’t resolve the issue:

Search for a solution. If the error message is unclear, check whether others have hit the same error, via a general web search or the WRF & MPAS-A User Support Forum.
Post to the forum. If the error remains unresolved, start a new thread on the WRF & MPAS-A User Support Forum, attaching the compile log and configure.wps file for support staff to review.

Recompiling WRF and/or WPS

Once the issues are resolved, clean the code (./clean -a), then reconfigure and recompile.

Next Steps

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