Getting started with BurnP3+
Here we provide a guided tutorial on BurnP3+, an open-source package for running spatially-explicit fire growth models to explore fire risk and susceptibility across a landscape.
BurnP3+ extends Burn-P3 (Parisien et al. 2005) by enhancing scalability, cross-compatibility, and flexibility (visit our Home page for more background information). BurnP3+ is built as a base package for SyncroSim, yet familiarity with SyncroSim is not required to get started with BurnP3+. Throughout the Quickstart tutorial, terminology associated with SyncroSim will be italicized, and whenever possible, links will be provided to the SyncroSim online documentation. For more on SyncroSim, please refer to the SyncroSim Overview and Quickstart tutorial.
BurnP3+ Quickstart Tutorial
This Quickstart tutorial will introduce you to the basics of working with BurnP3+ in the Windows User Interface (UI). The steps include:
- Installing BurnP3+ and required fire growth add-on packages
- Creating a new BurnP3+ Library
- Configuring the BurnP3+ Library to:
- Running the model
- Analyzing the model results
Step 1: Installing BurnP3+ and required fire growth add-on packages
Running BurnP3+ requires that the SyncroSim software be installed on your computer (version 2.4.10 or higher). Download the latest version of SyncroSim here and follow the installation prompts.
An additional Add-on Package to BurnP3+ is also available: burnP3PlusPrometheus. Unlike the Cell2Fire fire growth model that is raster-based, Prometheus is vector-based and capable of executing fine-scale simulations. This degree of accuracy, however, is more computationally demanding in terms of memory use. Moreover, running a burnP3PlusPrometheus model requires the installation of Prometheus 2021.12.03.
To install the BurnP3+ Package and the burnP3PlusCell2Fire Add-on Package, open the SyncroSim Windows UI (Start > Apps > SyncroSim) and select File > Packages….
Click on the Install… button.
Mark the checkboxes beside burnP3Plus and burnP3PlusCell2Fire, and click OK.
If you do not have Miniconda installed in your computer, a dialog box will open asking if you would like to install Miniconda. Click Yes. Once Miniconda is done installing, a dialog box will open asking if you would like to create a new conda environment. Click Yes.
Miniconda is an installer for conda, a package environment management system that installs any required packages and their dependencies. By default, BurnP3+ runs conda to install, create, save, and load the required environment for running BurnP3+. The BurnP3+ environment includes the R software environment and associated packages.
Step 2: Creating a new BurnP3+ Library
Having installed BurnP3+ and burnP3PlusCell2Fire, you are now ready to create your first SyncroSim Library. A Library is a file (with extension .ssim) that contains all of your model inputs and outputs. To create a new Library, select File > New Library….
When a new window opens, select the row for burnP3Plus - BurnP3+ package for burn probability modeling.
Then, select the Cell2Fire Example template as shown above. You can accept the default File name and Folder, or optionally type in a new file name for the Library and change the target folder using the Browse… button.
When you are ready to create the Library file, click OK. A new Library will be created and loaded into the Library Explorer window.
The Library Cell2Fire Example contains a Project named Definitions, with one Scenario named Baseline Burning Hours. This Library template uses a synthetic landscape to demonstrate the basics of running BurnP3+ using the Cell2Fire model as the fire growth model, and to assess the effects of burning conditions on fire risk across the landscape.
Step 3: Configuring the BurnP3+ Library
This Quickstart tutorial demonstrates the Cell2Fire fire growth model, which is already enabled as an Add-on Package in this template Library.
This information can be found by selecting File > Library Properties and navigating to the Add-ons tab. Here you’ll find that the burnP3PlusCell2Fire add-on package is enabled.
Next, on the Library Explorer window, double click on Definitions. Definitions are Project Datafeeds containing data shared across all Scenarios for a Project.
Navigate to the Fuels tab, under Fuel Types you will find a Name list for each of the fuel types present in the fuel grid, which the model requires as input. For the purposes of this Quickstart tutorial, the Library template was pre-loaded with a fuel grid with two fuel types: Boreal Spruce and Lodgepole Pine Slash. Note that these names are free-form and can be arbitrary. Each Name is associated with an ID that must correspond to the labels given to each fuel type in the fuel grid loaded for each scenario.
Next, under Cell2Fire Crosswalk, each fuel type listed under the Fuel Types tab needs to be linked to one of the fuel codes recognized by Cell2Fire. In the case of these two fuel types, Cell2Fire recognizes the Canadian Forest Service Fuel Codes C2 and S1.
Lastly, on the Library Explorer window, you will see one Scenario named Baseline Burning Hours. Model inputs in SyncroSim are organized into Scenarios. Each Scenario is associated with Scenario Datafeeds containing data that are specified for each Scenario.
To view the model inputs for the Scenario, double-click on Baseline Burning Hours.
On the General tab, the Pipeline Datasheet allows users to select the stages to include in the model run and their order. A full run of BurnP3+ consists of four stages: (1) Sample the number and locations of ignitions for each simulated burn season, or iteration; (2) Sample the burning conditions for each ignitions, which depend on when and where the ignitions occurred; (3) Simulate each fire deterministically using a fire growth model; and (4) Summarise the outputs of the fire growth model to calculate burn probability and other burn metrics. In this example, we will run the full pipeline:
- Stage 1: Sample ignitions
- Stage 2: Sample burn conditions
- Stage 3: Grow fires
- Stage 4: Summarize burn probability
The second tab, Run Control, allows users to specify the number of iterations or Monte Carlo realizations to run. In this example, each Scenario will run for 100 Iterations. Each iteration represents a stochastic simulation of a single fire season. Typically, BurnP3+ should be run for tens of thousands of iterations.
The Landscape Maps tab contains the pre-loaded raster files for Fuel and Elevation.
Raster files for Fire Zone and Weather Zone are optional and will not be considered in this Quickstart tutorial. These raster files allow end users to stratify the landscape and define different statistical distributions for model inputs and summarize model outputs according to these zones. For example, daily weather may vary according to Weather Zone.
The following four tabs contain the rules for stages 1 to 4.
Stage 1: Sample Ignitions
Under the Sample Ignitions tab, the Ignition Count Datasheet defines the number of fires that should be ignited every iteration within a season. For the purposes of this Quickstart tutorial, Ignition Count was set to 1.
Stage 2: Sample burn conditions
Navigate to the next tab, Sample Burning Conditions. The Spread Event Days Datasheet specifies the number of days uncontrolled fires are actively burning and spreading in a season. Similarly, for the purposes of this Quickstart tutorial, Spread Event Days was set to 1.
The Daily Burning Hours Datasheet defines the number of hours fires are actively burning per day. For the Baseline Burning Hours Scenario, Daily Burning Hours was set to 4.
The Daily Weather Datasheet specifies weather variables for the landscape of interest. Each row corresponds to one day of weather data. The required variables are: temperature, relative humidity, wind speed, wind direction, precipitation, fine fuel moisture code, duff moisture code, drought code, initial spread index, buildup index, and fire weather index.
Stage 3: Grow fires
Under the Fire Growth Model Options tab, all settings are optional. However, as advanced features, they will not be covered in this Quickstart tutorial. By leaving the Fire Growth Model Options empty, BurnP3+ will use the default values.
Stage 4: Summarize burn probability
Finally, the Output Options tab specifies which outputs will be generated after running the Scenario. All Tabular and Spatial output options are set to Yes. The only exception is Spatial > Burn Perimeters, which is not provided by Cell2Fire.
Note: If all rows in the Spatial Output Options Datafeed are left blank, BurnP3+ will default to generating all spatial outputs. However, if only some rows are set to return spatial outputs, the model will only return outputs for the specified rows.
Close the window for the Scenario Baseline Burning Hours.
Next, you will create a new Scenario to compare the effects of Daily Burning Hours on fire risk. While you could create a new empty Scenario, instead you will copy, paste, and modify the existing Scenario to save time and reuse the model inputs. To do so, on the Library Explorer window, right-click on the current Scenario (Baseline Burning Hours), and select Copy and Paste from the context menu.
Rename the Scenario by right clicking the newly created Scenario, selecting Rename… from the context menu, and typing Extended Burning Hours. Next, double click on the Scenario Extended Burning Hours and navigate to the Sample Burning Conditions tab. Here, you will modify the input Daily Burning Hours from 4 to 6.
Step 4: Running the model
After reviewing the model inputs and creating a new Scenario, you are now ready to run the model.
Multiprocessing is enabled to run 6 jobs in parallel. You can adjust the number of multiprocessing jobs according to the specifications of your computer. A good rule of thumb to follow is number of logical cores minus 1.
Next, right-click on the Scenario Baseline Burning Hours, and from the context menu select Run. If prompted to save your project, click Yes.
A Run Monitor window will appear, indicating the Status of the Scenario as Running. At the bottom of the SyncroSim Windows UI, an orange progress bar will provide further information during each stage of the pipeline.
When and if the run is successful, you will see the Status of Done in the Run Monitor. If an error or warning has been issued, click on the Run Log link to see a report of problems. Make any required changes to your Scenario and re-run it. If necessary, see Key Links on the Home page for support.
Running a model in SyncroSim produces Scenario Results, which contain the input Datafeeds associated with the parent Scenario, as well as output Datafeeds for the Scenario run. Each Scenario Result inherits the parent Scenario’s name and receives a unique ID.
Repeat the same process to run the Scenario Extended Burning Hours.
Step 5: Analyzing the model results
To view the tabular results from each of your runs, double-click on one of your Scenario Results and navigate to the last tab, Output Fire Statistics. Here, you can view the results and have the option to export the data by right-clicking anywhere on the spreadsheet, and selecting Export All from the context menu.
Next, move to the results panel at the bottom left of the Library Explorer window. Under the Charts tab, double-click on Burn Area by Fuel Type to see the tabular results for area burned.
Next, navigate to the Maps tab and double-click on Burn Probability Maps.
Lastly, under the Maps tab you can also find the Input Maps for fuel type and elevation.
Note: Map legends can be customized by double-clicking on the bins. You can also add and remove Scenario Results being charted or mapped by selecting a Scenario Result in the Library Explorer and then choosing either Add to Results or Remove from Results from context menu. Scenarios with results currently selected for analysis are highlighted in bold in the Library Explorer.