HSP2, Hydrologic Simulation Program Python (HSPsquared)

HSPsquared or HSP2 is a Python version of Hydrological Simulation Program - FORTRAN (HSPF). Currently it supports the major hydrology modules, and water quality modules are being developed.

Read our wiki for more information on our motivation and goals for HSP2:

• Wiki Home & HSP2 Goals
• About-HSPF
• Why-HSP2?

Project slides (January 2017) also provide helpful background.

HSPsquared is copyrighted 2020 by RESPEC and released under the GNU Affero General Public License.

ANNOUNCEMENT

HSP2 code has been updated to Python 3 in April 2020. Legacy Python 2 code is available in our archivePy2 branch.

Repository Directories

HSP2 contains the hydrology codes converted from HSPF and the main programs to run HSP2.

HSP2notebooks contains tutorials and useful Juptyer Notebooks.

HSP2tools contains supporting software modules such as the code to convert legacy WDM and UCI files to HDF5 files for HSP2, and to provide additional new and legacy capabilities.

docs contains relevant reference documentation.

tests contains unit testing code for testing code conversion (tests/convert/conversion_test.py) and code performance.

Installation Instructions

HSP2 is designed to work with Python 3.6, 3.7 and 3.8.

Follow these steps to install.

1. Install the Anaconda Python Distribution

We recommend installing the latest release of Anaconda Individual Edition. Follow their installation documentation.

2. Clone or Download this HSPsquared repository

From this Github site, click on the green "Code" dropdown button near the upper right. Select to either Open in GitHub Desktop (i.e. git clone) or "Download ZIP". We recommend using GitHub Desktop, to most easily receive updates.

Place your copy of the HSPsquared folder in any convenient location on your computer.

3. Create a Conda Environment for HSP2 Modeling (optional)

Although HSP2 can be run from the default base environment created by Anaconda, it can be helpful to create a leaner custom environment.

We have provided an environment.yml file, which lists all primary dependencies, to help. Create a hsp2_py38 environment either with the Import button on Anaconda Navigator's Environments tab, or use this Conda command in your terminal or console, replacing path/environment.yml with the full file pathway to the environment.yml file in the local cloned repository.

conda env create --file path/environment.yml

To update your environment, either use Anaconda Navigator, or run the following command:

conda env update --file path/environment.yml --prune

or

conda env create --file path/environment.yml --force

NOTE 1: The environment_dev.yml file provides an alternate environment that provides additional capabilities and newer libraries useful to the development team. It is tested to also work with the current HSP2 codebase and will likely serve as a preview of future updates to environment.yml.

NOTE 2: We recommend using JupyterLab to run our tutorial Juptyer Notebooks in the HSP2notebooks folder. The following JupyterLab extensions are useful (but not required):

• jupyter-matplotlib, an interactive widget.
• jupyterlab/toc, Table of Contents.
• qgrid2, for interactive sorting, filtering, and editing DataFrames

4. Add your HSPsquared Path to Anaconda sites-packages

To have access to the HSP2 and HSP2tools modules in your Python environments, it is necessary to have a path to your copy of HSPsquared in Anaconda's sites-packages directory (i.e. something like $HOME/path/to/anaconda/lib/pythonX.X/site-packages or $HOME/path/to/anaconda/lib/site-packages similar).

The easiest way to do this is to use the conda develop command in the console or terminal like this, replacing /path/to/module/ with the full file pathway to the local cloned HSPsquared repository:

conda-develop /path/to/module/

You should now be able to run the Tutorials and create your own Jupyter Notebooks!

Getting Started

We recommend looking over our Understanding HSP2 Tutorial then viewing or interactively running our Introduction to HSP2 notebook.