In the previous post, we discussed why automation is essential for modern computational hydraulics. We established that Python provides the foundation, but we need specialized tools to bridge the gap between Python and existing hydraulic modeling engines. In essence, these tools need to understand the input and output file formats of the hydraulic models, and be able to modify the input files and parse the output files.

pyHMT2D is one such tool. It is an open-source Python package developed by myself and can be found on GitHub: https://github.com/psu-efd/pyHMT2D. It has been used in my research for several years. Numerous publications and projects have been built upon it.

In this post, we introduce pyHMT2D—what it is, why it exists, and how it works. Then we walk through practical examples: using pyHMT2D to control runs of HEC-RAS 2D and SRH-2D from Python, and to convert their results to VTK for further analysis and visualization. By the end, you’ll see how pyHMT2D turns manual GUI workflows into scriptable, reproducible pipelines.

What is pyHMT2D?

pyHMT2D is a Python package designed to automate workflows in 2D hydraulic modeling. It provides a programmatic interface to popular hydraulic engines, starting with SRH-2D (from the U.S. Bureau of Reclamation) and HEC-RAS 2D (from the U.S. Army Corps of Engineers). The package is designed to be extensible, so support for additional engines can be added in the future.

At its core, pyHMT2D is designed for:

• Model control: Launch simulations, open/close projects, and run preprocessors from Python
• Result extraction: Parse outputs from different engines (HDF, XMDF, etc.) in a consistent way
• Format conversion: Convert simulation results to VTK and other formats for analysis, visualization, or machine learning
• Batch workflows: Run many scenarios automatically—the foundation for calibration and Monte Carlo (covered in later posts)

Why Develop pyHMT2D?

If you’ve worked with SRH-2D or HEC-RAS 2D, you know they’re powerful tools. But they share a common limitation: they don’t provide official Python APIs.

Reliably automating them from Python requires:

• Understanding each engine’s input file formats (which are often poorly documented)
• Parsing various output formats (ASCII, binary, HDF5, VTK, etc.)
• Managing simulation workflows (error handling, logging, parallel execution)
• Handling engine-specific quirks and version differences

pyHMT2D was developed to provide that layer: same Python patterns whether you’re driving SRH-2D or HEC-RAS 2D, and a path from raw results to VTK (and beyond) for downstream analysis.

Getting Started with pyHMT2D

To get started with pyHMT2D:

• Installation: See the pyHMT2D GitHub repository for installation instructions. I recommend cloning the repo and installing it in development mode with pip install -e . to run the examples.

A Practical Example: Controlling Runs and Converting Results to VTK

The pyHMT2D repository includes example scripts that show how to control a model run and convert results to VTK. We’ll use the Muncie 2D case (a demo created using the data from HEC-RAS) for both engines. The final VTK results from both models are visualized in ParaView and shown in the figure below:

Controlling HEC-RAS 2D from Python

The example lives under examples/HEC_RAS_Model/Muncie2D/. The script demo_HEC_RAS_Model.py does three things: copy the case files (if needed), run HEC-RAS, and convert the output to VTK.

Run control is done via the HEC_RAS_Model class:

import pyHMT2D

# Create a HEC-RAS model instance (version must match your install)
my_hec_ras_model = pyHMT2D.RAS_2D.HEC_RAS_Model(version="6.6", faceless=False)
my_hec_ras_model.init_model()

# Open the project and run
my_hec_ras_model.open_project("Muncie2D.prj")
my_hec_ras_model.run_model()
my_hec_ras_model.close_project()
my_hec_ras_model.exit_model()

No GUI interaction is required—Python opens the project, runs the plan, and closes it. The faceless=False option lets you watch the run in the HEC-RAS window if you want; set it to True for fully headless operation.

Converting HEC-RAS results to VTK uses RAS_2D_Data to read the HDF output and write VTK:

my_ras_2d_data = pyHMT2D.RAS_2D.RAS_2D_Data(
    "Muncie2D.p01.hdf",
    "Terrain/TerrainMuncie_composite.tif"
)
my_ras_2d_data.saveHEC_RAS2D_results_to_VTK(lastTimeStep=True)

The VTK files can then be opened in ParaView, used in custom Python (e.g., VTK or PyVista), or fed into other analysis pipelines.

Controlling SRH-2D from Python

The SRH-2D counterpart is in examples/SRH_2D_Model/. The script demo_SRH_2D_Model.py runs SRH-2D and converts its HDF5 results to VTK.

Run control uses the SRH_2D_Model class. You point it to the SRH-Pre and SRH-2D executables (typically under your SMS installation):

import pyHMT2D

version = "3.7.1"
srh_pre_path = r"C:\Program Files\SMS 13.4 64-bit\python\Lib\site-packages\srh2d_exe\SRH_Pre_Console.exe"
srh_path = r"C:\Program Files\SMS 13.4 64-bit\python\Lib\site-packages\srh2d_exe\SRH-2D_Console.exe"
extra_dll_path = r"C:\Program Files\SMS 13.4 64-bit\python\Lib\site-packages\srh2d_exe"

my_srh_2d_model = pyHMT2D.SRH_2D.SRH_2D_Model(
    version, srh_pre_path, srh_path, extra_dll_path, faceless=False
)
my_srh_2d_model.init_model()

my_srh_2d_model.open_project("Muncie.srhhydro")
my_srh_2d_model.run_pre_model()   # run preprocessor
my_srh_2d_model.run_model()       # run the 2D solver
my_srh_2d_model.close_project()
my_srh_2d_model.exit_model()

Converting SRH-2D results to VTK reads the HDF5 output and exports to VTK:

my_srh_2d_data = pyHMT2D.SRH_2D.SRH_2D_Data("Muncie.srhhydro")
xmdf_file = my_srh_2d_data.get_case_name() + "_XMDFC.h5"
my_srh_2d_data.readSRHXMDFFile(xmdf_file, bNodal=False)
my_srh_2d_data.outputXMDFDataToVTK(bNodal=False, lastTimeStep=True, dir="")

Again, the resulting VTK files are ready for ParaView or any VTK-based analysis.

Why VTK?

Both engines write results in their own formats (HDF for HEC-RAS, XMDF for SRH-2D). VTK is a widely supported format for scientific visualization and analysis. Python has excellent support for VTK, and many other libraries can read and write VTK files. By converting to VTK, pyHMT2D lets you:

• Use the same visualization and analysis tools regardless of which model engine (HEC-RAS 2D or SRH-2D) produced the run
• Feed results into custom Python (e.g., PyVista, VTK) for scripting
• Compare or post-process results from different engines on a common representation

Later posts will build on this: Part 3 uses the same control and result extraction for automated calibration, and Part 4 for Monte Carlo runs. Massive run of simulations can generate data sets for machine learning (ML), which will be covered in a later post.

If you have questions or run into issues, the pyHMT2D repository welcomes contributions and issue reports.

---

This is the second post in a series on automating computational hydraulics modeling. Read the first post to understand why automation matters, or continue to the next post to learn about automated calibration with pyHMT2D. Or go back to the index for the full series.