# mikebannis/rascontrol architecture

> Architecture diagram of the GitHub repository mikebannis/rascontrol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikebannis/rascontrol
- Repository: https://github.com/mikebannis/rascontrol

## Overview

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/rascontrol.py`](https://github.com/mikebannis/rascontrol/blob/master/rascontrol/rascontrol.py) (Controller Facade), [`tests/test_rascontrol.py`](https://github.com/mikebannis/rascontrol/blob/master/tests/test_rascontrol.py) (Behavior Tests), [`tests/models/507`](https://github.com/mikebannis/rascontrol/tree/master/tests/models/507) (Sample Models), [`setup.py`](https://github.com/mikebannis/rascontrol/blob/master/setup.py) (Package Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lib["Library"]
  node_init["Public API<br/>package init<br/>[__init__.py]"]
  node_controller["Controller Facade<br/>Python facade<br/>[rascontrol.py]"]
  node_errors["Exceptions<br/>error types<br/>[exceptions.py]"]
  node_apidoc["API Notes<br/>usage doc<br/>[api.txt]"]
end

subgraph group_runtime["Runtime Boundary"]
  node_hecras["HEC-RAS<br/>external desktop"]
  node_project["Project File<br/>RAS project"]
  node_plan["Plan Files<br/>model state"]
  node_results[("Output Files<br/>result artifacts")]
  node_version{{"Version Bind<br/>compat layer"}}
end

subgraph group_tests["Tests"]
  node_testsuite["Behavior Tests<br/>integration tests<br/>[test_rascontrol.py]"]
  node_installer["Env Setup<br/>test helper<br/>[install_hec_ras.py]"]
  node_helpers["Test Helpers<br/>shared utilities<br/>[util.py]"]
  node_models[("Sample Models<br/>fixture corpus")]
  node_steady["Steady Flow<br/>fixture set"]
  node_unsteady["Unsteady Flow<br/>fixture set"]
end

subgraph group_delivery["Delivery"]
  node_ci["CI Workflow<br/>github actions<br/>[tests.yml]"]
  node_packaging["Package Metadata<br/>python packaging<br/>[setup.py]"]
  node_deps["Requirements<br/>deps manifest<br/>[requirements.txt]"]
end

node_init -->|"exports"| node_controller
node_controller -->|"raises"| node_errors
node_controller -.->|"matches"| node_apidoc
node_controller -->|"binds"| node_version
node_version -->|"targets"| node_hecras
node_controller -->|"drives"| node_hecras
node_hecras -->|"opens"| node_project
node_project -->|"selects"| node_plan
node_hecras -->|"writes"| node_results
node_controller -->|"reads"| node_results
node_testsuite -->|"prepares"| node_installer
node_testsuite -->|"uses"| node_helpers
node_testsuite -->|"drives"| node_models
node_models -->|"includes"| node_steady
node_models -->|"includes"| node_unsteady
node_testsuite -->|"exercises"| node_controller
node_testsuite -->|"depends on"| node_hecras
node_ci -->|"runs"| node_testsuite
node_packaging -.->|"packages"| node_controller
node_packaging -.->|"declares"| node_deps

click node_init "https://github.com/mikebannis/rascontrol/blob/master/rascontrol/__init__.py"
click node_controller "https://github.com/mikebannis/rascontrol/blob/master/rascontrol/rascontrol.py"
click node_errors "https://github.com/mikebannis/rascontrol/blob/master/rascontrol/exceptions.py"
click node_apidoc "https://github.com/mikebannis/rascontrol/blob/master/rascontrol/api.txt"
click node_testsuite "https://github.com/mikebannis/rascontrol/blob/master/tests/test_rascontrol.py"
click node_installer "https://github.com/mikebannis/rascontrol/blob/master/tests/install_hec_ras.py"
click node_helpers "https://github.com/mikebannis/rascontrol/blob/master/tests/util.py"
click node_models "https://github.com/mikebannis/rascontrol/tree/master/tests/models/507"
click node_steady "https://github.com/mikebannis/rascontrol/tree/master/tests/models/507/1D Steady Flow Hydraulics"
click node_unsteady "https://github.com/mikebannis/rascontrol/tree/master/tests/models/507/1D Unsteady Flow Hydraulics"
click node_ci "https://github.com/mikebannis/rascontrol/blob/master/.github/workflows/tests.yml"
click node_packaging "https://github.com/mikebannis/rascontrol/blob/master/setup.py"
click node_deps "https://github.com/mikebannis/rascontrol/blob/master/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_init,node_controller,node_errors,node_apidoc toneBlue
class node_hecras,node_project,node_plan,node_results,node_version toneAmber
class node_testsuite,node_installer,node_helpers,node_models,node_steady,node_unsteady toneMint
class node_ci,node_packaging,node_deps toneRose
```

## Components

### Library

Python wrapper and public API surface

- [Public API](https://github.com/mikebannis/rascontrol/blob/master/rascontrol/__init__.py): package init · Exposes the top-level import surface · `rascontrol/__init__.py`
- [Controller Facade](https://github.com/mikebannis/rascontrol/blob/master/rascontrol/rascontrol.py): Python facade · Main RasController interface for opening projects, running plans, and reading results · `rascontrol/rascontrol.py`
- [Exceptions](https://github.com/mikebannis/rascontrol/blob/master/rascontrol/exceptions.py): error types · Package-specific failure classes · `rascontrol/exceptions.py`
- [API Notes](https://github.com/mikebannis/rascontrol/blob/master/rascontrol/api.txt): usage doc · Documented public methods and result access patterns · `rascontrol/api.txt`

### Runtime Boundary

External HEC-RAS desktop controller and native project/results files

- **HEC-RAS**: external desktop · Installed HEC-RAS application that executes the model
- **Project File**: RAS project · Entry point to a HEC-RAS model (.prj)
- **Plan Files**: model state · Plan and configuration artifacts used during runs
- **Output Files**: result artifacts · Generated data consumed by the wrapper, including DSS, HDF, map, and text outputs
- **Version Bind**: compat layer · Version-aware binding to a specific HEC-RAS installation

### Tests

Integration tests and bundled sample models

- [Behavior Tests](https://github.com/mikebannis/rascontrol/blob/master/tests/test_rascontrol.py): integration tests · Main API tests against real HEC-RAS models · `tests/test_rascontrol.py`
- [Env Setup](https://github.com/mikebannis/rascontrol/blob/master/tests/install_hec_ras.py): test helper · Locates or prepares the installed HEC-RAS environment · `tests/install_hec_ras.py`
- [Test Helpers](https://github.com/mikebannis/rascontrol/blob/master/tests/util.py): shared utilities · Shared test utilities for file handling and result checks · `tests/util.py`
- [Sample Models](https://github.com/mikebannis/rascontrol/tree/master/tests/models/507): fixture corpus · Bundled HEC-RAS example projects used for integration coverage · `tests/models/507`
- [Steady Flow](https://github.com/mikebannis/rascontrol/tree/HEAD/tests/models/507/1D%20Steady%20Flow%20Hydraulics): fixture set · Steady-flow example projects · `tests/models/507/1D Steady Flow Hydraulics`
- [Unsteady Flow](https://github.com/mikebannis/rascontrol/tree/HEAD/tests/models/507/1D%20Unsteady%20Flow%20Hydraulics): fixture set · Unsteady-flow example projects and outputs · `tests/models/507/1D Unsteady Flow Hydraulics`

### Delivery

Packaging and CI

- [CI Workflow](https://github.com/mikebannis/rascontrol/blob/master/.github/workflows/tests.yml): github actions · Automated test workflow · `.github/workflows/tests.yml`
- [Package Metadata](https://github.com/mikebannis/rascontrol/blob/master/setup.py): python packaging · Build and dependency declarations · `setup.py`
- [Requirements](https://github.com/mikebannis/rascontrol/blob/master/requirements.txt): deps manifest · Python dependency list · `requirements.txt`

## Connections

- 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
