Overview
This section looks at some highlights of this version. The following section gives a (somewhat redundant though) more detailed change log.
FlowGraph
The primary new capability introduced is the [`FlowGraph`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.FlowGraph.html) and its related classes. The `FlowGraph` allows users to combine different kinds flow solutions on [`FlowNodes`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.FlowNode.html) in arbitrary order. In the figure below, a node of class B is inserted into the original graph. Class B may have a different flow solution than the class A nodes in the original graph, but `FlowGraph` will handle new `FlowNodes` wherever you want to put them. This allows users to mix and match various flow solutions, or introduce new flow solutions at new locations. The figure below links to the `FlowGraph` documentation for further details.
<div style="text-align: center">
<a href="https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.FlowGraph.html">
<img src="https://pywatershed.readthedocs.io/en/latest/_images/flow_graph_schematic_1.png" style="width: 70%" />
</a>
</div>
While `FlowGraph`s may be constructed from scratch, a common use case (demonstrated in a new example notebook,
[06_flow_graph_starfit.ipynb](https://github.com/EC-USGS/pywatershed/blob/develop/examples/06_flow_graph_starfit.ipynb)) is to add a reservoir representation into an existing `FlowGraph` which is equivalent to `PRMSChannel`, using [`PRMSChannelFlowNode`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.PRMSChannelFlowNode.html). The STARFIT reservoir representation is implemented as [`StarfitFlowNode`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.StarfitFlowNode.html) which can be added into the `FlowGraph`. Other `FlowNodes` implemented are [`PassThroughFlowNode`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.PassThroughFlowNode.html) and [`ObsInFlowNode`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.ObsInFlowNode.html). The second reproduces the "obsin" capabilities present in PRMS. Please see the [`FlowGraph` documentation](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.FlowGraph.html) (linked throughout above) for additional details.
Additional PRMS Functionality
- Subclasses of PRMSRunoff, PRMSSoilzone, and PRMSGroundwater are available
which do not include depression storage: PRMSRunoffNoDprst, PRMSSoilzoneNoDprst, and PRMSGroundwaterNoDprst.
- Dunnian flow is implemented in PRMSSoilzone and is 2-way coupled to PRMSRunoff.
- Preferential flow is implemented in PRMSSoilzone.
MmrToMf6Dfw
The [`MmrToMf6Dfw`](https://pywatershed.readthedocs.io/en/latest/api/generated/pywatershed.MmrToMf6Dfw.html) class builds a MF6 1-D channel (CHF) simulation using diffusive wave (DFW) routing from PRMS NHM input files and a few simple assumptions. The lateral (to-channel) fluxes from a PRMS run are used as time varying boundary conditions. A new example notebook ([07_mmr_to_mf6_chf_dfw.ipynb](https://github.com/EC-USGS/pywatershed/blob/develop/examples/07_mmr_to_mf6_chf_dfw.ipynb)) runs the Delaware River Basin using MF6 CFH-DFW based on PRMS input files.
Breaking Changes
The parameter `pref_flow_infil_frac` is now a required parameter input for PRMSSoilzone. The NHM values assumed previously are zeros on all HRUs.
Detailed Change Log
For additional details, see the [What's New Documentation](https://pywatershed.readthedocs.io/en/main/whats-new.html):
New Features
- The [`FlowGraph`](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.FlowGraph.html#pywatershed.FlowGraph) capabilities are introduced. These allow users to combine different kinds flow solutions in arbitrary order on a "flow graph". The accompanying base classes [`FlowNode`](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.FlowNode.html) and [`FlowNodeMaker`](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.FlowNodeMaker.html) are introduced along with their subclasses for modeling [`PassThroughFlowNode`s](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.PassThroughFlowNode.html), [`ObsInFlowNode`s](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.ObsInFlowNode.html) (flow replacement by observations with sink and source tracking in mass balance), [`PRMSChannelFlowNode`s](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.PRMSChannelFlowNode.html), and [`StarfitFlowNode`s](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.StarfitFlowNode.html#pywatershed.StarfitFlowNode). A new example notebook, [examples/06_flow_graph_starfit.ipynb](https://github.com/EC-USGS/pywatershed/blob/develop/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.
- The [`MmrToMf6Dfw`](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.MmrToMf6Dfw.html) 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](https://github.com/EC-USGS/pywatershed/blob/develop/examples/07_mmr_to_mf6_chf_dfw.ipynb).
- 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.
- Dunnian flow is implemented (in PRMSSoilzone) and tested for sagehen_5yr.
- Preferential flow is implemented (in PRMSSoilzone) and tested for sagehen_5yr.
- Control instances have a diff method to compare with other instances.
- Feature to standardize subsetting input data (parameters and forcings) in space and time either from file ([`utils.netcdf_utils.subset_netcdf_file`](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.utils.netcdf_utils.subset_netcdf_file.html)) or in memory ([`utils.netcdf_utils.subset_xr`](https://pywatershed.readthedocs.io/en/main/api/generated/pywatershed.utils.netcdf_utils.subset_xr.html)).
Breaking Changes
- pref_flow_infil_frac now a required parameter input for PRMSSoilzone. The NHM values assumed previously are zeros on all HRUs.
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.
- Fixed calculation of variable dprst_area_open which was not being checked but was affecting no other variables.
- The variable pptmix was incorrectly calculated in certain situations not covered by the NHM configurations.
Internal changes
- Testing system refactor to handle pairs of domains and control files allowing much more flexibility in configuration/control testing.
- 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.
- Tests are now marked as "domain" or "domainless" to avoid redundant runs of domainless tests across test domains.
- 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.
- Migration to Numpy 2.0+.