Forebay guide
The guide that comes with the app (Help > Guide), with its three tutorials. The tutorials use Help > Sample Study: open it and follow along.
Guide
Getting started
Forebay runs reservoir operation studies: it takes a record of the flows into a reservoir and works out, period by period, what the reservoir could have supplied, where its level would have stood, and what it would have spilled.
The window
- The ribbon, across the top, has a tab for each part of a study and the commands: new, open and save, the examples, the exports and this guide.
- Each tab has its inputs and results in a column on the left, and a figure beside it, with a table under the figure.
The tabs follow the order of a study:
- Reservoir: the elevation-area-storage curve, the levels and the lake's losses.
- Inflow: the record of flows, and its time step.
- Demands: water supply, environmental flow, irrigation and hydropower.
- Operation: the order of the uses, the rule curves, and the run itself.
- Storage-Yield: how much the reservoir can give, and how much storage a draft needs.
- Rule Curves: a search for rule curves that ration well.
- Synthetic Inflows: the study over many records that might have been.
- Flood Routing: a flood through the reservoir and over its spillway.
The operation study is worked out again as you type: there's no Run button for it. The three studies that take longer (yield curves, the search and the traces) have one, and run in the background.
A field outlined in red doesn't hold a number. What's wrong with a study shows at the bottom of the window, and where its results would be.
A ? beside a heading explains that part.
A first look
Forebay starts with an empty study, as File > New does: give the reservoir its levels and its elevation–area–storage table, bring in an inflow record, then turn on the uses. To see a study that's ready to run first, choose Help > Sample Study: a valley dam with thirty years of monthly flows, irrigating two crops of rice a year, with a power plant at its foot. The first tutorial goes through it.
Units
Everything is metric: levels in m, areas in km², storage in million m³ (MCM), flows in m³/s, depths of rain and evaporation in mm, power in MW and energy in GWh. Irrigated areas are in hectares.
Read Methods and limits before relying on a result.
The reservoir
The curve
The elevation-area-storage curve is a table: for each elevation, the lake's surface area and the volume stored below it. Between its points the curve is a straight line.
- + adds a point above the last one; the bin removes one.
- Storage from Areas fills in the storages from the elevations and areas, taking each slice as the frustum of a cone: V = h/3·(A₁ + A₂ + √(A₁·A₂)).
Carry the curve up to the dam's crest, or higher: flood routing needs it above the spillway.
Levels
| Level | What it is |
|---|---|
| Minimum operating level | The lowest the lake is drawn to. The storage below it is dead storage. |
| Normal high water level | The top of the storage in use. Water above it spills. |
| Starting level | Where the lake stands as the run starts. |
The active storage lies between the first two.
Losses and gains
- Evaporation, in mm a month, is taken from the lake's surface as it stands in each period: the mean of its area at the start and at the end.
- Rain on the lake is added the same way. Leave it at 0 if the inflow record already includes it.
- Seepage is a steady loss in m³/s.
When the lake holds less than its losses, they're cut to what it holds.
The inflow record
The record is a list of flows in m³/s, one for each period: the mean flow into the reservoir over that period.
Time step
| Step | Periods in a year |
|---|---|
| Monthly | 12 |
| 10-day | 36: two of ten days and the rest of each month |
| Daily | 365 or 366 |
Changing the step converts the record: to a longer step by averaging, to a shorter one by keeping each flow through its period. A record made shorter that way has none of the variation of a measured one, so prefer a record measured at the step you want.
The record starts in the year and month given, on the first of the month.
Getting a record in
- Import reads a CSV or text file. A file dropped on the window is read the same way.
- Paste reads the clipboard, as copied from a spreadsheet.
- Edit opens the record as text, to change or type in.
- Copy puts it on the clipboard, with tabs between the values.
Three layouts are understood:
- A year and its twelve monthly flows on each line (or its 36 ten-day flows). A thirteenth value is taken for the year's total and left out. This sets the time step and the starting year.
- A date and a flow on each line:
1991-03-01, 12.5. Dates are year first, or month/day/year. The first date sets where the record starts; the time step is the one chosen. - The flows alone, in order, one or several to a line.
Values can be separated by commas, semicolons, tabs or spaces. Lines without numbers are skipped. A record can't have gaps or negative values: fill in missing flows before importing.
What's shown
The record through time, the range and the mean of its flows at each time of year, and its flow duration curve. The table under it gives the monthly means of each year.
Demands
Each use has a switch. A use that's off has no demand.
Water supply and environmental flow
A flow in m³/s for each month. All months fills the twelve with one value.
Irrigation
Month by Month: the water to divert in each month.
From Crops: worked out from a cropping pattern. For each crop:
| Field | Meaning |
|---|---|
| Area | hectares |
| Starts | the day and month land preparation begins (or the crop is planted, with no land preparation) |
| Land preparation | its days, and the water it takes, in mm |
| Paddy, percolation | water stands on the field, and seeps away at this rate |
| Stages | days of the initial, development, mid-season and late stages |
| Kc | the crop coefficient in the initial stage, at mid-season and at harvest |
On each day of the year a crop needs:
- during land preparation: its water spread evenly over its days, plus ETo, plus percolation for paddy;
- while growing: Kc × ETo, plus percolation for paddy. Kc is level through the initial stage, rises through development, is level at mid-season and falls through the late stage (FAO 56).
The rain the crops can use is taken off, by one of three rules:
| Rule | Effective rain from a month's rain P (mm) |
|---|---|
| USDA SCS | P·(125 − 0.2·P)/125 up to 250 mm; 125 + 0.1·P above |
| FAO | 0.6·P − 10 up to 70 mm; 0.8·P − 24 above |
| A share | that share of P |
What's left, over the irrigation efficiency, is the water to divert. 1 mm a day over 1 ha is 10 m³ a day. The table under the figure gives each month's figures, and the duty in litres a second per hectare.
The demand is the same every year: it doesn't follow each year's rain.
Hydropower
A plant at the foot of the dam.
Power = 9.81 × efficiency × discharge × net head (kW, with m³/s and m), up to the installed capacity. The net head is the lake's level, less the tailwater level, less the head loss, which goes with the square of the discharge.
- The turbines take no more than their most discharge, and don't run below their least, or with the lake below the lowest level to run.
- Through the turbines says whose releases pass them. Those releases make power on their way.
- Firm power is a power to keep up in each month. When the releases through the turbines don't make it, more water is released for it. Leave it at 0 to make power only from other releases and from water that would spill.
The operation study
For each period, in order:
- The lake gains the inflow and the rain, and loses evaporation and seepage.
- The water above the minimum operating level is shared among the uses in their order: the first gets all it wants before the second gets any.
- Storage above the flood control level is released, as fast as the outlets can.
- Storage above the normal high water level spills.
Evaporation and the head on the turbines depend on where the lake ends the period, so each period is worked out three times over.
The order of the uses
The arrows move a use up or down. Hydropower's place is that of the water released for power alone: releases for other uses make power whatever their place.
Rule curves
Each is a level for each month.
- Flood control level: the lake is kept at or below it. With an outlet capacity, no more than that is released for it in a period, and the rest stays (or spills at the top).
- Lower rule curve: when a period starts with the lake below it, each use gets only a share of its demand: its rationing factor.
- Critical rule curve: below it, a second set of factors.
Cutting supplies early in a drought, while there's still water, trades a few deep shortages for more, shallower ones. The Rule Curves tab searches for curves that do this well.
What's shown
Levels, Supply (each use's demand and what it got), Power, Typical Year (the range of levels at each time of year) and Duration curves.
The table gives every period; a supply in red was short, and a shaded row started below a rule curve.
On the right, for each use, see Measures of performance; then the energy, the water budget and the lake.
Table, in the ribbon, exports every period as CSV.
Storage and yield
This tab leaves the uses and the rule curves aside and asks two questions about one draft, taken from a lake that starts full.
The draft is uniform (the same all year) or shaped as the demands for water entered. Its size is its mean over the year.
How much storage does a draft need?
The sequent peak algorithm: going through the record, the deficit K grows by the draft less the inflow of each period, and never falls below zero:
K(t) = max(0, K(t−1) + D(t) − Q(t))
The largest K is the active storage needed. The record is gone through twice, so that a drought running over its end is counted. The figure shows K through the record.
It leaves out evaporation and the other losses, so the true need is a little more.
How much can the reservoir give?
Run Yield Curves finds, by trial runs of the operation study, the largest draft kept up:
- in every period: the firm yield;
- in 98, 95 and 90% of periods.
It does so for eight sizes of reservoir up to the one entered (the normal high water level is lowered to give each storage), which gives the storage-yield curves. Losses are counted.
The firm yield belongs to this record: a longer record, or another one as likely, would give another. Synthetic inflows show how much it might vary.
Searching for rule curves
The search looks for a lower rule curve, a level for each month, and optionally a critical curve and the rationing factors, that do best on the record.
What it makes small, or large
| Choice | Measure |
|---|---|
| Least Shortage | The shortage score: 100 × the mean of (shortage / demand)² over the periods, added over the uses by their weights |
| Least Worst Cut | The deepest shortage of each use in any period, added over the uses by their weights |
| Most Energy | Mean annual energy |
| Most Firm Power | The power kept up 95% of the time |
For the last two, each weighted use must still get at least the share given of its demand.
Weight says how much a use's shortages count; Rationed which uses the curves cut.
How
Differential evolution. A population of policies starts at random, with the policy in use and no rationing at all among them, so the result is never worse than either. Each generation, every policy is tried against a mix of three others, and the better is kept.
Smoothing charges a curve for jumping from month to month. With 0 the search finds whatever shape does best on this record; with more, a curve an operator could follow.
The same seed gives the same search.
Using the result
The figure shows the curve found; the column compares the study now and with it. Use These Curves puts them in the Operation tab.
The curves are fitted to one record. Try them on synthetic inflows before relying on them.
Synthetic inflows
A record is one sample of what a river can do. Synthetic records keep its statistics and put its wet and dry spells in other orders.
The model
Monthly and ten-day records: the Thomas-Fiering model. Each flow comes from the one before it:
q(j) = m(j) + r(j)·s(j)/s(j−1)·(q(j−1) − m(j−1)) + t·s(j)·√(1 − r(j)²)
with m and s the mean and deviation of season j, r its correlation with the season before, and t a random normal number.
On the logarithms (the default), the model works on log(q): flows stay positive and skewed.
Daily records are made month by month with the same model, and each month is given the day-to-day shape of that month in a year of the record picked at random (the method of fragments).
The study
Run Traces makes the number of records asked for, each of the years given (the record's length, if left empty), and runs the operation study over each.
- The first figure compares the record's seasonal means and deviations with the synthetic ones.
- The second ranks the traces by each use's reliability.
- The third gives the lake's level through the year: the median, and the bands that half and nine tenths of the years fell in.
The table gives, for each result, the value 5% of traces fell below, the median, and the value 95% fell below.
Export a Trace saves one synthetic record as CSV, which Import reads back.
Limits
The model keeps each season's mean, spread and link with the season before. It doesn't keep longer persistence (runs of dry years beyond what that link gives), and it knows nothing of a changing climate.
Flood routing
A flood's inflow hydrograph is routed through the reservoir by the level pool method: the lake's surface is taken as level, and over each step
S₂ − S₁ = Δt·((I₁ + I₂)/2 − (O₁ + O₂)/2)
is solved for the level at its end, with the outflow O a function of the level.
The flood
A Curve: Q = base + (peak − base)·(t/tp·e^(1 − t/tp))ⁿ, from the peak, the time to peak tp and the shape n.
Point by Point: times in hours and flows; flows between them are on straight lines.
The ways out
| Outlet | Flow |
|---|---|
| Open spillway | C·L·H^1.5, with H the head on the crest and L its net length |
| Gated spillway, gates opened by a | C·L·(H^1.5 − (H − a)^1.5) once the water is above the gates' lips; the open-crest flow below |
| Low outlet | Cd·A·√(2g·h), with h the depth of its centre |
The gates stay as set through the flood.
Results
The peak outflow, how much the peak is lowered and delayed, the highest level and the freeboard left below the dam's crest. A warning shows if the dam is overtopped, if the lake rises above the top of the curve, or if the hydrograph ends before the flood is out.
This tab stands apart from the operation study: the flood arrives with the lake at the level given.
Files and exports
A study is saved as a .forebay file: everything entered, the inflow record included. The results of the background studies aren't saved; run them again.
| Export | What |
|---|---|
| Report | A PDF of the study: inputs, the operation study and its figures, and the studies that have been run |
| Figure | The figure of the tab that's showing, as a PNG |
| Table | The table of the tab that's showing, as CSV |
Help > Sample Study and File > Examples have studies to open and take apart.
The install count
The first time Forebay runs on a computer, and the first time after each new version, it sends one short message to stats.syncster.dev: a random id for this copy, the version (and the one before, for an update), the system and the processor. That is how installs are counted. Nothing of your studies, your files or you is ever sent. The id is kept in stats.json in Forebay's data folder.
Tutorials
1. A first study
Choose Help > Sample Study. It's a valley dam with thirty years of monthly flows.
The reservoir and its river
- On Reservoir: the lake holds 268.5 million m³ between its minimum operating level (190 m) and its normal high water level (225 m).
- On Inflow: the river brings 21.71 m³/s on average, most of it from July to November.
The demands
On Demands: 2 m³/s for a town, 1.5 m³/s left in the river, and two crops of rice, 14,000 ha in the wet season and 15,000 ha in the dry. The table shows the dry-season crop asking for 17 to 23 m³/s from January to March, when the river brings 5 to 10.
The run
On Operation:
- Water supply and the environmental flow are met in every month.
- Irrigation is met in full in 95.5% of months, and gets 97.9% of its water. Its worst month is 70% short.
- The 3 MW of firm power is kept up in 90.6% of months.
- The plant makes 62.9 GWh a year.
- 13.4% of the inflow spills.
Click Supply to see when the shortages came, and Typical Year to see the lake drawn down from January to June and refilled by September.
Try
- Move Hydropower above Irrigation in the order, and watch the two reliabilities change places.
- On Demands, lower the dry-season area to 12,000 ha.
Next: rule curves.
2. Rule curves, and testing them
Start again from Help > Sample Study.
Irrigation's worst month is 70% short, and power stops altogether in some months: the lake is run down to its minimum and has nothing left. Rationing earlier would spread the shortage.
Search
- Open Rule Curves. Leave Least Shortage, with irrigation and hydropower rationed.
- Click Search. It takes a second or two.
The shortage score falls from 6.89 to about 1.35. The curve found is high from December to March (ration early in the dry season) and at the minimum level in July and August (no need to ration when the river is in flood). Below it, irrigation and power get 85%.
In the comparison:
- irrigation's worst shortage falls from 70% to 47%, but it's now short in about three months in ten, by a little;
- firm power is kept up in 96.7% of months, from 90.6%.
Whether many small cuts are better than a few deep ones is for the people who take the water to say. Give irrigation less weight, or switch its rationing off, and search again to see other answers.
Use
Click Use These Curves. The Operation tab now runs with them: the shaded rows of its table are the periods that started below the curve.
Test
The curve was fitted to thirty years. On Synthetic Inflows, click Run Traces: the study runs over 100 other records of thirty years.
Read the table's 5% column: in one record in twenty, things were worse than that. If the results over the traces are much worse than over the record, the curve was fitted too closely: raise the smoothing and search again.
3. Yield, and a flood
Start from Help > Sample Study.
Storage for a draft
On Storage-Yield, the draft is 12 m³/s, uniform. The sequent peak gives 135.9 million m³ of active storage: half of what there is. The figure shows the storage drawn on each dry season, and most in 2020.
Raise the draft to 17: the need passes the storage there is.
Yield
Click Run Yield Curves. The firm yield is 17.06 m³/s, 79% of the mean inflow; a draft met in 90% of months could be 19.6 m³/s. The curves flatten: the last third of the storage adds little yield.
A flood
On Flood Routing, a flood peaking at 1800 m³/s after 9 hours arrives with the lake full, at 225 m. Over a 60 m open spillway:
- the peak outflow is 778.5 m³/s, 56.8% lower, and 8.5 hours later;
- the lake rises to 228.37 m, leaving 3.63 m below the dam's crest.
Halve the spillway's length: the outflow falls and the lake rises. That trade, between the spillway's cost and the dam's height, is what routing is for.
Reference
Measures of performance
A period is short when a use gets less than 99.9% of its demand. A supply cut by a rule curve counts: the demand is what was wanted.
| Measure | Meaning |
|---|---|
| Periods served in full | 1 − short periods / periods with a demand (time reliability) |
| Volume served | supply / demand, over the run (volumetric reliability) |
| Years without shortage | the share of calendar years supplied in full (annual reliability) |
| Longest spell | the most short periods in a row |
| Worst shortage | the largest shortage of a period, as a share of its demand |
| Resilience | the share of short periods followed by one that isn't (Hashimoto and others, 1982) |
| Vulnerability | the worst shortage of each spell, averaged over the spells |
| Shortage index | 100/N·Σ(annual shortage / annual demand)², over N years |
| Shortage score | 100 × the mean of (shortage / demand)² over the periods: what the search makes small |
For hydropower the demand is the firm power, and volumes are energy.
Firm power (95%) is the power equalled or exceeded in 95% of periods. The plant factor is the mean power over the installed capacity.
The water budget closes: inflow + rain − evaporation − seepage − releases − spill = the change in storage.
Methods and limits
What Forebay assumes
- One reservoir. There's nothing upstream or downstream of it, and no routing of releases down the river.
- Flows are means over a period. Within a period nothing varies: a monthly study doesn't see a week's flood or a week's drought.
- Demands repeat every year. Irrigation demand doesn't follow each year's rain, and there's no growth.
- Rationing follows the level at the start of the period, not a forecast of the inflow.
- Water that would spill passes the turbines first, as far as they have room, when that's switched on. In a long period this overstates energy a little: a flood that comes in a few days can't all be turned.
- The tailwater level is fixed.
- Rule curves are by month. At the ten-day and daily steps the level steps at each month's start.
- No sediment. The curve is the same from the first year to the last.
Checks
The calculations are checked against hand calculations in tests/ops_test.tsl: the water balance step by step, the order of the uses, rationing, power, the sequent peak, effective rain and crop demand, the spillway formulas, the steady state and the volume balance of flood routing, and the statistics of long synthetic records.
They have not been compared with published worked examples or with other programs. Check a study that matters against one.
References
- Loucks, D.P. and van Beek, E. (2017). Water Resource Systems Planning and Management. Springer.
- McMahon, T.A. and Mein, R.G. (1986). River and Reservoir Yield. Water Resources Publications.
- Hashimoto, T., Stedinger, J.R. and Loucks, D.P. (1982). Reliability, resiliency and vulnerability criteria for water resource system performance evaluation. Water Resources Research 18(1).
- Thomas, H.A. and Fiering, M.B. (1962). Mathematical synthesis of streamflow sequences. In Design of Water Resource Systems, Harvard University Press.
- Allen, R.G. and others (1998). Crop Evapotranspiration. FAO Irrigation and Drainage Paper 56.
- Storn, R. and Price, K. (1997). Differential evolution. Journal of Global Optimization 11.
- Chow, V.T., Maidment, D.R. and Mays, L.W. (1988). Applied Hydrology. McGraw-Hill.