Implemented workflow

Ursa will execute a series of steps to setup, run, and finalize a runout hazard assessment for a specific fire. This page provides a high-level summary of the workflow ursa implements. Broadly, each blue box in the below figure corresponds to a function within the ursa API.

A user will specify the number of runs by modifying the configuration file. Ursa then uses snakemake to follow the below workflow. If ursa is interrupted, it will start where it left off using snakemake’s built-in restart capabilities.

Regions

An important feature within ursa is splitting up the entire fire into regions for which simulations may be undertaken in parallel. This feature was added to ursa because fire perimeters may span 10s to 1000s of square kilometers. It is not feasible or necessary to run D-Claw simulations for the entire fire at the same time. Rather, a single simulation is run for each region (by default, HUC12 watershed boundary polygons).

A user may specify regions as an optional input.

Note

The authors are aware that not all of the text is visible on this diagram. The diagram was made with mermaid and we have not yet figured out how to make all elements legible. We expect to eventually replace the diagram with one that is fully legible.

Workflow diagram

        flowchart TD
    A{START} --> B[Compile D-Claw]

    A --> C[Determine extent of fire]
    subgraph Setup["`**Setup**
        Prepare all files and directories`"]

    C -->D["`Preprocess inputs
    - parallel map
    - topography
    - EVT
    - roads
    - buildings
    -streams`"]
    D --> E[Run susceptibility hazard assesment]
    E --> I["`Generate a set of N runs *each with a different parameter set*`"]
    B --> I

    end
    subgraph Run["`**Run**
    Parallelize the N runs by breaking each run into M simulations`"]

    I --> J[Run 1]
    I --> K[Run 2]
    I --> L[Run N]
    J --> M[Simulation 1]
    J --> N[Simulation 2]
    J --> O[Simulation M]
    K --> P[Simulation 1]
    K --> Q[Simulation 2]
    K --> R[Simulation M]
    L --> S[Simulation 1]
    L --> T[Simulation 2]
    L --> U[Simulation M]
        M --> V[Collate Run 1]
    N --> V
    O --> V
    P --> W[Collate Run 2]
    Q --> W
    R --> W
    S --> X[Collate Run N]
    T --> X
    U --> X
    end

    subgraph Finalize["`**Finalize**
    Analyze results and generate plots`"]

    V --> Y[Synthesize Runs]
    W --> Y
    X --> Y
    Y --> AA[Quality control]
    Y --> BB[Geospatial files]
    Y --> Z[Exposure analysis]
    Y --> CC[Diagnostic plots]
    end
    AA --> ZZ{END}
    BB --> ZZ{END}
    Z --> ZZ{END}
    CC --> ZZ{END}
    

Generating a workflow diagram from snakemake

To see a visual depiction of exactly what snakemake is executing, the following two command line calls may be helpful. These commands will only work from within the top-level of project directory created by ursa initialize because they point to the expected location of the snakefile at workflow/Snakefile.

snakemake -s workflow/Snakefile --dag | dot -Tpdf > dag.pdf
snakemake -s workflow/Snakefile --rulegraph | dot -Tpdf > rulegraph.pdf

Note, the simulation steps in the above flowchart will not be fully depicted by the diagrams made by snakemake.