hydrocivil 1.2.0

a package for hydrological methods in enviromental engineering

hydrocivil: a package for hydrological methods in civil and enviromental engineering

Typical tasks related to water resources and engineering require quick calculations of hydrological phenomena such as: storm hyetographs, soil infiltration, flood hydrographs, flood routing through channels or reservoirs, etc. With this purpose in mind, the package is presented as an alternative to perform calculations that are usually done in tedious spreadsheets in a fast pythonic way. The purpose is to give tools to the engineer to calculate hydrologic processes with methods and techniques he/she deems convenient, such as different varieties of synthetic unit hydrographs, synthetic storms or basin geomorphometric parameters. The package isnt intended to be a replacement of larger hydrological models (e.g. HEC-HMS), but rather a fast customizable and automatic alternative for multi-basin calculations.

The package is largely oriented to Chilean national standards, however many methods originally come from the USA NCRS National Engineering Handbook.

Dependencies

Before installing, check your environment for the following packages:

• numpy, pandas, scipy, matplotlib
• xarray, rasterio, rioxarray
• shapely, geopandas
• networkx
• whitebox_workflows

Installation

Currently the package can only be installed via pip:

pip install --force-reinstall --no-deps hydrocivil

Example Use

from hydrocivil import RainStorm, RiverBasin
from hydrocivil.resources import load_example_data
import matplotlib.pyplot as plt

Compute basin properties

# ---------------------- Load example data (or your own) --------------------- #

# dem = rxr.open_rasterio('/path/to/dem.tif')
# curvenumber = rxr.open_rasterio('path/to/cn.tif')
# rivernetwork = gpd.read_file('path/to/rivers.shp')
# basin_polygon = gpd.read_file('path/to/basin.shp')
basin, rnetwork, dem, cn = load_example_data()

# Create RiverBasin object and compute properties
wshed = RiverBasin(fid='Example', basin=basin, dem=dem, rivers=rnetwork, lulc=cn, amc='wet')
wshed.compute_params()  # <- compute geomorphological parameters (SI units)
wshed.plot() # Check results (e.g basin polygon, identified main river, etc)

<Axes: title={'left': 'Example'}>

Create an hypothetical storm

# Create a 100 milimeter, 24 hours duration, SCS type I storm with pulses every half an hour
storm = RainStorm('SCS_I24', timestep=0.5, rain24=100)
storm.fit(ref_pgauge='Grunsky')
storm.compute(target_duration=24)
# Use SCS method for abstractions with the watershed average curve number
pr_eff, infr = wshed.infiltrate(pr = storm.pr, method = 'SCS')

storm.pr.to_series().plot(kind='bar', width=1, ec='k')
infr.to_series().plot(kind='bar', width=1, color='tab:purple', ec='k')

<Axes: >

Estimate the basin response (flood hydrograph)

# Compute the basin SCS unit hydrograph for the storm (UH related to the storm timestep)
wshed.SynthUnitHydro(method='SCS', timestep=storm.timestep) # By default this uses the 484 SCS unit hydrograph and SCS lagtime formula. 

# Compute the flood hydrograph as the convolution of the effective precipitation depth with the unit hydrograph
wshed.UnitHydro.convolve(pr_eff).plot()

<Axes: >