GDROM v2 Dataset Documentation

Overview of the dataset

Effective reservoir operation is critical for achieving multiple water management objectives, while also representing a major human intervention in hydrologic processes. However, due to sparse or inconsistent observations of daily inflow, release, and storage, most existing models either simplify or omit reservoir behavior. To address this gap, we present GDROM v2, a nationwide dataset covering daily operation data and derived operation rules for 2,017 reservoirs across the Contiguous United States (CONUS), building upon the original GDROM (Li et al., 2023) of 452 reservoirs. GDROM v2 also integrates historical reservoir operation records from ResOpsUS (Steyaert et al., 2022), USACE (2021), etc. along with two methods, detailed introduced in Zheng et al. (2025):

• Matched inflow and release data using USGS river discharge records (parameter code 00060, discharge, 2024)
• Estimated reservoir storage using satellite-derived surface area from SARAH-CONUS (Yadav and Gao, 2025) and bathymetric from GRDL (Hao et al., 2024)

Reservoirs are categorized into:

• Data-rich (Res-R): 748 reservoirs with >5 years of high-quality daily inflow, release and storage data, directly used for GDROM training.
• Data-limited (Res-L): 174 reservoirs with <5 years of daily inflow, release and storage data. GDROMs are transferred and fine-tuned from the most analogous Res-R.
• Data-missing (Res-M): 1,095 reservoirs, 203 have none of the three variables available (i.e., inflow, release, and storage), while the remaining reservoirs have either only one variable or two non-overlapping variables. GDROMs are transferred from the most analogous Res-R.

The GDROM for each reservoir is composed of two components:

• Modules: Simulate daily release based on daily inflow and storage. For Res-R, modules are trained by HMDT, as introduced by Zhao and Cai (2020). For Res-L, the functional form of each module follows predefined Six-Type release structures, including constant release, inflow- or storage-driven patterns, and joint combinations, as introduced in Li et al. (2024). For Res-M and Res-N, the modules are directly copied from the most analogous Res-R reservoirs.
• Module Conditions: Define the conditions under which a specific module to be used, based on daily inflow, initial storage, day of year (DOY), and Palmer Drought Severity Index (PDSI). The mapping from state variables to module index is captured by CART, as detailed in Chen et al. (2022). For reservoirs with a single module, this module condition file is not required.

Description of the dataset

readme.md

• This document describes the structure, metadata, and usage of GDROM v2.

reservoir_metadata.csv

• This metadata file documents key attributes for all 2,015 reservoirs. Each row represents a unique reservoir, and columns describe specific physical, geographic, operational, or modeling-related properties. Most physical, geographic, operational properties are sourced from the Global Reservoir and Dam (GRanD) database (Lehner et al., 2011), the remaining are sourced from the National Inverntory of Dams (NID) database (USACE, 2025). The metadata schema is detailed below:

• GRAND_ID: The unique identifier assigned to each reservoir, adopted from the GRanD database. For reservoirs not listed in GRanD, an ID is assigned starting from 10000.

• RES_NAME / DAM_NAME: The name of the reservoir and its associated dam.
• ADMIN_UNIT / STATE: The U.S. state where the reservoir is located, given in full (ADMIN_UNIT) and abbreviated (STATE) forms.
• STORAGE_MAX: The maximum observed storage during the available record period, in unit of acre-feet. For reservoirs lacking observed storage records, estimates are obtained using the Global Reservoir Storage (GRS; Li et al., 2023).
• USE_IRRI, USE_ELEC, USE_SUPP, USE_FCON, USE_RECR, USE_NAVI, USE_FISH, USE_PCON, USE_LIVE, USE_OTHR: Operational use priority indicators across ten standard water use categories, where "Main" indicates the primary purpose, "Sec" indicates secondary use, and a blank cell means the reservoir is not used for that purpose.
• MAIN_USE: The main use of the reservoir.
• LONGITUDE / LATITUDE: Geographic coordinates (in decimal degrees) representing the location of the dam.
• YEAR_RANGE: The range of years (e.g., 2005–2019) for which valid daily records are available for the reservoir.
• INFLOW/ RELEASE/ STORAGE Length: The number of daily inflow / outflow / storage data, in unit of acre-feet/day.
• INFLOW/ RELEASE/ STORAGE SOURSE: The source used to collect daily inflow / outflow / storage data.
• CATEGORY: The classification of each reservoir based on data availability.
• MODULE_NUMBER: The number of HMDT modules used for simulating release behavior.
• NSE / PBIAS: Model evaluation metrics—Nash-Sutcliffe Efficiency and Percent Bias—which are used to assess model performance for Res-R and Res-L.

Time series of reservoir variables/

• This folder contains all the time series of reservoir variables.

Time series of reservoir variables/collected data for all reservoirs

• Raw historical data collected and merged.
• The records of each reservoir are stored in a CSV file named as reservoirID.csv.

Time series of reservoir variables/cleaned data for Res-R & Res-L

• Historical operation data after data cleaning.
• The records of each reservoir are stored in a CSV file named as reservoirID.csv.

Time series of reservoir variables/normalized data for Res-R & Res-L

• Normalized historical operation data used for model training.
• The records of each reservoir are stored in a CSV file named as reservoirID.csv.

operation_rule/

• This folder contains the extracted operation rules for each reservoir.
• Two sub-folders: modules/ and module_conditions/, storing the representative operation modules and module conditions, respectively.

operation_rule/modules/

• Extracted operation modules for each reservoir.
• Each reservoir may have one or more modules, named as reservoirID_moduleID.txt, with module IDs starting from 0.
• Each operation module is written as a set of "if-then-else" statements, with inflow and storage as inputs and release as outputs.

operation_rule/module_conditions/

• Module conditions for reservoirs with multiple modules.
• Each applicable reservoir has one condition file, named as reservoirID.txt, describing the conditions under which each module is used.
• If a reservoir has only one module, no condition file is needed.
• Each condition file is written as a set of “if–then–else” statements, with inflow, storage, DOY, and PDSI as inputs, and the corresponding module IDs as outputs.

script/

• This folder contains the main Python scripts for running or training GDROM models.

script/Environment

• Contains instructions for setting up the Python environment required for training or running GDROM models.
• Please refer to environment.md in this folder for detailed setup guidance.

script/Reference Res-R

• Contains the data and operation rules needed for transfer learning from Res-R to Res-L and Res-M.

script/GDROM_Res_R.py

• Script for training GDROM models on Res-R reservoirs.

script/GDROM_Res_L.py

• Script for training GDROM models on Res-L reservoirs.

script/GDROM_Res_M.py

• Script for training GDROM models on Res-M reservoirs.

script/rule2model.py

• Script for applying existing rule-based models directly to reservoirs.
• Suitable for users who only want to simulate using pretrained models.

script/other .py files

• Contains auxiliary Python modules with shared functions used across all GDROM scripts.

Citations

• Chen, Y., Li, D., Zhao, Q., & Cai, X. (2022). Developing a generic data-driven reservoir operation model. Advances in Water Resources, 167, 104274. https://doi.org/10.1016/j.advwatres.2022.104274
• Hao, Z., Chen, F., Jia, X., Cai, X., Yang, C., Du, Y., & Ling, F. (2024). GRDL: A new global reservoir area-storage-depth data set derived through deep learning-based bathymetry reconstruction. Water Resources Research, 60, e2023WR035781. https://doi.org/10.1029/2023WR035781
• Lehner, B., Reidy Liermann, C., Revenga, C., Vörösmarty, C., Fekete, B., Crouzet, P., Döll, P., Endejan, M., Frenken, K., Magome, J., Nilsson, C., Robertson, J. C., Rodel, R., Sindorf, N., & Wisser, D. (2011). High-resolution mapping of the world’s reservoirs and dams for sustainable river-flow management. Frontiers in Ecology and the Environment, 9(9), 494–502. https://www.globaldamwatch.org/grand
• Li, D., Chen, Y., Cai, X., & Zhao, Q. (2023). Data-driven Reservoir Operation Rules for 450+ Reservoirs in Contiguous United States. HydroShare. https://doi.org/10.4211/hs.63add4d5826a4b21a6546c571bdece10
• Li, D., Chen, Y., Lyu, L., & Cai, X. (2024). Uncovering historical reservoir operation rules and patterns: Insights from 452 large reservoirs in the contiguous United States. Water Resources Research, 60, e2023WR036686. https://doi.org/10.1029/2023WR036686
• Li, Y., Zhao, G., Allen, G. H., & Gao, H. (2023). Diminishing storage returns of reservoir construction. Nature Communications, 14, 3203. https://doi.org/10.1038/s41467-023-38970-4
• Steyaert, J. C., Condon, L. E., Turner, W. D., & others. (2022). ResOpsUS, a dataset of historical reservoir operations in the contiguous United States. Scientific Data, 9, 34. https://doi.org/10.1038/s41597-022-01134-7
• U.S. Army Corps of Engineers (USACE). (2021). WM data dissemination [Dataset]. https://water.usace.arm.mil/
• U.S. Army Corps of Engineers (USACE). (2025). National Inverntory of Dams [Dataset], https://nid.sec.usace.army.mil/#/
• U.S. Geological Survey (USGS). (2024). Dataretrieval: Download hydrologic data [Dataset]. https://github.com/DOI-USGS/dataretrieval-python
• Yadav, A., & Gao, H. (2025). SARAH-CONUS: Sub-weekly area of reservoirs from analysis of harmonized Landsat and Sentinel-2 data for the continental US [Dataset]. Texas Data Repository, V1. https://doi.org/10.18738/T8/4BMYBP
• Zhao, Q., & Cai, X. (2020). Deriving representative reservoir operation rules using a hidden Markov-decision tree model. Advances in Water Resources, 146, 103753. https://doi.org/10.1016/j.advwatres.2020.103753
• Zheng, Z., Cai, X., et al. (2025). GDROM v2: A nationwide inventory of operation variable time series and rules for 2,017 large reservoirs across the CONUS (in preparation).

Contact

For any questions, please contact:

Zihan Zheng
Email: [zihanz10@illinois.edu]