README.md

metadata

title: FloodGate v1
emoji: 🌊
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.29.1
python_version: '3.12'
app_file: app.py
license: mit
pinned: false
short_description: Run the Army Corps' Cumberland dams through real 2025 floods
tags:
  - openenv
  - simulation
  - rl-environment
  - flood-control
  - water-resources
  - operations-research
  - beam

FloodGate v1 · OpenEnv

The agent is the U.S. Army Corps of Engineers' water manager for the four flood-control dams above Nashville: Wolf Creek, Dale Hollow, Center Hill and J. Percy Priest. It runs them through the real February and April 2025 Cumberland River floods, rebuilt from the public record (USACE dam operations, USGS gauges, NWS flood stages). Every 6 hours it sets each dam's release. The water takes 2-26 hours to reach the flood gauges at Burkesville, Celina and Nashville, and every acre-foot it holds back is risk for the next storm.

This Space serves live mode. The agent commits releases one day at a time, without knowing the future:

• it sees 8 forecast scenarios, each replaying the error path of a real 2025 National Weather Service river forecast;
• committed water cannot be recalled;
• each decision is graded against the scenario-optimal decision, a two-stage stochastic LP. The grade is the expected cost the decision added, so luck does not count.

page	what
/web	OpenEnv's web UI. Explore: the 3D replay and every committed run's results. Playground: reset, step and the tools by hand
/twin/	the 3D replay: any plan for any task on the basin's terrain, rivers and reservoirs (USGS), with the hydrographs
/reset, /step, /state, /ws, /mcp	OpenEnv
/api/tasks, /api/tasks/{id}/plans, /api/tasks/{id}/replay?plan=	read-only JSON

Tools (live mode)

tool	returns
get_status()	the clock and the block to commit, storage, recent flows, every forecast scenario
check_plan(plan)	a draft for the remaining steps simulated under every scenario: cost spread, gauge peaks, lake levels (10 per episode)
commit(releases)	commits the day's releases, e.g. {"WC": 12000, "DH": [3000, 3500, 4000, 4000]}; the last commit ends the episode

Results on the 24 sample tasks (live mode)

model or policy	mean reward (95% CI)	real	storm ×1.5	half full	solved
scenario-optimal decisions (the reference)	1.000	1.000	1.000	1.000	24
a perfect solver planning on the mean forecast (no model)	0.552	0.517	0.504	0.636	-
DeepSeek-V4.1-Flash	0.364 (0.306-0.428)	0.414	0.334	0.344	0
Beam-1.0-501B-A23B, default effort	0.236 (0.217-0.261)	0.226	0.263	0.219	0
Beam-1.0-501B-A23B, reasoning_effort high	0.237 (0.217-0.265)	0.216	0.260	0.234	0
hold every release (the lazy operator)	0.215	0.215	0.215	0.215	-

• Live mode is hard for every model: none solves a task, and none reaches a perfect solver that simply plans on the mean forecast.
• Beam over-releases into a river already in flood. It opens dams to their maximum while Nashville is above major flood stage, and on half the tasks its decisions add more expected cost than doing nothing.
• More reasoning effort does not change Beam's score. DeepSeek-V4.1-Flash beats Beam on 22 of the 24 tasks.

Data

All U.S. federal works, public domain:

• dam release, storage and pool levels: USACE CWMS;
• river flow and stage: USGS;
• flood categories and ratings: NOAA NWS;
• the river forecasts NWS issued in 2025: the Ohio River Forecast Center, via the Iowa Environmental Mesonet archive;
• the replay's terrain and hydrography: USGS 3DEP and NHD.

Each rule's source (real, derived or assumed) is in data/cumberland/SOURCE.md. Tasks, data and every run's plans: the FloodGate dataset.

How Beam was used

Beam (reflection/Beam-1.0-501B-A23B) played every task through the Hugging Face router (Baseten), at default and high reasoning effort:

• its reasoning_content was sent back on every turn, as Beam's providers require;
• its 1M-token context holds a whole live episode (6 decisions, 8 scenarios each) without truncation;
• its plans are in the replay and the dataset.

The environment is also an RL environment for Beam: a deterministic grader with no LLM in the reward, and an exact reference for every task.