What’s New

What’s New#

v3.0.0 (Unreleased)#

New Features#

  • The base.ConservativeProcess class now supports both mass and energy budgets. Processes can specify which quantity to budget using the quantity parameter in _set_budget(). The new mass_budget and energy_budget properties provide explicit access to each budget type. The legacy budget property is deprecated and will be removed in the next major release - use mass_budget instead. (PR343) By James McCreight.

  • The new PRMSStreamTemp and PRMSStreamTempHumidityCBH classes provide stream temperature simulation using the PRMS stream temperature methodology, computing water temperatures based on energy balance in stream segments. The latter class accepts time-varying humidity inputs on the HRUs while the former accepts a mean monthly humidity for each segment. The classes support optional energy flux tracking and budgeting via the track_energy_fluxes parameter (default: True). When enabled, it computes and tracks 11 energy flux components including advective heat transport (upstream, lateral, outflow), surface energy exchange (solar radiation, longwave emission/absorption, evaporative cooling, convective exchange), and internal sources (friction heating, groundwater conduction). These fluxes are available as output variables and included in the energy budget. When disabled (track_energy_fluxes=False), energy flux variables are set to None and excluded from NetCDF output, with imbalance_behavior required to be None. The classes PRMSStreamTemp and PRMSStreamTempHumidityCBH take a stream shade class as input on initialization. Two stream shade classes have been implemented, PRMSStreamShadeConstant and PRMSStreamShadeDynamic. The former works based on 3 parameters: summer shade fraction, winter shade fraction, and segment latitude. The latter class computes shade dynamically based on topographic and vegetation parameters using solar geometry calculations. This is the default PRMS behavior when stream_temp_shade_flag = 0 and requires 13 parameters describing topography and vegetation characteristics for each stream segment. The classes PRMSStreamTemp and PRMSStreamTempHumidityCBH also require one of PRMSHydraulicGeometryFull or PRMSHydraulicGeometryWidthOnly as an upstream process to provide hydraulic geometry variables needed for energy balance calculations. PRMSHydraulicGeometryFull computes flow-dependent hydraulic geometry (width, depth, area, velocity) using power-law relationships when all parameters are provided, while PRMSHydraulicGeometryWidthOnly uses PRMS default values for depth parameters (depth_alpha=0.27, depth_m=0.39) when they are missing from the parameter file, matching PRMS 5.2.1 behavior. These capabilities are demonstrated in notebooks examples/01_multi-process_models.ipynb and examples/02_prms_legacy_models.ipynb as part of the NHM configuration in pywatershed. (PR343) By James McCreight.

  • Option for Model class to read from a single netcdf file or (not and, the existing option,) from a directory containing multiple netcdf files. (PR333) By James McCreight.

  • A new SourceSinkFlowNode class adds or removes flow above some minimum flow parameter as specified by an input data file. (PR327) By James McCreight.

  • The Control class has new method set_init_start_times to manage changing these times. (PR335) By James McCreight.

  • The FlowGraph class has new method plot to show an abstract plot of the FlowGraph. (PR351) By James McCreight.

  • The base.Process class and subclasses have a new restart capability. See notebook examples/08_restart_streamflow.ipynb for examples. (PR349, PR362) By James McCreight.

  • The PRMSAtmosphereTranspFrost implements the transp_frost module of PRMS. (PR354) By James McCreight.

  • The load() method of parameters.PrmsParameters now supports reading multiple parameter files which are treated as addenda to the first parameter file in the list which contains the dimension information. (PR354) By James McCreight.

  • The StarfitSourceSinkFlowNode allows sources and sinks to interact with storage of a Starfit reservoir/FlowNode. (PR348) By James McCreight.

  • The new Output class provides flexible output collection and statistical analysis for models, supporting HRUs of interest (HOI), segments/nodes of interest (NOI), and monthly accumulations. Includes Zarr chunked output capability for efficient large-scale data writing (~6x faster than NetCDF). See notebook examples/09_model_output.ipynb for examples. (PR363) By James McCreight.

  • 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 ET. PRMSSoilzoneAg is a simplified version without the observed ET iteration, suitable when ET observations are not available. See notebook examples/10_ag_irrigation_use.ipynb for examples. (PR362) By James McCreight.

  • Add pre-commit hook to run security review on staged files or on entire repository, checks for: 1. Absolute paths, 2. IP addresses, 3. Internal server hostnames, and 4. Usernames/passwords or credentials. See .github/scripts/check_security.py. (PR384) By James McCreight.

  • Bug fixes for PRMS 5.2.1.1: 1) errant code skipped humidity CBH files entirely when they were selected to be used, 2) code deletion resulted in seg_humid not being zeroed each timestep and erroneously accumulating. Both fixes are extensively documented. The PRMS code was modified (compared to the released 5.2.1.1) and the pywatershed code was made to match PRMS stream temperature when using humidity inputs from 1. CBH, 2. scalar parameter, and 3. monthly spatially distributed parameters. (PR386) By James McCreight.

  • Add a weekly security scan using Safety CLI in a GitHub Actions workflow (.github/workflows/security_check.yaml): checks conda-installed packages, pip-installed packages, and pyproject.toml dependencies separately. (PR387) By James McCreight.

Breaking Changes#

  • The budget_type parameter has been renamed to imbalance_behavior in base.ConservativeProcess and all its subclasses, in base.FlowGraph, and in control options. Update all budget_type references to imbalance_behavior in your code and configuration files. This breaking change clarifies what the parameter does and is intentionally distinct from the budget quantity parameter. (PR343) By James McCreight.

  • Budget netcdf output filenames have changed to include the quantity type. Mass budgets are now named ProcessName_mass_budget.nc instead of ProcessName_budget.nc. Energy budgets use ProcessName_energy_budget.nc. (PR343) By James McCreight.

Bug fixes#

  • PRMS 5.2.1.1 had a bug in stream temperature where division by HRU area was repeated multiple times. In the old code this occurred in routing.f90 on lines 764 and 765 and then again on 789 and 790, where seginc_swrad and seginc_potet were divided despite this having already occurred on lines 744 and 745. Comments regarding the fix are found on lines 764 and 793 in the fixed code. (PRXXX) By Author Name.

Internal changes#

  • The base.ConservativeProcess class now uses _mass_budget and _energy_budget attributes internally instead of budget. The budget property remains as a deprecated alias for _mass_budget for backward compatibility.

  • Refactor of test_data/generate/convert_prms_output_to_nc.py to put final variables into a separate file to run by pytests both after all other variables are generated and so the final variables are run serially. (PR331) By James McCreight.

v2.0.4 (23 February 2026)#

New Features#

Fixes to release workflow, pypi publishing.

v2.0.3 (22 February 2026)#

New Features#

Some minor fixes. This is a data release for the upcoming major release, new data will be an asset on this release.

v2.0.2 (14 March 2025)#

Bug fixes#

  • Fixed setup.py to allow editable installs, keeping up with changes in the pythonverse. Deprecated all fortran code built and interfaced using f2py as it was not popular and had only maybe very slight speed advantages compared to numba. This was not considered a breaking change because there are redundant alternatives to the fortran. (PR331) By James McCreight.

v2.0.1 (19 December 2024)#

New Features#

  • Corrected disclaimer on top-level README.md. Other minor fixes not to code base (CI, envs, etc).

v2.0.0 (16 December 2024)#

New Features#

Breaking Changes#

  • pref_flow_infil_frac now a required parameter input for PRMSSoilzone. The NHM values assumed previously are zeros on all HRUs. (PR288) By James McCreight.

Bug fixes#

  • Fixed calculation of the variable transp_on was incorrectly calculated in certain situations not covered by NHM configuratons but covered by sagehen_5yr. (PR288) By James McCreight.

  • Fixed calculation of variable dprst_area_open which was not being checked but was affecting no other variables. (PR288) By James McCreight.

  • The variable pptmix was incorrectly calculated in certain situations not covered by the NHM configurations. (PR288) By James McCreight.

Internal changes#

  • Testing system refactor to handle pairs of domains and control files allowing much more flexibility in configuration/control testing. (PR278) By James McCreight.

  • New testing domain “sagehen_5yr” is added to test_data directory with configuration sagehen_no_cascades. This domain introduces multiple PRMS capabilities (noted indvidually in this PR) not used in the NHM configuration and provides a test for these. (PR288) By James McCreight.

  • Tests are now marked as “domain” or “domainless” to avoid redundant runs of domainless tests across test domains. (PR288) By James McCreight.

  • New tests test_prms_above_snow and test_prms_below_snow replace test_model and are extremely close to PRMS (PRMSSolarGeometry: 1.0e-8, PRMSAtmosphere: 1.0e-5, PRMSCanopy: 1.0e-6, PRMSRunoff: 1.0e-8, PRMSRunoffNoDprst: 1.0e-8, PRMSSoilzone: 1.0e-8, PRMSSoilzoneNoDprst: 1.0e-8, PRMSGroundwater: 1.0e-8, PRMSGroundwaterNoDprst: 1.0e-8, PRMSChannel: 5.0e-7) for all test domains. (PR288) By James McCreight.

  • Migration to Numpy 2.0+. (PR310) By James McCreight.

v1.1.0 (25 June 2024)#

New features#

  • Minor enhancement to ensure PRMSSnow hru_deplcrv parameter is integer or coercable. (PR296) By James McCreight.

  • Release assests to include new GIS files and an additional domain to support the upcoming major release. By James McCreight.

v1.0.0 (18 December 2023)#

New features#

Breaking changes#

  • The control.options “netcdf_output_dir”, “netcdf_output_var_names”, and “netcdf_output_separate_files” match the keyword arguments “output_dir”, “output_vars”, and “separate_files” for both process.intitalize_netcdf() and model.initialize_netcdf(). None of these arguments can be supplied in both places (control and method call). It used to be that calling initialize_netcdf() would override what is supplied in control.options but this will now throw an error. The suggestion is to use control.options and not pass arguments to intialize_netcdf(). When using Control.load() (deprecated) or Control.load_prms() from a PRMS control file, note that the “control.options” of “netcdf_output_dir” and “netcdf_output_var_names” are set by values in the PRMS control file. You can edit these, but be aware that they are now set in that load. (PR257) By James McCreight.

Deprecations#

Performance#

Bug fixes#

  • Mass balance fix in PRMS snow for rain on snow followed by evaporation consuming the entire snow pack. (PR248) By James McCreight.

  • Fix mass balance issue in PRMSSnow is also present in PRMS, snow evap is not taken from freeh2o when there is no pk_ice. (PR236) By James McCreight.

  • Resolve issues with different ways of specifying necdf output options. (PR230) By James McCreight.

  • Resolve issues with different ways of specifiying netcdf output options. (PR230) By James McCreight.

  • PRMSSoilzone remove soil_moist_prev because soil_moist is not prognotic and PRMSRunoff was needing it in the advance and not getting the correct value. PRMSRunoff now depends on soil_lower_prev and soil_rechr_prev instead. (PR244) By James McCreight.

Documentation#

Internal changes#

  • New system for generating test_data, by calling generate_test_data.py from autotest/. The system helps autotest know if test data were generated and if they are up to date. (PR253) By James McCreight.

  • Apply pylint and flake8 everywhere as much as possible. (PR251) By James McCreight.

  • Remove diagnostic variables pkwater_equiv_change, pkwater_ante (PR248) By James McCreight.

  • Use v1 instead of main for fortran-lang/setup-fortran. (PR242, PR243) By Wes Bonelli.

  • Refactor test data generation to solve race condition for dependent tests. (PR237) By Wes Bonelli.

  • Refactor tests against PRMS for consistency, flexibility, and thoroughness. (PR244) By James McCreight.

v0.2.1 (19 July 2023)#

Bug fixes#

v0.2.0 (18 July 2023)#

New features#

  • New example notebooks. Moved old notebooks to examples/developer. (PR204) By James McCreight.

  • New way to specify Model instantiation either in-memory or from yaml files using a model dictionary. The approach is loosely based on MODFLOW 6 input organization. See Model documentation. Introduced the concept of discretizations for PRMS, defining “dis_hru” and “dis_seg”. These are components of how model dictionaries are specified. (PR188) By James McCreight.

  • New Control.from_yaml() method. (PR188) By James McCreight.

  • What’s new workflow (behold!) per GH180 and PR181 By James McCreight.

  • Add automatic release workflow to PyPi as per GH178. Associated implementation of gitflow and semver conventions. Overhauled CONTRIBUTING.md, DEVELOPER.md, README.md, and .github/RELEASE.md to document adopted practices. Adoption of git-cliff to generate change logs by filtering comitt messages, see cliff.toml. Clean up of environment files and streamlining against pyproject.toml. Symlink gfortran dylibs to /usr/local/lib on macOS CI so PRMS binaries included in this repo can find them. (PR179) By Wes Bonelli.

Breaking changes#

  • Move Control attribute “config” to “options” for handling global options. (PR188) By James McCreight.

  • Remove arguments from Model initialization. Options pass via control, new set_options() method on Process and ConservativeProcess (PR188) By James McCreight.

  • Control no longer takes a Parameter object as an initialization argument. Process subclasses now require arguments discretization and parameters. The firstargument of Model not a indefinite number of processes, it is now either a list of Process subclasses or a model dictionary (see Model documentation. (PR188) By James McCreight.

Deprecations#

Performance#

  • Introduce ASV performance benchmarks for import and various NHM configurations in pywatershed. (GH170 and PR184) By James McCreight.

Bug fixes#

Documentation#

Internal changes#

  • Introduce precommit hooks: nbstripout, blackdoc, and doctoc. (PR197) By James McCreight.

  • Rename StorageUnit to ConservativeProcess that subclasses from a new Process class that contains most of the StorageUnit functionality. (PR188) By James McCreight.

  • New set_options() method on Process and ConservativeProcess to set their initialization options as ‘_` atrributes. (PR188) By James McCreight.

  • Clean up of how the calc_method option assigns function names to reduce the total amount of code and do it upon initialization. (PR188) By James McCreight.

  • Rename many modules to use lower-snake-case names including those in base/, atmoshpere/, and hydrology/ (PR188) By James McCreight.

  • NHM “self-driving” tests (PR160) By James McCreight.

  • Refactor dependencies for standard pypi installation. (PR164, GH178) By Joseph Hughes.

v0.1.1 (27 April 2023)#

Initial release.