Cell2Fire Quickstart
This page represents my initial experience with to Cell2Fire, Alpha 0.11 version, a fire spread simulator that can be used for wildland fire research. It is a cell-based simulator for modeling fire spread across non-urban landscapes. It works by dividing the landscape into numerous cells, each with specific attributes such as fuel type, weather conditions, fuel moisture levels, and topography. Fire spread rate within these cells is determined by a fire spread model like the Canadian Forest Fire Behavior Prediction System. Large scale simulations can be generated quickly since Cell2Fire uses multi-threading. Its outputs include statistical, graphical output, and spatial analysis features to assist in visualizing and analyzing predicted fire growth[1]. In-depth details of the simulator, as well as comparisons with the Prometheus simulator can be found in Cell2fire: A Cell Based Forest Fire Growth Model[2].
Installation: This involves cloning the repository to a local directory from GitHub[1] and compiling using Make. The GitHub page also lists a number of libraries that need to be preinstalled prior to compiling. Linux and Mac users can install directly but Windows users may need to use the Unix subsystem or docker. Good installation instructions are available at [3]. An in-depth log of my installation experience (including problems) can be found here.
Running the Simulation: Cell2Fire is a command line program. An introduction to the basic command that launches the program can be found at [4]. A list of arguments and their explanations can be found using the usual -h flag. At its most basic you need to indicate where the input data is and where you would like the output to go. There are however many other arguments that can be used to customize the simulation.
python main.py --input-instance-folder ../data/Sub40x40/ --output-folder ../results/Sub40x40 --ignitions --sim-years 1 --nsims 5 --finalGrid --weather rows --nweathers 1 --Fire-Period-Length 1.0 --output-messages --ROS-CV 0.0 --seed 123 --stats --allPlots --IgnitionRad 5 --grids --combineExample command to run Cell2Fire simulation.
MyComputer:User$ python main.py -h
usage: main.py [-h] [--input-instance-folder INFOLDER] [--output-folder OUTFOLDER] [--sim-years SIM_YEARS]
[--nsims NSIMS] [--seed SEED] [--nweathers NWEATHERS] [--nthreads NTHREADS]
[--max-fire-periods MAX_FIRE_PERIODS] [--IgnitionRad IGRADIUS] [--gridsStep GRIDSSTEP]
[--gridsFreq GRIDSFREQ] [--heuristic HEURISTIC] [--MessagesPath MESSAGES_PATH] [--GASelection]
[--HarvestedCells HCELLS] [--msgheur MSGHEUR] [--applyPlan PLANPATH] [--DFraction TFRACTION]
[--GPTree] [--customValue VALUEFILE] [--noEvaluation] [--ngen NGEN] [--npop NPOP] [--tsize TSIZE]
[--cxpb CXPB] [--mutpb MUTPB] [--indpb INDPB] [--weather WEATHEROPT] [--spreadPlots] [--finalGrid]
[--verbose] [--ignitions] [--grids] [--simPlots] [--allPlots] [--combine] [--no-output]
[--gen-data] [--output-messages] [--Prometheus-tuned] [--trajectories] [--stats]
[--correctedStats] [--onlyProcessing] [--bbo] [--fdemand] [--pdfOutputs]
[--Fire-Period-Length INPUT_PERIODLEN] [--Weather-Period-Length WEATHER_PERIOD_LEN]
[--ROS-Threshold ROS_THRESHOLD] [--HFI-Threshold HFI_THRESHOLD] [--ROS-CV ROS_CV]
[--HFactor HFACTOR] [--FFactor FFACTOR] [--BFactor BFACTOR] [--EFactor EFACTOR]
[--BurningLen BURNINGLEN]
options:
-h, --help show this help message and exit
--input-instance-folder INFOLDER
The path to the folder contains all the files for the simulation
--output-folder OUTFOLDER
The path to the folder for simulation output files
--sim-years SIM_YEARS
Number of years per simulation (default 1)
--nsims NSIMS Total number of simulations (replications)
--seed SEED Seed for random numbers (default is 123)
--nweathers NWEATHERS
Max index of weather files to sample for the random version (inside the Weathers Folder)
--nthreads NTHREADS Number of threads to run the simulation
--max-fire-periods MAX_FIRE_PERIODS
Maximum fire periods per year (default 1000)
--IgnitionRad IGRADIUS
Adjacents degree for defining an ignition area (around ignition point)
--gridsStep GRIDSSTEP
Grids are generated every n time steps
--gridsFreq GRIDSFREQ
Grids are generated every n episodes/sims
--heuristic HEURISTIC
Heuristic version to run (-1 default no heuristic, 0 all)
--MessagesPath MESSAGES_PATH
Path with the .txt messages generated for simulators
--GASelection Use the genetic algorithm instead of greedy selection when calling the heuristic
--HarvestedCells HCELLS
File with initial harvested cells (csv with year, number of cells: e.g 1,1,2,3,4,10)
--msgheur MSGHEUR Path to messages needed for Heuristics
--applyPlan PLANPATH Path to Heuristic/Harvesting plan
--DFraction TFRACTION Demand fraction w.r.t. total forest available
--GPTree Use the Global Propagation tree for calculating the VaR and performing the heuristic plan
--customValue VALUEFILE
Path to Heuristic/Harvesting custom value file
--noEvaluation Generate the treatment plans without evaluating them
--ngen NGEN Number of generations for genetic algorithm
--npop NPOP Population for genetic algorithm
--tsize TSIZE Tournament size
--cxpb CXPB Crossover prob.
--mutpb MUTPB Mutation prob.
--indpb INDPB Individual prob.
--weather WEATHEROPT The 'type' of weather: constant, random, rows (default rows)
--spreadPlots Generate spread plots
--finalGrid Generate final grid
--verbose Output all the simulation log
--ignitions Activates the predefined ignition points when using the folder execution
--grids Generate grids
--simPlots Generate simulation/replication plots
--allPlots Generate spread and simulation/replication plots
--combine Combine fire evolution diagrams with the forest background
--no-output Activates no-output mode
--gen-data Generates the Data.csv file before the simulation
--output-messages Generates a file with messages per cell, hit period, and hit ROS
--Prometheus-tuned Activates the predefined tuning parameters based on Prometheus
--trajectories Save fire trajectories FI and FS for MSS
--stats Output statistics from the simulations
--correctedStats Normalize the number of grids outputs for hourly stats
--onlyProcessing Read a previous simulation OutFolder and process it (Cell2Fire simulation is not called)
--bbo Use factors in BBOFuels.csv file
--fdemand Finer demand/treatment fraction
--pdfOutputs Generate pdf versions of all plots
--Fire-Period-Length INPUT_PERIODLEN
Fire Period length in minutes (needed for ROS computations). Default 60
--Weather-Period-Length WEATHER_PERIOD_LEN
Weather Period length in minutes (needed weather update). Default 60
--ROS-Threshold ROS_THRESHOLD
A fire will not start or continue to burn in a cell if the head ros is not above this
value (m/min) default 0.1.
--HFI-Threshold HFI_THRESHOLD
A fire will not start or continue to burn in a cell if the HFI is not above this value
(Kw/m) default is 10.
--ROS-CV ROS_CV Coefficient of Variation for normal random ROS (e.g. 0.13), but default is 0
(deterministic)
--HFactor HFACTOR Adjustment factor: HROS
--FFactor FFACTOR Adjustment factor: FROS
--BFactor BFACTOR Adjustment factor: BROS
--EFactor EFACTOR Adjustment ellipse factor
--BurningLen BURNINGLEN Burning length period (periods a cell is burning)
Example of help text for Cell2Fire command line options.
Demo Files: There are many good demo files within the Cell2Fire installation folder in ./tests and ./contributed. An in-depth tutorial of a 9x9 cell example can be found at [5]. The input files for the tutorial demonstrate how straightforward a Cell2Fire simulation can be. All that is needed is .asc file (GIS Ascii) representing the composition of the forest (fuel load) and a .csv with each row representing the fire weather for 1 time step. The more rows you have more time steps. Simulations can become more complex by adding more inputs such as elevation maps in .asc format. The examples section and files provided in the ./tests folder are good examples of what can be done. In particular, multiple runs may be done at once on a single set of input data using different probabilisticly determined ignition points. One key file that is not clearly explained in the tutorials (that I have seen) is the Data.csv file. This file holds the assembled data for each cell from all the different inputs and is key to the program functioning properly. For instance it lists the fuel type, latitude, longitude, fire weather, time, elevation, etc. Changing the fuel type in your forest.asc file and not changing it in Data.csv will result in no change in the simulation. So, keep the Data.csv file up-to-date!
Outputs: The results of a simulation, or many simulations, are output in .csv and .png formats. An overall summary can be provided as well as information for each time step. The data within the .csv files can be filtered to just focus on 1 cell within the cell grid. Since Cell2Fire is time based data and images for each time step is produced, and if you are running multiple versions of the same simulation each version gets its own folder of results.
Other Features: Random Ignitions and Random Weather can be generated by Cell2Fire to introduce additional stochastics into the simulation[6]. One of the purposes of Cell2Fire is to act as a tool for forest management. To this end various heuristics are provided to simulate different forest treatments and their effectiveness[7].
Other Fire Spread Simulators: There are many other wildfire simulators available, each with its own strengths and weaknesses. Some notable examples include FlamMap and Burn-P3+. The Missoula Fire Sciences Laboratory creates a number of products that simulate how individual elements such as wind can effect wildland fire. For some papers covering simulators see A Comparative Review on Wildfire Simulators, Software-Based Simulations of Wildfire Spread and Wind-Fire Interaction and Applications of Simulation-Based Burn Probability Modelling: a Review.
16x16 grid with fire break added
[1] Cell2Fire: A Cell-Based Forest Fire Growth Model. Accessed: Jul. 24, 2024. [Online]. Available: https://github.com/cell2fire/Cell2Fire
[2] C. Pais, J. Carrasco, D. L. Martell, A. Weintraub, and D. L. Woodruff, “Cell2Fire: A Cell-Based Forest Fire Growth Model to Support Strategic Landscape Management Planning,” Frontiers in Forests and Global Change, vol. 4, 2021. [Online]. Available: https://www.frontiersin.org/articles/10.3389/ffgc.2021.692706
[3] “Cell2Fire Installation Guide,” Accessed: Jul. 24, 2024. [Online]. Available: https://cell2fire.readthedocs.io/en/latest/rstfiles/install.html
[4] Cell2Fire: Running the Simulation. Accessed: Jul. 24, 2024. [Online]. Available: https://cell2fire.readthedocs.io/en/latest/rstfiles/run.html
[5] Cell2Fire: Examples. Accessed: Jul. 24, 2024. [Online]. Available: https://cell2fire.readthedocs.io/en/latest/rstfiles/examples.html
[6] Cell2Fire: Stochastics?. Accessed: Jul. 24, 2024. [Online]. Available: https://cell2fire.readthedocs.io/en/latest/rstfiles/HarvestPlan.html
[6] Cell2Fire: Heuristics. Accessed: Jul. 24, 2024. [Online]. Available: https://cell2fire.readthedocs.io/en/latest/rstfiles/heuristics.html
This web page was last updated July 2024.