`make.reservoir`¶

The typical usage for make.reservoir differs from the other digger.make functions in that it relies not on a set of shapefiles indicating the location of landslide material but instead requires a dictionary indicating the location and size of a series of hypothetical dams.

make.reservoir conducts gradient descent analysis on the provided topography (often called ‘flow routing’) and then recursively determines the location and thickness of material located upstream of the (x,y) location specified for the dam outlet. The upstream extent of impounded material within the newly created reservoir is set by the provided volume. The thickness of impounded material varies spatially such that the top surface of the impounded material is level (i.e., has no slope).

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.

This method assumes that the user is providing locations with high drainage area in the bottom of confined channels.

Usage is as follows:

Prepare a topography file as a geotif. If the area of interest includes submarine regions, the topography and bathymetry should be represented as a seamless surface in a single file.
Determine the location, volume, and solid volume fraction of initial, potentially mobile, material to be placed behind landslide dams. This material is provided as the keyword argument dam_dict and has the following format.

dam_dict = {
  dam_id: {"x": xcoord, "y": ycoord, "volume": volume, "m0": solid_fraction},
  dam_id: {"x": xcoord, "y": ycoord, "volume": volume, "m0": solid_fraction},
  }

Run make.reservoir to generate input files for D-Claw. Inspect the output and adjust any input parameters as needed.
Using these files, set up a D-Claw simulation to run and analyze. digger will not do this for you.

A code snippet that uses make.reservoir may be found in the file digger/examples/pre-run/schultz_fire/make_dam.py.

"""Example using digger.make.reservoir.

This examples uses digger.make.reservoir to generate input for an example at
the Schultz fire in Arizona.

The amount of material is specified using a dictionary containing the
location and size of the dam.

Note: The volume specified here is very large in order to clearly depict
where material is placed.
"""

from digger import make

regions = make.reservoir(
    topo_path="../../../data/sch_bsn5210_topo_10m.tif",
    q1_prefix="q1_sch_reservoir",
    q4_prefix="q4_sch_reservoir",
    eta_prefix="eta_sch_reservoir",
    dam_dict={"1": {"x": 444065, "y": 3909870, "volume": 100000, "m0": 0.61}},
    write_tt3=True,
    write_tif=True,
    fig_path="schultz_reservoir.png",
)

Attention

This code snippet is not fully self-sufficient. To reproduce the example, execute the code such that the relative path is correct. This may be done by executing the example script from within the directory in which it is located.

After this code runs, it will produce geotif and topotype3 files that specify the upper and lower surfaces of the landslide and the initial solid-volume fraction of the landslide material.

It will also create diagnostic figures to assist the user.

Example digger.make.reservoir summary figure. — Fig. 5 An example of the diagnostic output provided by digger.make.reservoir.¶

make.reservoir¶

`make.reservoir`¶