digger.make.reservoir

make.reservoir allows a user to create initial conditions for h, eta, and m for material impounded behind hypothetical dams.

make.reservoir expects that a user knows the location, solid volume fraction, and volume of material impounded behind one or more hypothetical dams, but that the user does not know the spatial extent of the reservoir. make.reservoir is typically used to place material within steep, mountainous catchements.

The amount of material is specified in a dictionary that contains information about the location, volume, and solid volume fraction of impounded material impounded behind the hypothetical dam. Gradient descent directions are calculated on the topographic surface using pysheds and are used to determine which grid cells contain reservoir material. Each reservoir has a horizontally flat upper surface and extends upstream from the provided location.

A user might expect that make.reservoir would place material within grid cells upstream of a vertical plane that intersects the topography and is oriented perpendicular to the channel thalweg at the location of the hypothetical dam. However, this is not exactly what make.reservoir does. Only grid cells that are within the catchment upstream of the hypothetical dam location based on the gradient descent directions are included in the final reservoir extent. For most topographic contexts, this means that there will be a sliver of grid cells located near the thalweg-orthogonal plane that are not included in the reservoir. This is because these cells are not located within the catchment that drains to the hypothetical dam location.

Module Contents

Functions

reservoir

Calculate the thickeness of initial landslide material behind a series of dams.

API

digger.make.reservoir.reservoir(topo_path: str, q1_prefix: str = 'q1', q4_prefix: str = 'q4', eta_prefix: str = 'eta', dam_dict: dict = {}, coarsen_factor: int = 1, limit_depth: bool = False, max_depth: float = 5.0, write_tt3: bool = False, write_tif: bool = False, fig_path: str = 'dam.png')

Calculate the thickeness of initial landslide material behind a series of dams.

Inputs:
topo_pathstr

Path to rasterio-readable file containing the initial topography input file. Output is written at the resolution of this file. Expected in projected coordinates (e.g., meters or feet, not degrees).

q1_prefixstr

Prefix of the path to write any output of q1 (thickness, h).

eta_prefixstr

Prefix of the path to write any output of q8 (surface altitude, eta). Outside of the area with h>0 area, eta is set to a very low value to ensure that D-Claw uses the value of b.

q4_prefixstr

Prefix of the path to write any output of q4 (solid volume fraction, m).

dam_dictdict

A dictionary containing the information needed to construct each dam. The dictionary has keys indicating a unique identifier for each dam and the values are themselves a dictionary with the following keys:

  • x: The x-coordinate of the downstream end of the dam

  • y: The y-coordinate of the downstream end of the dam

  • volume: The total volume of material behind the dam

  • m0: The solid volume fraction of the material behind the dam

coarsen_factorint

A factor by which to coarsen the DEM before further processing. This may be useful in cases for which fine topography is available but not needed for reservoir construction (the reservoir building algorithm is slow for small grid cell sizes). Default is 1, which results in no coarsening.

limit_depthbool

Whether the depth should be limited. Default is False. Should this be set to True the result will not be a flat-topped reservoir, but a sloping area with depth no larger than max_depth.

max_depthfloat

The maximum depth used if limit_depth==True.

write_tt3bool

Whether to write out topotype 3 files of q1, eta, q4, and b. If written, the *_prefix for each output has ‘.tt3’ added to the end.

write_tifbool

Whether to write out geotif files of q1, eta, q4, and b. If written, the *_prefix for each output has ‘.tif’ added to the end.

fig_pathstr

Path where to generate a figure summarizing the output.

Outputs:
regions: dict of lists

Each entry in the dict is a list [xmin, xmax, ymin, ymax] indicating the bounding box surrounding the material in each dam. The key is the dam_dict key associated with each dam.