Metadata-Version: 2.4
Name: rivia
Version: 0.3.0
Summary: A modern Python interface for HEC-RAS Visualization, Information, and Automation
Author: Gyan Basyal, WEST Consultants, Inc.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gyanz/rivia
Project-URL: Repository, https://github.com/gyanz/rivia
Project-URL: Issues, https://github.com/gyanz/rivia/issues
Keywords: hec-ras,hydraulics,hydrology,modeling,water-resources
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: h5py
Requires-Dist: pywin32; sys_platform == "win32"
Requires-Dist: psutil; sys_platform == "win32"
Requires-Dist: pydantic>=2
Provides-Extra: geo
Requires-Dist: geopandas; extra == "geo"
Requires-Dist: rasterio; extra == "geo"
Requires-Dist: matplotlib; extra == "geo"
Requires-Dist: numba; extra == "geo"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# RIVIA

**RAS Interface for Visualization, Information, and Automation**

A modern, modular Python library for interacting with [HEC-RAS](https://www.hec.usace.army.mil/software/hec-ras/) hydraulic modeling software.

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://www.hec.usace.army.mil/software/hec-ras/)
[![Documentation](https://readthedocs.org/projects/rivia/badge/?version=latest)](https://rivia.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/rivia.svg)](https://pypi.org/project/rivia/)

## Documentation

Full documentation is available at [rivia.readthedocs.io](https://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

```bash
pip install rivia
```

With geospatial extras (required for raster export):

```bash
pip install rivia[geo]
```

## Quick Example

```python
import numpy as np
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 and run
model.set_plan(short_id="BC")
model.run(hide_window=False)

# Export a WSE raster (pixel-perfect RASMapper equivalent)
vrt = model.export_wse(timestep=None, render_mode="sloping")

hdf = model.results          # UnsteadyPlan

# 2D flow areas
area = hdf.flow_areas["Perimeter 1"]
area.max_water_surface       # pd.DataFrame  — max WSE per cell, columns [value, time]
area.get_depth(timestep=0)   # np.ndarray   — water depth snapshot

# 1D cross sections — mapping interval
xs = hdf.cross_sections("mapping")["Butte Cr Upper 7"]
xs.wse              # pd.Series  — WSE indexed by pd.DatetimeIndex
xs.flow             # pd.Series
xs.velocity_channel # pd.Series

# 1D cross sections — Post Process Profiles (rich hydraulic output)
coll = hdf.cross_sections("post_process")
coll.wse            # pd.DataFrame  — location × ["max_wse", 0, 1, …] profiles
coll.velocity_channel
coll.profile_table("EG Slope")   # any variable by name

xs_pp = coll[0]     # integer index, name "Butte Cr Upper 7", or (river, reach, rs) tuple — all equivalent
xs_pp.wse           # pd.Series  — timeseries only, Max WS excluded
xs_pp.energy_grade  # pd.Series

# Storage areas — DSS hydrograph interval
sa = hdf.storage_areas("output")["Reservoir 1"]
sa.wse              # pd.Series  — WSE indexed by pd.DatetimeIndex

# max_wse / min_wse are only available for output="mapping" (Base Output summary)
sa_map = hdf.storage_areas("mapping")["Reservoir 1"]
sa_map.max_wse      # pd.DataFrame  — columns [value, time]

# Structures — DSS Profile interval
structs = hdf.structures("profile")
inl = structs.inlines["Butte Cr Upper 100"]
inl.stage_hw        # pd.Series  — headwater stage
inl.flow_total      # pd.Series  — total flow

conn = structs.connections["Dam"]
conn.stage_hw       # pd.Series
conn.stage_tw       # pd.Series

# WSE and flow profiles along / across a line
# xy can be an (n, 2) ndarray or any object with a __geo_interface__ (e.g. shapely LineString)
xy = np.array([[500, 200], [600, 250], [700, 300]])
df     = model.wse_along_line(xy, timestep="max", interval=1.0)  # pd.DataFrame — station, wse, …
series = model.flow_across_line(xy)                               # pd.Series — discharge time series
```

## 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

```bash
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](LICENSE).
