Ursa
====

Ursa is a python tool for the setup, management, and analysis of postfire debris-flow runout simulations. Ursa provides (1) a set of python functions that accomplish each phase of a hazard assessment workflow and (2) a `Snakemake <https://snakemake.readthedocs.io/en/stable/index.html>`_ snakefile that uses the python functions to run the entire workflow.

Ursa is intended as a flexible tool for a particular purpose. It is not intended as a general or extensible software package.

.. Warning::
    
    Before using ursa, review the :doc:`Disclaimer and Limitations page <src/resources/limitations>`.



Using the documentation
-----------------------

The documentation contains four elements. Most users should start with the :doc:`User Guide <src/userguide/index>`, which provides an overview of what ursa does, the computational resources it needs, and the information it produces. Should a user find that they need to run ursa, the next portion of the documentation that may interest them is the :doc:`Getting Started <src/gettingstarted/index>` section, which describes the platform requirements and installation instructions. After installation, we suggest running the example case study for the 2016 Sherpa Fire described by the :doc:`example application <src/tutorials/index>`.

Most use-cases are accommodated by modifying the ursa :doc:`config.yml <src/userguide/config>` file. However, for those with a need to add functionality or change the workflow, the :doc:`API <src/autodoc2/index>`, and other :doc:`development resources <src/resources/develop>` will be of interest.

Citation
--------

If you use ursa in a publication, cite it as follows

.. code-block:: text

    Barnhart, K.R., and Fruge, A.S., 2026, ursa - Python library for postfire
    debris-flow runout hazard assessments and research, version 1.0.0: U.S.
    Geological Survey software release, https://doi.org/10.5066/P15CKL9J.


Bibtex

.. code-block:: text

    @misc{barnhart_2025,
        title = {ursa - Python library for postfire debris-flow runout hazard
                 assessments and research, version 1.0.0},
        author = {Barnhart, K.R. and Fruge, A.S.},
        url = {https://code.usgs.gov/ghsc/lhp/ursa},
        year = {2026},
        doi = {10.5066/P15CKL9J}
    }



.. toctree::
    :caption: Documentation
    :hidden:

    Introduction <self>
    src/userguide/index
    src/gettingstarted/index
    src/tutorials/index
    src/autodoc2/index

.. toctree::
    :caption: PWFDF-R Data Spec
    :hidden:

    src/data-spec/archive/index

.. toctree::
    :caption: Resources
    :hidden: 

    src/resources/limitations
    src/resources/contribute
    src/resources/develop
    src/resources/legal