# Table of Contents

# Lesson 1 - Source code overview and compilation¶

## Overview¶

In this lesson, we will cover the basic structure of the source code, discuss the various compile-time options, and compile the model code.

### Software and conventions¶

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.

## Orientation to the WRF-Hydro source code directory¶

### Where to download¶

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.

### Directory structure¶

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.

## Compiling WRF-Hydro¶

### WRF-Hydro compile-time options¶

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

### Compiling WRF-Hydro in uncoupled mode¶

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.

In [1]:

    %%bash
    ls ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS

    CPL
    Data_Rec
    Debug_Utilities
    Doc
    HYDRO_drv
    Land_models
    MPP
    Makefile
    README.build.txt
    Rapid_routing
    Routing
    arc
    compile_offline_Noah.sh
    compile_offline_NoahMP.sh
    compile_options.json
    configure
    deprecated
    hrldas_namelists.json
    hydro_namelists.json
    nudging
    template
    utils
    wrf_hydro_config

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.

In [2]:

    %%bash
    cd ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/; ./configure 2

    Configured: gfort

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.

In [3]:

    %%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.

In [4]:

    %%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.

In [5]:

    %%bash
    tail -13 ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/compile.log

    *****************************************************************
    Make was successful

    *****************************************************************
    The environment variables used in the compile:
    HYDRO_D=1
    NCEP_WCOSS=0
    NETCDF=/usr/local
    SPATIAL_SOIL=1
    WRFIO_NCD_LARGE_FILE_SUPPORT=1
    WRF_HYDRO=1
    WRF_HYDRO_NUDGING=0
    WRF_HYDRO_RAPID=0

## Exploring compilation artifacts¶

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

In [6]:

    %%bash
    ls ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/Run

    CHANPARM.TBL
    GENPARM.TBL
    HYDRO.TBL
    MPTABLE.TBL
    SOILPARM.TBL
    hydro.namelist
    namelist.hrldas
    wrf_hydro.exe
    wrf_hydro_NoahMP.exe

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

# Next up - Running WRF-Hydro¶

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.