Overview
In pywatershed version 3.0.0, the primary new capabilities introduced are stream temperature simulation following the PRMS methodology and the simulation of irrigated agriculture based on GSFLOW. See the v3.0.0 extended release notes for a fuller narrative.
Stream Temperature
The new PRMSStreamTemp and PRMSStreamTempHumidityCBH classes simulate stream temperature using the PRMS stream temperature methodology, computing water temperatures based on energy balance in stream segments, with optional tracking and budgeting of 11 energy flux components. The stream temperature classes take a stream shade class on initialization, either PRMSStreamShadeConstant or PRMSStreamShadeDynamic, and require one of PRMSHydraulicGeometryFull or PRMSHydraulicGeometryWidthOnly as an upstream process. These capabilities are demonstrated as part of the NHM configuration in notebooks 01_multi-process_models.ipynb and 02_prms_legacy_models.ipynb. In the course of this work, several bugs were found and corrected in the stream temperature code of PRMS 5.2.1.1; the PRMS source contained in the pywatershed repository was corrected and pywatershed matches the corrected code.
Agricultural Water Use
New agricultural water use classes enable simulation of irrigated agriculture based on GSFLOW. PRMSRunoffAg extends PRMSRunoff to calculate infiltration separately for pervious and agricultural areas. PRMSSoilzoneAgObsET provides dual-area soil moisture accounting with iterative adjustment of irrigation to match observed actual evapotranspiration, and PRMSSoilzoneAg is a simplified version for when ET observations are not available. These capabilities are demonstrated in a new example notebook, 10_ag_irrigation_use.ipynb.
Energy Budgets
The ConservativeProcess class now supports both mass and energy budgets. The new mass_budget and energy_budget properties provide explicit access to each budget type. The legacy budget property is deprecated; use mass_budget instead.
Transpiration and Frost
PRMSAtmosphereTranspFrost implements the transp_frost module of PRMS. PRMSAtmosphereTranspFrostDynamic extends it to accept dynamic (time-varying) fall and spring frost dates from PRMS dynamic parameter files.
Output Collection and Statistics
The new Output class provides flexible output collection and statistical analysis for models, supporting HRUs of interest, segments/nodes of interest, and monthly accumulations, with Zarr chunked output for efficient large-scale data writing. See the new example notebook 09_model_output.ipynb.
Model Restart
The Process class and its subclasses have a new restart capability, allowing runs to be split and continued. See the new example notebook 08_restart_streamflow.ipynb.
Additional FlowGraph and Model Functionality
A new SourceSinkFlowNode class adds or removes flow above some minimum flow parameter as specified by an input data file, and StarfitSourceSinkFlowNode allows sources and sinks to interact with storage of a Starfit reservoir.
The FlowGraph class has a new method plot to show an abstract plot of the FlowGraph.
The new staticmethod Model.solve_inputs determines where each process input comes from — another process or a file — from a process list or model dictionary, without instantiating a Model.
The Model class can read all inputs from a single NetCDF file as an alternative to a directory of NetCDF files, and PrmsParameters.load supports multiple parameter files treated as addenda to the first.
Breaking Changes
The budget_type parameter has been renamed to imbalance_behavior in ConservativeProcess and all its subclasses, in FlowGraph, and in control options. Budget NetCDF output filenames now include the quantity type: mass budgets are named ProcessName_mass_budget.nc instead of ProcessName_budget.nc, and energy budgets use ProcessName_energy_budget.nc.
Detailed Change Log
For additional details, see the What's New Documentation:
New Features
Stream temperature simulation: PRMSStreamTemp and PRMSStreamTempHumidityCBH, with stream shade classes PRMSStreamShadeConstant and PRMSStreamShadeDynamic and hydraulic geometry classes PRMSHydraulicGeometryFull and PRMSHydraulicGeometryWidthOnly; optional energy flux tracking and budgeting of 11 flux components.
Agricultural water use based on GSFLOW: PRMSRunoffAg, PRMSSoilzoneAgObsET, and PRMSSoilzoneAg, demonstrated in notebook 10_ag_irrigation_use.ipynb.
ConservativeProcess supports both mass and energy budgets with new mass_budget and energy_budget properties; the budget property is deprecated.
PRMSAtmosphereTranspFrost implements the PRMS transp_frost module; PRMSAtmosphereTranspFrostDynamic adds dynamic frost dates from PRMS dynamic parameter files.
The Output class for flexible output collection and statistics, including Zarr chunked output; notebook 09_model_output.ipynb.
Restart capability for processes; notebook 08_restart_streamflow.ipynb.
SourceSinkFlowNode and StarfitSourceSinkFlowNode for adding/removing flows in a FlowGraph; FlowGraph.plot.
Model.solve_inputs staticmethod to determine input sources without instantiating a Model.
Model can read all inputs from a single NetCDF file; PrmsParameters.load accepts multiple parameter files as addenda; Control.set_init_start_times manages changing initial/start times.
Corrections to PRMS 5.2.1.1 stream temperature (humidity CBH handling and seg_humid accumulation); pywatershed matches the corrected PRMS source in this repository.
A pre-commit security review hook and a weekly dependency security scan in CI.
Breaking Changes
budget_type renamed to imbalance_behavior in ConservativeProcess and subclasses, FlowGraph, and control options.
Budget NetCDF output filenames include the quantity type (ProcessName_mass_budget.nc, ProcessName_energy_budget.nc).
Bug fixes
utils.PrmsDynamicParameter now forward-fills from the most recent dynamic parameter date at or before the run start; previously runs starting between dynamic parameter dates saw fill values.
The PRMSRunoffAg mass budget did not balance on canopy-changeover days: the changeover budget input term was never set and depression storage inflow was missing changeover water. The budget now closes to machine precision.
PRMS 5.2.1.1 stream temperature repeated division by HRU area; corrected in the PRMS source contained in this repository.
Internal changes
Release procedures revamped: step-by-step release guide, guarded release automation (checks, package build/publish, frozen conda environment exports per platform), and a shared local/CI preflight script.
CI provides gfortran from the conda environment; flopy is temporarily installed from its develop branch pending the next flopy release.
The autotests require an explicit --domain option (the silent default was removed).