This lesson covers two topics: creating your case-specific domain that will also be used throughout the WRF-Hydro system and defining static and initial conditions used for the land surface model.
This notebook is not intended to be used interactively, but rather provide instructions for how to use an additional Docker container to generate several domain files needed to run WRF-Hydro.
This lesson uses the wrfhydro/wps:centam docker utility, which can be obtained using the command docker pull wrfhydro/wps:centam
.
Note: For in person WRF-Hydro trainings this has been done for you. DO NOT pull the container.
Additionally, we will use several files from the Costa Rica example case provided for this training.
All paths used in this lesson assume that the lesson materials are located under your home directory in a folder named wrf-hydro-training.
WRF-Hydro leverages the extensive domain generation and geophysical dataset processing tools available in the WRF Preprocessing System (WPS). The geographical input data (e.g. land cover, soil texture, and terrain height) are some of the primary datasets used by WRF-Hydro. The entire dataset collection can be obtained from the WPS geographical input data download page. However, these data are rather large (~50GB) and contain a number of datasets that are not used in most implementations of WRF-Hydro. To facilitate the domain generation process, the WRF-Hydro team has created a subset of the data by removing unnecessary data, removing resolutions of the data not commonly used, and limiting the areal extent of this subset. This is consistent with the availability of other datasets used in this tutorial. Thus, the dataset provided with the wrfhydro/wps Docker container is considerably smaller than the complete WRF-WPS dataset.
The WPS program geogrid.exe is used to create the geo_em_d01.nc file, hereafter referred to as the 'geogrid' file. The geogrid.exe program takes a Fortran namelist (namelist.wps) and the WPS geographical input data as inputs and creates the geogrid file. However, the geogrid.exe program requires that WRF and WPS be built according to your system specification, and building WRF and WPS can be difficult on some systems. Additionally, much of the functionality of WRF and WPS is not utilized for creating a geogrid file for WRF-Hydro, and many of the options in the namelist.wps are not relevant to this process. Therefore, we have created a Docker container and Python command line utility to abstract much of the WRF/WPS complexity and simplify the process of creating a geogrid file for WRF-Hydro users.
We will cover the steps to create the geogrid file using this method in the section 'Creating the geogrid file'. For more advanced usage please see the WPS documentation.
The land surface model in WRF-Hydro operates on the domain defined within the geogrid file. The geogrid.exe program generates this file based upon input variables specified in the namelist.wps file. The first step to creating the geogrid file is to define our domain boundaries. The geogrid.exe program takes a centerpoint, x and y grid specifications, and other projection information to define a bounding box for the domain. If you do not already have coordinates, you can obtain them from Google Earth or a standard GIS system. However, for this tutorial we have supplied the coordinates for you and you may use the WRF-Hydro geogrid python command line utility to visualize the domain location and create the geogrid file given these coordinates.
The WPS geogrid.exe utility is controlled by options set in the namelist.wps. As previously stated, there are many options in the namelist.wps file that are not relevant to most WRF-Hydro users. For educational purposes, we will take a quick look at a full namelist.wps file and then discuss the relevant options used by the WRF-Hydro geogrid utility wrapper in more detail.
&share
wrf_core = 'ARW',
max_dom = 1,
start_date = '2006-08-16_12:00:00'
end_date = '2006-08-16_18:00:00'
interval_seconds = 21600
io_form_geogrid = 2,
/
&geogrid
parent_id = 1,
parent_grid_ratio = 1,
i_parent_start = 1,
j_parent_start = 1,
e_we = 14,
e_sn = 12,
geog_data_res = 'usgs_30s+default',
dx = 1000,
dy = 1000,
map_proj = 'lambert',
ref_lat = 10.2191,
ref_lon = -84.2899
truelat1 = 10.0,
truelat2 = 0.0,
stand_lon = -90.0
/
&ungrib
out_format = 'WPS',
prefix = 'FILE',
/
&metgrid
fg_name = 'FILE'
io_form_metgrid = 2,
/
A full description of these options can be found in the WPS user guide at http://www2.mmm.ucar.edu/wrf/users/docs/user_guide_V3.9/users_guide_chap3.html. The options that are of interest to most WRF-Hydro users are the following:
Table 1. WPS namelist options relevent to WRF-Hydro
Option | Description |
---|---|
e_we | The number of grid edges in the west-east dimension. The number of grid centers will be e_we-1. |
e_sn | The number of grid edges in the south-north dimension. The number of grid centers will be e_sn-1. |
ref_lat | A real value specifying the latitude part of a (latitude, longitude) center-point of the domain. |
ref_lon | A real value specifying the longitude part of a (latitude, longitude) center-point of the domain. West longitudes are negative, and the value of ref_lon should be in the range [-180, 180]. |
dx | A real value specifying the grid distance in the x-direction where the map scale factor is 1. The grid distance is in meters for the 'polar', 'lambert', and 'mercator' projection, and in degrees longitude for the 'lat-lon' projection. |
dy | A real value specifying the grid distance in the y-direction where the map scale factor is 1. The grid distance is in meters for the 'polar', 'lambert', and 'mercator' projection, and in degrees latitude for the 'lat-lon' projection. |
map_proj | A character string specifying the projection of the simulation domain. Accepted projections are 'lambert', 'polar', 'mercator', and 'lat-lon'. Default value is 'lambert'. |
truelat1 | A real value specifying, the first true latitude for the Lambert conformal conic projection, or the only true latitude for the Mercator and polar stereographic projections. |
truelat2 | A real value specifying, the second true latitude for the Lambert conformal conic projection. For all other projections, truelat2 is ignored. No default value. |
stand_lon | A real value specifying, the longitude that is parallel with the y-axis in the Lambert conformal and polar stereographic projections. For the regular latitude-longitude projection, this value gives the rotation about the earth's geographic poles. No default value. |
geog_data_res | A character string specifying a corresponding resolution or list of resolutions separated by + symbols of source data to be used when interpolating static terrestrial data to the grid. This string should contain a resolution matching a string preceding a colon in a rel_path or abs_path specification (see the description of GEOGRID.TBL options) in the GEOGRID.TBL file for each field. If a resolution in the string does not match any such string in a rel_path or abs_path specification for a field in GEOGRID.TBL, a default resolution of data for that field, if one is specified, will be used. If multiple resolutions match, the first resolution to match a string in a rel_path or abs_path specification in the GEOGRID.TBL file will be used. Default value is 'default'. |
geog_data_path | A character string giving the path, either relative or absolute, to the directory where the geographical data directories may be found. This path is the one to which rel_path specifications in the GEOGRID.TBL file are given in relation to. No default value. |
To simplify the process of creating the geogrid file, these options are the only ones needed when using the WRF-Hydro geogrid Docker utility.
Lets take a look at the namelist.wps file used by the wrfhydro/wps:centam
docker utility. This is also included in the training container example case at the following path: ~/wrf-hydro-training/example_case/supplemental/namelist.wps
&share
wrf_core = 'ARW',
max_dom = 1,
start_date = '2006-08-16_12:00:00'
end_date = '2006-08-16_18:00:00'
interval_seconds = 21600
io_form_geogrid = 2,
/
&geogrid
parent_id = 1,
parent_grid_ratio = 1,
i_parent_start = 1,
j_parent_start = 1,
e_we = 14,
e_sn = 12,
geog_data_res = 'usgs_30s+default',
dx = 1000,
dy = 1000,
map_proj = 'lambert',
ref_lat = 10.2191,
ref_lon = -84.2899
truelat1 = 10.0,
truelat2 = 0.0,
stand_lon = -90.0
/
&ungrib
out_format = 'WPS',
prefix = 'FILE',
/
&metgrid
fg_name = 'FILE'
io_form_metgrid = 2,
/
In general, users want to generate the largest, highest-resolution model domain possible. Unfortunately, we are often constrained by available computational power or drive storage. These contraints usually define the acceptable grid sizes for us (e_we, e_sn).
We recommend that users first define the coordinates of the center of their domain via ref_lat and ref_lon. Once you know your domain center, you can play with dx dy and e_we e_sn* if needed to cover your area of interest.
To help users visualize the extent of their model domain we have also created a plotting utility that runs within the WPS container to preview a domain based upon a specied namelist. A flag can be specified in order to run only this plotting utility. To learn more about how to run the WPS docker utility let's read the help.
On your local machine open up a new terminal or PowerShell window and type the following:
docker run wrfhydro/wps --help
Note that the Docker utility entrypoint script takes 4 arguments, the first --namelist_path
is the path to your namelist.wps file, the second --output_dir
is the path to the directory to hold the output, and the third --plot_only
is a boolean True
or False
indicating whether or not to plot the domain. If plot_only
the utility will only plot the domain and not create the geogrid file. This option is useful for making changes to your domain location or extent. The fourth argument --create_wrfinput
is a boolean True
or False
indicating whether or not to create a wrfinput file that is used to provide initial land surface conditions to WRF-Hydro.
In order to run the WPS utility you will need to provide a namelist (namelist.wps
) file. To create this file open any text editor and copy the text from the namelist displayed above. Save this file as namelist.wps
in working directory on your local machine.
Now, let's create a plot from your namelist.wps. Run the following command replacing the <local directory with your namelist.wps>
with full path to the directory containing your namelist. Note that output file(s) will also appear in this directory.
docker run -v <local directory with your namelist.wps>:/home/docker/mount wrfhydro/wps:centam --namelist_path /home/docker/mount/example_case/supplemental/namelist.wps --output_dir /home/docker/mount --plot_only
Now view the plot of your model domain.
Now we will create the geogrid and wrfinput files using the container.
This time we run the utility with --plot_only
set to False (this is the default). A plot of the domain will still be produced, but the geogrid.exe utility will also be executed to create the geogrid file.
An R script will also run within the container in order to produce the wrfinput file. The wrfinput_d01.nc is a very basic WRF-Hydro initialization file (wrfinput) from a WRF geogrid file and a set of user-specified conditions. The file contains fields of spatially uniform initial model states of soil moisture, soil temperature, soil liquid water content and skin temperature among a few other variables necessary for model cold-start initialization. This file can be used as a 'cold start' for long-term model spin-up or users can overwrite the fields in the file created. Sophisticated and WRF-savvy users can bypass this script and use the WRF utility real.exe to create a wrfinput file from model or reanalysis products.
The R script used to create this file can be downloaded at https://ral.ucar.edu/projects/wrf_hydro/pre-processing-tools.
To run the container enter the following command in the terminal on your local machine:
docker run -v <local directory with your namelist.wps>:/home/docker/mount wrfhydro/wps:centam --namelist_path /home/docker/mount/example_case/supplemental/namelist.wps --output_dir /home/docker/mount --create_wrf_input
Now that we have created our files locally using the WPS Docker utility, we will take a look at the same files included in our example case within the training Docker container.
We quickly display the file headers using the ncdump command line utility and open the geogrid file using the Python library xarray
to visualize its contents.
%%bash
ncdump -h ~/wrf-hydro-training/example_case/Gridded/DOMAIN/geo_em.d01.nc
%matplotlib inline
import xarray as xr
geogrid = xr.open_dataset('~/wrf-hydro-training/example_case/Gridded/DOMAIN/geo_em.d01.nc')
geogrid.HGT_M.plot()
View the contents of the wrfinput_d01.nc file
%%bash
ncdump -h ~/wrf-hydro-training/example_case/Gridded/DOMAIN/wrfinput_d01.nc
This concludes the lesson on domain definition and initial conditions for WRF-Hydro.