ncar / wrf_hydro_training

Jupyter notebooks for WRF-Hydro trainings

WRF-Hydro

Overview

This repository contains lessons in the form of Jupyter notebooks focused on understanding the basic functionality of WRF-Hydro.

Requirements

The easiest and recommended way to run these lessons is via the wrfhydro/training Docker container, which has all software dependencies and data pre-installed.

• Docker >= v.17.12
• Web browser (Google Chrome recommended)

Where to get help and/or post issues

If you have general questions about Docker, there are ample online resourves including the excellent Docker documentation at https://docs.docker.com.

If you have questions about WRF-Hydro or these lessons please use the contact form on our website: https://ral.ucar.edu/projects/wrf_hydro/contact.

If you have found a bug in these lessons please log an issue on the Issues page of the GitHub repository at https://github.com/NCAR/wrf_hydro_training/issues.

How to run

Make sure you have Docker installed and that it can access your localhost ports. Most out-of-the-box Docker installations accepting all defaults will have this configuration.

Step 1: Open a terminal or PowerShell session

Step 2: Pull the wrfhydro/training Docker container for the desired code version Each training container is specific to a release version of the WRF-Hydro source code, which can be found at https://github.com/NCAR/wrf_hydro_nwm_public/releases.

Issue the following command in your terminal to pull a specific version of the training corresponding to your code release version.

docker pull wrfhydro/training:v5.2.0-rc1

Step 3: Start the training container Issue the following commnand in your terminal session to start the training Docker container.

docker run --name wrf-hydro-training -p 8888:8888 -it wrfhydro/training:v5.2.0-rc1

Note: If you have already started the training once you will need to remove the previous container using the command docker rm wrf-hydro-training

The container will start and perform a number of actions before starting the training.

1. The container will pull the model code
2. The container will pull an example test case
3. The container will launch a Jupyter Lab server and echo the address to your terminal

Note: Port forwarding is setup with the -p 8888:8888 argument, which maps your localhost port to the container port. If you already have sometihng running on port 8888 on your localhost you will need to change this number

wrf_hydro_training's Issues

Create lesson 4

Lesson 4 - Run time options

An in-depth look at namelists and run time options

• Create technical lesson material
• Technical proofing
• Editorial proofing

Lesson-S1-wps - use of rectilinear

When you consider this from the perspective of lat / lon coordinates the WRF / WRF-Hydro domains are curvilinear grids. Only bringing this up because it's an important point for regridding (forcing or other data) to the domain (it's how ESMF classifies these grids). My apologies for not mentioning this earlier when you asked about the grids, but was thinking about this from a different context (projection coordinates).

Need to change the output_channelBucket_influx option in the test case

output_channelBucket_influx is an option in the hydro.namelist controlling the content of the CHRTOUT files and it is only used for the channel only runs. For the channel only runs since we require the inflows into the stream as input, we output them in full model run and write them into the CHRTOUT files. Then these CHRTOUT files would become the input files for the Channel only runs. I am assuming we are not using this option for the training and we should leave it as 0=None for the test cases.

Right now the output_channelBucket_influx is set to 2, and it will cause the model to fail if you change the groundwater bucket model option to zero or 2. I would suggest changing this option in for the distributed test case.

FORCING as a third prong on the framework fork

The way "model" and "domain" are defined in the diagram, I would contend that FORCING is separate from both. It is specific to the domain because of the extent, but it has to be prepared separately.

Update reference simulations in croton_NY domain

The old reference restarts files and hydrographs may be stale. Update once code is updated

Agenda with notes on hands on sessions - what activities were done etc.

Proper code and syntax highlighting in all guides would be nice.

Get a consistent syntax highlighting theme and for all code-based student guides

Transcribe student guides/exercises to markdown

Tag each docker container with label

There was some confusion over what docker students were in later in hte course when multiple containers were open.

Adding the compilation of the coupled mode

I am not sure if we want to talk about coupled WRF-Hydro, but if yes, it would be nice to add the compilations steps to this lesson.

Namelist changes for Thursday exercises

(not in order)

1. Supplemental Precip - Arezoo is working on this one

2. Warm vs. Cold Start - Arezoo is working on this one

3. Terrain Routing
   Cycles these hydro.namelist options all on (1s) and all off (0s):
   ! Switch to activate subsurface routing...(0=no, 1=yes)
   SUBRTSWCRT = 1
   ! Switch to activate surface overland flow routing...(0=no, 1=yes)
   OVRTSWCRT = 1

4. Groundwater
   In hydro.namelist, walk through all 0-2 options here:
   ! Switch to activate baseflow bucket model...(0=none, 1=exp. bucket, 2=pass-through)
   GWBASESWCRT = 1

5. Reach routing
   (requires new domain files)
   Change the channel routing option to 2:
   ! Specify channel routing option: 1=Muskingam-reach, 2=Musk.-Cunge-reach, 3=Diff.Wave-gridded
   channel_option = 2
   Uncomment the route link file specification:
   ! Specify the reach file for reach-based routing options (e.g.: "Route_Link.nc")
   route_link_f = "./DOMAIN/Route_Link.nc"

6. NWM
   (requires new domain files, and is a modification of reach routing above)
   Channel routing option is 2:
   ! Specify channel routing option: 1=Muskingam-reach, 2=Musk.-Cunge-reach, 3=Diff.Wave-gridded
   channel_option = 2
   Route link file is specified:
   ! Specify the reach file for reach-based routing options (e.g.: "Route_Link.nc")
   route_link_f = "./DOMAIN/Route_Link.nc"
   Turn on user-defined mapping:
   ! User defined mapping, such NHDPlus: 0=no (default), 1=yes
   UDMP_OPT = 1
   Specify a spatial weights file:
   ! If on, specify the user-defined mapping file (e.g.: "spatialweights.nc")
   !udmap_file = "./DOMAIN/spatialweights.nc"

7. Gridded lakes - Laura is working on this one

8. Parameter experiments - coming soon!

Remove the separate /output directories.

This is confusing and I think we can just stick with our traditional ways to setup directories and run the model, unless there is something with the environment that prevents it.

push last data/docker/material update monday 10/16

how to start docker/ training environment at home guide

Create lesson S1

Lesson S1 - WRF Preprocessing System (WPS)

• Create technical lesson material
• Technical proofing
• Editorial proofing

Remove the upper level ./DOMAIN dir.

I think this will cause confusion for users and it is not how I'd advocate a user setting up their model. Obviously this is my opinion, but I'd suggest using, e.g.:
NWM/DOMAIN
or
NWM/RUN/DOMAIN

I also think we should skip the symlinking. Can't we just setup the simulation in the directory structure we've already setup? This is what we recommend for users in their own system setup as far as I know.

Replace ls with bash ls

WRF-Hydro dockerfile needs ot be made

rebuild docker with latest source code

Create Lesson 5

Lesson 5 - NWM and Reach configurations

A quick look at running the NWM and Reach configurations

• Create technical lesson material
• Technical proofing
• Editorial proofing

using RESTART file from the run with LAKE for the run WO LAKE

It is stating in the -Gridded_no_lakes: (Lesson 2)
-RESTART: Directory containing model restart files for the Gridded
routing option with lakes included.
Is this a typo, or we are going to use the RESTART from the run with LAKES on for the run without any lake?

suggest adding the GIS map of Croton domain

I made a map - Molly has it. Might be nice to give users some context of this domain.

quickstart guide for beginning of training

Get final presentations

Molly is refactoring powerpoint presentations onto consistent template

Get presentations loaded up to repo

Need WRF-Hydro source code that works with test case

Currently @jmills-ncar does not have a final WRF-Hydro source code and test case to use for the Oct Cuahsi training. This is an issue thread to track progress.

WPS Docker file and build needs to be checked by @barlage

Add attendee list/ pre survey

& Post survey feedback

Create lesson 2

Lesson 2 - Running WRF-Hydro

• Create technical lesson material
• Technical proofing
• Editorial proofing

The definition of "model" - this is for discussion

I have a general issue with the distinction of "model" vs. "domain". I think this will cause some confusion as it is not really how I think of it - but we should get others' input.
The "model" to me is the complete set of the domain and the binary/code. The code is sort of the brain and the domain is the ...body? It's not a perfect analogy, but I would advocate that if we're going to separate these, we use: code base/binary and domain as categories, which comprise the complete model.

Coordination checklist ?

Finalize classroom setup/IT document

https://docs.google.com/a/ucar.edu/document/d/1TQWf9jwI7NvqB7_Wp4Si48HkSRI3H__MNwbNhs9lzZc/edit?usp=sharing

Synopsis write up regarding the students/feedback/notes/timeline and advancements that were made for this training compared to the last cuahsi training

Create lesson 3

Lesson 3 - visualizing outputs

This is just a short lesson showing how we will use xarray to plot hydrographs. This needs to proceed the more in-depth run-time option lesson (lesson 4) to be able to see the effects of the changes

• Create technical lesson material
• Technical proofing
• Editorial proofing

WRF-Hydro Test case

This issue to to track progress on the test case for Oct 2017 Cuahsi training

RStudio docker file

WPS cutout has been provided by Milke, still needs to be tested

Need to run the WPS cutout provided by @barlage through the container to test its functionality

Rebuild wrf_docker container with proper source code

R dockerfile with rwrfhydro and dependcies

ARC GIS and preprocessing tools

Use different Linux editor

We used VI this round because the thinking was that editing would be easier done in the host system using notepad++, etc.

However, this is not always possible an also maybe is confusing.

Change editor to nano in all containers

Confusing explanation on the *Supplemental* in Lesson 2

-Supplemental: Directory containing supplemental files used to create the domain

The above is confusing because you also have supplemental forcing there and forcing is not required to create the domain.

Move WRF_WPS/WPS/utilities to WRF_WPS/utilities

Create Lesson 1

Lesson 1 - Source code overview and compilation

• Create technical lesson material
• Technical proofing
• Editorial proofing

Meet with Kay to finalize the software image on 10/10 at 9am

The ext of _NO_LAKES on the hydro.namelist and namelist.hrldas files

I think this naming is problematic. It can be solved by keeping these configurations in separate dirs. such as:
/GRIDDED_NO_LAKES/RUN/hydro.namelist
/GRIDDED/RUN/hydro.namelist

Since the model isn't going to read files with hydro.namelist_NO_LAKES, I think we're creating a potential situation where users may think they're running one thing but actually are running another.

Another idea: We could have the users create these in the experiment - hands-on section.

Create lesson S2

Lesson S2 - Regridding forcing using ESMF scripts

• Create technical lesson material
• Technical proofing
• Editorial proofing

Find better method for writing PDF student guides

Converting google doc, or any doc, to PDF sometimes causes line wrapping in code/bash commands.

This caused issues with commands not working. Need to find a way to either a) Enforce a line character limit, or b) automate line wrapping with appropriate line break code character

Better structure the containers to reduce size

Making a base container with dependencies and the nbuilding off of that would make them a bit smaller

R vignettes for R activites