Welcome to NWSRFSpy

NWSRFSpy is a Python library that provides a high-performance interface to the National Weather Service River Forecast System (NWSRFS) hydrologic models.

It utilizes F2PY to wrap the original Fortran source code for models like SAC-SMA, SNOW-17, Lag-K, and UNIT-HG, enabling vectorized execution directly within Python. This library is designed to support the NWS-NWRFC autocalibration workflow.

Key Features

Vectorized Execution: Run models across multiple zones and timesteps simultaneously using NumPy arrays.
Pandas Integration: Inputs and outputs are handled via Pandas DataFrames for easy analysis.
Core Models:
- SacSnow: Combined wrapper for SAC-SMA and SNOW-17.
- Gamma UNIT-HG: Gamma Unit Hydrograph generation and routing.
- Lag-K: Lag and K routing for upstream reaches.
- CONS_USE Irrigation diversion adjustments.
- CHANLOSS Channel loss, natural or anthropogenic, adjustments.

Installation

git clone https://github.com/NOAA-NWRFC/nwsrfs-hydro-models.git
cd nwsrfs-hydro-models/nwsrfs_py
pip install .

Usage Example

Here is a simple example of initializing a run using the NWRFC AutoCalibration tools:

from nwsrfs_py import simulation

# Initialize a run with package example data
model_run = simulation.NwsrfsRun.load_example('NRKW1')

# Access the simulated streamflow
sim_flow = model_run.sim
print(sim_flow.head())

Documentation

For model background, see the NWSRFS User Manual.

How to Cite Us

If you use this software or the underlying calibration framework in your research, we ask that you please cite our published paper:

Walters, G., Bracken, C., Gillies, B., et al. (2026). A comprehensive calibration framework for the Northwest River Forecast Center. JAWRA Journal of the American Water Resources Association, 62(2), e70112. https://doi.org/10.1111/1752-1688.70112.

BibTeX:

@article{walters2026calibration,
  title={A comprehensive calibration framework for the Northwest River Forecast Center},
  author={Walters, Geoffrey and Bracken, Cameron and Gillies, Brad and Pope, Leah and Pai, Henry and Chokshi, Sonali and Stegemiller, Victor and King, Stephen and Bracken, Julie and Dixon, Taylor and Intermill, Joe},
  year={2026},
  journal={JAWRA Journal of the American Water Resources Association},
  volume={62},
  number={2},
  pages={e70112},
  doi={10.1111/1752-1688.70112},
  url={https://doi.org/10.1111/1752-1688.70112}
}

Citing the Software Directly:

For the sake of reproducibility, please also consider citing the specific version of the software you used. You can find the citation metadata for this repository below:

cff-version: 1.2.0
message: "If you use this repository, please cite both the software and the associated publication."
title: "NWSRFS Operational Hydrology Models (nwsrfs-hydro-models)"
authors:
  - family-names: "Walters"
    given-names: "Geoffrey"
    orcid: "https://orcid.org/0009-0009-3804-8898"
  - family-names: "Bracken"
    given-names: "Cameron"
    orcid: "https://orcid.org/0000-0003-1917-402X"
repository-code: "https://github.com/NOAA-NWRFC/nwsrfs-hydro-models"
url: "https://noaa-nwrfc.github.io/nwsrfs-hydro-models/"
preferred-citation:
  type: article
  title: "A Comprehensive Calibration Framework for the Northwest River Forecast Center"
  authors:
    - family-names: "Walters"
      given-names: "Geoffrey"
      orcid: "https://orcid.org/0009-0009-3804-8898"
    - family-names: "Bracken"
      given-names: "Cameron"
      orcid: "https://orcid.org/0000-0003-1917-402X"
    - family-names: "Gillies"
      given-names: "Brad"
    - family-names: "Pope"
      given-names: "Leah"
    - family-names: "Pai"
      given-names: "Henry"
    - family-names: "Chokshi"
      given-names: "Sonali"
    - family-names: "Stegemiller"
      given-names: "Victor"
    - family-names: "King"
      given-names: "Stephen"
    - family-names: "Bracken"
      given-names: "Julie"
    - family-names: "Dixon"
      given-names: "Taylor"
    - family-names: "Intermill"
      given-names: "Joe"
  year: 2026
  journal: "JAWRA Journal of the American Water Resources Association"
  volume: 62
  issue: 2
  doi: "10.1111/1752-1688.70112"
  url: "https://doi.org/10.1111/1752-1688.70112"
references:
  - type: dataset
    title: "NWSRFS Autocalibration Sample Runs"
    authors:
      - family-names: "Walters"
        given-names: "Geoffrey"
        orcid: "https://orcid.org/0009-0009-3804-8898"
      - family-names: "Bracken"
        given-names: "Cameron"
        orcid: "https://orcid.org/0000-0003-1917-402X"
    doi: "10.5281/zenodo.18829935"
    url: "https://zenodo.org/records/18829935"
    repository-code: "https://github.com/NOAA-NWRFC/nwsrfs-hydro-autocalibration"
  - type: software
    title: "NWRFC Autocalibration Framework"
    authors:
      - family-names: "Walters"
        given-names: "Geoffrey"
        orcid: "https://orcid.org/0009-0009-3804-8898"
      - family-names: "Bracken"
        given-names: "Cameron"
        orcid: "https://orcid.org/0000-0003-1917-402X"
    repository-code: "https://github.com/NOAA-NWRFC/nwsrfs-hydro-autocalibration"

Contents: