.. currentmodule:: pywatershed What's New ========== .. ipython:: python :suppress: import numpy as np import pywatershed as pws np.random.seed(123456) v3.0.0 (Unreleased) --------------------- New Features ~~~~~~~~~~~~~~~~ - The :class:`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. (:pull:`343`) By `James McCreight `_. - The new :class:`PRMSStreamTemp` and :class:`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 :class:`PRMSStreamTemp` and :class:`PRMSStreamTempHumidityCBH` take a stream shade class as input on initialization. Two stream shade classes have been implemented, :class:`PRMSStreamShadeConstant` and :class:`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 :class:`PRMSStreamTemp` and :class:`PRMSStreamTempHumidityCBH` also require one of :class:`PRMSHydraulicGeometryFull` or :class:`PRMSHydraulicGeometryWidthOnly` as an upstream process to provide hydraulic geometry variables needed for energy balance calculations. :class:`PRMSHydraulicGeometryFull` computes flow-dependent hydraulic geometry (width, depth, area, velocity) using power-law relationships when all parameters are provided, while :class:`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. (:pull:`343`) By `James McCreight `_. - Option for :class:`Model` class to read from a single netcdf file or (not and, the existing option,) from a directory containing multiple netcdf files. (:pull:`333`) By `James McCreight `_. - A new :class:`SourceSinkFlowNode` class adds or removes flow above some minimum flow parameter as specified by an input data file. (:pull:`327`) By `James McCreight `_. - The :class:`Control` class has new method `set_init_start_times` to manage changing these times. (:pull:`335`) By `James McCreight `_. - The :class:`FlowGraph` class has new method `plot` to show an abstract plot of the FlowGraph. (:pull:`351`) By `James McCreight `_. - The :class:`base.Process` class and subclasses have a new restart capability. See notebook ``examples/08_restart_streamflow.ipynb`` for examples. (:pull:`349`, :pull:`362`) By `James McCreight `_. - The :class:`PRMSAtmosphereTranspFrost` implements the transp_frost module of PRMS. (:pull:`354`) By `James McCreight `_. - The `load()` method of :class:`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. (:pull:`354`) By `James McCreight `_. - The :class:`StarfitSourceSinkFlowNode` allows sources and sinks to interact with storage of a Starfit reservoir/FlowNode. (:pull:`348`) By `James McCreight `_. - The new :class:`~base.output.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. (:pull:`363`) By `James McCreight `_. - New agricultural water use classes enable simulation of irrigated agriculture based on GSFLOW. :class:`PRMSRunoffAg` extends :class:`PRMSRunoff` to calculate infiltration separately for pervious and agricultural areas. :class:`PRMSSoilzoneAgObsET` provides dual-area soil moisture accounting with iterative adjustment of irrigation to match observed actual ET. :class:`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. (:pull:`362`) 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. (:pull:`384`) 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. (:pull:`386`) 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. (:pull:`387`) By `James McCreight `_. Breaking Changes ~~~~~~~~~~~~~~~~ - The ``budget_type`` parameter has been renamed to ``imbalance_behavior`` in :class:`base.ConservativeProcess` and all its subclasses, in :class:`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. (:pull:`343`) 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``. (:pull:`343`) 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. (:pull:`XXX`) By `Author Name `_. Internal changes ~~~~~~~~~~~~~~~~ - The :class:`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. (:pull:`331`) By `James McCreight `_. .. _whats-new.2.0.4: v2.0.4 (23 February 2026) -------------------------- New Features ~~~~~~~~~~~~~~~~ Fixes to release workflow, pypi publishing. .. _whats-new.2.0.3: 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. .. _whats-new.2.0.2: 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. (:pull:`331`) By `James McCreight `_. .. _whats-new.2.0.1: 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). .. _whats-new.2.0.0: v2.0.0 (16 December 2024) ----------------------------- New Features ~~~~~~~~~~~~~~~~ - The :class:`FlowGraph` capabilities are introduced. These allow users to combine different kinds flow solutions in arbitrary order on a "flow graph". The accompanying base classes :class:`FlowNode` and :class:`FlowNodeMaker` are introduced along with their subclasses for modeling :class:`PassThroughFlowNode`\ s, :class:`ObsInFlowNode`\ s (flow replacement by observations with sink and source tracking in mass balance), :class:`PRMSChannelFlowNode`\ s, and :class:`StarfitFlowNode`\ s. A new example notebook, `examples/06_flow_graph_starfit.ipynb `__ demonstrates adding STARFIT reservoir nodes into a FlowGraph otherwise simulating `PRMSChannel` and highlights helper functions for this use case. (:pull:`233`) By `James McCreight `_. - The :class:`MmrToMf6Dfw` class builds a MF6 simulation with Diffusive Wave (DFW) routing from PRMS NHM input files and a few simple assumptions. The lateral (to-channel) fluxes from a PRMS are used as time varying boundary conditions. A new notebook runs the Delaware River Basin using MF6 DFW: `examples/07_mmr_to_mf6_chf_dfw.ipynb `__. (:pull:`290`) By `James McCreight `_. - No depression storage subclasses are available for PRMSRunoff, PRMSSoilzone, and PRMSGroundwater by adding "NoDprst" to the end of the names. Depression storage is switched off in sagehen_5yr and in new nhm_no_dprst configurations. (:pull:`288`) By `James McCreight `_. - Dunnian flow is implemented (in PRMSSoilzone) and tested for sagehen_5yr. (:pull:`288`) By `James McCreight `_. - Preferential flow is implemented (in PRMSSoilzone) and tested for sagehen_5yr. (:pull:`288`) By `James McCreight `_. - Control instances have a diff method to compare with other instances. (:pull:`288`) By `James McCreight `_. - Feature to standardize subsetting input data (parameters and forcings) in space and time either from file (:func:`utils.netcdf_utils.subset_netcdf_file`) or in memory (:func:`utils.netcdf_utils.subset_xr`). (:pull:`304`) By `James McCreight `_. Breaking Changes ~~~~~~~~~~~~~~~~ - pref_flow_infil_frac now a required parameter input for PRMSSoilzone. The NHM values assumed previously are zeros on all HRUs. (:pull:`288`) 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. (:pull:`288`) By `James McCreight `_. - Fixed calculation of variable dprst_area_open which was not being checked but was affecting no other variables. (:pull:`288`) By `James McCreight `_. - The variable pptmix was incorrectly calculated in certain situations not covered by the NHM configurations. (:pull:`288`) By `James McCreight `_. Internal changes ~~~~~~~~~~~~~~~~ - Testing system refactor to handle pairs of domains and control files allowing much more flexibility in configuration/control testing. (:pull:`278`) 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. (:pull:`288`) By `James McCreight `_. - Tests are now marked as "domain" or "domainless" to avoid redundant runs of domainless tests across test domains. (:pull:`288`) 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. (:pull:`288`) By `James McCreight `_. - Migration to Numpy 2.0+. (:pull:`310`) By `James McCreight `_. .. _whats-new.1.1.0: v1.1.0 (25 June 2024) --------------------- New features ~~~~~~~~~~~~ - Minor enhancement to ensure PRMSSnow hru_deplcrv parameter is integer or coercable. (:pull:`296`) By `James McCreight `_. - Release assests to include new GIS files and an additional domain to support the upcoming major release. By `James McCreight `_. .. _whats-new.1.0.0: v1.0.0 (18 December 2023) ------------------------- New features ~~~~~~~~~~~~ - Control object features including (optional) warnings for unused legacy options, and defined and enforced options. Also to_yaml() and __str__ implementations. (:pull:`240`) By `James McCreight `_. - Example notebook of how to edit Parameters with associated bug fixes to do so. (:pull:`232`) By `James McCreight `_. - Conda feedstock for pywatershed ``_. By `Joseph Hughes `_. 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. (:pull:`257`) By `James McCreight `_. Deprecations ~~~~~~~~~~~~ - Deprecation of Control.load() for Control.load_prms(). (:pull:`240`) By `James McCreight `_. Performance ~~~~~~~~~~~ Bug fixes ~~~~~~~~~ - Mass balance fix in PRMS snow for rain on snow followed by evaporation consuming the entire snow pack. (:pull:`248`) 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. (:pull:`236`) By `James McCreight `_. - Resolve issues with different ways of specifying necdf output options. (:pull:`230`) By `James McCreight `_. - Resolve issues with different ways of specifiying netcdf output options. (:pull:`230`) 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. (:pull:`244`) By `James McCreight `_. Documentation ~~~~~~~~~~~~~ - Implement sphinx_autodoc_typehints. (:pull:`257`) By `James McCreight `_. - New gh-pages branch (without history) to publish `"pywatershed notes" `_ including the `extended release notes for v1.0.0 `_. This branch publishes analysis supporting the version 1.0.0 release. - Add about section for version 1.0 to describe how pywatershed matches PRMS' NHM configuration and how to perform the comparison. (:pull:`244`) By `James McCreight `_. 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. (:pull:`253`) By `James McCreight `_. - Apply pylint and flake8 everywhere as much as possible. (:pull:`251`) By `James McCreight `_. - Remove diagnostic variables pkwater_equiv_change, pkwater_ante (:pull:`248`) By `James McCreight `_. - Use v1 instead of main for fortran-lang/setup-fortran. (:pull:`242`, :pull:`243`) By `Wes Bonelli `_. - Refactor test data generation to solve race condition for dependent tests. (:pull:`237`) By `Wes Bonelli `_. - Refactor tests against PRMS for consistency, flexibility, and thoroughness. (:pull:`244`) By `James McCreight `_. .. _whats-new.0.2.1: v0.2.1 (19 July 2023) --------------------- Bug fixes ~~~~~~~~~ - Package data was not properly installed. (:pull:`219`) By `James McCreight `_. - Small addition to notebook 02 (:pull:`219`) By `James McCreight `_. .. _whats-new.0.2.0: v0.2.0 (18 July 2023) --------------------- New features ~~~~~~~~~~~~ - New example notebooks. Moved old notebooks to `examples/developer`. (:pull:`204`) 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. (:pull:`188`) By `James McCreight `_. - New `Control.from_yaml()` method. (:pull:`188`) By `James McCreight `_. - What's new workflow (behold!) per :issue:`180` and :pull:`181` By `James McCreight `_. - Add automatic release workflow to PyPi as per :issue:`178`. 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. (:pull:`179`) By `Wes Bonelli `_. Breaking changes ~~~~~~~~~~~~~~~~ - Move Control attribute "config" to "options" for handling global options. (:pull:`188`) By `James McCreight `_. - Remove arguments from `Model` initialization. Options pass via control, new `set_options()` method on Process and ConservativeProcess (:pull:`188`) 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. (:pull:`188`) By `James McCreight `_. Deprecations ~~~~~~~~~~~~ Performance ~~~~~~~~~~~ - Introduce ASV performance benchmarks for import and various NHM configurations in pywatershed. (:issue:`170` and :pull:`184`) By `James McCreight `_. Bug fixes ~~~~~~~~~ - Remove non-pep-compliant post-release reset PR steps. (:pull:`203`) By `Wes Bonelli `_. - Add doc building requirements to environment.yml (:pull:`188`) By `James McCreight `_. - Revive fortran compiling for editable installs (:pull:`188`) By `James McCreight `_. - Made the Parameter class data completely private by converting dicts to MappingProxyTypes and setting numpy.ndarrays to read-only. (:issue:`177` and :pull:`183`) By `James McCreight `_. - ModelGraph improvements and fixes (however result are platform dependent) (:pull:`162`) By `James McCreight `_. Documentation ~~~~~~~~~~~~~ - Model class, DatasetDict and general documentation overhaul (:pull:`188`) By `James McCreight `_. Internal changes ~~~~~~~~~~~~~~~~ - Introduce precommit hooks: `nbstripout`, `blackdoc`, and `doctoc`. (:pull:`197`) By `James McCreight `_. - Rename StorageUnit to ConservativeProcess that subclasses from a new Process class that contains most of the StorageUnit functionality. (:pull:`188`) By `James McCreight `_. - New set_options() method on Process and ConservativeProcess to set their initialization options as '_` atrributes. (:pull:`188`) 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. (:pull:`188`) By `James McCreight `_. - Rename many modules to use lower-snake-case names including those in base/, atmoshpere/, and hydrology/ (:pull:`188`) By `James McCreight `_. - NHM "self-driving" tests (:pull:`160`) By `James McCreight `_. - Refactor dependencies for standard pypi installation. (:pull:`164`, :issue:`178`) By `Joseph Hughes `_. .. _whats-new.0.1.1: v0.1.1 (27 April 2023) ---------------------- Initial release.