HEC-HMS is one of the most widely used watershed models available that is also backed by the US Army Corps of Engineers (USACE). HEC-HMS modeling results are written to a USACE developed database called HEC-DSS, which was created in 1979 specifically to store the types of time series outputs that are common with a model like HEC-HMS.

HEC-HMS and HEC-DSS are both Java-based programs, which means library access in Python can be a challenge. Prior to the recent release of the VTools and PyDSS python libraries, access to HEC-DSS from Python required 32-bit Jython with Java, and documentation on writing standalone programs was scarce or nonexistent. I previously put together a standalone program for a personal project, but it required a lot of digging on my part.

VTools and the PyDSS library will be the best tools to use going forward. Parts of the source code for the PyDSS library have not been released, and there is no documentation publicly available for PyDSS (that I could find). This appears to be an internal USACE library at this time, with no public distribution, outside of the VTools website.

This post discusses how you can use these libraries to bring some automation to your HEC-HMS workflow. One note on the application of these libraries. These libraries do not provide access to the input data outside of any input data that is already in HEC-DSS. If you want to manipulate the input data, that will require some parsing of the text files themselves. The primary use case in this blog post is reading output from HEC-HMS as input into other software (such as FLO-2D or TUFLOW).

The first step is to navigate to the VTools website and download and install both the PyDSS and VTools libraries. The requirements are not directly stated in the documentation, but you will need to install dateutil, numpy, and scipy in addition to the PyDSS and VTools libraries.

If you are a Windows user not well-versed in installing python packages, I highly recommend Christoph Gohlke's site to download the individual libraries (wheel files) and use pip or use the Anaconda package manager. For further information on using pip see the following link. You will need to use the 64 bit version of Python in order to use the PyDSS and VTools library.

Once you have the needed libraries installed, you can fire up your editor. We are using a slightly revised version of the pre-installed HEC-HMS example project "castro.hms".

from vtools.datastore.dss.api import *

f = "castro.dss"
ts = dss_retrieve_ts(f, selector='B=SUBBASIN-1 C=FLOW F=RUN:SCS 010YR')

print(ts.data[:10]) # Printing first 10 flow values for Subbasin-1

Print output

[  0.46439999   0.47227398   0.4906736    0.51045662   0.52920479
   0.54762942   0.56458026   0.58034694   0.59522349   0.60863549]

You can also dynamically select data from the dss file based on a list of inputs.

storms = ['002YR', '010YR', '100YR']

for storm in storms:

    selector = 'B=SUBBASIN-1 C=FLOW F=RUN:SCS {0}'.format(storm)
    ts = dss_retrieve_ts(f, selector)

    print(ts.data[:10])

Print output

[0.46439999 0.47227398 0.4906736  0.51045662 0.52920479 0.54762942
 0.56458026 0.58034694 0.59522349 0.60863549]
[0.46439999 0.47995865 0.51584244 0.55439728 0.59095353 0.6268847
 0.65996969 0.69076771 0.71984649 0.74609697]
[0.46439999 0.4919126  0.55499393 0.62274939 0.68700713 0.75017071
 0.80835325 0.86253333 0.91370451 0.95992595]

If you want to dig further into the capabilities of the VTools library and the DSS Retrieve function, you can read through the detailed example under C:\Python27\Lib\site-packages\vtools-1.1.1-py2.7-win64.egg\vtools\datastore\dss\examples.