Metadata-Version: 2.1
Name: nwsrfspy
Version: 1.0.0
Summary: Python tools for NWSRFS modeling with FORTRAN source Code integration
Keywords: hydrology,nwsrfs,conceptual-modeling,operational-forecasting,operations,noaa,national-weather-service,nws,river-forecast-centers,rfc
Author-Email: Geoffrey Walters PE <geoffrey.walters@noaa.gov>, Cameron Bracken <cameron.bracken@pnnl.gov>
License: Software code created by U.S. Government employees is not subject to copyright in the
         United States (17 U.S.C. §105). The United States/Department of Commerce reserves all
         rights to seek and obtain copyright protection in countries other than the United States
         for Software authored in its entirety by the Department of Commerce. To this end, the
         Department of Commerce hereby grants to Recipient a royalty-free, nonexclusive license
         to use, copy, and create derivative works of the Software outside of the United States.
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Fortran
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Description-Content-Type: text/markdown

# NWSRFSpy

`nwsrfs_py` is a Python interface to NWSRFS hydrologic models using `f2py` wrappers around FORTRAN implementations.

It is designed to support [NWRFC autocalibration](https://github.com/NOAA-NWRFC/nwsrfs-hydro-autocalibration) workflows and provides classes for simulation and AdjustQ operations. Sample calibration data is archived on [Zenodo](https://doi.org/10.5281/zenodo.18829935).

## Install (PyPI)

```bash
pip install nwsrfspy
```

## Quick Start

```python
from nwsrfs_py import simulation

# Load packaged example data
model_run = simulation.NwsrfsRun.load_example("NRKW1")

# Simulated streamflow series
sim_flow = model_run.sim
print(sim_flow.head())
```

## Included Model Components

* SAC-SMA + SNOW-17 (`SacSnow`)
* UNIT-HG (`GammaUh`)
* LAG-K (`Lagk`)
* CHANLOSS (`Chanloss`)
* CONS_USE (`Consuse`)

## Documentation

Python docs: [https://NOAA-NWRFC.github.io/nwsrfs-hydro-models/python/](https://NOAA-NWRFC.github.io/nwsrfs-hydro-models/python/)

## Build From Source (Developers)

Source builds require a Fortran toolchain plus build tools.

Requirements:

* Python 3.10+
* `numpy`, `pandas`, `scipy`
* `gfortran`
* `meson`, `meson-python`, `ninja`

### Using pixi (recommended)

From repository root:

```bash
pixi run install-py
```

### Using conda

```bash
conda create -n nwsrfs_env python=3.10
conda activate nwsrfs_env
conda install -c conda-forge fortran-compiler meson meson-python ninja
```

Install from source:

```bash
git clone https://github.com/NOAA-NWRFC/nwsrfs-hydro-models.git
cd nwsrfs-hydro-models/nwsrfs_py
pip install .
python -c "import nwsrfs_py; print('Success!')"
```

Editable install:

```bash
pip install -e . --no-build-isolation -v
```

For runnable scripts in the source tree, see `examples/`.

## Citation

If you use this package, please cite:

Walters, G., Bracken, C., et al., "A comprehensive calibration framework for the Northwest River Forecast Center." Journal of the American Water Resources Association (JAWRA), accepted for publication in 2026. [Preprint](https://eartharxiv.org/repository/view/8993/)
