Differentiable modelling
Session 11 used slopes to calibrate. This session explains where dCREST's slopes come from: not from nudging parameters, but from running the computation backwards with the chain rule. The same slopes answer other questions too: which parameters matter, which ones cannot matter at all, and how much today's river owes to the rain of each past day.
You will be able to
- apply the chain rule backwards through a small simulation by hand;
- explain what automatic differentiation does, and why its cost does not grow with the number of parameters;
- compare finite differences with automatic derivatives, and explain the choice of step size;
- read the gradient at the calibrated optimum on the training and test decades;
- explain why a gradient can be exactly zero, and how that exposed two dead parameters;
- read how one day's flow depends on the rain of the past year;
- say how switches and limits are handled, and how the package scales to 665 catchments.
A gradient is a list of slopes
For a score that depends on sixteen parameters, the gradient is sixteen numbers. Each says how fast the score changes when one parameter increases a little and the others stay fixed: a partial derivative, written \(\partial\,\text{NSE} / \partial \theta\). A positive value means increasing the parameter improves the score; zero means the score does not respond at all.
There are two ways to compute one. Finite differences nudge each parameter in turn and re-run the model: simple, but one or two extra runs per parameter, and only approximate. Automatic differentiation gets all of them from one extra pass through the computation, exact up to rounding. To see how, start with a model small enough to do by hand.
The chain rule, by hand
Take the fast reservoir of Session 8 on its own, for four days. Each day, the inflow \(x_t\) is added to the storage, a fraction \(k\) of it is released as flow \(Q_t\), and the rest is kept:
We score the simulation against four "observed" flows \(O_t\) with the sum of squared errors \(L = \sum_t (Q_t - O_t)^2\), and want \(dL/dk\). The flow on day 3 depends on \(k\) directly (the release fraction) and indirectly (\(k\) also decided how much water was left in storage after days 1 and 2). The chain rule adds up all these paths, and the efficient way to do it is backwards, from the score to the start.
Going backwards, each quantity gets a "bar" value, the derivative of the score with respect to it. Start from the score: \(\bar Q_t = 2(Q_t - O_t)\), and \(\bar S_4 = 0\) because the final storage does not affect the score. Then, for \(t\) = 4, 3, 2, 1:
Each line is the chain rule for one arrow: \(S'_t\) affects the score through \(Q_t\) (slope \(k\)) and through \(S_t\) (slope \(1-k\)); \(k\) affects \(Q_t\) with slope \(S'_t\) and \(S_t\) with slope \(-S'_t\).
Two things come for free. The backward pass also produced \(\bar S'_t = \partial L/\partial x_t\), the sensitivity of the score to each day's inflow, without any extra work. And its cost was one more sweep through the four days, whatever the number of things we want derivatives for.
Automatic differentiation
dCREST does exactly this, at scale. It is written in PyTorch, which records every elementary operation of the forward run (each addition, multiplication, exponential and minimum on each of the thousands of days) and then walks the record backwards, applying the chain rule at each step. This is reverse-mode automatic differentiation, also called backpropagation. Three properties matter:
- Exact. The result is the derivative of the computation actually performed, accurate to rounding, not an approximation.
- Cheap in the number of inputs. One backward pass gives the derivative of one score with respect to every input at once: sixteen parameters, or the rain on each of four thousand days. Its cost is a small multiple of a forward run.
- No extra code. The model is written once, as a simulation. The derivatives follow from it.
Because the model steps through days, dCREST's derivatives are the derivatives of that daily computation, not of some smooth equations behind it. If the daily scheme has kinks, the derivatives see them (more below).
Finite differences, and their step size
A finite difference replaces the slope by a measured rise over a short run: \(\partial f/\partial \theta \approx [f(\theta + h) - f(\theta - h)] / 2h\). The step \(h\) is a compromise. Too large, and the curve between the two points is not straight, or a switch flips between them. Too small, and the two scores agree in so many digits that rounding errors dominate their difference. The widget computes this for the Leaf River test NSE and compares it with the automatic derivative stored from the PyTorch package.
For most parameters the curve is a V: errors fall as the step shrinks, reach about 10−9 near steps of 10−5 to 10−7 of the range, then rise again as rounding takes over. For ksoil, gwc and hmaxaq the step must be smaller still, 10−6 to 10−7 of the range: these parameters pass through several capped fluxes, and somewhere in the 4,748 days a cap changes branch inside any larger step. For tsnow every step of 10−4 of the range or more flips the rain/snow switch on some day, and the difference means nothing. (Near a bound the widget uses a one-sided difference, so the model is never run with a value outside the allowed range.) The paper ran the same check in 96 catchments for all sixteen parameters (its Sect. 4.4); where the two disagreed, the left and right slopes of the score genuinely differ, at a kink.
All sixteen parameter slopes by central differences: 32 extra model runs, each approximate. By automatic differentiation: one backward pass. The sensitivity of one day's flow to the rain on that day and each of the 365 days before it (below): 366 extra runs by finite differences, one backward pass by automatic differentiation. On the GPU used for the paper, a model run of all 665 catchments over twelve years took 0.46 s and a run with its gradient 3.5 s.
What the gradient says at the optimum
At the top of a hill the ground is flat: if the calibration found the best training score, the training gradient should be close to zero. The test decade is a different landscape, and its gradient need not be. The chart shows both, as the change in NSE for a 1% increase of each parameter.
On the training period the largest effect of a 1% change is 5 × 10−6: the calibration is at the top of its hill. On the test decade the effects are up to 1.1 × 10−3, and the largest of them ask for two things. Lower ke (less evaporation), lower wm (a smaller soil, so more runoff) and, further down the list, lower lf (less loss) all mean more water in the river. Lower nshape and kmult and a higher qc all mean faster routing and sharper peaks. The gradient has found, on its own, both faults Session 10 found from the ratios: too little water in the test decade (\(\beta\) below 1) and swings that are too small (\(\alpha\) below 1). This is a diagnosis, not a recipe; tuning on the test gradient would be tuning on the test data.
Exactly zero: dead parameters
Some operations in the model are switches and limits. Their slope is zero on one side: the rain/snow switch does not change when the threshold moves slightly (unless a day sits exactly at it), and a cap that is never reached does not care how high it is. If a parameter acts only through such an inactive branch, its gradient is not small but exactly zero, and gradient descent will never move it.
This happened in the first calibration of dCREST. Before every calibration, the package now records the share of catchments in which each parameter's gradient is exactly zero. In the first set-up, two parameters scored 100% and 99.2%:
- fc was allowed 0–150 mm/hour and started at 10. At that size the interflow cap (Session 6) exceeded the runoff on every day, so the cap never acted.
- kmult was cut off by a lower limit of half a day on the unit-hydrograph time scale. Most CAMELS catchments are small enough that their time scale fell below the limit, which then acted instead.
Both parameters ended exactly where they started, and nothing in the loss curve or the scores showed it. The widget recreates both effects on the Leaf River.
For the Leaf River, any fc above 4.47 mm/hour gives exactly the same discharge in the training period: the cap never binds, and the curve is perfectly flat. With the half-day limit, any kmult below 1.11 gives the same unit hydrograph. Starting values inside a flat stretch mean a gradient of exactly zero. Narrowing fc to 0–5 mm/hour and lowering the limit to one hour made both parameters active; the released sets have no inert parameter.
A derivative-free optimiser would have reported the same two parameters as "insensitive", which looks exactly like a real property of the catchments. Only a separate sensitivity analysis could have told the two apart. An exactly-zero gradient in nearly every catchment is a different signal (this parameter cannot matter under the current bounds and code), and it comes free with the first calibration step.
How today's river remembers the past
Gradients can be taken with respect to the forcing, not only the parameters. Pick one day, and ask: if one more millimetre of rain had fallen on that day, or on any one of the 365 days before it, how much higher would the flow be? One backward pass gives all 366 answers.
On the winter flood of 1991-02-22 (model 21.3 mm/day, observed 21.4), one more millimetre of rain the day before would have added 0.24 mm/day; rain on the day itself adds less (0.10) because the unit hydrograph has not yet delivered most of it. Further back the sensitivity falls in steps rather than smoothly, because each past day's extra rain would have taken the path set by that day's state: on a dry day most of it evaporates, on a wet day it is stored in the soil, on a day when the soil fills up it runs straight off. And because there are so many earlier days, the last eight days (the flood day included) account for only 13% of the sum of all 366 sensitivities: wet soils, filled over the preceding months, set the stage.
On the late-summer low flow of 1993-08-31 (0.21 mm/day), the sensitivities are 50 to 100 times smaller, and only 8% of their sum comes from the last eight days. Rain in a dry summer mostly goes back to the air; the trickle in the river is drained from the aquifer, which was filled weeks and months before.
Both curves end in a cliff. Rain on 1993-01-21 or earlier has practically no effect on the August low flow (sensitivities below 10−100), while rain the next day still matters (1.7 × 10−5). On that day a 48 mm storm filled the soil to capacity while the aquifer was overflowing. Extra rain on that day or before would have run straight off and left the catchment within weeks: a store that fills up forgets how it got full. The winter curve has the same cliff at its left edge, a saturating storm of 39 mm on 1990-02-22. Press the button to check any of this: the finite differences, one model run per past day, land on the automatic derivatives.
Switches, limits and kinks
A model with switches is not smooth everywhere. dCREST contains a rain/snow threshold, the wet-day/dry-day branch, minima that cap a flux by the water available, and clamps that keep stores from going negative. The package uses one rule for all of them: the gradient passes through the branch that is active, and nothing passes through the other; a switch itself carries no gradient.
So the model is differentiable almost everywhere: exactly at a kink the left and right slopes differ, and the package reports the slope of the branch it took. In practice the score has many such kinks along each parameter axis (dozens or more over thirteen years of days), and the rain/snow switch even makes small jumps, which is why a finite difference spanning one disagrees with the automatic derivative. The paper's Table 2 lists, for every parameter, each non-smooth operation it passes through. Two small guards keep derivatives finite: powers in the infiltration curve are evaluated with an offset of 10−9, and non-finite intermediate values are replaced before they can spread to other catchments.
Fast enough for 665 catchments
Three implementation choices make calibration of every CAMELS catchment practical on one GPU:
- Batching. All catchments are columns of one array, so one model run simulates all of them at once, and one backward pass gives every parameter of every catchment its gradient. The catchments do not interact; the loss is their average, so each catchment's parameters receive only their own catchment's gradient.
- Checkpointing. The backward pass needs the values computed on the way forward, for every day. Storing all of them for twelve years and 665 catchments would take a lot of memory, so the package stores them only at the start of every 96-day segment and recomputes each segment when the backward pass reaches it. The gradients are bit-identical with and without it.
- Compilation. The function that advances one day is compiled (with PyTorch's
torch.compile) into a few fused GPU programs, instead of dozens of small ones.
On one NVIDIA B200, a model run for all 665 catchments over the training period and its spin-up takes 0.46 s, and a run with its gradient 3.5 s. One calibration run (2,048 steps for every catchment) took 2.6 hours; the released set used six such runs.
In Python
The four-day reservoir, forwards and backwards, in plain NumPy, checked against a finite difference. Change k, the inflows or the observations and run it again.
Check your understanding
Why does reverse-mode differentiation cost about the same for 16 parameters as for 4,000 daily rain values?
The backward pass computes the derivative of one score with respect to every input in a single sweep from the score back to the start. The number of inputs only changes how many derivatives are collected along the way, not the number of sweeps.
A finite difference with a step of 10% of the range disagrees badly with the automatic derivative. Which one is wrong?
Usually the finite difference. With a large step the score is not a straight line between the two points, and switches can flip inside the step. With steps around 10−6 of the range the two agree to about nine digits, except exactly at kinks.
The training gradient at the optimum is almost zero, the test gradient is not. Should we follow the test gradient?
No. It is a useful diagnosis (here: the test decade wanted more water in the river), but following it would be calibrating on the test data.
A parameter's gradient is exactly zero in 99% of catchments. What do you check?
Whether it acts only through an inactive branch: a cap that is never reached, a limit that always binds, a process that never happens (snow in a warm catchment). If so, the bounds or the code make it unable to matter, and changing its bounds, its starting value or the limit can bring it to life.
Why does a summer low flow depend so little on last week's rain?
In a dry summer most rain is taken by the canopy and the soil and evaporates. The river is fed from the aquifer, which drains slowly and was filled weeks and months earlier.
What to remember
- A gradient is a list of slopes; dCREST gets them by running the computation backwards with the chain rule (automatic differentiation).
- One backward pass gives the derivative with respect to every input, parameters or daily forcing, at a small multiple of a forward run.
- Finite differences need a step that is neither too large (curvature, switches) nor too small (rounding).
- At the optimum the training gradient vanishes; the test gradient can diagnose what changed between decades.
- An exactly-zero gradient means a parameter cannot matter as set up; checking for it caught two dead parameters.
- Switches and limits pass the gradient of the active branch only; the model is differentiable almost everywhere.