Cell2Fire Class Reference

Collaboration diagram for Cell2Fire:

Public Member Functions
	Cell2Fire (arguments args)
	Constructs and initializes the Cell2Fire object to run a simulation.
void	InitCell (int id)
	Initializes a cell within the simulation and adds it to the cell collection.
void	reset (int rnumber, double rnumber2, int simExt)
	Resets the simulation environment for a new run.
bool	RunIgnition (std::default_random_engine generator, int ep)
	Simulates the ignition phase of the fire spread model for a single simulation year.
std::unordered_map< int, std::vector< int > >	SendMessages ()
	Message-sending phase of the fire spread model, where burning cells propagate fire messages to neighboring cells.
void	GetMessages (std::unordered_map< int, std::vector< int > > sendMessageList)
	Processes incoming fire messages to determine the ignition and progression of fire in cells.
void	Results ()
	Generates and outputs simulation results, including fire behavior metrics, final grid status, and logs.
void	outputGrid ()
	Outputs the current state of the forest grid to a CSV file.
void	updateWeather ()
	Updates the weather conditions during the simulation based on specified criteria.
void	Step (std::default_random_engine generator, int ep)
	Executes a single simulation step in the forest fire model.
void	InitHarvested ()
std::vector< float >	getROSMatrix ()
	Retrieves the Rate of Spread (ROS) matrix for all cells.
std::vector< float >	getFireProgressMatrix ()
	Retrieves the Fire Progress matrix for all cells.

Public Attributes
arguments	args
arguments *	args_ptr
fuel_coefs *	coef_ptr
fuel_coefs	coefs [18]
int	sim
int	rows
int	cols
int	widthSims
int	weatherPeriod = 0
int	year = 1
int	gridNumber = 0
int	weatherperiod = 0
int	counter_wt = 0
long int	nCells
int	nIgnitions = 0
double	xllcorner
double	yllcorner
bool	noIgnition = true
bool	activeCrown = false
bool	messagesSent = false
bool	repeatFire = false
bool	done = false
bool	noMessages = false
double	cellSide
double	areaCells
double	perimeterCells
double	ROSRV
string	gridFolder
string	messagesFolder
string	rosFolder
string	crownFolder
string	surfaceIntensityFolder
string	crownIntensityFolder
string	sfbFolder
string	cfbFolder
string	surfaceFlameLengthFolder
string	maxFlameLengthFolder
string	crownFlameLengthFolder
string	historyFolder
string	ignitionsFolder
std::vector< int >	fire_period
std::vector< std::vector< int > >	coordCells
std::vector< std::unordered_map< std::string, int > >	adjCells
std::vector< std::vector< std::string > >	DF
std::vector< std::vector< std::string > >	WDist
std::vector< std::string >	WeatherHistory
std::vector< float >	ignProb
std::vector< int >	statusCells
std::vector< int >	fTypeCells
std::vector< string >	fTypeCells2
std::vector< std::vector< std::string > >	WeatherDF
std::vector< int >	IgnitionPoints
vector< int >	burnedOutList
std::vector< double >	FSCell
std::vector< float >	crownMetrics
std::vector< int >	crownState
std::vector< float >	surfaceIntensities
std::vector< float >	crownIntensities
std::vector< float >	crownFraction
std::vector< float >	surfFraction
std::vector< float >	RateOfSpreads
std::vector< float >	surfaceFlameLengths
std::vector< float >	crownFlameLengths
std::vector< float >	maxFlameLengths
std::vector< std::vector< int > >	IgnitionSets
std::unordered_set< int >	availCells
std::unordered_set< int >	nonBurnableCells
std::unordered_set< int >	burningCells
std::unordered_set< int >	burntCells
std::unordered_set< int >	harvestCells
std::unordered_map< int, Cells >	Cells_Obj

Constructor & Destructor Documentation

Cell2Fire()

Cell2Fire::Cell2Fire

(

arguments

_args

)

Constructs and initializes the Cell2Fire object to run a simulation.

This constructor initializes the Cell2Fire object by reading configuration and data files required for simulating fire spread in a forested environment. It populates various member variables, including fuel coefficients, forest structure, weather data, ignition points, and other simulation-related parameters. It also performs preprocessing steps to categorize cells into burnable and non-burnable types and to establish fire ignition sets.

Parameters

_args

List of command line arguments containing configuration and file paths needed for the simulation.

Returns

A fully initialized Cell2Fire object ready for simulation.

Notes:

• Initializes forest data from the fuels data and Data.csv files.
• Initializes weather data from Weather.csv and optionally WeatherDistribution.csv.
• Processes ignition points from Ignitions.csv (if provided) and computes adjacent cells based on the ignition radius.
• Categorizes cells as burnable, non-burnable, or harvested based on input data.
• If BBO tuning is enabled, initializes tuning factors using BBOFuels.csv.
• Validates and adjusts simulation parameters based on the weather file consistency.

Here is the call graph for this function:

Member Function Documentation

getFireProgressMatrix()

std::vector< float > Cell2Fire::getFireProgressMatrix

(

)

Retrieves the Fire Progress matrix for all cells.

Returns

A vector of floats representing the fire progress values for each cell.

GetMessages()

void Cell2Fire::GetMessages

(

std::unordered_map< int, std::vector< int > >

sendMessageList

)

Processes incoming fire messages to determine the ignition and progression of fire in cells.

This method handles the reception and processing of messages sent by burning cells. Based on the received messages, cells may ignite, continue burning, or be marked as burnt out. The method also manages the transitions between fire periods and updates relevant cell sets (e.g., available, burning, burnt).

Parameters

sendMessageList

A map where each key is the ID of a burning cell, and the associated value is a list of neighboring cell IDs that received fire messages from that cell.

Detailed Behavior:

• For each cell receiving messages:
  • Initializes the cell if it hasn't been processed before.
  • Checks ignition conditions and marks the cell as burnt if applicable.
  • Updates fire-related metadata, ensuring fire does not propagate back to the sender cell.

Key Updates:

• burntCells: Updated with cells that are fully burnt.
• burningCells: Updated with newly ignited cells.
• availCells: Reduced by removing newly burning cells.
• fire_period: Incremented at the end of each fire period.
• year: Incremented if no messages are sent and repeatFire is false.

Verbose Mode:

When args.verbose is enabled:

• Logs detailed information about fire messages, ignition, and cell state transitions.
• Prints the current state of cell sets (available, non-burnable, burning, burnt, harvested).

Weather Updates:

• Calls updateWeather to apply weather conditions for the next fire period.
• Provides a note if the weather is constant, indicating its effect on the fire model.

Here is the call graph for this function:

Here is the caller graph for this function:

getROSMatrix()

std::vector< float > Cell2Fire::getROSMatrix

(

)

Retrieves the Rate of Spread (ROS) matrix for all cells.

Returns

A vector of floats representing the ROS values for each cell.

InitCell()

void Cell2Fire::InitCell

(

int

id

)

Initializes a cell within the simulation and adds it to the cell collection.

This method creates a Cells object for the specified cell ID, populates it with the necessary parameters, and stores it in the Cells_Obj unordered map. It also initializes the fire-related fields for the cell and, if verbose mode is enabled, prints debugging information about the cell.

Parameters

id	The ID of the cell to initialize.

Details:

• The Cells object is constructed using the cell's properties, including:
  • areaCells: The area of the cell.
  • coordCells: The coordinates of the cell.
  • fTypeCells: The fuel type of the cell.
  • fTypeCells2: A textual description of the fuel type.
  • perimeterCells: The perimeter of the cell.
  • statusCells: The status of the cell (e.g., burning, available).
  • id: The identifier for the cell.
• The newly created cell is added to the Cells_Obj unordered map.

Here is the caller graph for this function:

outputGrid()

void Cell2Fire::outputGrid

(

)

Outputs the current state of the forest grid to a CSV file.

This method generates a binary representation of the forest grid, with cell statuses indicating their condition (burning, burnt, harvested, etc.) during the simulation. The file is saved with a unique name in the designated output folder.

Behavior:

• Cell Status Update:
  • Updates a vector (statusCells2) to reflect the current statuses of cells:
    • 1 for burning or burnt cells.
    • -1 for harvested cells.
    • 0 for all other cells.
• File Naming:
  • Constructs a file name based on the simulation's gridNumber and saves it in the gridFolder directory.
  • File names follow the pattern: ForestGrid<gridNumber>.csv.
• Verbose Mode:
  • Logs the file name and output process to the console if args.verbose is enabled.
• Output Format:
  • The CSV file represents the forest grid in rows and columns, with each cell's status stored in statusCells2.

Outputs:

• A CSV file is saved in the gridFolder directory, with the grid's state for the current simulation step.
• Example CSV content:

  0, 0, 1, 0
  0, -1, 0, 1
  1, 0, 0, 0

Notes:

• Ensure the gridFolder directory exists before calling this method to avoid file I/O errors.
• The method automatically increments gridNumber after each call to ensure unique file names.

Here is the caller graph for this function:

reset()

void Cell2Fire::reset	(	int	rnumber,
		double	rnumber2,
		int	simExt = 1
	)

Resets the simulation environment for a new run.

This method initializes and resets all relevant parameters, structures, and files needed for the simulation. It handles:

• Global simulation parameters
• Output directories and files
• Weather configuration
• Randomized inputs for fire spread simulation
• Data structures related to cells and fire metrics

Parameters

rnumber	Random seed or identifier for weather selection.
rnumber2	Random value for initializing ROS (Rate of Spread) variations.
simExt	Simulation extension identifier (default: 1).

Here is the call graph for this function:

Results()

void Cell2Fire::Results

(

)

Generates and outputs simulation results, including fire behavior metrics, final grid status, and logs.

This method processes the results of the fire simulation, updating cell statuses and generating various outputs such as grid data, fire spread metrics, and intensity logs. It supports multiple file formats (e.g., CSV, ASCII) and organizes output into designated folders for easy analysis and debugging.

Behavior:

• Updates the status of cells:
  • burntCells and burningCells are marked as fully burnt (status = 2).
• Computes summary statistics:
  • Reports the number and percentage of available, burnt, non-burnable, and firebreak cells.
• Writes outputs to files:
  • Grid Status: Outputs the final grid state to a CSV file if args.FinalGrid is enabled.
  • Network Messages: Logs fire message data to a CSV file if args.OutMessages is enabled.
  • Fire Spread Metrics:
    • Rate of Spread (ROS)
    • Byram Intensity
    • Flame Length
    • Crown Fraction Burn
    • Surface Fraction Burn
    • Crown Fire Behavior
• Ignition Log: Logs ignition history if args.IgnitionsLog is enabled.

Outputs:

• The output files are organized into subfolders under the designated output directory (args.OutFolder).
• Naming conventions include simulation IDs (sim) to ensure unique file names.
• File types:
  • CSV for grids and messages.
  • ASCII for rate of spread, intensity, flame length, and other fire behavior metrics.

Example Output:

----------------------------- Results -----------------------------
Total Available Cells:    120 - % of the Forest: 40.0%
Total Burnt Cells:        80 - % of the Forest: 26.67%
Total Non-Burnable Cells: 100 - % of the Forest: 33.33%
Total Firebreak Cells:    10 - % of the Forest: 3.33%

Notes:

• Ensure the output directory structure exists before running the simulation to avoid file I/O errors.
• This method supports optional outputs, which can be toggled using command-line arguments.

Here is the call graph for this function:

Here is the caller graph for this function:

RunIgnition()

bool Cell2Fire::RunIgnition	(	std::default_random_engine	generator,
		int	ep
	)

Simulates the ignition phase of the fire spread model for a single simulation year.

This method is responsible for selecting ignition points, either randomly or from predefined data (e.g., CSV files), and attempting to ignite those points based on the conditions of the cells (availability, burnability, etc.). The simulation state is updated accordingly, including tracking ignited, burnt, and available cells, as well as the fire and weather periods.

Parameters

generator	A random engine used to generate random values for ignition point selection.
ep	The current simulation epoch, used to seed the secondary random generator for parallel simulations.

Returns

true If no ignition occurs during the current simulation year.

false If at least one ignition occurs during the current simulation year.

Detailed Behavior:

• If no ignition points are provided (args.Ignitions == 0), a random point is selected repeatedly until a valid ignition is found or a limit is reached.
• If ignition points are provided, the algorithm selects a point directly or samples from a specified radius around the predefined points.
• The ignition process updates the state of the forest, including burning and burnt cells, and prepares for the next period or year if no ignition occurs.

Key Updates:

• Ignition history (IgnitionHistory)
• Forest cell states (statusCells, burningCells, burntCells, availCells)
• Fire and weather periods

Verbose Mode:

When args.verbose is true, detailed logs of the ignition process, including selected points, random values, and status updates, are printed to the console.

Here is the call graph for this function:

Here is the caller graph for this function:

SendMessages()

std::unordered_map< int, std::vector< int > > Cell2Fire::SendMessages

(

)

Message-sending phase of the fire spread model, where burning cells propagate fire messages to neighboring cells.

This method iterates through all burning cells, updates their fire progress, and determines whether fire messages should be sent to neighboring cells. A fire message is sent to a cell if fire reaches its center. Burnt-out cells are also identified and removed from the burning set.

Returns

A map of cell IDs to lists of neighboring cell IDs that received fire messages. Each key is the ID of a burning cell, and the value is a list of neighboring cell IDs affected by the fire.

Detailed Behavior:

• Iterates over all currently burning cells to manage fire propagation using either the manageFire or manageFireBBO methods, depending on tuning options.
• Builds a list of neighboring cells (sendMessageList) that receive fire messages for potential ignition.
• Tracks cells that burn out during this phase and removes them from the active burning set.
• Handles special conditions where repeat fire propagation may occur.

Key Updates:

• burningCells: Updated to exclude cells that have burnt out.
• burnedOutList: Contains cells that are no longer burning after this phase.
• messagesSent: A flag indicating if any fire messages were sent during this phase.

Verbose Mode:

When args.verbose is enabled:

• Prints detailed logs of the fire progress and messages sent by each burning cell.
• Outputs the current fire period, sets of cells (available, non-burnable, burning, burnt, harvested), and fire message details.

Warning:

• A warning is issued if the fire period approaches the maximum allowed (args.MaxFirePeriods).

Send messages logic

Here is the caller graph for this function:

Step()

void Cell2Fire::Step	(	std::default_random_engine	generator,
		int	ep
	)

Executes a single simulation step in the forest fire model.

This method simulates one fire period, handling all related processes such as ignition, message exchange, weather updates, and transitioning between simulation years or scenarios. It is the core operational logic for advancing the simulation in discrete steps.

Behavior:

• Verbose Logging:
  • If verbose is enabled, prints details about the current simulation state, including the year, fire period, weather period, and grid status.
• Simulation Logic:
  • End of Simulation Checks:
    • Ends the simulation if the current year exceeds the total years (TotalYears).
    • If the available cells or burning cells are empty, the simulation is marked as complete.
  • Ignition:
    • Handles ignition logic during the first fire period. If no ignition occurs, checks for available burning cells.
  • Fire Spread:
    • Processes fire spread by sending and receiving messages between cells.
  • Weather Updates:
    • Resets the weather period at the start of each new year.
  • Fire Period Limits:
    • If the current fire period exceeds the maximum allowed fire periods (MaxFirePeriods), advances to the next year.
  • Results Handling:
    • Outputs results and weather history if required.
• Transition to Next Simulation:
  • Advances to the next simulation if the maximum year or conditions for termination are met.
  • Handles additional simulation-specific logic based on weather options and history requirements.

Here is the call graph for this function:

updateWeather()

void Cell2Fire::updateWeather

(

)

Updates the weather conditions during the simulation based on specified criteria.

This method dynamically updates the weather parameters used in the simulation based on the simulation's fire period and weather options. It can optionally output the current state of the forest grid and log weather updates if verbose mode is enabled.

Behavior:

• Weather Update Check:
  • Weather is updated if:
    • The WeatherOpt argument is not set to "constant".
    • The fire period multiplied by the fire period length exceeds the current weatherPeriod.
  • When the conditions are met, the weatherPeriod is incremented.
• Grid Output:
  • If the OutputGrids argument is enabled, the current forest grid is output using the outputGrid method.
• Verbose Logging:
  • If verbose mode is enabled:
    • Logs the weather update to the console.
    • Prints detailed weather information for the current period using CSVWeather.printWeatherDF.

Here is the call graph for this function:

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• /home/runner/work/C2F-W/C2F-W/Cell2Fire/Cell2Fire.h
• /home/runner/work/C2F-W/C2F-W/Cell2Fire/Cell2Fire.cpp