How mikebannis/rascontrol works
1. What this repo is
- rascontrol is a thin Python automation layer over the HEC-RAS Controller interface.
- It is not a hydraulic solver itself; the real execution happens inside an installed HEC-RAS desktop application.
2. Top-level architecture
- The package is centered on a single controller facade in rascontrol/rascontrol.py.
- rascontrol/__init__.py exposes the public API so users can import rascontrol and work from one entry point.
- rascontrol/exceptions.py holds package-specific error types for controller/runtime failures.
- rascontrol/api.txt appears to document the supported public methods and result access patterns.
3. Core runtime boundary
- The main boundary is between Python and an external HEC-RAS instance.
- Python code opens an existing project, starts a plan run, and then queries results from the model through the controller interface.
- The README’s note about “close() does not currently appear to be working” suggests controller/process lifecycle is managed indirectly and may reuse already-open RAS sessions.
4. Primary usage flow
- A caller creates a RasController with a specific HEC-RAS version.
- The controller opens a .prj project file, runs the current plan, and then reads output values.
- Result access is organized around profiles and cross sections; the example shows querying a metric like water surface elevation (WSEL) from a cross section for a given profile.
5. Result access model
- The API looks like a small object model over RAS outputs: projects/plans on one side, profiles and cross sections on the other.
- Rather than returning raw files, the wrapper exposes high-level value extraction methods.
- This is the main “data plane” of the library: open model -> run model -> retrieve hydraulic results.
6. External dependency
- HEC-RAS must already be installed locally; the Python package does not bundle the solver/controller.
- The version parameter (version='506' in the README) indicates the wrapper is version-aware and likely binds to a specific RAS installation/release.
- This repo therefore depends on a Windows desktop automation environment, not a server-side runtime.
7. Test architecture
- The tests/ folder is built around real HEC-RAS sample models, not synthetic unit mocks alone.
- tests/install_hec_ras.py likely helps prepare the test environment or locate the installed RAS executable/controller.
- tests/test_rascontrol.py is the main behavioral test file for the wrapper API.
- tests/util.py probably contains shared helpers for launching models, locating files, or comparing extracted results.
8. Fixture-heavy model corpus
- tests/models/507/... contains many HEC-RAS example projects spanning steady flow, unsteady flow, bridges, culverts, levees, pumps, gates, breaches, and encroachment.
- These fixtures exercise the wrapper against a broad range of RAS project types and output artifacts.
- The presence of .prj, .g01, .p01, .u01, .dss, .rasmap, .hdf, and related files shows the tests operate on native HEC-RAS model state and generated outputs.
9. Integration focus
- The repository’s quality strategy is integration-first: validate that the Python wrapper can drive actual HEC-RAS models end to end.
- That makes the tests more representative of production use, but also ties them to the installed RAS version and its file formats.
10. Packaging and delivery
- setup.py and requirements.txt indicate a standard Python package distribution.
- GitHub Actions (.github/workflows/tests.yml) provides CI coverage, likely for running the wrapper tests in an environment with HEC-RAS available.
- LICENSE and README make this a small, focused library rather than a multi-service application.
11. Diagram takeaway
- The architecture diagram should show one Python library layer, one controller facade, and one external HEC-RAS runtime boundary.
- Under that, show HEC-RAS project files and result files as the persistent model/data layer.
- The tests are best represented as a separate validation subsystem that drives the same HEC-RAS boundary using bundled sample projects.
Main entry points: rascontrol.py Controller Facade · test_rascontrol.py Behavior Tests · 507 Sample Models · setup.py Package Metadata
Components 18
Library
Python wrapper and public API surface
- Public API · Exposes the top-level import surface
rascontrol/__init__.py - Controller Facade · Main RasController interface for opening projects, running plans, and reading results
rascontrol/rascontrol.py - Exceptions · Package-specific failure classes
rascontrol/exceptions.py - API Notes · Documented public methods and result access patterns
rascontrol/api.txt
Runtime Boundary
External HEC-RAS desktop controller and native project/results files
- HEC-RAS · Installed HEC-RAS application that executes the model
- Project File · Entry point to a HEC-RAS model (.prj)
- Plan Files · Plan and configuration artifacts used during runs
- Output Files · Generated data consumed by the wrapper, including DSS, HDF, map, and text outputs
- Version Bind · Version-aware binding to a specific HEC-RAS installation
Tests
Integration tests and bundled sample models
- Behavior Tests · Main API tests against real HEC-RAS models
tests/test_rascontrol.py - Env Setup · Locates or prepares the installed HEC-RAS environment
tests/install_hec_ras.py - Test Helpers · Shared test utilities for file handling and result checks
tests/util.py - Sample Models · Bundled HEC-RAS example projects used for integration coverage
tests/models/507 - Steady Flow · Steady-flow example projects
tests/models/507/1D Steady Flow Hydraulics - Unsteady Flow · Unsteady-flow example projects and outputs
tests/models/507/1D Unsteady Flow Hydraulics
Delivery
Packaging and CI
- CI Workflow · Automated test workflow
.github/workflows/tests.yml - Package Metadata · Build and dependency declarations
setup.py - Requirements · Python dependency list
requirements.txt
Connections 20
- Public API → Controller Facade: exports · Public package entry point exposes the controller facade
- Controller Facade → Exceptions: raises · Controller operations surface package-specific failures
- Controller Facade → API Notes: matches · Documented API describes supported methods and access patterns
- Controller Facade → Version Bind: binds · Controller is instantiated against a specific HEC-RAS version
- Version Bind → HEC-RAS: targets · Version binding selects an installed desktop controller/runtime
- Controller Facade → HEC-RAS: drives · Python wrapper opens projects, runs plans, and queries outputs through HEC-RAS
- HEC-RAS → Project File: opens · External runtime loads the project file
- Project File → Plan Files: selects · Project contains plan/configuration state for execution
- HEC-RAS → Output Files: writes · Run execution produces output artifacts
- Controller Facade → Output Files: reads · Wrapper extracts hydraulic values from generated results
- Behavior Tests → Env Setup: prepares · Tests depend on environment setup for HEC-RAS access
- Behavior Tests → Test Helpers: uses · Behavior tests share common utilities
- Behavior Tests → Sample Models: drives · Integration tests execute bundled sample models
- Sample Models → Steady Flow: includes · Fixture corpus contains steady-flow examples
- Sample Models → Unsteady Flow: includes · Fixture corpus contains unsteady-flow examples
- Behavior Tests → Controller Facade: exercises · Tests validate the public wrapper against real runs
- Behavior Tests → HEC-RAS: depends on · Tests require an installed HEC-RAS runtime
- CI Workflow → Behavior Tests: runs · Workflow executes the integration test suite
- Package Metadata → Controller Facade: packages · Distribution bundles the main library module
- Package Metadata → Requirements: declares · Package metadata references runtime dependencies