This code is now being maintained in Bitbucket, here
The Hydrologic Simulation Program–Python (HSP2) watershed model is is a port of the well-established Hydrological Simulation Program - FORTRAN (HSPF), re-coded with modern scientific Python and data formats.
HSP2 (pronouced "HSP-squared") is being developed by an open source team launched and led by RESPEC with internal funding and now in collaboration with LimnoTech and with additional support from the U.S. Army Corps of Engineers, Engineer Research and Development Center (ERDC), Environmental Laboratory.
HSP2 currently supports all HSPF hydrology and detailed water quality modules. Support for specialty modules is currently in progress. See our Release Notes for up-to-date details.
Read our wiki for more information on our motivation and goals for HSP2:
The HSPF Conversion Project slides (January 2017) and the Introduction to HSP2 by Jason Love (RESPEC) video (December 2017) provide additional background on the intial release.
HSPsquared is released under the GNU Affero General Public License (AGPL), copyrighted 2017 by RESPEC.
-
HSP2 contains the hydrology and water quality code modules converted from HSPF, along with the main programs to run HSP2.
-
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.
-
HSP2IO is new in v0.10 and contains an abstracted approach to getting data in and out of HSP2 for flexibility and performance and also to support future automation and model coupling.
- NOTE: With v0.10 the I/O abstraction classes provide an alternate approach to running HSP2. Our plan is to migrate solely using the I/O abstracted methods, but we will maintain both approaches for for several more releases for backward compability.
-
docs contains relevant reference documentation.
-
examples contains examples of how to use HSP2, organized as interactive Juptyer Notebook tutorials.
-
tests contains HSPF use cases, their input files, code to compare HSP2 vs HSPF model outputs (
tests/convert/conversion_test.py), and code to test for performance.
We recommend getting started by:
-
Following our HSP2 Installation Instructions.
-
Opening our interactive HSP2 tutorials in JupyterLab.
HSP2 is designed to work with Python 3.7, 3.8, and 3.9.
We presently recommend Python 3.8.
We provide two options to installing HSP2, yet strongly recommend option 1.
Follow these steps to install using the conda package manager.
We recommend installing the latest release of Anaconda Individual Edition, which includes the conda, a complete Python (and R) data science stack, and the helpful Anaconda Navigator GUI.
- Follow Anaconda Installation documentation.
A lighter-weight alternative is to install Miniconda.
From the HSP2squared Github page, 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.
Although HSP2 can be run from the default base environment created by Anaconda, we recommend creating a custom environment that includes the exact combination of software dependencies that we've in development and testing.
Create the hsp2_py38 environment from our environment.yml file, which lists all primary dependencies, using one of these approaches:
-
Use the Import button on Anaconda Navigator's Environments tab, or
-
Use the following
conda createcommand in your terminal or console, replacingpath/environment.ymlwith the full file pathway to theenvironment.ymlfile 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 --pruneor
conda env create --file path/environment.yml --forceNOTE: 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.
To have access to the HSP2, HSP2tools, and HSP2IO 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!
Follow these steps to install using pip, the Package Installer for Python.
Instructions for downloading Python to your computer based on your operating system can be found in this helpful wiki.
Check to see if pip is installed by running the following in the command line:
pip helpIf you get an error, you will need to install pip. Otherwise, both Python and pip are on your machine.
Follow the instructions in Install with Conda Step 2, above.
We strongly recommend creating custom Python virtual environment for using HSP2, following the venv — Creation of virtual environments package documentation to create and activate a new environment for running HSP2.
Navigate to your copy of the HSPsquared folder on your computer in the command line.
To install from the current local directory using pip:
pip install .The pip installed 'hsp2' command has help created from the function docstrings in HSP2tools/HSP2_CLI.py.
Use the help to learn how to use the model and each sub-command:
hsp2 --helphsp2 import_uci --helphsp2 run --helpIntended workflow from the command line:
hsp2 import_uci import_test.uci new_model.h5
hsp2 run new_model.h5