In this lesson, we will cover the basics of constructing and running a WRF-Hydro simulation using a prepared domain for the 'Gridded' configuration. For a detailed description of model configurations see the Technical Description.
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 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.
In this section we will describe the primary files needed to run a WRF-Hydro simulation.
A WRF-Hydro simulation consists of the following major components:
We will only cover basic descriptions of these elements in this lesson, for a detailed description see the Technical Description.
The WRF-Hydro model code, compiled executable/binary, and associated parameter table files were described in Lesson 1. If you have not already completed Lesson 1, please stop and do so now
Model run-time options are specified in two namelist files hydro.namelist and namelist.hrldas. These namelist files contain file path specifications, simulation duration, physics options, and output file selections, among others. We will cover many of these options in more depth in Lessons 4 and 5.
This lesson will use a prepared domain located in the ~/wrf-hydro-training/example_case directory. The structure of the example_case directory serves as a good example of how to organize your domain files. If using another domain with this lesson, such as one you may have created in the Geospatial processing tutorial, it is imperative that the file names and directory structure match those described below.
If using an official WRF-Hydro training example case, there will be a study area map and a Readme.txt file that describes the geographic setting, the directory, and the files.
First lets take a look at the map of the study area (map.png).
Now, lets view the Readme.txt included with the domain for a brief description of the example case and its contents.
%%bash
cat ~/wrf-hydro-training/example_case/Readme.txt
Now lets take a look at the actual directory
%%bash
ls ~/wrf-hydro-training/example_case
In this example case we have created 3 routing configurations for WRF-Hydro, National Water Model (NWM), Gridded, and Reach. For detailed descriptions of routing and physics configurations see the Technical Description. These three routing configurations have different geospatial data associated with them, and thus are represented by 3 separate directories in the ~/wrf-hydro-training/example_case
directory. Additionally, you will notice a fourth directory Gridded_no_lakes
. When running the Gridded configuration, some modifications to the geospatial data are needed to remove lakes from the domain. Therefore, domain files for the Gridded configuration without lakes are located in a separate gridded_no_lakes
directory.
This directory contains all the forcing data for our simulation. Note that there is only one FORCING
directory. The same forcing data can be used with all three configurations.
For this lesson, we will be running the Gridded configuration. Now we will explore the ~/wrf-hydro-training/example_case/Gridded
directory.
%%bash
ls ~/wrf-hydro-training/example_case/Gridded
The contents of this directory are described briefly in the Readme.txt
file that we viewed earlier, but we will discuss them again here. For a more detailed description of these files beyond what will be described below, see the Technical Description
DOMAIN: Directory containing all geospatial data and input files for the Gridded routing option with lakes included
%%bash
ls ~/wrf-hydro-training/example_case/Gridded/DOMAIN
Filename | Description | Source | Required |
---|---|---|---|
Fulldom_hires.nc | High resolution full domain file. Includes all fields specified on the routing grid. | WRF-Hydro GIS pre-processing toolkit | Yes |
GWBASINS.nc | 2D file defining the locations of groundwater basins on a grid | WRF-Hydro GIS pre-processing toolkit | When the baseflow bucket model is turned on and user defined mapping is off |
GWBUCKPARM.nc | Groundwater parameter table containing bucket model parameters for each basin | WRF-Hydro GIS pre-processing toolkit | When the baseflow bucket model is turned on |
LAKEPARM.nc | Lake parameter table containing lake model parameters for each catchment | WRF-Hydro GIS pre-processing toolkit | When lake and reservoir routing is turned on |
hydro2dtbl.nc | Spatially distributed parameter table for lateral flow routing within WRF-Hydro. | create_SoilProperties.R script (will also be automatically generated by WRF-Hydro) | When using spatially distributed terrain routing parameters |
geo_em_d01.nc | The data required to define the domain and geospatial attributes of a spatially-distributed, or gridded, 1-dimensional (vertical) land surface model (LSM) | GEOGRID utility in the WRF preprocessing system (WPS) | Yes |
wrfinput_d01.nc | file including all necessary fields for the Noah-MP land surface model, but with spatially uniform initial conditions. Users should be aware that the model will likely require additional spin-up time when initialized from this file. | create_Wrfinput.R script | Yes |
soil_properties.nc | Spatially distributed land surface model parameters | create_SoilProperties.R script | If SPATIAL_SOIL compile-time option set to 1 |
GEOGRID_LDASOUT_Spatial_Metadata.nc | projection and coordinate information for the land surface model grid. | WRF-Hydro GIS pre-processing toolkit | NO, but allows for CF compliant outputs |
lake_shapes/ | supplimental shape files that define lakes | arcGIS | NO |
RESTART: Directory containing model restart files.
%%bash
ls ~/wrf-hydro-training/example_case/Gridded/RESTART
Restart files are an essential part of the WRF-Hydro modeling system. They are output on a fixed timestep specified by the user in the namelist.hrldas and hydro.namelist files, and represent a complete 'snapshot' of the model state at that time. These files can be used to restart a WRF-Hydro simulation from where the previous simulation terminated with all the model states intact.
When running a WRF-Hydro simulation, you may start your simulation with default initial conditions, referred to as a 'cold start'. When starting from a cold start, a model spinup period is needed to move the model state away from the default initial conditions to a more realistic, physically-based model state. Model output from the spinup period is generally not used for interpretation.
Restart files output at the end the spinup period can be used as the initial conditions for subsequent simulations, referred to as a 'warm start'. Simulations that start from a 'warm start' are generally the primary target for interpretation. 'Warm' and 'cold' starting the model will be discussed more in Lesson 4.
Namelists are another key component of the WRF-Hydro modeling system and are the primary means of specifying inputs, outputs, and run-time options. There are two namelist files used by WRF-Hydro: hydro.namelist for the routing and hydrologic model and namelist.hrldas for the land-surface model. NOTE: These filenames are hard-coded into the model and can not be changed.
For all official WRF-Hydro domains, namelists will be included with each of the three domain configurations. This is done so that a user can easily run each configuration with minimal setup, and they serve as a starting point for users to specify their own namelists for a given configuration.
There are different namelists for each configuration because certain namelist options are specific to the domain configuration used. We will cover the various namelist options in detail in Lesson 4, but for now we will simply view the namelist and use the default namelist provided with the Gridded configuration to construct our simulation.
Take a moment and read through the two namelists below and note how all filepaths are relative to the current directory containing the namelist. This is the recommended way of specifying filepaths.
%%bash
cat ~/wrf-hydro-training/example_case/Gridded/hydro.namelist
%%bash
cat ~/wrf-hydro-training/example_case/Gridded/namelist.hrldas
Now that we have covered the major functional elements that constitute a simulation, we will combine these elements and construct a simulation. This is done by placing the FORCING
, Gridded/DOMAIN
, trunk/NDHMS/Run
directories and namelist.hrldas
and hydro.namelist
files together in a directory that will be our simulation directory. However, to save disk space it is often preferable to create symbolic links rather than copying the actual files. NOTE: We will only use symbolic links with files that we will NOT be editing
In the following steps, we will construct our simulation directory.
Step 1. Create simulation directory
We will create a directory for our simulation
%%bash
mkdir -p ~/wrf-hydro-training/output/lesson2/run_gridded_default
ls ~/wrf-hydro-training/output/lesson2/
Step 2. Copy model run files
We will copy the required model run files from the ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/Run directory. These files are small so we will make actual copies rather than symbolic links in this case. Additionally, copies are preferred in this case because a user may want to edit the *.TBL files and as stated previously symbolic links should not be used with files that we may edit.
%%bash
cp ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/Run/*.TBL \
~/wrf-hydro-training/output/lesson2/run_gridded_default
cp ~/wrf-hydro-training/wrf_hydro_nwm_public/trunk/NDHMS/Run/wrf_hydro.exe \
~/wrf-hydro-training/output/lesson2/run_gridded_default
ls ~/wrf-hydro-training/output/lesson2/run_gridded_default
Step 3. Symlink DOMAIN files
We will create symbolic links to the required domain files from the ~/wrf-hydro-training/DOMAIN/Gridded
directory. These files can be large so we will make symbolic links rather than copying the actual files. NOTE: Because we are using symbolic links, the paths MUST be absolute and can't use ~. We can simply replace the ~
with the $HOME
environment variable to make an absolute path.
%%bash
cp -as $HOME/wrf-hydro-training/example_case/FORCING \
~/wrf-hydro-training/output/lesson2/run_gridded_default
cp -as $HOME/wrf-hydro-training/example_case/Gridded/DOMAIN \
~/wrf-hydro-training/output/lesson2/run_gridded_default
cp -as $HOME/wrf-hydro-training/example_case/Gridded/RESTART \
~/wrf-hydro-training/output/lesson2/run_gridded_default
ls ~/wrf-hydro-training/output/lesson2/run_gridded_default
Step 4. Copy namelist files
Because we are using the default prepared namelists from the example WRF-Hydro domain, we will copy those in as well. If you were using your own namelists, they would likely be edited and copied from elsewhere. These are small text files so we will make actual copies rather than symbolic links.
%%bash
cp ~/wrf-hydro-training/example_case/Gridded/namelist.hrldas \
~/wrf-hydro-training/output/lesson2/run_gridded_default
cp ~/wrf-hydro-training/example_case/Gridded/hydro.namelist \
~/wrf-hydro-training/output/lesson2/run_gridded_default
ls ~/wrf-hydro-training/output/lesson2/run_gridded_default
We have now constructed our simulation directory with all the requisite files. In the next section we will run the simulation using mpi.
Now that we have constructed our simulation directory, we can run our simulation. For this we will be using the mpi run
command, which has a number of arguments. For this simple case, we only need to supply one argument, the number of cores. This is done with the -np
argument, and we will set it to 4 cores.
We will pipe the output to a log file because running a simulation can generate a lot of standard output in the terminal.
%%bash
cd ~/wrf-hydro-training/output/lesson2/run_gridded_default
mpirun -np 2 ./wrf_hydro.exe >> run.log 2>&1
If your simulation ran successfully, there should now be a large number of output files in the ~/wrf-hydro-training/output/lesson2/run_gridded_default
. We will describe these output files in more depth in Lesson 4. Additionally, detailed descriptions of the output files can be found in the Technical Description.
List the contents of the ~/mount/wrf-hydro-training/output/lesson2/run_gridded_default
directory.
%%bash
ls ~/wrf-hydro-training/output/lesson2/run_gridded_default | tail -40
There are also four important files for determining the success or failure of the run, diag_hydro.0000*. The number of diag files is equal to the number of cores used for the run. These diag_hydro.0000* files contain logs and diagnostics on the simulation run. Since we ran using 4 cores, we have 4 diag_hydro.0000* files.
You can check that your simulation ran successfully by examining the last line of the diag files, which should read The model finished successfully........
%%bash
tail -1 ~/wrf-hydro-training/output/lesson2/run_gridded_default/diag_hydro.00000
This concludes Lesson 2. In the next lesson, we will briefly discuss working with some of the output files. The output files from WRF-Hydro are standard netCDF4 files, and thus there are many way to work with these data. In lesson 3 we will simply cover a few Python libraries and commands that we will need for later lessons in this tutorial. Lesson 3 is by no means a comprehensive guide to working with netCDF files.
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.