From d736df556c2fcaa50cab3894ef1c261d4094c362 Mon Sep 17 00:00:00 2001 From: James McCreight Date: Fri, 15 Dec 2023 16:36:14 -0700 Subject: [PATCH] update readme and index one, final?, time --- README.md | 137 +++++++++++++++++++------------------------------- doc/index.rst | 26 +++++----- 2 files changed, 65 insertions(+), 98 deletions(-) diff --git a/README.md b/README.md index 4757f74c..c80ba64a 100644 --- a/README.md +++ b/README.md @@ -20,53 +20,33 @@ **Table of Contents** -- [Purpose](#purpose) +- [About](#about) - [Installation](#installation) -- [Contributing](#contributing) -- [Example Notebooks](#example-notebooks) -- [Overview of Repository Contents](#overview-of-repository-contents) +- [Getting started / Example notebooks](#getting-started--example-notebooks) +- [Community engagement](#community-engagement) - [Disclaimer](#disclaimer) -## Purpose +## About -The purpose of this repository is to refactor and redesign the [PRMS modeling -system](https://www.usgs.gov/software/precipitation-runoff-modeling-system-prms) -while maintaining its functionality. Code modernization is a step towards -unification with [MODFLOW 6 (MF6)](https://github.com/MODFLOW-USGS/modflow6). +Welcome to the pywatershed repository! -The following motivations are taken from our [AGU poster from December -2022](https://agu2022fallmeeting-agu.ipostersessions.com/default.aspx?s=05-E1-C6-40-DF-0D-4D-C7-4E-DE-D2-61-02-05-8F-0A) -which provides additional details on motivations, project status, and current -directions of this project as of approximately January 2023. +Pywatershed is Python package for simulating hydrologic processes motivated by +the need to modernize important, legacy hydrologic models at the USGS, +particularly the +[Precipitation-Runoff Modeling System](https://www.usgs.gov/software/precipitation-runoff-modeling-system-prms) +(PRMS, Markstrom et al., 2015) and its role in +[GSFLOW](https://www.usgs.gov/software/gsflow-coupled-groundwater-and-surface-water-flow-model>) +(Markstrom et al., 2008). +The goal of modernization is to make these legacy models more flexible as process +representations, to support testing of alternative hydrologic process +conceptualizations, and to facilitate the incorporation of cutting edge +modeling techniques and data sources. Pywatershed is a place for experimentation +with software design, process representation, and data fusion in the context +of well-established hydrologic process modeling. -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 +For more information on the goals and status of pywatershed, please see the [pywatershed docs](https://pywatershed.readthedocs.io/). ## Installation @@ -81,7 +61,7 @@ all platforms. The `pywatershed` package is [available on conda-forge](https://anaconda.org/conda-forge/pywatershed). The installation is the quickest way to get up and running by provides only the minimal set of -dependencies (not including jupyter nor all packages needed for running the +dependencies (not including Jupyter nor all packages needed for running the example notebooks, also not suitable for development purposes). We recommend the following installation procedures to get fully-functional @@ -92,7 +72,7 @@ repository before installing `pywatershed` itself. Mamba will be much faster than Ananconda (but the conda command could also be used). If you wish to use the stable release, you will use `main` in place of -`` in the following commands. If you want to follow developemnt, you'll +`` in the following commands. If you want to follow development, you'll use `develop` instead. Without using `git` (directly), you may: @@ -121,67 +101,54 @@ you will also need to activate this environment by name.) We install the `environment_w_jupyter.yml` to provide all known dependencies including those for running the example notebooks. (The `environment.yml` -does not contain jupyter or jupyterlab because this interferes with installation -on WholeTale, see Example Notebooks seection below.) +does not contain Jupyter or JupyterLab because this interferes with installation +on WholeTale, see Getting Started section below.) -## Contributing -See the [developer documentation](./DEVELOPER.md) for instructions on setting up -a development environment. See the [contribution guide](./CONTRIBUTING.md) to -contribute to this project. +## Getting started / Example notebooks -## Example Notebooks +Please note that you can browse the API reference, developer info, and index +in the [pywatershed docs]((https://pywatershed.readthedocs.io/)). But +*the best way to get started with pywatershed is to dive into the example +notebooks*. For introductory example notebooks, look in the [`examples/`](https://github.com/EC-USGS/pywatershed/tree/main/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. +completed in order. Numbered starting at 00, these are meant to be completed +in order. Notebook outputs are not saved in Github. But you can run these +notebooks locally or using WholeTale (an NSF funded project supporting logins +from many institutions, free but sign-up or log-in required) +where the pywatershed environment is all ready to go: [![WholeTale](https://raw.githubusercontent.com/whole-tale/wt-design-docs/master/badges/wholetale-explore.svg)](https://dashboard.wholetale.org) - * [WholeTale container for latest release (main - branch)](https://dashboard.wholetale.org/run/64ae29e8a887f48b9f173678?tab=metadata) - * [WholeTale container for develop - branch](https://dashboard.wholetale.org/run/64ae25c3a887f48b9f1735c8?tab=metadata) + * [Run latest release in WholeTale](https://dashboard.wholetale.org/run/64ae29e8a887f48b9f173678?tab=metadata) + * [Run the develop branch in WholeTale](https://dashboard.wholetale.org/run/64ae25c3a887f48b9f1735c8?tab=metadata) -WholeTale will give you a jupyter-lab running in the root of this +WholeTale will give you a JupyterLab 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 +Non-numbered notebooks in `examples/` cover additional topics. These +notebooks are not yet covered by testing and you may encounter some +issues. In `examples/developer/` there are notebooks of interest to +developers who may want to learn about running the software tests. -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 -``` +## Community engagement + +We value your feedback! Please use [discussions](https://github.com/EC-USGS/pywatershed/discussions) +or [issues](https://github.com/EC-USGS/pywatershed/issues) on Github. +For more in-depth contributions, please start by reading over +the pywatershed +[DEVELOPER.md](https://github.com/EC-USGS/pywatershed/blob/develop/DEVELOPER.md) and +[CONTRIBUTING.md](https://github.com/EC-USGS/pywatershed/blob/develop/CONTRIBUTING.md) +guidelines. + +Thank you for your interest. + ## Disclaimer diff --git a/doc/index.rst b/doc/index.rst index 2060e4a1..7c5f941b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,7 +7,7 @@ pywatershed: A hydrologic model in Python Welcome to the `pywatershed` docs! Pywatershed is Python package for simulating hydrologic processes motivated by -the need to modernize important, legacy hydrologic models at the USGS +the need to modernize important, legacy hydrologic models at the USGS, particularly the `Precipitation-Runoff Modeling System `__ (PRMS, Markstrom et al., 2015) and its role in @@ -18,12 +18,12 @@ representations, to support testing of alternative hydrologic process conceptualizations, and to facilitate the incorporation of cutting edge modeling techniques and data sources. Pywatershed is a place for experimentation with software design, process representation, and data fusion in the context -of well established hydrologic process modeling. +of well-established hydrologic process modeling. The Python language was choosen because it is accessible to a wide audience of potential contributors which will help foster community development and experimentation. A large number of advanced libraries available for Python can -be applied to hdyrologic modeling, including libraries for parallelism, data +also be applied to hdyrologic modeling, including libraries for parallelism, data access and manipulation, and machine learning. Following the conceptual design of PRMS, pywatershed calculates explicit solutions @@ -36,12 +36,12 @@ land use change at temporal scales ranging from days to centuries. Pywatershed enhances PRMS with a new software design that is object-oriented and highly flexible, allowing users to easily run "sub-models", replace process representations, and incorporate new data. There are base classes which manage mass and energy conservation -and the implementation of concrete, process classes follows a self-describing design -which allows for Model class to properly connect hydrologic proecsses based on their -own descriptions of themselves. A variety of input data sources is managed by the +and the implementation of concrete process classes follows a self-describing design +which allows for a Model class to connect hydrologic process classes based on their +descriptions of themselves. A variety of input data sources is managed by the Adapter class which implements subclasses for different sources. The design of -pywatershed is documented in these docs and also deomonstrated by numbered jupyter -notebooks in the `examples/` directory. +pywatershed is documented in these docs and also demonstrated by numbered Jupyter +Notebooks in the `examples/` directory. The flexible structure of pywatershed helps it to couple with other hydrologic models. We can easily one-way couple pywatershed to @@ -56,7 +56,7 @@ sustainable manner that allows individual software components to evolve independ ========================= -Current Version: 1.0.0 +Current version: 1.0.0 ========================= With pywatershed version 1.0.0, we have faithfully reproduced the PRMS process representations used in the USGS `National Hydrolgical Model `__ (NHM, Regan et al., @@ -73,11 +73,11 @@ gridded configurations and cascading flows. We are also working on reservoir representations. ================= -Getting Started +Getting started ================= Please note that you can browse the API reference, developer info, and index using the table of contents on the left. But *the best way to get started -with pywatershed is to dive in to the example notebooks*. +with pywatershed is to dive into the 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. Notebook outputs are not saved in Github. But you can run these notebooks locally or using WholeTale (free but sign-up or log-in required) where the pywatershed environment is all ready to go: @@ -92,10 +92,10 @@ on both `running locally `_ or `using WholeTale `_. ======================== -Community Engagement +Community engagement ======================== We value your feedback! Please use `discussions `_ -or `issues `_ on our Github page. You may also suggest +or `issues `_ on Github. You may also suggest edits to this documentation or open an issue by clicking on the Github Octocat at the top of the page. For more in-depth contributions, please start by reading over the `DEVELOPER.md file `_.