NWM GDROM: GDROM reservoir operation rules for the National Water Model¶

GDROM v2 reservoir operation rules packaged for the National Water Model's T-Route routing engine.

nwm-gdrom transforms the public GDROM v2 dataset (learned daily operating rules for 2,017 regulated reservoirs across the contiguous United States) into a single versioned binary catalog (.npz) that T-Route loads once at initialization. The catalog occupies about 23 megabytes resident, compresses to about 2 megabytes on disk, and loads in tens of milliseconds.

Install¶

pip install git+https://github.com/NGWPC/nwm-gdrom.git

For development with the bundled pixi environment:

git clone https://github.com/NGWPC/nwm-gdrom.git
cd nwm-gdrom
pixi install -e dev

Generate the catalog¶

Build the catalog end-to-end from the upstream HydroShare release. This downloads the GDROM v2 bag (~740 MB), normalizes the layout, computes the out-of-distribution thresholds from the training time series, packs the rules into a flat-array catalog, and writes the compressed .npz. Total wall time is dominated by the network download; CPU work is about 15 seconds once the data is local:

nwm-gdrom --source-dir ./data --out dist/nwm_gdrom_catalog.npz --rule-version v0.1.0

If you already have the GDROM v2 release locally, skip the download:

# Pre-extracted directory
nwm-gdrom -d ./data --source-existing /path/to/gdromv2 --rule-version v0.1.0

# Pre-downloaded zip
nwm-gdrom -d ./data --source-zip /path/to/gdromv2.zip --rule-version v0.1.0

The --rule-version flag pins the version stamp that gets embedded in the .npz; defaults to git describe --tags --always.

Load the catalog¶

import nwm_gdrom

catalog = nwm_gdrom.load_catalog(
    "dist/nwm_gdrom_catalog.npz",
    expected_rule_version="v0.1.0",
)

print(f"{catalog.n_reservoirs} reservoirs, rule_version={catalog.rule_version}")
# 2017 reservoirs, rule_version=v0.1.0

# The dataclass exposes the flat numpy arrays directly; T-Route's reservoir
# kernel reads them by reference in its compute loop.
print(catalog.grand_ids[:5])  # int64 GRanD identifiers, sorted
print(catalog.category[:5])  # 0=Res_R, 1=Res_L, 2=Res_M
print(catalog.storage_cap_m3[:5])  # float32, cubic meters

The expected_rule_version argument is validated against the version embedded in the .npz at build time; a mismatch raises CatalogVersionMismatchError rather than silently continuing.

Use a prebuilt catalog¶

For T-Route integrators who don't need to build locally, every tagged release publishes the prebuilt catalog as a GitHub Release asset:

# Latest release
curl -L -o nwm_gdrom_catalog.npz \
  https://github.com/NGWPC/nwm-gdrom/releases/latest/download/nwm_gdrom_catalog.npz

# Specific version
curl -L -o nwm_gdrom_catalog.npz \
  https://github.com/NGWPC/nwm-gdrom/releases/download/v0.1.0/nwm_gdrom_catalog.npz

Documentation¶

Full documentation is at https://NGWPC.github.io/nwm-gdrom/:

Installation: pip and pixi setups, system requirements.
Quickstart: produce and load a catalog in five minutes.
CLI reference: the nwm-gdrom command and all its flags.
Catalog format: on-disk schema, rule grammar, unit conventions.
API reference: public Python API.
Design notes: context, T-Route integration, and key design decisions.

Repository layout¶

nwm-gdrom/
├── src/nwm_gdrom/      Package source (incl. cli.py for the `nwm-gdrom` command)
├── tests/              Pytest suite
│   └── data/           Small fixture set (12 representative reservoirs), version-controlled
├── docs/               mkdocs site
└── .github/workflows/  CI for tests, docs, and releases

The full GDROM v2 source data is gitignored under ./data/ and downloaded on demand via the CLI.