HSPsquared or HSP2 is a Python version of Hydrological Simulation Program - FORTRAN (HSPF). HSP2 currently supports all HSPF hydrology modules and major 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:
Project slides (January 2017) also provide helpful background.
HSPsquared is copyrighted 2020 by RESPEC and released under the GNU Affero General Public License.
HSP2 contains the hydrology and water quality code modules converted from HSPF, along with 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.
HSP2 is designed to work with Python >3.6 (since April 2020). We recommend Python 3.8. Legacy Python 2 code is available in our archivePy2 branch.
Follow these steps to install.
We recommend installing the latest release of Anaconda Individual Edition. Follow their installation documentation.
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.
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.ymlTo 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 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!
We recommend looking over our Understanding HSP2 Tutorial then viewing or interactively running our Introduction to HSP2 notebook Jupyter Notebook.
We recommend using JupyterLab to run our tutorial Juptyer Notebooks in the HSP2notebooks folder, due to many additional built-in features and extensions. The following JupyterLab extensions are particularly useful: