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. 1. :ref:`System Environment Tests` 2. :ref:`Install Libraries` 3. :ref:`Library Compatibility Tests` 4. :ref:`Compiling WRF` 5. :ref:`Compiling WPS` 6. :ref:`Troubleshooting` | .. 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: 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. .. code-block:: 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: .. code-block:: 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. .. code-block:: gfortran TEST_1_fortran_only_fixed.f a.out If successful, the following message should print to the screen: .. code-block:: SUCCESS test 1 fortran only fixed format | | Test #2: Free Format Fortran **************************** Issue the following two commands from within the *TESTS* directory. .. code-block:: gfortran TEST_2_fortran_only_free.f90 ./a.out If successful, the following message should print to the screen: .. code-block:: 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. .. code-block:: gcc TEST_3_c_only.c ./a.out If successful, the following message should print to the screen: .. code-block:: 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. .. code-block:: 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: .. code-block:: 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. .. code-block:: ./TEST_csh.csh If successful, the following message should print to the screen: .. code-block:: SUCCESS csh test | | Test #6: perl ************* Issue the following two commands from within the *TESTS* directory. .. code-block:: ./TEST_perl.pl If successful, the following message should print to the screen: .. code-block:: SUCCESS perl test | | Test #7: sh *********** Issue the following two commands from within the *TESTS* directory. .. code-block:: ./TEST_sh.sh If successful, the following message should print to the screen: .. code-block:: 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: .. csv-table:: :widths: 10, 10, 10, 10, 10 :width: 50% 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: 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** .. code-block:: 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** .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: 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": .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: C function called by Fortran Values are xx = 2.00 and ii = 1 status = 2 SUCCESS test 2 fortran + c + netcdf + mpi | | | .. _Compiling WRF: 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: | .. code-block:: cd WRF #. Run the WRF configuration to specify your computing environment and compiler. | .. code-block:: ./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., | .. code-block:: ./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) |br| real.exe (real-data initialization) |br| ndown.exe (one-way nesting) |br| tc.exe (tc-bogusing) | **Compile for an idealized case** wrf.exe (model executable) |br| 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: 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: | .. code-block:: 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 ``./configure`` instead of the below command. | .. code-block:: ./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*. | .. code-block:: export WRF_DIR=path-to-wrf-directory/wrf-directory #. Issue the compile command. | .. code-block:: ./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: 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 :ref:`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 * `Obtain geographical input data`_ * `Obtain meteorological input data`_ | | | .. _`Installing a Terminal Window on Windows Machines`: ../terminal_windows.html .. _`Download the Fortran+C packaged file`: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/Fortran_C_tests.tar .. _netCDF-c: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/netcdf-c-4.7.2.tar.gz .. _netCDF-fortran: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/netcdf-fortran-4.5.2.tar.gz .. _MPI: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/mpich-3.0.4.tar.gz .. _jasper: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/jasper-1.900.1.tar.gz .. _zlib: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/zlib-1.2.11.tar.gz .. _libpng: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/libpng-1.2.50.tar.gz .. _`see csh Commands for Setting Environment Variables`: ./csh_env_var_commands.html .. _`see Installing Libraries for an Intel Compile`: ./install_libs_intel.html .. _`Download the library compatibility tests`: https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compile_tutorial/tar_files/Fortran_C_NETCDF_MPI_tests.tar .. _`obtain the WRF source code`: https://www2.mmm.ucar.edu/wrf/site/access_code/wrf_source.html .. _`Obtain the WPS source code`: https://www2.mmm.ucar.edu/wrf/site/access_code/wps_source.html .. _`Obtain geographical input data`: ../../access_code/geog_data.html .. _`Obtain meteorological input data`: ../../access_code/input_data.html .. _`WRF & MPAS-A User Support Forum`: https://forum.mmm.ucar.edu/