# Digger

Digger is a python package that provides a number of pre- and post-processing tools for working with landslide runout models. It has been tailored for use with the [D-Claw model](https://github.com/geoflows/dclaw). It may also be useful for initializing and postprocessing the results of other runout models.

D-Claw requires input files and generates output files in very specific formats. Simulation output generates files in a specific format (see the [clawpack documentation for more detail](https://www.clawpack.org/contents.html#full-table-of-contents)). The purpose of this package is to make it easier to create these input files and conduct semi-standard analyses on the output files.

The package is broken into modules that focus on different tasks within a typical runout modeling workflow. [`digger.make`](#digger.make) provides functions that *make* spatially variable input files (e.g., depth of landslide material). [`digger.analyze`](#digger.analyze) provides functions to *analyze* simulation output. [`digger.compare`](#digger.compare) provides functions that *compare* simulation output with observations. Finally, [`digger.utils`](#digger.utils) provides many utility functions for use with digger-enabled workflows.

## License

Digger uses the [GPLv3 license](https://code.usgs.gov/ghsc/lhp/digger/-/blob/main/LICENSE.md?ref_type=heads). Read more about this license [here](https://www.gnu.org/licenses/gpl-3.0.en.html).

## Using the documentation

The documentation contains multiple elements. Most users should start with the [User Guide](src/user-guide/index.md), which provides an overview of what digger does. Next, look through the [examples](src/user-guide/examples/index.md) within the user guide, which describe some example applications. Should a user find that they want to install and use digger themselves, they can refer to the [installation instructions](src/getting-started/index.md).

Finally, refer to the [API](src/autodoc2/index.rst) for function-level documentation.

:::{note}
digger is scientific software. A user should expect to gain a high-level understanding of what is being done by each function using the documentation. For detailed understanding, a user should expect to read the source code of the functions they are using.
:::

:::{warning}
digger was designed to make it easier to run D-Claw, a model based on the [clawpack package](https://www.clawpack.org/). This documentation presumes knowledge of how D-Claw and clawpack applications are specified. Where most relevant, links to clawpack documentation are provided. Without knowledge of clawpack application specification and file formats, some aspects of digger may be confusing.
:::

## Citation

If you use digger in a publication, cite it as follows:


```none
Barnhart, K.R., George, D. L., Collins, A.L., Amaral, T.O., 2024, digger -
Utility tools for landslide runout modeling, version 1.1: U.S. Geological
Survey software release, https://doi.org/10.5066/P14TUMBB.
```

Bibtex:
```none
@misc{barnhart2024digger,
    title = {digger - Utility tools for landslide runout modeling, version 1.1},
    author = {Barnhart, K.R. and George, D. L. and Collins, A.L. and Amaral, T.O.},
    url = {https://code.usgs.gov/ghsc/lhp/digger},
    year = {2024},
    doi = {10.5066/P14TUMBB}
}
```


```{toctree}
---
caption: Documentation
hidden: True
---
src/user-guide/index.md
src/getting-started/index.md
src/autodoc2/index.rst
```

```{toctree}
---
caption: Resources
hidden: True
---
src/resources/index.md
```