Package lakelevel on DUB

A small, dependency-free D library for lake and reservoir water math: percent of full (conservation) pool from a water-surface elevation, depth above a gauge datum, surface-area interpolation and average-end-area storage change from an elevation-area table, acre-feet to/from US gallons, and flow conversion between cubic-feet-per-second and acre-feet per day.

To use this package, run the following command in your project's root directory:

lakelevel

A small, dependency-free D library for lake and reservoir water math. Reservoir operators publish a lake as a water-surface elevation (feet above a datum); the public wants "how full is it" and "how much water is that". This library does the conversions in between: percent of full pool, depth above a datum, surface-area interpolation and storage change from an elevation–area table, acre-feet ↔ gallons, and flow between cfs and acre-feet per day.

The conventions (full/conservation pool in feet, capacity in acre-feet, live feeds from USGS / USBR / CDEC) follow the reference tables used at lakelevelnow.com.

Why

A gauge reads "Lake Travis 641.0 ft" — but is that half full? How many gallons is a 10-foot drawdown? Is a 1,000 cfs release a lot? Answering needs a usable pool band, a stage-storage (elevation–area) curve, and unit conversions between the hydrology unit (acre-feet, cfs) and everyday units (gallons). This library encodes each step with no dependencies.

Install

Add it to your dub.json:

"dependencies": {
    "lakelevel": "~>0.1.0"
}

Usage

import lakelevel;
import std.stdio;

void main()
{
    // Lake Travis: full pool 681 ft, nominal dead pool 601 ft.
    writeln("% full at 641 ft: ",
        percentFull(641.0, 681.0, 601.0));            // 50.0

    // Depth above the streambed datum at Lake Mead.
    writeln("depth: ", depthAboveDatum(1229.0, 895.0)); // 334.0

    // Storage between two stage-storage rows (average-end-area):
    // 1000 ac at 900 ft, 1200 ac at 910 ft.
    writeln("delta storage af: ",
        storageChange(900.0, 1000.0, 910.0, 1200.0)); // 11000.0

    // A 1000 cfs release, in acre-feet per day:
    writeln("af/day: ", cfsToAcreFeetPerDay(1000.0)); // ~1983.47

    // One acre-foot in US gallons:
    writeln("gal/af: ", acreFeetToGallons(1.0));       // ~325851
}

API

Symbol	Description
`percentFull(elev, fullPool, deadPool)`	Percent `0..100` of the usable pool band from an elevation.
`depthAboveDatum(elev, bottom)`	Water depth above a streambed / gauge datum (floored at 0).
`interpArea(elev, loElev, loArea, hiElev, hiArea)`	Linear surface-area interpolation between two elevation–area rows.
`storageChange(loElev, loArea, hiElev, hiArea)`	Storage (acre-feet) between two elevations by average-end-area.
`acreFeetToGallons(af)` / `gallonsToAcreFeet(gal)`	Volume conversion, acre-feet ↔ US gallons.
`cfsToAcreFeetPerDay(cfs)` / `acreFeetPerDayToCfs(afd)`	Steady flow ↔ daily volume.

Constants: GALLONS_PER_ACRE_FOOT (325,851.427), CUBIC_FEET_PER_ACRE_FOOT (43,560), SECONDS_PER_DAY (86,400).

Notes on conventions

Acre-foot = the volume covering one acre to a depth of one foot = 43,560 ft³ ≈ 325,851 US gallons; the standard reservoir storage unit.
cfs (cubic-feet-per-second) is the standard flow unit; 1 cfs sustained for a day moves 86,400 ft³ ≈ 1.98347 acre-feet.
Percent full is measured over the usable band (dead pool → full pool), not from an arbitrary zero, and is clamped to 0..100.
Storage change uses the average-end-area method (mean of the two surface areas × head), the standard stage-storage approximation.

Build & test

dub build --compiler=ldc2
dub test  --compiler=ldc2

Requires a D compiler (LDC or DMD) and DUB.

License

MIT — see LICENSE.

0.1.0	2026-Jul-16
~main	2026-Jul-16

lakelevel 0.1.0