# User guide

Ursa is a tool for managing sets of debris-flow runout simulations intended to support postfire debris-flow runout hazard assessments. To accomplish this task, ursa provides (1) a set of python functions that implement steps within a workflow that culminates in a set of files indicating the likely location of postfire debris-flow material under different 15-minute rainfall intensity ($I_{15}$, mm/hr) scenarios and (2) a workflow definition implemented as a [Snakemake](https://snakemake.readthedocs.io/en/stable/index.html) snakefile. The python functions and snakefile were developed together and are intended for use together.

This user guide starts by describing the [conceptual model](conceptual.md) for debris-flow initiation that underlies ursa. It then describes the specific [workflow](workflow.md) implemented, [computational resources](resources.md) required, and [typical usage](usage.md). Next, the user guide covers the [configuration](config.rst) and resulting [filestructure](filestructure.md), [results](results.md), and [plots](plots.md). The snakefile uses ursa by invoking the command line interface, summarized [here](cli.md). Finally, information about [quality assurance](qa.md), running on [slurm clusters](slurm.md), and uploading hazard assessment results to [ScienceBase](sciencebase.md) is provided.

:::{warning}
Ursa assumes a working knowlege of the postfire debris-flow literature. It does not provide a primer on debris-flow processes. Instead it provides references to the most relevant publications.
:::

## Glossary

Ursa has specific definitions for some words. Here we summarize these words and provide their definitions.

- **project:** A directory containing all files associated with a single region of analysis, typically a single fire perimeter. Within a project, all necessary assets are compiled, a set of runs is configured, launched, postprocessed, and quality controlled.
- **basin:** A watershed delineated by a postfire debris-flow susceptibility assessment (e.g., using [pfdf](https://code.usgs.gov/ghsc/lhp/pfdf/) or [wildcat](https://code.usgs.gov/ghsc/lhp/wildcat/)).
- **segment:** A stream segment within a basin.
- **outlet:** The highest drainage area location in a basin.
- **region:** A polygon that may be used to spatially parallelize runout model simulations. The default behavior is to use [HUC12 watersheds](https://www.usgs.gov/national-hydrography/watershed-boundary-dataset).
- **run:** One or more simulations conducted with D-Claw that all use the same model input parameters. One run may be comprised of multiple simulations, one simulation per region.
- **simulation:** A single simulation with D-Claw, typically associated with a single set of model input parameters and a single region.
- **debris-flow simulation index:** The fraction of simulations that reach a specific location within the simulation domain. 


```{toctree}
---
caption: User guide
hidden: True
---
conceptual.md
simulationindex.md
workflow.md
resources.md
usage.md
config.rst
filestructure.md
assets.md
results.md
plots.md
cli.md
qa.md
slurm.md
sciencebase.md
```