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¶
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 toTrue
the result will not be a flat-topped reservoir, but a sloping area with depth no larger thanmax_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.