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 snakefile. The python functions and snakefile were developed together and are intended for use together.

This user guide starts by describing the conceptual model for debris-flow initiation that underlies ursa. It then describes the specific workflow implemented, computational resources required, and typical usage. Next, the user guide covers the configuration and resulting filestructure, results, and plots. The snakefile uses ursa by invoking the command line interface, summarized here. Finally, information about quality assurance, running on slurm clusters, and uploading hazard assessment results to ScienceBase 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 or 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.

  • 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.