An interactive course · 13 sessions and a special topic on river routing

dCREST, step by step

How a computer model turns a day of rain into a river's flow, and how it learns its own settings from data. Explained from zero, one piece per session, on a real river: the Leaf River in Mississippi.

For anyone curious, no hydrology neededTime about 6 hours, plus 2 hours for the routing topicRuns in your browser, nothing to installVideos every session opens with a narrated video, 111 minutes in all
The worked case. The Leaf River near Collins, Mississippi (USGS gauge 02472000) drains 1924 km² of low, forested hills. Grey dots are the other catchments of the CAMELS-US dataset, on which dCREST has been calibrated.

What this course is about

A rainfall–runoff model answers one question: given the weather over a river basin, how much water flows past a point on the river each day? Flood forecasters, reservoir operators and water planners use such models every day. This course takes one of them apart.

The model is dCREST. It is built on CREST, the water-balance model at the core of the EF5 flood-forecasting system, which runs across the United States in FLASH, the flash-flood forecasting system used by National Weather Service forecasters. dCREST keeps CREST's soil water balance, adds a groundwater store from CRESTPhys (a CREST extension in a fork of EF5, not part of the official EF5) and its own snow, canopy and routing steps, and it is written so that a computer can work out, automatically, how every output changes when any input or setting changes. That property, called differentiability, is what the “d” stands for. It lets dCREST learn its settings for hundreds of rivers at once, and it lets us ask questions such as “if it had rained one millimetre more last Tuesday, how much more water would be in the river today?”

By the end you will be able to follow a single day of rain through every part of the model, say what each of its 16 parameters does, judge whether a simulation is any good, and explain how the model is calibrated with gradients.

The case: Leaf River near Collins, Mississippi

Every session uses the same river, so that numbers from one session can be checked against the next. The Leaf River was chosen because it is a classic in this field: Sorooshian, Duan and Gupta (1993) used its historical record to show that the SCE-UA search algorithm could reliably calibrate the Sacramento model, a cousin of CREST, and the basin has been a test case in many studies of model calibration since. It is also a friendly first river. It is warm, so snow hardly matters (by the CAMELS estimate, about 0.6% of precipitation falls as snow), it is wet, and its record is long and complete.

Leaf River near Collins, MSvaluewhat it means
Drainage area1924 km²all the land that drains to the gauge
Mean elevation, slope123 m, 6.8 m/kmlow, gentle hills
Forest cover67%mostly mixed forest
Precipitation1515 mm/yrwater years 1981–2014, basin average (Daymet)
River flow478 mm/yrUSGS record, expressed as a depth over the basin
Mean air temperature17.8 °Conly about 4 days a year below 0 °C

How each session works

Every session is one page and follows the same pattern:

Hover over any symbol written like SM or wm to see what it means, its units and its name in the code. The glossary lists them all. In the model diagrams, colours mark the parts of the model: snowcanopysoilgroundwaterfast flowevaporation.

Is the browser model the real model?

Yes, to within rounding. The official dCREST package is written in PyTorch. These pages use line-by-line ports of it in JavaScript (for the widgets) and NumPy (for the Python cells). Session 9 reruns the JavaScript port in your browser and compares it with stored runs of the PyTorch package; they agree to about 10−14 mm per day, which is the precision limit of computer arithmetic.

Syllabus

Sessions 1 to 13 are the course proper and stay on the Leaf River. Sessions 14 to 16 are a special topic for readers who want to go further into one step, routing: they leave the Leaf River for the Rhine, a basin 77 times larger, where the way water travels down the river network can no longer be summed up in one curve.

#SessionYou will learn
Foundations
1A river basin as a water budgetcatchments, gauges, flow as a depth, the water balance, why flow is seasonal
2What a conceptual model isstores, fluxes, states and parameters; a one-bucket model; the map of dCREST
Inside one day
3Snow: the degree-day methodrain or snow, how melt is computed, what the method gets wrong
4Evaporation demand and the canopypotential evaporation, interception, why the canopy evaporates first
5Soil I: the infiltration curvethe VIC curve, the heart of CREST: how a storm splits into stored water and runoff
6Soil II: interflow and dry daysthe two runoff paths, and where evaporation comes from when it does not rain
7Groundwater: drainage, spill, baseflowthe slow store that keeps rivers flowing in dry weather
8Routing: reservoir and unit hydrographhow runoff made today arrives at the gauge over the following days
Putting it together
9One day, one yearstep through any day with every variable on screen; ten years of water balance
10Is the model any good?NSE, KGE, training and testing periods, what the scores do and do not say
Learning from data
11Calibrationtune the model by hand, then watch gradient descent do it in your browser
12Differentiable modellingthe chain rule through 4 000 days, non-smooth steps, the river's memory of rain
13From one river to 665the CAMELS benchmark, using the package, and what the parameters can be trusted for
Special topic: river routing
14Routing I: how a flood moves down a riverflood waves, travel times on a river network, and when a unit hydrograph is all you need
15Routing II: the methods and their costfrom the full equations to Muskingum, what EF5 and other systems use, time steps and computing cost
16Routing III: the Rhine on a river networka flood followed through 2,242 river reaches; what routing fixes, and what lakes, dams and floodplains change
The code

dCREST is open source: github.com/Skyan1002/dCREST. Each session points to the file and function that does what the session describes, so you can read the real thing next to the explanation.