rivia 0.2.0

A modern Python interface for HEC-RAS Visualization, Information, and Automation

RIVIA

RAS Interface for Visualization, Information, and Automation

A modern, modular Python library for interacting with HEC-RAS hydraulic modeling software.

Documentation

Full documentation is available at rivia.readthedocs.io.

Overview

rivia provides a clean, Pythonic interface for working with HEC-RAS projects:

• Control HEC-RAS via COM automation — open projects, switch plans, run simulations
• Read and write HEC-RAS text input files (.prj, .g*, .p*, .f*, .u*)
• Access HDF5 results — water surface, velocity, depth, and other outputs
• Export rasters — pixel-perfect RASMapper-equivalent rasters (WSE, depth, velocity, etc.)
• Export terrain — mosaic and modify terrain from HEC-RAS terrain HDF files

Requirements

• Windows — HEC-RAS is Windows-only
• Python 3.10+
• HEC-RAS 5.x or later installed

Installation

pip install rivia

With geospatial extras (required for raster export):

pip install rivia[geo]

Quick Example

from rivia.model import Project

# Open a HEC-RAS project
model = Project("path/to/project.prj")
print(model.version)       # e.g. "6.30"

# Switch plans
model.set_plan(title="Base Condition")
model.set_plan(short_id="BC")
model.set_plan(index=0)

# Run model
model.run(hide_window=False)

# Read HDF results
area = model.results.flow_areas["Perimeter 1"]
wse_max = area.max_water_surface

# Export a WSE raster
vrt = model.export_wse(timestep=None, render_mode="sloping")
print(vrt.path)

Package Structure

rivia/
├── controller/  # COM interface to run/control HEC-RAS
├── model/       # Project — primary project interface; read/write text input files, read HDF results
├── hdf/         # Read HEC-RAS HDF5 geometry and result files
├── geo/         # Geospatial operations: raster export (geopandas/rasterio)
└── utils/       # Shared helpers

Development

git clone https://github.com/gyanz/rivia.git
cd rivia
pip install -e ".[dev,geo,docs]"

# Run tests
pytest tests/ -x --tb=short

# Lint
ruff check src/

# Type check
mypy src/rivia

# Build docs
sphinx-build -b html docs docs/_build/html

License

Copyright 2025 Gyan Basyal and WEST Consultants, Inc.

Licensed under the Apache License, Version 2.0.