# `make.reservoir`

The typical usage for [`make.reservoir`](#digger.make.reservoir) differs from the other [`digger.make`](#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`](#digger.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`](#digger.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`](#digger.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:

1. 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.
2. 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.
```python
dam_dict = {
  dam_id: {"x": xcoord, "y": ycoord, "volume": volume, "m0": solid_fraction},
  dam_id: {"x": xcoord, "y": ycoord, "volume": volume, "m0": solid_fraction},
  }
```
3. Run [`make.reservoir`](#digger.make.reservoir) to generate input files for D-Claw. Inspect the output and adjust any input parameters as needed.
4. 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`](#digger.make.reservoir) may be found in the file `digger/examples/pre-run/schultz_fire/make_reservoir.py`.

```{literalinclude} ../../../../../examples/pre-run/schultz_fire/make_reservoir.py
:language: python
```

:::{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](https://www.clawpack.org/topo.html) 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.

```{figure} ../../../../_static/from_examples/schultz_reservoir.png
:alt: Example digger.make.reservoir summary figure.

An example of the diagnostic output provided by digger.make.reservoir.
```