pyHMT2D: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Commands

# Install in editable mode (development)
pip install -e .

# Run all tests
pytest

# Run a specific test file
pytest tests/01_SRH_2D_Data/01_01_SRH_2D_Data_test.py

# Run tests with verbose output (already enabled via pytest.ini addopts = -s)
pytest -v

CLI tools (available after install):

# Convert HEC-RAS 2D mesh to SRH-2D format
hmt-cli ras_to_srh --args '{"ras_hdf_file": "input.hdf", "terrain_tif_file": "terrain.tif", "srh_case_name": "output"}'

# Convert SRH-2D results to VTK (last time step)
hmt-cli srh_to_vtk --args '{"srhhydro_file": "case.srhhydro", "output_file": "result.h5"}'

# Export SRH-2D mesh only to VTK
hmt-cli srh_to_vtk --args '{"srhhydro_file": "case.srhhydro", "output_file": "mesh.vtk", "mesh_only": true}'

Architecture

pyHMT2D automates and post-processes 2D hydraulic simulations for two external solvers: SRH-2D (USBR) and HEC-RAS 2D (USACE). It is Windows-only due to solver dependencies (SRH-2D via subprocess, HEC-RAS via COM interface).

Package Layout

pyHMT2D/
├── Hydraulic_Models_Data/         # Model-specific data and control
│   ├── Hydraulic_Models_Data_Base/  # Abstract base classes
│   │   ├── HydraulicModel.py        # Base for all model controllers
│   │   └── HydraulicData.py         # Base for all data readers
│   ├── SRH_2D/                      # SRH-2D implementation
│   ├── RAS_2D/                      # HEC-RAS 2D implementation
│   └── Backwater_1D/                # Simple 1D demo model
├── Calibration/                   # Model calibration (scipy-based)
├── Parametric_Study/              # Batch/Monte Carlo parametric studies
├── Misc/                          # Utilities shared across models
│   ├── Terrain.py                   # DEM/raster processing (rasterio)
│   ├── RAS_to_SRH_Converter.py      # Mesh/BC format conversion
│   ├── vtk_utilities.py             # VTK export and manipulation
│   └── tools.py                     # Result sampling and probing
└── __common__.py                  # Global config (verbose flag, etc.)