Rain falls, then it moves. On a roof it follows the slope to a gutter. On open ground the same idea applies at a larger scale: water leaves higher ground and gathers on lower ground, unless a curb, a pipe, a garden bed, or a fresh pad of soil interrupts it. This page teaches one common map model of that surface path. The model is for learning. It is not a survey of a real lot, and it is not a plan for moving soil.
The model starts with a digital elevation model, a grid of heights. Each cell stores one elevation. A usual teaching version then does two things. First it gives every cell one downhill neighbor: the neighbor in the direction of steepest descent. From a square cell there are eight possible steps, north, northeast, east, southeast, south, southwest, west, and northwest, so the rule is called D8. Jenson and Domingue described this kind of extraction of drainage directions from an elevation grid in 1988. Second, after every cell has a single step, the model counts upstream cells. That count is flow accumulation. In the story the model tells, a little water is treated as if it entered each cell and then followed the steps. Cells where many paths join have a larger upstream count.
The numbers in the grid below are made up for the classroom. They are not a clip from a federal tile, and they are not a parcel. Real grids of this general kind are what the U.S. Geological Survey has published as elevation: the National Elevation Dataset, assembled as a seamless product and described in USGS fact sheets, and the 3D Elevation Program, which is the current program name. The National Elevation Dataset name was retired as the work moved under the 3D Elevation Program. Those products have their own cell sizes. This lesson uses a coarse 10 m cell so the arithmetic stays visible.
A 3 by 3 grid
Use three rows and three columns. Row 0 is north. The cell size is 10 m. Elevations are in meters. Written as one array, row 0 north, the grid is [[5,5,5],[5,4,3],[5,4,2]]. Spread out, it looks like this:
5 5 5
5 4 3
5 4 2The center cell is row 1 col 1, elevation 4 m. The only question in this hand check is which of the eight neighbors is the steepest step down from that center cell.
Slope here means drop divided by the distance the water travels. Drop is the center elevation minus the neighbor elevation. A positive drop is downhill. An orthogonal neighbor, the ones that share a full side, is 10 m away. A diagonal neighbor is farther, because the step cuts across the corner. That diagonal distance is 10*sqrt(2) m, about 14.14 m.
Walk the eight neighbors from the center:
- North, row 0 col 1, is 5 m. The drop is 4 minus 5, which is -1 m. That step is uphill.
- Northeast, row 0 col 2, is 5 m. That step is also uphill, and the diagonal path is longer, so it is not a steep descent.
- East, row 1 col 2, is 3 m. The drop is 1 m over 10 m, so the slope is 0.10 m/m.
- Southeast, row 2 col 2, is 2 m. The drop is 2 m. The travel distance is 10*sqrt(2) m.
- South, row 2 col 1, is 4 m. The drop is 0 m. That direction is level.
- Southwest, row 2 col 0, is 5 m. That step is uphill.
- West, row 1 col 0, is 5 m. That step is uphill.
- Northwest, row 0 col 0, is 5 m. That step is uphill.
The southeast neighbor is lower, and the slope is about 0.14 m/m (2 m drop over 10*sqrt(2) m). Divide 2 by the whole diagonal distance, (10 times the square root of 2), and you get about 0.141, which rounds to about 0.14 m/m. That is steeper than the eastward slope of 0.10 m/m. Under a steepest-descent rule, the center cell's single step points southeast. This hand check is only the center cell's steepest descent.
What this hand check does not count
This hand check does not route the other cells, and it does not produce an accumulation count. Counting upstream cells is a second step. It has to visit the whole grid, not one center cell. Accumulation counts, edge handling, and ties come from the versioned program catalog at /labs/where-does-rainwater-go/catalog.json, which is produced by educational_demonstrations.py. Read that catalog on the lab before you repeat a program figure. This tutorial does not state an accumulation integer. A hand route of one cell is not the same object as a finished upstream count.
Edges matter. A cell on the border has fewer than eight neighbors, and a path that would leave the grid has to stop or be marked as an outlet. Ties matter. Two neighbors can share the same slope, and a program needs a written rule before it can pick one. Whether a cell counts itself in its accumulation total is also a rule of the program, not a result you can see from the center-cell slope. Those choices belong to the program version in the catalog. They are not decided by the arithmetic on this page. The worked example repeats the center-cell division so you can check 0.14 m/m with your own calculator, and it still does not invent a count of upstream cells.
A pit, and a flat cell
A counterexample shows why steepest descent is not always defined. Keep the 10 m cells, but imagine a pit: the center is 2 m and every neighbor is 5 m. Every drop is negative. There is no downhill neighbor, so steepest descent is undefined. A fill step, which raises a sink so the surface can be given a drainage direction, would change those elevations before any path is drawn. The path after filling is a path on a different surface. It is not a path read from the pit you started with. People fill sinks to remove spurious holes in an elevation model, and sometimes they also erase a real basin. The teaching model has to say which of those it did. This page does not run that fill.
A flat cell is the other failure of the same rule. If the center and its neighbors are all 4 m, every drop is zero. No direction is steeper than another, so a unique steepest descent does not exist. A separate rule for flats would have to invent a direction the elevations do not show. That invented direction can change which cells are called upstream. Again, the catalog is where a versioned program records its rule. The flat grid is here only as a warning that "follow the steepest step" has no answer when every step is the same.
Uncertainties between the grid and the ground
Several ordinary facts sit between this model and water you can see. The elevation grid has a resolution. A 10 m cell hides a ditch, a curb opening, or a garden berm narrower than the cell. Agency grids have a resolution too. A coarser cell smooths the land. A finer cell still misses a pipe.
Filled sinks change paths. The fill raises depressions that may be errors in the elevation grid, and it can also remove a pond that really holds water. If you do not know whether the surface was filled, you do not know which landscape the arrows describe.
Culverts and storm pipes carry water under a ridge or a road that the bare-earth surface still shows as a wall. The D8 step cannot see that opening. Subsurface flow through soil is not in a surface path at all. Water can sink into a sandy spot and reappear lower down, or it can stay in a clay hollow that the slope arrows leave quickly. Recent grading, a new driveway, or a pile of fill can be newer than the elevation model. The map then describes a surface that is already gone.
Mapped flow is not a drainage design. An arrow on a teaching grid is not a size for a channel, not a depth for a basin, and not a reason to cut a swale. The same caution applies to any figure you later read in the program catalog. A computed count of cells is still a model result on a grid.
What to look at outside
Use the model to learn the idea, then look at the ground. After rain, walk the low places. See where water actually stands, where it runs in a thin sheet, and where it is already in a small channel. Notice curbs, downspouts, compacted tracks, and fresh soil. Do not dig from a screen. A page like this cannot tell you that a berm belongs in a particular spot.
If you want mapped federal context for a parcel, you can request a parcel snapshot: https://groundskeeper.groundworkokc.org/snapshot. The free public screening reports mapped federal context and does not, by itself, run this flow model on the visitor's land. The snapshot and this lesson are different things. There is also a short path, /snapshot, to that same public screening. Neither link turns this 3 by 3 grid into a report about a piece of ground.
Limitations
This is a simplified teaching model. It is not a validated property analysis. It is not a construction or permit document. Do not treat the center-cell step, or any catalog figure, as instructions for a particular piece of land. The southeast slope of about 0.14 m/m is a check on one made-up cell. It is not a measurement of a hillside, and it is not an upstream count.