Jython can be used to run HMS, a Java program, in a "headless" way.

At a minimum you will need HEC-HMS. You might also consider running your script via a batch file or an IDE, in which case you will need an instance of Jython.

A Jython example

An sample python script, compute_current.py, is shown below:

from hms.model import Project
from hms import Hms

myProject = Project.open('C:/Projects/castro/castro.hms')


Running the script via HEC-HMS

This is the easiest way to run a jython script. HEC-HMS uses an embedded python interpreter and takes care of setting the environment. Simply pass your script to HEC-HMS.cmd or HEC-HMS.exe with the -script or -s argument followed by the path to script. For example:

cd /d C:/Programs/HEC-HMS-4.4
hec-hms.cmd -script C:/Projects/castro/scripts/compute_current.py

Running the script via batch

Scripts can also be run via batch file. In this case you will need to set an equivalent environment to HEC-HMS. Batch file, compute_current.bat, is shown below:

set "PATH=C:/Programs/HEC-HMS-4.4-beta.2/bin/gdal;%PATH%"
set "GDAL_DRIVER_PATH=C:/Programs/HEC-HMS-4.4-beta.2/bin/gdal/gdalplugins"
set "GDAL_DATA=C:/Programs/HEC-HMS-4.4-beta.2/gdal/bin/gdal-data"
set "PROJ_LIB=C:/Programs/HEC-HMS-4.4-beta.2/gdal/bin/projlib"

set "CLASSPATH=C:/Projects/hms/HEC-HMS/build/distributions/HEC-HMS-4.4-beta.2/hms.jar;C:/Projects/hms/HEC-HMS/build/distributions/HEC-HMS-4.4-beta.2/lib/*"

C:/jython2.7.1/bin/jython -Djava.library.path="C:/Programs/HEC-HMS-4.4-beta.2/bin;C:/Programs/HEC-HMS-4.4-beta.2/bin/gdal" compute_current.py

Line 1: The path to GDAL binaries prepends the the PATH environment variable. This is probably not necessary unless you are working with the HMR52 storm in the met model. Paths to TauDEM and MPI are not included because we will not be accessing these via scripting.

Lines 2-4: Other GDAL environment variables are configured. These are probably not necessary for most scripting applications.

Line 5: Set the java classpath to include the path to hms.jar and dependent libraries. All of the dependent libraries are located in the distribution lib directory. In this case a wildcard * indicates that all libraries in the lib directory should be added to the classpath.

Line 6: Use the jython executable to execute the script. -Djava.library.path sets the path to native libraries. Paths should include the distribution bin directory, where javaHeclib.dll and WindowsEnvironment.dll reside, as well as the bin/gdal directory where gdal201.dll resides.

Running the script in an IDE

Scripts can also be executed in an integrated development environment (IDE). IDEs provide useful features such as code completion, automated refactoring, and debugging. This example demonstrates using IntelliJ with the Python plugin; Other IDE configurations such as eclipse with the PyDev plugin can be used.

A new project is created called jython-hms-scripts. The file compute_current.py is placed in the project:

The script is compute_current.py, from the code snippet above.

In Project Structure, set the Project SDK to an instance of Jython.

In Project Structure, add hms.jar as a library. You can optionally add the rest of the dependent library jars here.

Create a new run configuration, such as compute_current.

In the run configuration, set environment variables. See notes in the Running a script via batch section. In this case the CLASSPATH environment variable is set to the distribution lib directory. Alternatively you can add each jar explicitly in Project Structure | Libraries.

In the run configuration, set interpreter options to include -Djava.library.path. See notes in the Running a script via batch section.

For the HEC-HMS API reference, see Scripting in the HEC-HMS User's Manual.

Happy scripting!