pywatershed is a Python package for hydrologic modeling
Project description
pywatershed
Table of Contents
Purpose
The purpose of this repository is to refactor and redesign the PRMS modeling system while maintaining its functionality. Code modernization is a step towards unification with MODFLOW 6 (MF6).
The following motivations are taken from our AGU poster from December 2022 which provides additional details on motivations, project status, and current directions of this project as of approximately January 2023.
Goals of the USGS Enterprise Capacity (EC) project include: * A sustainable integrated, hydrologic modeling framework for the U.S. Geological Survey (USGS)
- Interoperable modeling across the USGS, partner agencies, and academia
Goals for EC Watershed Modeling: * Couple the Precipitation-Runoff Modeling System (PRMS, e.g. Regan et al, 2018) with MODFLOW 6 (MF6, e.g. Langevin et al, 2017) in a sustainable way * Redesign PRMS to be more modern and flexible * Prioritize process representations in the current National Hydrological Model (NHM) based on PRMS 5.2.1
Prototype an EC watershed model: "pywatershed" * Redesign PRMS quickly in python
- Couple to MF6 via BMI/XMI interface (Hughes et al, 2021; Hutton et al, 2020) * Establish a prototyping ground for EC codes that couples to the compiled framework: low cost proof of concepts (at the price of potentially less computational performance) * Enable process representation hypothesis testing * Use cutting-edge techniques and technologies to improve models * Machine learning, automatic differentiation * Address challenges of modeling across space and time scales * Transition prototype watershed model to compiled EC code
Installation
To install the software you will need Python 3.9 or 3.10.
We currently recommend dependencies be installed with Mamba which will be much faster than Ananconda (but the conda command can also be used). An environment containing all core and optional dependencies can be created from the project root with:
mamba env create -f environment_w_jupyter.yml
(The environment environment.yml
does not contain jupyter or jupyterlab
in order to not interfere with installation in WholeTale, see Example
Notebooks seection below.)
The pywatershed
package is available on
PyPI. At the moment, the installation
may not be reliable on all platforms and we are working to fix this.
Using PyPI (with the above caveat), pywatershed
can be installed with:
pip install pywatershed
A number of extra dependencies are needed to run the example notebooks. These can be installed with pip with
pip install "pywatershed[optional]"
These installation steps are suitable for pywatershed
end users. See the
developer documentation for detailed instructions on
configuring a development environment.
Contributing
See the developer documentation for instructions on setting up a development environment. See the contribution guide to contribute to this project.
Example Notebooks
For introductory example notebooks, look in the
examples/
directory in the repository. Numbered starting at 00, these are meant to be
completed in order. Non-numbered notebooks coveradditional topics. These
notebooks are note yet covered by testing and so may be expected to have some
issues until they are added to testing. In examples/developer/
there are
notebooks of interest to developers who may want to learn about running the
software tests.
Though no notebook outputs are saved in Github, these notebooks can easily navigated to and run in WholeTale containers (free but sign-up or log-in required). This is a very easy and quick way to get started without needing to install pywatershed requirements yourself. WholeTale is an NSF funded project and supports logins from many institutions, e.g. the USGS, and you may not need to register.
There are containers for both the main
and develop
branches.
WholeTale will give you a jupyter-lab running in the root of this
repository. You can navigate to examples/
and then open and run the notebooks
of your choice. The develop container may require the user to update the
repository (git pull origin
) to stay current with development.
Overview of Repository Contents
The contents of directories at this level is described. Therein you may discover another README.md for more information.
.github/: Github actions, scripts and Python environments for continuous integration (CI) and releasing,
asv_benchmarks/: preformance benchmarking by ASV
autotest/: pywatershed package testing using pytest
autotest_exs/: pywatershed example notebook testing using pytest
bin/:PRMS executables distributed
doc/:Package/code documentation source code
evaluation/: tools for evaluation of pywatershed
examples/:How to use the package, mostly jupyter notebooks
prms_src/:PRMS source used for generating executables in bin/
pywatershed/:Package source
reference/:Ancillary materials for development
resources/:Static stuff like images
test_data/:Data used for automated testing
Disclaimer
This information is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The information has not received final approval by the U.S. Geological Survey (USGS) and is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the information.
From: https://www2.usgs.gov/fsp/fsp_disclaimers.asp#5
This software is in the public domain because it contains materials that originally came from the U.S. Geological Survey, an agency of the United States Department of Interior. For more information, see the official USGS copyright policy
Although this software program has been used by the USGS, no warranty, expressed or implied, is made by the USGS or the U.S. Government as to the accuracy and functioning of the program and related program material nor shall the fact of distribution constitute any such warranty, and no responsibility is assumed by the USGS in connection therewith. This software is provided "AS IS."
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pywatershed-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8448dd16b45077820e1c26a7d1b9837e7e4f3322e1c469867ee8959b0387710e |
|
MD5 | f388fc3a0a52fdb235ff8894e78e31f5 |
|
BLAKE2b-256 | 94e351029f66445e50d44c7035191be27f18d8fbc0cb3497769918452da33793 |