1. Introduction
This document outlines the steps to building WRF on a Linux-based machine. Firstly the compatibility of the system’s compilers will be checked. Then instruction for installing some necessary libraries will be given. These libraries will then be checked for compatility.
Producing a WRF forecast requires the building of two systems, WRF and WRF-Preprocessing System (WPS). Sections 5 and 6 describe the steps for setting up WRF and WPS. Lastly a description will be given for downloading the static data needed to run WPS.
2. Testing System Compatibility
To install WRF on your machine, the first step is to ensure that you have the necessary fortran and C++ compiler which are needed to execute the code within the model. This can be achieved by typing the following into your terminal:
seanieucd@seanieucd2016:~$ which gfortran /usr/bin/gfortran seanieucd@seanieucd2016:~$ which cpp /usr/bin/cpp seanieucd@seanieucd2016:~$ which gcc /usr/bin/gcc
Running each of these commands should return a file path, which indicates that these compilers are installed on your machine. Furthermore, you can check the version of each of these by inputting
seanieucd@seanieucd2016:~$ gfortran --version GNU Fortran (Ubuntu 5.4.0-6ubuntu1~16.04.4) 5.4.0 20160609 Copyright (C) 2015 Free Software Foundation, Inc. GNU Fortran comes with NO WARRANTY, to the extent permitted by law. You may redistribute copies of GNU Fortran under the terms of the GNU General Public License. For more information about these matters, see the file named COPYING seanieucd@seanieucd2016:~$ cpp --version cpp (Ubuntu 5.4.0-6ubuntu1~16.04.4) 5.4.0 20160609 Copyright (C) 2015 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. seanieucd@seanieucd2016:~$ gcc --version gcc (Ubuntu 5.4.0-6ubuntu1~16.04.4) 5.4.0 20160609 Copyright (C) 2015 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Using a version of gfortran which is 4.4.0 or newer is recommended. Once you have ensured that you have the necessary compilers installed on your machine. The next step is to test that they are operating correctly and can interact with one another. Firstly create two new directories called “Build_WRF” and “TESTS”, using the 1 mkdir command. Then download the set of test files by clicking on the link below and place the .tar file in the TESTS directory.
Unpack the test files by entering the following input into the terminal:
tar -xf Fortran_C_tests.tar
The following tests are then executed to test the functionality of your machine.
TEST #1: Fixed Format Fortran Test
Enter the following pair of commands into the terminal:
gfortran TEST_1_fortran_only_fixed.f ./a.out
Successfull completion of the test is indicated by the following being printed to the screen:
SUCCESS test 1 fortran only fixed format
TEST #2: Free Format Fortran Test
Enter the following pair of commands into the terminal:
gfortran TEST_2_fortran_only_free.f90 ./a.out
Again successfull completion of the test is indicated as follows:
Assume Fortran 2003: has FLUSH, ALLOCATABLE, derived type, and ISO C Binding SUCCESS test 2 fortran only free format
TEST #3: C
Enter the following pair of commands into the terminal:
gcc TEST_3_c_only.c ./a.out
Again successfull completion of the test is indicated as follows:
SUCCESS test 3 c only
TEST #4: Fortran Calling a C Function (gcc and gfortran have different defaults, so we force both to always use 64 bit (-m64) when combining them)
Enter the following terminal commands sequentially:
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
Successfull completion of this test is indicated as follows:
C function called by Fortran Values are xx = 2.00 and ii = 1 SUCCESS test 4 fortran calling c
Lastly we will test that 3 different scripting languages: csh, perl and sh are working properly on the machine.
TEST #5: csh
Enter the following command into the terminal:
./TEST_csh.csh
Which should produce:
SUCCESS csh test
TEST #6: perl
Enter the following command into the terminal:
./TEST_perl.pl
Which should produce:
SUCCESS perl test
TEST #7: sh
Enter the following command into the terminal:
./TEST_sh.sh
Which should produce:
SUCCESS sh test
If all of these tests have executed succesfully then your machine has the necessary compilers and scripting features to run WRF. Next it will be necessary to install some libraries which are required to run WRF.
3. Building Libraries
The following 5 libraries are necessary to run WRF. NetCDF is needed for the handling of .nc data files. MPICH is needed if you plan on running WRF in parallel using MPI (Message Passing Interface). The final three libraries: zlib, libpng and JasPer are used for handling GRIB2 files during the WPS portion of running WRF. To begin, one should navigate into the Build_WRF directory and create a new directory called LIBRARIES as follows:
cd Build_WRF/ mkdir LIBRARIES
The next step is to download the tar files for these libraries:
Once you have downloaded the 5 files, they should be placed in the LIBRARIES directory.
The process of building these libraries requires the creation of some environment variables. I have included how to assign these as temporary variables within the upcoming steps. A description of how to permanently assign these variables are given at the end of this section, along with all the environment variables collected in a single list.
3.1 NetCDF
Firstly, ensure you are situated in the LIBRARIES directory. The upcoming instructions use the bash scripting language, as opposed to csh (for a description using csh please see this link). These are the following steps to install netcdf:
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
Now that the environment variables have been set, you can now proceed to unpack and install netcdf.
tar xzvf netcdf-4.1.3.tar.gz cd netcdf-4.1.3 ./configure --prefix=$DIR/netcdf --disable-dap --disable-netcdf-4 --disable-shared make make install export PATH=$DIR/netcdf/bin:$PATH export NETCDF=$DIR/netcdf cd ..
3.2 MPICH
MPICH is required if you intend on running your version of WRF in parallel using MPI (Message Passing Interface). The following steps will install MPICH on your machine.
tar xzvf mpi-3.0.4.tar.gz cd mpich-3.0.4 ./configure --prefix=$DIR/mpich make make install export PATH=$DIR/mpich/bin:$PATH cd ..
3.3 zlib
export LDFLAGS=-L$DIR/grib2/lib export CPPFLAGS=-I$DIR/grib2/include tar xzvf zlib-1.2.7.tar.gz cd zlib-1.2.7 ./configure --prefix=$DIR/grib2 make make install cd ..
3.4 libpng
tar xzvf libpng-1.2.50.tar.gz cd libpng-1.2.50 ./configure --prefix=$DIR/grib2 make make install cd ..
3.5 JasPer
tar xzvf jasper-1.900.1.tar.gz cd jasper-1.900.1 ./configure --prefix=$DIR/grib2 make make install cd ..
3.6 Permanent Export
The export commands made during these steps are not permanent and will not remain in place when you restart your machine. In order to make these environment variables permanent you need to edit the bashrc file on your machine. This can be done using a simple text editor such as gedit (or emacs etc..) and accessed as follows:
gedit /.bashrc
Then you can proceed to add the previously mentioned export commands into this file. For convenience I have list them below:
# added by me when building WRF export DIR="/home/seanieucd/Models/Build_WRF/LIBRARIES" export CC="gcc" export CXX="g++" export FC="gfortran" export FCFLAGS="-m64" export F77="gfortran" export FFLAGS="-m64" export PATH="$DIR/netcdf/bin:$PATH" export NETCDF="$DIR/netcdf" export PATH="$DIR/mpich/bin:$PATH" export LDFLAGS="-L$DIR/grib2/lib" export CPPFLAGS="-I$DIR/grib2/include" export JASPERLIB="$DIR/grib2/lib" export JASPERINC="$DIR/grib2/include"
4 Library Compatibility Tests
The next step to download the tests and place the tar file in the TESTS directory.
Fortran_C_NETCDF_MPI_tests.tar
Unpack the tar file as follows:
tar -xf Fortran_C_NETCDF_MPI_tests.tar
Now you can proceed with the following two tests.
Test #1: Fortran + C + NetCDF
The first test solely checks the compatibility of the combination of Fortran, C and NetCDF. This proceeds as follows:
cp ${NETCDF}/include/netcdf.inc .
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, this should produce:
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
The second test checks the compatibility of the combination of Fortran, C and NetCDF when executed using MPI (Message Passing Interface). This proceeds as follows:
cp ${NETCDF}/include/netcdf.inc .
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, this should produce:
C function called by Fortran Values are xx = 2.00 and ii = 1 status = 2 SUCCESS test 2 fortran + c + netcdf + mpi
At this point, you are now ready to proceed to building WRF.
5 Building WRF
Firstly, click on the link below to download the tar file which contains the necessary files to build WRF and place it in the Build WRF directory.
Alternatively, you could visit the UCar website to check for the latest version of the WRF-ARW model that is available.
The usual methods to unpack the file can then be applied:
gunzip WRFV3.8.1.TAR.gz tar -xf WRFV3.8.1.TAR
Move into the WRFV3 directory and begin the configuration process.
cd WRFV3 ./configure
At this point you will be presented with a number of configuration options for WRF, regarding your type of compiler and whether you wish to run WRF serially or in parallel. It is quite likely that option “34” will be the most suitable, though it is worth checking that this is the case first. This option is for GNU Fortran compilers and runs WRF with “dmpar”; which is running it in parallel with distributed memory. This should generate a configure.wrf file. There are a number of set up choices for running WRF depending on the application. A list of the set up choices are given below:
| Configuration | Scenario |
|---|---|
| em_real | (3d real case) |
| em_quarter_ss | (3d ideal case) |
| em_b_wave | (3d ideal case) |
| em_les | (3d ideal case) |
| em_heldsuarez | (3d ideal case) |
| em_tropical_cyclone | (3d ideal case) |
| em_hill2d_x | (2d ideal case) |
| em_squall2d_x | (2d ideal case) |
| em_squall2d_y | (2d ideal case) |
| em_grav2d_x | (2d ideal case) |
| em_seabreeze2d_x | (2d ideal case) |
| em_scm_xy | (1d ideal case) |
It is likely that you will will to run the 3d real case. If so the following command should be entered:
./compile em_real >& log.compile
If you wish to compile WRF with a different set up then substitute “em real” for one of the other choices given above. This compilation process could take 10-30 minutes depending on the speed of your machine.
Once this has finished, a quick check to see if the necessary executable files have been produced can be done by entering the following into the terminal.
ls -ls main/*.exe
This should return the following four files:
wrf.exe real.exe ndown.exe tc.exe
Within the WRFV3 directory there are two sub-directories where these files have been linked.
WRFV3/run WRFV3/test/em real
You can run WRF within either directory.
6 Building WPS
There are similar initial steps to the previous section. Download the WPS file below and unpack it.
gunzip WPSV3.8.1.TAR.gz tar -xf WPSV3.8.1.TAR
Navigate into the WPS directory.
cd WPS
If you have performed the permanent export of environment variables at the end of Section 3, this next step is unnecessary. Otherwise the following are required:
export JASPERLIB=$DIR/grib2/lib export JASPERINC=$DIR/grib2/include
These are needed for the ungrib libraries within WPS.
**For WPS3.9.1 and newer, a potential problem can arise.
If you work with an old version of gfortran (as is the case on SONIC at UCD), an issue has been noted when compiling WPS. If these steps are not taken, “ungrib.exe” might not compile correctly.
Now you can begin to configure:
./configure
In a similar way to WRF in the last section, you will be presented with a list of configuration options. These relate to the type of compilers, if you want to be able to handle to GRIB2 files and also whether you want to run WPS serially or in parallel. If you chose option “34” when building WRF, it is likely that option “1” is a good choice for you. The belief is that WPS does not need to be configured in parallel, as its tasks are not as computationally taxing as WRF. And it is generally reccomended to choose an option that can handle GRIB2 files.
This generates a “configure.wps” file. This contains the following:
WRF DIR = ../WRFV3
If this does not reflect the path to the WRF directory on your machine, or if you have renamed your WRF directory, you will need to edit this file.
The final step is then to compile WPS:
./compile >& log.compile
WPS takes much less time to compile compared to WRF. Once it has finished, you can check if WPS was successfully built by doing the following:
ls -ls *.exe
If the build was good, this should return the three executable files needed to run WPS.
geogrid.exe metgrid.exe ungrib.exe
The final step needed is to download the static data for running WRF.
7 Static Data
The above file is to download the full list of static data files for running WRF. This is a large compressed file (≈ 2.3 GB) and may take a while to download. This file should be moved into your Build WRF directory and unpacked. This file will expand to about 50GB in size.
bunzip2 geog complete.tar.bz2 tar -xf geog complete.tar
This will produce a directory called “geog”, which should be renamed by doing the following:
mv geog WPS GEOG
This static data is used during the WPS system and you need to ensure that WPS can access this data. This is done by editing a file called “namelist.wps” in the WPS directory. There is a line which specifies the location of the static data, called “geog data path”, this should be edited as follows to reflect your environment:
geog_data_path =path_to_directory/Build_WRF/WPS_GEOG
WRF should now be built on your machine and ready to run.
Comments
One response to “WRF installation on a Linux machine”
[…] MetClim – WRF installation on a Linux machine […]