pyHMT2D API

pyHMT2D base classes, constants, and tools

class HydraulicData(name)

Hydraulic data base class

name

name of the hydraulic mode that this data is for, e.g., SRH-2D, HEC-RAS, or just the name of the data set, e.g., terrain, flow

Type:

str

clear_data()

clear the data

init_data()

Initialize the data

modify_ManningsN(materialIDs, newManningsNValues, materialNames)

Modify materialIDs’s Manning’s n values to new values

Parameters:

• materialID (int) – material ID

• newManningsNValue (float) – new Manning’s n value

• materialName (str) – name of the material

reset_data()

Reset the data

class HydraulicModel(name, version)

Hydraulic model base class

name

name of the hydraulic model, e.g., SRH-2D, HEC-RAS

Type:

str

version

version of the hydaulic model, e.g., 3.3, 5.0.7, 6.0

Type:

str

exit_model()

Exit the model

init_model()

Initialize the model

run_model()

Run the model

gMax_Nodes_per_Element

maximum number of nodes for an element

gMax_Elements_per_Node

maximum number of elements for a node

Backwater-1D related classes and tools

Package summary for Backwater-1D:

class Backwater_1D_Data(config_json_file_name)

A class for Backwater-1D data I/O, manipulation, and format conversion

Backwater_1D_Data class constructor

Parameters:

config_json_file_name (str) – name of the JSON configuration file

build_ManningNFunc()

Define the Manning’s n interpolation function based on the Manning’s n zone information

load_configuration_data()

Load only the configuration data (not result) from the JSON file

modify_ManningsN(materialIDs, newManningsNValues, materialNames)

Modify materialID’s Manning’s n value to new value

Parameters:

• materialIDs (list) – material ID list

• newManningsNValues (list) – new Manning’s n value list

• ManningN_MaterialNames (list) – name of materials list

outputResultToVTK(dir='')

Output result data to vtkUnstructuredGrid

This has to be called after the result has been obtained by running the model

Parameters:

dir (str, optional) – directory to write to

Returns:

vtkFileName – name of the output vTK file

Return type:

str

write_configuration_data_to_JSON(json_file_name)

Write the configuration data only (not result) to JSON file

Parameters:

json_file_name (str) – name of the JSON file to write to

class Backwater_1D_Model

Simple 1D backwater curve model .

This model only works for subcritical flows!!! It does not work critical flows or transcritical flows.

Attributes:

SRH_2D_Model constructor

get_simulation_case()

Get the simulation case

init_model()

Initialize Backwater-1D model

run_model()

Run the Backwater-1D model

It will run the current Backwater-1D case.

set_simulation_case(backwater_1d_data)

Set the simulation case to backwater_1D_data (if it has been created already)

Parameters:

backwater_1d_data (Backwater_1D_Data) – an object from class Backwater_1D_Data, which should be created before calling

SRH-2D related classes and tools

Package summary for SRH-2D:

class SRH_2D_Data(srhcontrol_filename)

A class for SRH-2D data I/O, manipulation, and format conversion

This class is designed to read SRH-2D results in format other than VTK. It can save SRH-2D results into VTK format for visualization in Paraview, parse SRH-2D mesh information and convert/save to other formats, query SRH-2D results (e.g., for post-processing or analysis), etc.

Between srhdryo and srhsif, only one of them is needed depending on the type of the input file.

hdf_filename

The name for the HDF result file generated by HEC-RAS

Type:

str

srhhydro_obj

An object to hold information in the SRHHYDRO file

Type:

SRH_2D_SRHHydro

srhsif_obj

An object to hold information in the SIF file

Type:

SRH_2D_SIF

srhgeom_obj

An object to hold information in the SRHGEOM file

Type:

SRH_2D_SRHGeom

srhmat_obj

An object to hold information in the SRHMAT file

Type:

SRH_2D_SRHMat

Constructor for SRH_2D_Data

srhgeom_filename and srhmat_filename are contained in the SRHHydro or SRH-2D SIF file.

Parameters:

srhcontrol_filename (str) – Name of the SRH-2D control file: either SRHHydro or SIF file

buildManningN_cells_nodes()

Build Manning’s n values at cell centers and nodes

This calculation is based on the srhhydro and srhgeom files, not interpolation from a GeoTiff file. This is the Manning’s n value used by SRH-2D.

cell_center_to_vertex(cell_data, vertex_data)

Interpolate result from cell center to vertex

Not implemented yet.

get_ManningN_dict()

Get the Manning’s n dictionary from the SRH-2D control file

get_case_name()

Get the “Case” name for this current case (“Case” in srhhyro file)

Returns:

case_name – Case name

Return type:

str

get_output_format_unit()

Get the format and unit of the output

modify_ExitH(exit_h_bc_IDs, new_exit_h_values)

Modify the exit water surface elevation for the specified boundary IDs

Parameters:

• exit_h_bc_IDs (list) – list of exit water surface elevation boundary IDs

• new_exit_h_values (list) – list of new exit water surface elevation values

modify_InletQ(inlet_q_bc_IDs, new_inlet_q_values)

Modify the inlet flow rate for the specified boundary IDs

Parameters:

• inlet_q_bc_IDs (list) – list of inlet flow rate boundary IDs

• new_inlet_q_values (list) – list of new inlet flow rate values

modify_ManningsNs(materialIDs, newManningsNValues, materialNames)

Modify the Manning’s n value for the specified material IDs

Parameters:

• materialIDs (list) – list of material IDs

• newManningsNValues (list) – list of new Manning’s n values

• materialNames (list) – list of material names

outputSRHCDataToVTK(timeStep=-1, lastTimeStep=False, dir='')

Output SRHC data to VTK format

Parameters:

• timeStep (int) – Specific timestep to output (-1 for all timesteps)

• lastTimeStep (bool) – Only output last timestep if True

• dir (str) – Output directory

outputVTK(vtkFileName, resultVarNames, resultData, bNodal)

Output result to VTK file

The supplied resultVarNames and resultData should be compatible with the mesh. If resultVarNames is empty, it only outputs the mesh with no data.

Parameters:

• vtkFileName (str) – name for the output vtk file

• resultVarNames (str) – result variable names

• resultData (numpy.ndarray) – 2D array containing result data

• bNodal (bool) – whether the data is nodal (True) or at cell center (False)

outputXMDFDataToPINNData(bNodal, PINN_normalization_specs, bBoundary=False, dir='')

Output XMDF result data to PINN data files - data_points.npy: rows of (x, y) coordinates of the points for steady state data (currently only support one time step) - data_values.npy: rows of (h, u, v) values of the solution variables at the points in data_points.npy - data_flags.npy: rows of flags for the points in data_points.npy (h_flag, u_flag, v_flag) - all_data_points_stats.pny: statistics of the data points (min, max, mean, std, etc.)

This has to be called after the XMDF data have been loaded by calling readSRHXMDFFile(…).

Parameters:

• bNodal (bool) – whether export nodal data or cell center data. Currently, it can’t output both.

• (dict) (PINN_normalization_specs)

• bBoundary (bool) – whether export boundary data

• dir (str, optional) – directory to write to

Return type:

None

outputXMDFDataToVTK(bNodal, timeStep=-1, lastTimeStep=False, dir='')

Output XMDF result data to VTK

This has to be called after the XMDF data have been loaded by calling readSRHXMDFFile(…).

Parameters:

• bNodal (bool) – whether export nodal data or cell center data. Currently, it can’t output both.

• timeStep (int) – optionly only the specified time step will be saved

• lastTimeStep (bool) – optionally specify only the last time step

• dir (str, optional) – directory to write to

Returns:

vtkFileNameList – a list of vtkFileName (for each time step)

Return type:

list

output_2d_mesh_to_vtk(meshVTKFileName, bFlat=False, dir='')

output the flat mesh to vtk

Parameters:

• meshVTKFileName (str) – file name for the mesh

• bFlat (bool) – whether to make the 2d mesh flat (node’s z coordinate -> 0)

• dir (str, optional) – directory to write to

output_boundary_manning_n_profile(nodeStringID, nodeStringFileName, dir='')

Output Manning’s n profile for a specified boundary

Parameters:

• nodeStringID (int) – nodeString ID of specified boundary

• nodeStringFileName (str) – name of output file

• dir (str, optional) – directory for the output file

readOneSRHFile(srhFileName)

Read one single SRH-2D result file in SRHC (cell center) or SRH (point) format.

Note: SRH-2D outputs an extra “,” to each line. As a result, Numpy’s genfromtext(…) function adds a column of “nan” to the end. Need to take care of this.

Parameters:

srhFileName (str) – file name for the SRH result file

readSRHCFiles(case_name)

Read SRH-2D results from SRHC files (cell-centered data)

Parameters:

case_name (str) – Base filename without _SIF.dat extension

readSRHXMDFFile(xmdfFileName, bNodal)

Read SRH-2D result file in XMDF format. The XMDF file can be either nodal or cell center. It also contains results from multiple time steps.

Parameters:

• xmdfFileName (str) – file name for the XMDF data

• bNodal (bool) – whether it is nodal (True) or at cell center (False)

readTECFile(tecFileName)

Read SRH-2D results in Tecplot format

Parameters:

tecFileName (str) – Tecplot file name

vertex_to_cell_center(vertex_data, cell_data)

Interpolate result from vertex to cell center

Not implemented yet.

class SRH_2D_Model(version, srh_pre_path, srh_path, extra_dll_path, faceless=False)

SRH-2D Model which can control simulation runs.

SRH_2D_Model controls the run of SRH-2D. A case can be loaded and executed. Currently SRH_2D_Model has very limited capability to modify geometry, mesh, and flow data. One of the main use scenarios is for Monte Carlo or batch simulations.

_faceless

bool whether show the SRH-2D window when it is running

_srh_path

str path to the SRH_2D program (e.g., srh_2d.exe depending on the version of SRH-2D and the operating system)

_srh_pre_path

str path to the SRH_2D preprocessing program (e.g., srh_2d_pre.exe depending on the version of SRH-2D and the operating system)

_extra_dll_path

str path for library Dlls, such as XMDL, zlib, hdf5, and msvcr used by SRH-2D (only relevant for Windows).

_srh_2d_data

SRH_2D_Data a SRH_2D_Data object to hold the simulation case data.

SRH_2D_Model constructor

Parameters:

• version (str) – version number of SRH-2D

• srh_pre_path (str) – path to the SRH_2D preprocessing program (e.g., srh_2d_pre.exe depending on the version)

• srh_path (str) – path to the SRH_2D program (e.g., srh_2d.exe depending on the version)

• extra_dll_path (str) – path for library Dlls, such as XMDL, zlib, hdf5, and msvcr used by SRH-2D

• faceless (bool, optional) – whether show the SRH-2D window when it is running

close_project()

Close the opened SRH-2D project (if any)

It will set _srh_2d_data to None.

exit_model()

Exit the model (SRH-2D specific)

get_simulation_case()

Get the simulation case to srh_2D_data

Returns:

srh_2d_data – an object from class SRH_2D_Data, which should be created before calling

Return type:

SRH_2D_Data

init_model()

Initialize SRH-2D model

It will check the existance of SRH-2D executable files and add extra DLL path to the system PATH environment (only relevant for Windows).

open_project(srhcontrol_filename)

Open a SRH-2D project with the specified srhcontrol file which can be a srhhydro or SIF file

A SRH_2D_Data object will be created to hold the project information.

Parameters:

srhcontrol_filename (str) – name of the srhcontrol file which can be a srhhydro or SIF file

run_model(sleepTime=10.0, bShowProgress=True)

Run the SRH-2D model

It will run the current SRH-2D project (case) and show a progress bar. The case has to be created before with open_project(…) or set_simulation_case().

Parameters:

• sleepTime – float sleep time between each check on the progress

• bShowProgress – bool whether show the progress bar

run_pre_model()

Run SRH-2D Pre to preprocess the simulation case

Run SRH-2D’s preprocessing step for current case.

set_simulation_case(srh_2d_data)

Set the simulation case to srh_2D_data (if it has been created already)

Parameters:

srh_2d_data (SRH_2D_Data) – an object from class SRH_2D_Data, which should be created before calling

class SRH_2D_SIF(srhsif_filename)

Class to parse and manage SRH-2D SIF (Simulation Input File) data

Initialize SIF parser with srhsif_filename

get_ManningN_dict()

Return Manning’s n values

get_flow_obstructions()

Return flow obstructions specifications

get_intermediate_output()

Return intermediate output control settings

get_output_format()

Return output format and unit

get_pressurized_zones()

Return pressurized zones specifications

get_simulation_start_end_time()

Return simulation start and end time

get_simulation_time_step_size()

Return simulation time step size

get_wall_roughness()

Return wall roughness specifications

modify_ExitH(bcIDs, newExitHValues)

Modify the exit water surface elevation for the specified boundary IDs

Parameters:

• bcIDs (list) – list of boundary IDs

• newExitHValues (list) – list of new exit water surface elevation values

modify_InletQ(bcIDs, newInletQValues)

Modify the inlet flow rate for the specified boundary IDs

Parameters:

• bcIDs (list) – list of boundary IDs

• newInletQValues (list) – list of new inlet flow rate values

modify_ManningsN(materialIDs, newManningsNValues, ManningN_MaterialNames)

Modify materialID’s Manning’s n values to new values for a given list of material IDs

Parameters:

• materialIDs (list) – material ID list

• newManningsNValues (list) – new Manning’s n value list

• ManningN_MaterialNames (list) – name of materials list

modify_one_manning_n_in_srhsif_content(material_id, new_manning_n)

Modify one Manning’s n value for a specific material ID in self.srhsif_content

save_as(srhsif_filename=None)

Save the current data in self.srhsif_content back to a SIF file

So to modify a SIF file, one needs to change the data in self.srhsif_content, and then call this function to save the data back to the SIF file.

Parameters:

srhsif_filename (str, optional) – The filename to save the SIF file to. If not provided, the filename will be the same as the original filename.

set_intermediate_output(value, output_type='interval')

Set intermediate output control

Parameters:

• value – float or list of floats

• output_type – ‘interval’ or ‘list’

set_output_format(format_type, unit='EN', stl_face=False)

Set output format and unit

set_wall_roughness(values)

Set wall roughness specifications

class SRH_2D_SRHGeom(srhgeom_filename, bcDict)

A class to handle srhgeom file for SRH-2D

Notes

1. In SMS (SRH-2D), monitoring lines (ML) and monitoring points (MP) are treated separately and differently. ML is created in the same way as boundary lines. Nodes closest to the line are recorded as a NodeString in SRHGEOM file. MP is created as a feature point and its coordinates are recorded in the “srhmpoint” file. Interpolation is done to probe the results at MPs.

   This potentially have some drawbacks:

   1. The MLs and MPs have to be defined before the simulation is run, not afterwards. One can use plot over a line or point, but it is not convenient and it is limited. For example, to calculate flow over a line, one has to cut a line and then integrate.

   2. The way MLs are defined if slightly limited by the mesh (node locations). To be exactly at a ML, one has to interpolate the simulated solution to the points on MLs.

2. Because BC and ML are mixed together, we need to separate them. However, this can only be done with the BC information in the srhhydro file. That is why we need to pass in bcDict in the constructor.

Constructor for SRH_2D_SRHGeom

Parameters:

• srhgeom_filename (str) – Name of the SRHGeom file

• bcDict (dict) – Boundary condtion dictionary

buildEdgesAndBoundaryEdges()

Build edges and boundaryEdges dictionaries

buildNodeElements()

Build node’s element list for all nodes

calculate_bed_slope()

Calculate the bed slope of each element and then interpolate the bed slope to each node. The slope of each element (e.g., triangle and quadrilateral) is calculated by using the Gauss theorem. For each element, the bed slope is calculated by: 1. compute the outward normal vector of each edge of the element. 2. interpolate the bed elevation at the center of each edge of the element from the the two points of the edge. 3. use the Gauss theorem to calculate the bed slope of the element: S = -(1/A) * int_{partial A} z * n * ds, where A is the area of the element,

z is the bed elevation, n is the outward normal vector, and ds is the length of the edge.

4. interpolate the bed slope of the element to each node of the element.

extrude_to_3D(layerHeights, mshFileName, bTerrainFollowing=False, dir='')

Extrude the 2D mesh to 3D with layers

When extruded: node -> line, edge -> face, 2D element-> volume, boundary line -> boundary face

The extruded mesh is written to a GMSH MSH file. Tried MSH version 4. But it seems too complicated (entities etc.). They are not necessary for our purpose. Therefore, we will stick with version 2 and OpenFOAM takes this version well.

Ref: https://gmsh.info/doc/texinfo/gmsh.html#MSH-file-format-version-2-_0028Legacy_0029

Parameters:

• layerHeights (list) – a list with strictly increasing heights for the layers. If bTerrainFollowing is True, only the last value is used as the top elevation.

• mshFileName (str) – name of the GMSH MSH file to be written

• bTerrainFollowing (bool) – whether to follow the terrain. If False, the bottom will be at z = 0, and the layer heights are specified in layerHeights. If True, the bottom will key the terrain elevation, the top will be at layerHeights[-1] and interpolation inbetween.

getNumOfElementsNodes()

Get the number of elements and nodes in srhgeom mesh file

Returns

output_2d_mesh_to_vtk(meshVTKFileName, bFlat=False, dir='')

output the 2D mesh to vtk

Parameters:

• meshVTKFileName (str) – VTK file name for the mesh

• bFlat (bool, optional) – whether to make a flat mesh (z=0)

• dir (str, optional) – directory to write the VTK file to

output_as_gmsh(gmshFileName, dir='')

Output SRH-2D mesh in GMESH format

Not implemented yet.

Parameters:

• gmshFileName (str) – GMSH MSH file name to write to

• dir (str, optional) – directory name to write to

output_nodeString_line_coordinates(nodeStringID, nodeStringFileName, dir='')

Output the nodeString line coordinates into a text file

Parameters:

• nodeStringID (int) – the ID of the nodeString to be written out

• nodeStringFileName (str) – the name of the file to be written to

• dir (str, optional) – directory to write the output file to

readSRHGEOMFile()

Get mesh information by reading the srhgeom file

save_as(newSrhgeomFileName, dir='')

Save as a srhgeom file.

It can be used to save to a new srhgeom file after things have been modified, e.g., bathymetry

class SRH_2D_SRHHydro(srhhydro_filename)

A class to handle srhhydro file for SRH-2D

srhhydro_filename

name for the srhhydro file

Type:

str

srhhydro_content

a dictionary to hold all information in the srhhydro file

Type:

dictionary

Methods

Constructor for SRH_2D_SRHHydro

The SRH_2D_SRHHydro file contains all information for a SRH-2D run.

Parameters:

srhhydro_filename (str) – The name of the SRHHydro file

get_BC()

Get boundary condition dictionary.

get_ExitH()

Get ExitH dictionary:

get_InletQ()

Get InletQ dictionary:

get_ManningN_dict()

Get the dictionary for Manning’s n

get_grid_file_name()

Get grid file name (should be like “xxx.srhgeom”)

Returns:

value – Name of the grid file

Return type:

str

get_mat_file_name()

Get material file name (should be like “xxx.srhmat”)

Returns:

value – Name of the material file

Return type:

str

get_pressure_overtop(nodestring_id=None)

Get pressure overtop parameters

Parameters:

nodestring_id – Optional nodestring ID. If None, returns all parameters

Returns:

Pressure overtop parameters

Return type:

dict

get_pressure_weir_params(nodestring_id=None)

Get pressure weir parameters

Parameters:

nodestring_id – Optional nodestring ID. If None, returns all parameters

Returns:

Pressure weir parameters

Return type:

dict

get_simulation_start_end_time()

Get the start and end time of simulation (in hours, from the “SimTime” entry)

Returns:

• startTime (float) – start time in hours

• endTime (float) – end time in hours

get_simulation_time_step_size()

Get the time step size of simulation (in seconds, from the “SimTime” entry)

Returns:

deltaT – time step size in seconds

Return type:

float

modify_Case_Name(newCaseName)

Modify grid file name

Parameters:

newCaseName (str) – new case name

modify_ExitH(bcIDs, newExitHValues)

Modify bcID’s ExitH value to new value.

Currently only constant WSE is supported.

Parameters:

• bcIDs (list) – bc ID list

• newExitHValues (list) – new ExitH value list

modify_Grid_FileName(newGridFileName)

Modify grid file name

Parameters:

newGridFileName (str) – new grid file name

modify_HydroMat_FileName(newHydroMatFileName)

Modify grid file name

Parameters:

newHydroMatFileName (str) – new HydroMat file name

modify_InletQ(bcIDs, newInletQValues)

Modify bcID’s InletQ value to new value.

Currently only constant inlet flow is supported.

Parameters:

• bcIDs (list) – bc ID list

• newInletQValues (list) – new InletQ value list

modify_ManningsN(materialIDs, newManningsNValues, ManningN_MaterialNames)

Modify materialID’s Manning’s n value to new value

Parameters:

• materialIDs (list) – material ID list

• newManningsNValues (list) – new Manning’s n value list

• ManningN_MaterialNames (list) – name of materials list

parse_srhhydro_file()

Parse the SRHHydro file

save_as(new_srhhydro_file_name=None)

Save as a new SRHHydro file (useful for modification of the SRHHydro file)

Parameters:

new_srhhydro_file_name (str) – name of the new srhhydro file. If not provided, the original filename will be used.

class SRH_2D_SRHMat(srhmat_filename)

A class to handle srhmat file for SRH-2D

srhmat_filename

name of the srhmat file

Type:

str

numOfMaterials

number of materials defined in the srhmat file

Type:

int

matZoneCells

each material zone’s cell list (in a dictionary: material zone ID and cell list)

Type:

dict

Methods

SRH_2D_SRHMat constructor from a srhmat file

Parameters:

srhmat_filename (str) – name of the srhmat file

buildMaterialZonesData()

Build the data for material zones from reading the srhmat file

find_cell_material_ID(cellID)

Given a cell ID, find its material (Manning’s n) ID

Parameters:

cellID (int) – cell ID to find material ID for

save_as(new_srhmat_file_name)

Save as a new SRHMat file (useful for modification of the SRHMAT file)

Parameters:

new_srhmat_file_name (str) – name of the new srhmat file

HEC-RAS related classes and tools

Package summary for RAS-2D:

class HEC_RAS_Geometry(geom_id, geom_file, project)

Data for a HEC-RAS geometry (.g## file and .g##.hdf file).

The .g##.hdf file (geometry HDF) is created by HEC-RAS after geometry preprocessing and may not exist if preprocessing has not been run. This class reads the geometry HDF lazily (only when needed).

Parameters:

• geom_id (str) – Geometry short ID, e.g. ‘g02’.

• geom_file (str) – Absolute path to the .g## text file.

• project (HEC_RAS_Project) – Back-reference to the owning project.

hdf_exists()

Return True if the geometry HDF file exists.

property terrain_hdf_file

Absolute path to the RASMapper terrain HDF file.

property terrain_tiff_file

Absolute path to the terrain GeoTIFF file, resolved via fallback chain.

class HEC_RAS_Model(version, faceless=False)

HEC-RAS Model class

HEC-RAS Model controls the run of HEC-RAS. A plan can be loaded and executed. Currently HEC_RAS_Model has very limited capability to modify HEC-RAS project, plan, geometry, and flow data. It is mainly used for Monte Carlo or batch simulations.

_faceless

bool whether show the HEC-RAS GUI

_ras_path

str path to the HEC-RAS program (Ras.exe)

_RASController

object RASController

_project_file_name

str HEC-RAS project name (including the full path)

_project

HEC_RAS_Project HEC_RAS_Project object corresponding to current project

HEC_RAS_Model constructor

Parameters:

• version (str) – HEC-RAS version

• faceless (bool, optional) – whether to run HEC-RAS without GUI

close_project()

Close the current project (if any)

exit_model()

Exit the model (HEC-RAS specific)

get_current_planFile()

Return the current plan file path.

get_current_project()

Return the current HEC_RAS_Project.

get_plan_names(IncludeOnlyPlansInBaseDirectory)

Get the list of plan names in the current project

Based on this COM object function: Plan_Names(self, PlanCount=defaultNamedNotOptArg, PlanNames=defaultNamedNotOptArg, IncludeOnlyPlansInBaseDirectory=defaultNamedNotOptArg)

Parameters:

IncludeOnlyPlansInBaseDirectory (bool) – whether only include plans in the base directory

Returns:

• PlanCount (int) – number of plans in the current project

• PlanNames (list) – a list of plan names in the current project

get_simulation_case(bReload=False)

Return the RAS_2D_Data for the current plan, loading if necessary.

Parameters:

bReload (bool, optional) – If True, reload results from the HDF file even if already loaded.

Return type:

RAS_2D_Data

init_model()

Initialize a HEC-RAS instance

load_current_plan_results(terrain_file=None)

Load simulation results for the current plan.

Parameters:

terrain_file (str, optional) – Path to a GeoTIFF terrain file. Passed to plan.load_results(). If None, terrain is auto-detected from the geometry HDF and rasmap.

Return type:

RAS_2D_Data

open_project(projectFileName)

Open the specified HEC-RAS project.

Parses the project file structure and opens the project via the COM interface. The returned HEC_RAS_Project can also be created without COM for post-processing-only workflows.

Parameters:

projectFileName (str) – Path to the HEC-RAS project file (.prj).

Returns:

The parsed project object.

Return type:

HEC_RAS_Project

run_model()

Run the HEC-RAS model

A project and a plan have to be defined and selected before the run.

save_project()

Save the current project

set_current_plan(plan_id_or_name)

Set the current plan by short ID (e.g. ‘p03’) or plan title.

Parameters:

plan_id_or_name (str) – Plan short ID (e.g. ‘p03’) or plan title string.

class HEC_RAS_Plan(plan_id, plan_file, project)

Data for a HEC-RAS plan (.p## file).

Each plan owns a RAS_2D_Data object (populated lazily via load_results()).

Parameters:

• plan_id (str) – Plan short ID, e.g. ‘p03’.

• plan_file (str) – Absolute path to the .p## text file.

• project (HEC_RAS_Project) – Back-reference to the owning project.

property geometry

Return the HEC_RAS_Geometry object associated with this plan.

hdf_exists()

Return True if the plan result HDF file exists.

load_results(terrain_file=None)

Load plan simulation results into ras_2d_data.

Parameters:

terrain_file (str, optional) – Path to a GeoTIFF terrain file. Overrides auto-detection from the geometry HDF and rasmap. Required only if auto-detection fails.

Returns:

The loaded data object (also stored as self.ras_2d_data).

Return type:

RAS_2D_Data

class HEC_RAS_Project(prj_file)

HEC-RAS project class — parses .prj and .rasmap files.

Can be used standalone (no COM / HEC-RAS installation required) for post-processing simulation results.

Typical usage (post-processing only):

project = HEC_RAS_Project("Muncie.prj")
plan    = project.get_plan("p03")      # by ID or title
data    = plan.load_results()           # terrain auto-detected
data.saveHEC_RAS2D_results_to_VTK(...)

When running simulations use HEC_RAS_Model (which extends this via composition and adds COM control).

Parameters:

prj_file (str) – Path to the HEC-RAS project file (.prj).

property current_plan

Return the current plan as an HEC_RAS_Plan object.

get_plan(plan_id_or_name)

Get a plan by short ID (e.g. ‘p03’) or by plan title.

Parameters:

plan_id_or_name (str) – Plan short ID or plan title string.

Return type:

HEC_RAS_Plan

set_current_plan_id(plan_id)

Set current plan by short ID.

class HEC_RAS_RASMapper(rasmap_file)

Parses a HEC-RAS .rasmap XML file to discover available terrain and land cover layers.

get_first_terrain()

Return first terrain entry (document order), or None if no terrains defined.

class HEC_RAS_SteadyFlow(flow_id, flow_file, project)

Data for a HEC-RAS steady flow (.f## file).

class HEC_RAS_UnsteadyFlow(flow_id, flow_file, project)

Data for a HEC-RAS unsteady flow (.u## file).

Note: DSS (HEC Data Storage System) support for reading/writing boundary condition time series is a planned future feature.

class RAS_2D_Data(plan, terrain_file=None)

A class for HEC-RAS 2D data I/O, manipulation, and format conversion

This class is designed to read HEC-RAS results in HDF format. It can save RAS2D results into VTK format for visualization in Paraview, parse RAS2D mesh information and convert/save to SRH-2D format, query RAS2D results (e.g., for post-processing or analysis), etc.

In HEC-RAS, one plan corresponds to one HDF file. So essentially, this class is designed to read one HDF file (one plan results).

hdf_filename

the name for the HDF result file generated by HEC-RAS.

Type:

str

plan_filename

the name for the HEC-RAS run plan file

Type:

str

plan_name

the name of the HEC-RAS run plan

Type:

str

plan_shortID

the short name of the run, called “Short Identifier” in HEC-RAS

Type:

str

project_filename

the name of the HEC-RAS project file

Type:

str

geometry_file_name

the name of the HEC-RAS geometry file

Type:

str

RAS_2D_Data class constructor

Parameters:

• plan (HEC_RAS_Plan) –

  The HEC-RAS plan object. Must have:

  • plan.hdf_file : str (path to plan result HDF)

  • plan.geometry : HEC_RAS_Geometry (geometry object)

  • plan.geometry.terrain_tiff_file : str or None

• terrain_file (str, optional) – Path to a GeoTIFF terrain file. Overrides auto-detection from the geometry HDF. Pass this when auto-detection fails or to use a different terrain than the one stored in the project.

build2DAreaBoundaries()

Build boundaries with their point list

build2DAreaCellFaceList()

Build cell’s face list

build2DAreaFaceHydraulicInformation()

For 2D flow area, build face hydraulic information table (face area elevation)

build2DAreaFacePointCoordinatesList()

Build face point coordinates list

build2DAreaFaceProfile()

Build face profile

Face profile in HEC-RAS represents the sub-grid terrain.

build2DInterpolatorFromGeoTiff(geoTiffFileName)

Build 2D interpolator for from geoTiff file, e.g., terrain and Manning n ID, using Python interpolate.interp2d

Assume the data is in band 1.

This method is too slow (use with caution if the case is large).

geoTiffFileName

name for the geoTiff file

Type:

str

build2DManningNZones()

Build 2D flow area’s Manning n zones from the land cover (Manning’s n) HDF file

Assume that there is “Land Cover Filename” and “Land Cover Layername” in the result HDF file. If they don’t exist (mostly for the case that the whole domain uses the default, constant Manning’s n value in [“Geometry”][“2D Flow Areas”][0][1]), just use that constant.

buildCellManningNFromGeoTiffHDF()

Build 2D flow area cell’s Manning n value from HEC-RAS’s GeoTiff and HDF files for Manning n.

This method is more accurate than interpolateManningN_face_to_cell(), which uses a face to cell interpolation.

Also need to consider the case where the “Land Cover Filename” is empty and the whole domain uses the default constant Manning’s n.

buildFace_FacePoints()

Build face’s facepoint list

change_ManningsN(materialIDs, newManningsNValues, materialNames)

Change materialID’s Mannings n values to new values and save to file (for HEC-RAS v5, v6.1.0, and v6.6)

Parameters:

• materialIDs

• newManningsNValues

• materialNames

change_ManningsN_v60(materialIDs, newManningsNValues, materialNames)

Change materialID’s Mannings n values to new values and save to file (for HEC-RAS v6.0.0)

Parameters:

• materialIDs

• newManningsNValues

• materialNames

change_ManningsN_v66(materialIDs, newManningsNValues, materialNames)

Change materialID’s Mannings n values to new values and save to file (for HEC-RAS v6.6)

Parameters:

• materialIDs

• newManningsNValues

• materialNames

change_PorosityDrag_b_Coefficient_v66(materialIDs, newPorosityDrag_b_Coefficients, materialNames)

Change materialID’s PorosityDrag_b_Coefficient values to new values and save to file (for HEC-RAS v6.6)

Parameters:

• materialIDs

• newManningsNValues

• materialNames

dump_all_data()

Dump all data to screen (for debugging purpose)

exportBoundariesToVTK(boundaryVTKFileName, dir='', twoDAreaNumber=0)

Export boundaries of 2D area to VTK (for visual inspection in Paraview and check the ID of NodeString)

Parameters:

• boundaryVTKFileName (str) – name of the VTK file for output

• twoDAreaNumber (int, optional) – 2D flow area number (default is 0)

exportFaceProfilesToVTK(faceProfileVTKFileName, dir='', twoDAreaNumber=0)

Export face profile of 2D area to VTK (for visual inspection in Paraview)

Parameters:

• faceProfileVTKFileName (str) – name of VTK file to write to

• dir (str, optional) – directory to write to

• twoDAreaNumber (int, optional) – 2D flow area number (default is 0)

exportSRHGEOMFile(srhgeomFileName, twoDAreaNumber=0)

Export srhgeom file

Parameters:

• srhgeomFileName (str) – name of the srhgeom file

• twoDAreaNumber (int, optional) – 2D flow area number (default = 0)

exportSRHMATFile(srhmatFileName, twoDAreaNumber=0)

Export the SRHMAT file

Parameters:

• srhmatFileName (str) – name of the srhmat file to write to

• twoDAreaNumber (int, optional) – 2D flow area number (default = 0)

extract_geometry_file_name_from_hdf_file()

Extract the geometry file name from the HDF file

The “Geometry Filename” attribute stored by HEC-RAS may be:

• an absolute path from the original machine (invalid after the project folder is moved), or

• a bare filename with no directory component.

In either case, resolve it to the directory that contains the plan result HDF file so that helper functions (e.g. extract_terrain_file_names) can open the geometry HDF regardless of the current working directory.

extract_plan_information_from_hdf_file()

Extract the plan information from the HDF file

extract_start_end_time()

Extract the start_time and end_time from the plan file

extract_units()

Extract the units used in the HEC-RAS project

Units used in HEC-RAS can be either ‘Feet’ or ‘Meter’.

extract_version()

Get the version of HEC-RAS that produced this file

Version of HEC-RAS, such as “5.0.7”, “6.0.0”, “6.1.0”

get2DAreaBoundaryNamesTypes()

Get 2D Flow Area boundary names, which 2D area it belongs to, type (External or Internal), and Length

Returns:

hdf2DAreaBoundaryNamesTypes – the content of the “Attributes” table in HDF, which includes “Name”, “SA-2D”, “Type”, and “Length”

Return type:

list

get2DAreaBoundaryPoints()

Get 2D Flow Area boundary points (all points on boundaries)

Returns:

hdf2DAreaBoundaryPoints – the content of the “External Faces” table in HDF, which include “BC Line ID”, “Face Index”, “FP Start Index”, “FP End Index”, “Station Start”, and “Station End”

Return type:

numpy.ndarray

get2DAreaCellCenterCoordiantes(area)

Get 2D Flow Area cell center coordinates for a specified 2D area

Note: these coordinates only have (x,y), no z.

Parameters:

area (str) – name of area

get2DAreaCellCounts()

Get 2D Flow Areas cell counts

get2DAreaCellFacePointsIndexes(area)

Get 2D Flow Area cell face points indexes for a specified 2D area

Parameters:

area (str) – name of the area

get2DAreaCellPoints()

Get 2D Flow Area cell points

get2DAreaCellsFaceOrientationInfo(area)

Get cells face and orientation info for a specified 2D area

Parameters:

area (str) – name of area

get2DAreaCellsFaceOrientationValues(area)

Get cells face and orientation values for a specified 2D area

Parameters:

area (str) – name of area

get2DAreaFaceAreaElevationInfo(area)

Get faces area elevation info for a specified 2D area

Two columns: first column-starting index, second column-length of record

Parameters:

area (str) – name of area

get2DAreaFaceAreaElevationValues(area)

Get faces area elevation values for a specified 2D area

Four columns: first column-elevation, second column-area

third column-wetted perimeter, fourth column-Manning’s n (a constant as of now RAS version <=6)

Parameters:

area (str) – name of area

get2DAreaFaceFacePointIndexes(area)

Get face’s facepoint indexes (two interger IDs)

Parameters:

area (str) – name of area

get2DAreaFacePointsCoordinates(area)

Get the face points’ coordinates for a specified 2D area

Parameters:

area (str) – name of area

get2DAreaNames()

Get the names of 2D Flow Areas in the HEC-RAS Plan’s geometry

get2DAreaSolutionTimeDates()

Get 2D Flow Area solution time_dates

Returns:

hdf2DAreaSolutionTimeDates – list of solution time and dates

Return type:

list

get2DAreaSolutionTimes()

Get 2D Flow Area solution times

Returns:

hdf2DAreaSolutionTimes – list of solution times

Return type:

list

get_intervals()

Get the computation, output, and map intervals

get_time_minutes(interval)

pass the interval to this function to get the minute value

Parameters:

interval (str) – internal in string format

hdf2DAreaResultVar(area, varName)

Get HEC-RAS solution time series result for a given variable

Parameters:

• area (str) – name of area

• varName (str) – variable name

interpolateManningN_face_to_cell()

interpolate Manning’s n from face to cell center

HEC-RAS 2D stores Manning’s n value at faces, not cell centers. We need to interpolate its value from face to cell center. Another option is to use the cell center coordinates and direclty query the Manning’s n layer in RAS Mapper, which might be too complicated because HEC-RAS has default Manning’s n, Land Use Cover, Override polygon, etc. Here, the interpolation from face to cell might not be a bad choice.

For each face, HEC-RAS currently does not support varying Manning’s n (horizontally and veritcally). Thus, effectively, it is a constant value for each face. This may change in the future.

interpolateZcoord2Points(facePointsCoordinates3D)

Interpolate the elevation (bathymetry) to 2D area’s points (z-coordinate)

Parameters:

facePointsCoordinates3D (numpy.ndarray) – face points coordinates in 3D

interpolatorFromGeoTiff(geoTiffFileName, pointList, dataType=<class 'numpy.float64'>)

Interpolate from a GeoTiff file given a point list.

Parameters:

• geoTiffFileName (str) – name of the GeoTiff file

• pointList (list) – list of points (x,y)

• dataType (int, optional) – data type in the GeoTiff (default is numpy.float)

interpolatorFromGeoTiff_rasterio(geoTiffFileName, pointList, dataType=<class 'numpy.float64'>)

Interpolate from a GeoTIFF file using rasterio (preferred on Windows).

Falls back to interpolatorFromGeoTiff() (GDAL-based) if rasterio is not available or if opening the file fails.

Parameters:

• geoTiffFileName (str) – name of the GeoTiff file

• pointList (list) – list of points (x,y)

• dataType (int, optional) – data type in the GeoTiff (default is numpy.float)

load2DAreaSolutions()

Load solutions (cell depth and water surface elevation, node X and Y vel.) for all 2D areas

modify_ManningsN(materialIDs, newManningsNValues, materialNames)

Modify materialID’s Manning’s n values to new values

Assume that there is “Land Cover Filename” and “Land Cover Layername” in the result HDF file. If they don’t exist (mostly for the case that the whole domain uses the default, constant Manning’s n value in [“Geometry”][“2D Flow Areas”][0][1]), just use newManningsNValues[0].

Parameters:

• materialIDs (list) – material ID list (0-based)

• newManningsNValues (list) – new Manning’s n values in a list

• materialNames (list) – names of the material in a list (0-based)

modify_PorosityDrag_b_Coefficient(materialIDs, newPorosityDrag_b_Coefficients, materialNames)

Modify materialID’s PorosityDrag_b_Coefficient values to new values

Assume that there is “Porosity and Flow Drag Filename” and “Porosity and Flow Drag Layername” in the result HDF file.

Parameters:

• materialIDs (list) – material ID list

• newPorosityDrag_b_Coefficients (list) – new PorosityDrag_b_Coefficient values in a list

• materialNames (list) – names of the material in a list

saveHEC_RAS2D_results_to_VTK(timeStep=-1, lastTimeStep=False, fileNameBase='', dir='', bFlat=False, combined_areas=False)

Save HEC-RAS 2D solutions to VTK files.

Note

• Each area saved separately (default) or merged into one VTK file per time step when combined_areas=True.

• Each time saved separately

The resulted files will be RAS2D_areaName_timeSequence.vtk, e.g., RAS2D_SpringCreek_0001.vtk, RAS2D_SpringCreek_0002.vtk, etc. When combined_areas=True the file will be RAS2D_combined_timeSequence.vtk.

The option lastTimeStep specifies whether only the last time step is saved (default=False). The option timeStep specifies the particular step to be saved. If both lastTimeSTep and timeStep are specified, lastTimeStep has the priority.

Note

• In most HEC-RAS versions, the velocity can be exported at nodes (face points). But somehow in HEC-RAS 6.6, the nodal velocity is not exported correctly (it has overflow float points; don’t know why); however, the velocity at cell centers is correct. Thus, we save the cell center velocity for version 6.6.

Parameters:

• timeStep (int, optional) – only the specified time step will be saved

• lastTimeStep (bool, optional) – specify only the last time step

• dir (str, optional) – directory name to write to

• combined_areas (bool, optional) – if False (default), write one VTK file per 2D area; if True, merge all areas into a single VTK file per time step.

Miscellaneous classes and tools

Package summary for Misc:

class RAS_to_SRH_Converter(prj_file, plan_id_or_name, srh_case_name, twoDAreaNumber=0)

Converts a HEC-RAS 2D plan result to SRH-2D input format.

For cases with multiple 2D areas, specify which area to convert via twoDAreaNumber (default: 0, the first area).

Parameters:

• prj_file (str) – Path to the HEC-RAS project file (.prj).

• plan_id_or_name (str) – Plan short ID (e.g. ‘p03’) or plan title to convert.

• srh_case_name (str) – Base name for the output SRH-2D files (.srhgeom, .srhmat).

• twoDAreaNumber (int, optional) – Index of the 2D area to convert (default 0, i.e. first area). For single-area cases this should always be 0.

convert_to_SRH()

Perform the conversion and write .srhgeom and .srhmat files.

class Terrain(name)

A Python class for terrain data I/O, creation, and manipulation

Typical work flow is as follows:

1. create the Terrain object

2. create the terrain (elevation, pixel_width/height): user can either call some pre-defined terrains such as constant slope, or create the terrain by themsleves and then call set_terrain(…), and set_pixel_size(…)

3. set the georeferencing by calling set_georeference(…)

4. save the terrain to file by calling save_terrain_to_file(…)

name

name of the terrain

Type:

str

elevation

elevation of the terrain (2D numpy array)

Type:

numpy.ndarray

geoTopLeft_x

raster’s top-left corner georeferenced x-coordinate

Type:

float

geoTopLeft_y

raster’s top-left corner georeferenced y-coordinate

Type:

float

pixel_width

pixel width (in x), i.e, each pixel is how many meters/feet wide?

Type:

float

pixel_height

pixel height (in y), i.e, each pixel is how many meters/feet high?

Type:

float

EPSGCode

EPSG (European Petroleum Survey Group) code that defines the coordinate reference system

Type:

int

geoTransform

affine transform for the raster image from image pixel to real coordinates

Type:

list

supportedGDALDrivers

list of supported GDAL drivers (short names only)

Type:

list

Terrain class constructor

Parameters:

name (str) – name of the terrain

add_bedform(channel_lenx, channel_leny, Lb, Hb, alpha_lee, a_stoss, rotation=0, perturbation=0, perturb_distribution=0)

Add bedform feature to the terrain

Typical use scenario is firstly to create a constant slope channel and then add the bedform features.

Parameters:

• channel_lenx (float) – channel length in x

• channel_leny (float) – channel length in y

• Lb (float) – bed form length

• Hb (float) – bed form height

• alpha_lee (float) – bed-form’s lee side slope angle (in degrees)

• a_stoss (float) – bed-form’s stoss size sine function amplitude

• rotation (float) – optional rotation angle of the domain in degrees (default is zero)

• perturbation (float) – optional perturbation added to the terrain (default is zero)

• perturb_distribution (integer) – optional perturbation distribution type: 0-uniform, 1-normal (mean=0, sd=perturbation/1.96)

add_composite_channel(channel_lenx, channel_leny, L1, B, D, alpha)

Add composite channel to the terrain

Typical use scenario is firstly to create a constant slope channel and then add the composite channel.

Parameters:

• channel_lenx (float) – channel length in x

• channel_leny (float) – channel length in y

• L1 (float) – flood plain’s width on one side (the other side can be calculated)

• B (float) – main channel bottom width

• D (float) – main channel depth

• alpha (float) – main channel’s side slope angle (in degrees)

build_supported_GDAL_drivers_list()

Build the list of supported GDAL drivers list

create_constant_slope_channel_elevation(slope, channel_lenx, channel_leny, pixel_width, pixel_height, elevation_origin=0, extra_len=0)

Create a constant slope channel elevation

The slope is in the x direction only. The slope in the y direction is zero.

Parameters:

• slope (float) – slope in x

• channel_lenx (float) – channel length in x

• channel_leny (float) – channel length in y

• elevation_origin (float) – the elevation at the origin (top left; does not account for the extra fringe)

• extra_len (float) – optional extra fringe length added to the channel domain (to have some free room in developing 2D models in e.g., SMS or HEC-RAS.

get_elevation()

Get the elevation array

Returns:

elevation – elevation 2D array

Return type:

numpy.array

get_terrain_name()

Get the terrain name

Returns:

name – name of the terrain

Return type:

str

save_terrain_to_file(terrainFileName, geoDriverName='GTiff')

save terrain to file, such as GeoTiff

Parameters:

• terrainFileName (str) – file name for the saved terrain

• geoDriverName (str) – GDAL raster driver names, such as ‘GTiff’

set_elevation(elevation)

Set the elevation array

Parameters:

elevation (numpy.ndarray) – elevation 2D array

set_georeference(geoTopLeft_x, geoTopLeft_y, EPSGCode)

Set the georeferencing information

Parameters:

• geoTopLeft_x (float) – raster’s top-left corner georeferenced x location

• geoTopLeft_y (float) – raster’s top-left corner georeferenced y location

• EPSGCode (int) – EPSG (European Petroleum Survey Group) code that defines the coordinate reference system

set_pixel_size(pixel_width, pixel_height)

Set the pixel size in x and y directions

Parameters:

• pixel_width (float) – the width of each pixel in real world

• pixel_height (float) – the height of each pixel in real world

gmsh2d_to_srh(gmsh2d_fileName, srh_caseName, shift_x=0.0, shift_y=0.0, units='Meters', bAddMonitoringLines=False, monitoringLines=[], monitoringlineTol=0.001)

Convert Gmsh 2D mesh into SRH-2D format with the option to add monitoring lines.

It generates two files: srhgeom for mesh and srhmat for Manning’s n

The srhhydro file has to be generated separately.

For monitoring lines: SRH-2D treats the monitoring lines similarly as boundaries. Both are nodeStrings in the srhgeom file. However, Gmsh2d does not directly support internal boundary such as the monitoring lines. Thus, for any monitoring line, we need to add it to the nodeStrings list here.

Parameters:

• gmsh2d_fileName (str) – file name of the Gmsh MSH file

• srh_caseName (str) – case name for SRH-2D.

• shift_x (float) – shift of coordinates in x direction

• shift_y (float) – shift of coordinates in y direction

• units (str, default Meters) – length units of Gmsh file

• bAddMonitoringLines (whether add monitoring lines)

• monitoringLines (list of monitoring lines. Currently only straightlines are supported.)

• monitoringlineTol (a float tolerance to check whether a node is close to the monitoring line)

AI Tools (MCP Server)

Package summary for AI_Tools:

pyHMT2D AI Tools

A collection of 25 AI-agent-callable tools for automating 2D hydraulic modelling workflows with SRH-2D and HEC-RAS.

Quick start

Python API:

from pyHMT2D.AI_Tools.tools import get_project_info, get_materials, set_manning_n

MCP server (stdio, for Claude Desktop / Claude Code):

python -m pyHMT2D.AI_Tools.mcp_server

Tool groups

1. Discoverylist_model_files, get_project_info, get_materials,

   get_boundary_conditions, get_result_variables

2. Parametersset_manning_n, set_inlet_flow, set_exit_wse,

   save_modified_inputs

3. Execution : run_preprocessing, run_simulation, get_simulation_status

4. Resultsread_results, get_value_at_point, get_result_statistics,

   get_flood_extent, get_cross_section_profile

5. Export : export_to_vtk, export_mesh_to_vtk

6. Calibration : load_observations, evaluate_parameters, run_calibration

7. Monte Carlo : generate_mc_samples, run_monte_carlo, get_mc_statistics

get_session() → HydraulicSession

Return the global session singleton.

reset_session() → None

Clear the global session (useful in tests).