In this lesson, we will cover the basic structure of the source code, discuss the various compile-time options, and compile the model code.
The easiest way to run these lessons is via the wrfhydro/training Docker container, which has all software dependencies and data pre-installed.
For a complete description of the software environment used for this training please see Lesson 0 - Getting started.
You may either execute commands by running each cell of this notebook. Alternatively, you may open a terminal in Jupyter Lab by selecting New -> Terminal
in your Home
tab of Jupyter Lab and input the commands manually if you prefer. You can also use your own terminal by logging into the container with the command docker exec -it wrf-hydro-training bash
All paths used in this lesson assume that the lesson materials are located under your home directory in a folder named wrf-hydro-training. If your materials are located in another directory, you will not be able to run the commands in this notebook inside Jupyter and will need to type them manually in your terminal session.
Current, stable WRF-Hydro source code can be obtained from the WRF-Hydro website at https://ral.ucar.edu/projects/wrf_hydro/model-code, and the bleeding-edge version can be obtained from our GitHub page at https://github.com/NCAR/wrf_hydro_nwm_public.
The top-level directory structure of the code is described below as nested under trunk/NDHMS. The tables below provide brief descriptions of the file contents of each subdirectory.
Table 1 Description of the file contents of each source code sub-directory.
File/directory name | Description |
---|---|
arc/ | Contains macro files, which specify the compile configurations, compiler options, links to netCDF libraries, etc |
CPL/Noah_cpl/ | Contains the WRF-Hydro coupling interface for coupling WRF-Hydro components with the standalone (offline) Noah land surface model data assimilation and forecasting system |
CPL/_cpl/ | Contains the WRF-Hydro coupling interface for coupling WRF-Hydro components with the standalone (offline) Noah-MP land surface model data assimilation and forecasting system |
CPL/WRF_cpl/ | Contains the WRF-Hydro coupling interface for coupling WRF-Hydro components with the WRF system |
CPL/CLM_cpl/, CPL/LIS_cpl/, CPL/NUOPC_cpl/ | Work in progress for ongoing coupling work. Not actively supported. |
Data_Rec/ | Contains some data declaration modules |
deprecated/ | Contains files not currently used |
Doc/ | Pointer to location of full documentation (i.e. this document). |
HYDRO_drv/ | Contains the high-level WRF-Hydro component driver: module_HYDRO_drv.F |
Land_models/Noah/ | Contains the Noah land surface model driver for standalone or uncoupled applications |
Land_models/NoahMP/ | Contains the Noah-MP land surface model driver for standalone or uncoupled applications |
MPP/ | Contains MPI parallelization routines and functions |
nudging/ | Contains nudging data assimilation routines and functions |
Rapid_routing/ | Contains the files necessary for RAPID routing model coupling. Unsupported as version of RAPID is out of date. |
Routing/ | Contains modules and drivers related to specific routing processes in WRF-Hydro |
template/ | Contains example namelist files for Noah, Noah-MP and the WRF-Hydro modules (HYDRO). Default and example parameter tables are also included for HYDRO. Note: Parameter tables for Noah and Noah-MP are stored within the Land_models directory. A sample bash script (setEnvar.sh) that could be passed to the compile script listing compile time options for WRF-Hydro is also located here. |
compile_offline_Noah.sh | Script for compiling WRF-Hydro standalone (offline) version with the Noah land surface model |
compile_offline_NoahMP.sh | Script for compiling WRF-Hydro standalone (offline) version with the Noah-MP land surface model |
configure | Script to configure the WRF-Hydro compilation |
Makefile | The top-level makefile for building and cleaning WRF-Hydro code |
README.build.txt | WRF-Hydro build instructions for the standalone model |
wrf_hydro_config | Configure script for coupled WRF-Hydro configuration |
*.json | JSON files used for testing |
See the Technical Description for more detailed information on individual Fortran modules.
Compile-time options are choices about the model structure that are determined when the model is compiled. Below is a table describing the compile time options.
Variable | Options | Description |
---|---|---|
WRF_HYDRO | 1=On | This is a WRF environment variable. Always set to 1 for compiling WRF-Hydro. |
HYDRO_D | 0=Off, 1=On | Enhanced diagnostic output for debugging |
SPATIAL_SOIL | 0=Off, 1=On | Spatially distributed parameters for Noah-MP. This allows Noah-MP to use spatially distributed parameters for the land surface model rather than parameter based upon soil class and land use category look up tables. See Section 5.3.1 of the Technical Description |
WRF_HYDRO_RAPID | 0=Off, 1=On | Coupling with the RAPID routing model. This option is not currently supported. |
WRFIO_NCD_LARGE_FILE_SUPPORT | 0=Off, 1=On | Large netcdf file support. Allow netCDF I/O of files larger than 2GB. |
NCEP_WCOSS | 0=Off, 1=On | WCOSS file units. Do not use unless working on the WCOSS machines. |
WRF_HYDRO_NUDGING | 0=Off, 1=On | Streamflow nudging. Enable the streamflow nudging routines for Muskingum-Cunge Routing. See Section 3.6.2. of the Technical Description |
In this section we will compile the model in "standalone" or "uncoupled" mode using the Noah-MP land-surface model.
NOTE: These compile options may change depending on system configuration if you are running this lesson on your native system rather than in the wrfhydro/training Docker container. The WRF-Hydro source code currently supports compilation under the PGI Fortran compiler, the Intel ifort compiler and the public license GNU Fortran compiler gfortran. See the How To Build & Run WRF-Hydro in Standalone Mode user guide for information on system requirements.
Step 1. List the contents of the trunk/NDHMS directory.
%%bash
ls ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS
Step 2. Configure the compilation environment.
As noted in Table 1, the script configure is used to configure the compilation environment. Execute the configure script and you will be prompted with a choice of compiler. Because we are using the GNU Fortran compiler in our training environment, we will select option 2
for "gfortran".
NOTE: If running this tutorial on your own system, select the appropriate compiler for your system.
%%bash
cd ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/; ./configure 2
Step 3. Make a copy of the template environment variable file, template/setEnvars.sh
As described in Table 1, the template/setEnvars.sh script can be used to specify compile-time options by setting environment variables. We will use this method of compilation for this lesson.
%%bash
cp ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/template/setEnvar.sh \
~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/setEnvar.sh
Step 4. Set compile-time options
Edit the trunk/NDHMS/setEnvar.sh script to set environment variables required by the compile script. Your setEnvar.sh should look like the bash script below when you are finished.
#!/bin/bash
# WRF-Hydro compile time options
# This is a WRF environment variable. Always set to 1=On for compiling WRF-Hydro.
export WRF_HYDRO=1
# Enhanced diagnostic output for debugging: 0=Off, 1=On.
export HYDRO_D=1
# Spatially distributed parameters for NoahMP: 0=Off, 1=On.
export SPATIAL_SOIL=1
# RAPID model: 0=Off, 1=On.
export WRF_HYDRO_RAPID=0
# Large netcdf file support: 0=Off, 1=On.
export WRFIO_NCD_LARGE_FILE_SUPPORT=1
# WCOSS file units: 0=Off, 1=On.
export NCEP_WCOSS=0
# Streamflow nudging: 0=Off, 1=On.
export WRF_HYDRO_NUDGING=0
Step 5. Compile WRF-Hydro in uncoupled mode
We support compiling the uncoupled WRF-Hydro model with both the Noah and Noah-MP (recommended) land surface models. Two helper scripts are supplied, compile_offline_Noah.sh and compile_offline_NoahMP.sh, to assist users with the compilation process. We will be compiling with the Noah-MP land surface model for this lesson, and thus we will be using the compile_offline_NoahMP.sh script.
The compile_offline_Noah.sh and compile_offline_NoahMP.sh execute a similar process during compilation, and this process is described in more detail in How to Build & Run WRF-Hydro in Standalone Mode and section 2.6 of the Technical Description. One action that these scripts perform is to source the configureEnvars.sh script to specify compile-time options by setting environment variables.
We will now compile the model by executing the compile_offline_NoahMP.sh script and supplying our configureEnvars.sh script as the first argument. Additionally, we will pipe the output from the compilation process to a log file because compilation can generate a lot of output.
%%bash
cd ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/; \
./compile_offline_NoahMP.sh setEnvar.sh >> compile.log 2>&1
Step 6. Check the compile log to make sure that compilation completed successfully
The last few lines of your compile log should look like the following if compilation succeeded for this lesson.
%%bash
tail -13 ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/compile.log
After a successful compilation, there will be a new directory created called Run in the trunk/NDHMS directory. The Run directory contains the compiled binary wrf_hydro.exe as well as a number of template input files to assist users with parameterizing WRF-Hydro.
Check the contents of the Run directory
%%bash
ls ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/Run
The Run directory now contains parameter tables, two namelist files, and the executable. Table 3 below briefly describes the contents of the Run directory. More information on the individual files can be found in the Technical Description. Table 3 Description of the file contents of the Run directory.
Filename | Description |
---|---|
CHANPARM.TBL | Channel routing parameter table |
GENPARM.TBL | This file contains global parameters for the Noah-MP land surface model |
HYDRO.TBL | Parameter table for lateral flow routig within WRF-Hydro. In the HYDRO.TBL file parameters are specified by land cover type or soil category |
MPTABLE.TBL | This file contains parameters that are a function of land cover type |
SOILPARM.TBL | This parameter table contains parameters that are assigned based upon the soil classification |
hydro.namelist | Specifies the settings for all of the routing components of WRF-Hydro. Edit this file to your research interests |
namelist.hrldas | Specifies the land surface model options to be used. Edit this file to your research interests. |
wrf_hydro.exe | WRF-Hydro executible/binar file |
wrf_hydro_NoahMP.exe | symlink to the executible file compiled for Noah-MP |
This concludes Lesson 1. In the next lesson we will run a basic WRF-Hydro simulation using a prepared domain, and briefly discuss run-time options.
IT IS BEST TO EITHER SHUTDOWN THIS LESSON OR CLOSE IT BEFORE PROCEEDING TO THE NEXT LESSON TO AVOID POSSIBLY EXCEEDING ALLOCATED MEMORY. Shutdown the lesson be either closing the browser tab for the lesson or selecting KERNAL->SHUTDOWN
in the jupyter notebook toolbar.