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.
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, MS | value | what it means |
|---|---|---|
| Drainage area | 1924 km² | all the land that drains to the gauge |
| Mean elevation, slope | 123 m, 6.8 m/km | low, gentle hills |
| Forest cover | 67% | mostly mixed forest |
| Precipitation | 1515 mm/yr | water years 1981–2014, basin average (Daymet) |
| River flow | 478 mm/yr | USGS record, expressed as a depth over the basin |
| Mean air temperature | 17.8 °C | only about 4 days a year below 0 °C |
How each session works
Every session is one page and follows the same pattern:
- The idea, in plain words first and then as the exact equation the model uses.
- The Leaf River: what that piece of the model actually computes on real days, with every intermediate number shown.
- Interactive widgets marked Try it. Move a slider and the real model reruns in your browser.
- Python cells. Short programs you can edit and run. The first run downloads a Python interpreter (Pyodide, about 15 MB) into the page; after that each run takes a moment. Press Shift+Enter or the Run button.
- Check your understanding: a few questions with answers you can reveal.
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.
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.
| # | Session | You will learn |
|---|---|---|
| Foundations | ||
| 1 | A river basin as a water budget | catchments, gauges, flow as a depth, the water balance, why flow is seasonal |
| 2 | What a conceptual model is | stores, fluxes, states and parameters; a one-bucket model; the map of dCREST |
| Inside one day | ||
| 3 | Snow: the degree-day method | rain or snow, how melt is computed, what the method gets wrong |
| 4 | Evaporation demand and the canopy | potential evaporation, interception, why the canopy evaporates first |
| 5 | Soil I: the infiltration curve | the VIC curve, the heart of CREST: how a storm splits into stored water and runoff |
| 6 | Soil II: interflow and dry days | the two runoff paths, and where evaporation comes from when it does not rain |
| 7 | Groundwater: drainage, spill, baseflow | the slow store that keeps rivers flowing in dry weather |
| 8 | Routing: reservoir and unit hydrograph | how runoff made today arrives at the gauge over the following days |
| Putting it together | ||
| 9 | One day, one year | step through any day with every variable on screen; ten years of water balance |
| 10 | Is the model any good? | NSE, KGE, training and testing periods, what the scores do and do not say |
| Learning from data | ||
| 11 | Calibration | tune the model by hand, then watch gradient descent do it in your browser |
| 12 | Differentiable modelling | the chain rule through 4 000 days, non-smooth steps, the river's memory of rain |
| 13 | From one river to 665 | the CAMELS benchmark, using the package, and what the parameters can be trusted for |
| Special topic: river routing | ||
| 14 | Routing I: how a flood moves down a river | flood waves, travel times on a river network, and when a unit hydrograph is all you need |
| 15 | Routing II: the methods and their cost | from the full equations to Muskingum, what EF5 and other systems use, time steps and computing cost |
| 16 | Routing III: the Rhine on a river network | a flood followed through 2,242 river reaches; what routing fixes, and what lakes, dams and floodplains change |
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.