embrs.base_classes.base_fire#

Base class implementation of fire simulation model.

Builds fire simulation and contains core calculations for propagation model. Contains fire interface properties and functions.

class embrs.base_classes.base_fire.BaseFireSim(fuel_map: ndarray, fuel_res: float, topography_map: ndarray, topography_res: float, wind_vec: Wind, roads: list, fire_breaks: list, time_step: int, cell_size: float, duration_s: float, initial_ignition: list, size: tuple, burnt_cells: list = None, display_freq_s=300)#

Base class implementation of fire simulation.

Based on the work of Trucchia et. al. The basis of the simulator is a hexagonal grid, each cell in the grid is a Cell object that contains all the pertinent fire spread parameters for that cell. The simulator takes into account the effects of fuel, slope, and wind on the fire propagation.

Parameters:

  • fuel_map (np.ndarray) – 2D array that represents the spatial distribution of fuel types in the sim. Each element must be one of the 13 Anderson FBFMs. Note: array is flipped across the horizontal axis after input.

  • fuel_res (float) – Resolution of the fuel map in meters. How many meters each row/column represents in space

  • topography_map (np.ndarray) – 2D array that represents the elevation in meters at each point in space. Note: array is flipped across the horizontal axis after input.

  • topography_res (float) – Resolution of the topography map in meters. How many meters each row/column represents in space.

  • wind_vec (Wind) – Wind object defining the wind conditions for the simulation.

  • roads (list) – List of points that will be considered roads for the simulation. Format for each element in list: ((x,y), fuel_content). Where (x,y) is a tuple containing the spatial in the sim measured in meters, and fuel_content is the amount of fuel to be modeled at that point (between 0 and 1)

  • fire_breaks (list) – List of dictionaries representing fire-breaks where each dictionary has a “geometry” key with a shapely.LineString value and a “fuel_value” key with a float value which represents the amount of fuel modeled along the shapely.LineString.

  • time_step (int) – Time step of the simulation, defines the amount of time each iteration will model.

  • cell_size (float) – Size of each cell in the simulation, measured as the distance in meters between two parallel sides of the regular hexagon cells.

  • duration_s (float) – Duration of time (in seconds) the simulation should run for, the sim will run for this duration unless the fire is extinguished before the duration has passed.

  • initial_ignition (list) – List of shapely polygons that represent the regions of the sim that should start as initially on fire.

  • size (tuple) – Size of the simulation backing array (rows, cols)

  • display_freq_s (int, optional) – The amount of time (in seconds) between updating the real-time visualizer, only used if real-time visualization is selected, defaults to 300

add_agent(agent: AgentBase)#

Add agent to sim’s list of registered agent.

Enables sim to log agent data along with sim data so that it is included in visualizations.

Parameters:

agent (AgentBase) – agent to be added to the sim’s list

Raises:

TypeError – if agent is not an instance of AgentBase

property burnt_cells: list#

List of Cell objects that are currently in the BURNT state.

property cell_dict: dict#

Dictionary mapping cell IDs to their respective Cell instances.

property cell_grid: ndarray#

2D array of all the cells in the sim at the current instant.

property cell_size: float#

Size of each cell in the simulation.

Measured as the distance in meters between two parallel sides of the regular hexagon cells.

property curr_fires: list#

List of Cell objects that are currently in the FIRE state.

property curr_time_h: float#

Current sim time in hours

property curr_time_m: float#

Current sim time in minutes

property curr_time_s: int#

Current sim time in seconds

property finished: bool#

True if the simulation is finished running. False otherwise

property fire_break_cells: list#

List of Cell objects that fall along fire breaks

property fire_breaks: list#

List of dictionaries representing fire-breaks.

Each dictionary has:

  • a “geometry” key with a shapely.LineString

  • a “fuel_value” key with a float value which represents the amount of fuel modeled along the LineString.

property frontier: list#

List of cells on the frontier of the fire.

Cells that are in the CellStates.FUEL state and neighboring at least one cell in the CellStates.FIRE state. Excludes any cells surrounded completely by CellStates.FIRE.

property fuel_map: ndarray#

2D array that represents the spatial distribution of fuel types in the sim.

Each element is one of the 13 Anderson FBFMs.

property fuel_res: float#

Resolution of the fuel map in meters

get_avg_fire_coord() → Tuple[float, float]#

Get the average position of all the cells on fire.

If there is more than one independent fire this will include the points from both.

Returns:

average position of all the cells on fire in the form (x_avg, y_avg)

Return type:

Tuple[float, float]

get_cell_from_indices(row: int, col: int) → Cell#
Returns the cell in the sim at the indices [row, col] in

cell_grid.

Columns increase left to right in the sim visualization window, rows increase bottom to top.

Parameters:

  • row (int) – row index of the desired cell

  • col (int) – col index of the desired cell

Raises:

  • TypeError – if row or col is not of type int

  • ValueError – if row or col is out of the array bounds

Returns:

Cell instance at the indices [row, col] in the cell_grid.

Return type:

Cell

get_cell_from_xy(x_m: float, y_m: float, oob_ok=False) → Cell#

Returns the cell in the sim that contains the point (x_m, y_m) in the cartesian plane.

(0,0) is considered the lower left corner of the sim window, x increases to the right, y increases up.

Parameters:

  • x_m (float) – x position of the desired point in units of meters

  • y_m (float) – y position of the desired point in units of meters

  • oob_ok (bool, optional) – whether out of bounds input is ok, if set to True out of bounds input will return None, defaults to False

Raises:

ValueError – oob_ok is False and (x_m, y_m) is out of the sim bounds

Returns:

Cell at the requested point, returns None if the point is out of bounds and oob_ok is True

Return type:

Cell

get_curr_wind_speed_dir() → Tuple[float, float]#

Get the current wind conditions broken up into a speed (m/s) and a direction (deg).

Returns:

The current wind conditions as a tuple in the form of (speed(m/s), direction(deg))

Return type:

Tuple[float, float]

get_curr_wind_vec() → list#

Get the current wind conditions as its velocity components.

Returns:

The current wind conditions as a 2d vector [x velocity (m/s), y velocity (m/s)]

Return type:

list

property grid_height: int#

Height of the sim’s backing array or the number of rows in the array

property grid_width: int#

Width of the sim’s backing array or the number of columns in the array

property initial_ignition: list#

List of shapely polygons that were initially ignited at the start of the sim

property iters: int#

Number of iterations run so far by the sim

property roads: list#

List of points that define the roads for the simulation.

Format for each element in list: ((x,y), fuel_content).

  • (x,y) is the spatial position in the sim measured in meters

  • fuel_content is the amount of fuel modeled at that point (between 0 and 1)

set_fuel_content_at_cell(cell: Cell, fuel_content: float)#

Set the fraction of fuel remaining in a cell between 0 and 1

Parameters:

  • cell (Cell) – Cell object to set fuel content in

  • fuel_content (float) – desired fuel content at cell between 0 and 1.

Raises:

  • TypeError – if ‘cell’ is not of type Cell

  • ValueError – if ‘cell’ is not a valid Cell in the current sim

  • ValueError – if ‘fuel_content’ is not between 0 and 1

set_fuel_content_at_indices(row: int, col: int, fuel_content: float)#

Set the fraction of fuel remanining in the cell at indices [row, col] in cell_grid between 0 and 1.

Parameters:

  • row (int) – row index of the cell where fuel content should be changed

  • col (int) – col index of the cell where fuel content should be changed

  • fuel_content (float) – desired fuel content at indices [row, col} between 0 and 1.

set_fuel_content_at_xy(x_m: float, y_m: float, fuel_content: float)#

Set the fraction of fuel remaining at a point (x_m, y_m) in the Cartesian plane between 0 and 1.

Parameters:

  • x_m (float) – x position in meters of the point where fuel content should be changed

  • y_m (float) – y position in meters of the point where fuel content should be changed

  • fuel_content (float) – desired fuel content at point (x_m, y_m) between 0 and 1.

set_fuel_moisture_at_cell(cell: Cell, fuel_moisture: float)#

Set the fuel mositure at a cell

Parameters:

  • cell (Cell) – cell where fuel moisture is set

  • fuel_moisture (float) – desired fuel mositure at cell, between 0 and 1.

Raises:

  • TypeError – if ‘cell’ is not of type Cell

  • ValueError – if ‘cell’ is not a valid Cell in the current sim

  • ValueError – if ‘fuel_moisture’ is not between 0 and 1

set_fuel_moisture_at_indices(row: int, col: int, fuel_moisture: float)#

Set the fuel moisture at the cell at indices [row, col] in the sim’s backing array.

Parameters:

  • row (int) – row index of the cell where fuel moisture is set

  • col (int) – col index of the cell where fuel moisture is set

  • fuel_moisture (float) – desired fuel moisture at indices [row, col], between 0 and 1.

set_fuel_moisture_at_xy(x_m: float, y_m: float, fuel_moisture: float)#

Set the fuel moisture at the point (x_m, y_m) in the Cartesian plane.

Parameters:

  • x_m (float) – x position in meters of the point where fuel moisture is set

  • y_m (float) – y position in meters of the point where fuel moisture is set

  • fuel_moisture (float) – desired fuel moisture at point (x_m, y_m), between 0 and 1.

set_prescribed_fire_at_cell(cell: Cell)#

Set a prescribed fire at a specific cell.

Parameters:

cell (Cell) – Cell object to set a prescribed fire in

set_prescribed_fire_at_indices(row: int, col: int)#

Set a prescribed fire in the cell at indices [row, col] in the sim’s backing array

Parameters:

  • row (int) – row index of the desired prescribed ignition cell

  • col (int) – col index of the desired prescribed ignition cell

set_prescribed_fire_at_xy(x_m: float, y_m: float)#

Set a prescribed fire in the cell at position x_m, y_m in the Cartesian plane.

Parameters:

  • x_m (float) – x position of the desired prescribed ignition point in meters

  • y_m (float) – y position of the desired prescribed ignition point in meters

set_state_at_cell(cell: Cell, state: CellStates, fire_type=0)#

Set the state of the specified cell

Parameters:

  • cell (Cell) – Cell object whose state is to be changed

  • state (CellStates) – desired state to set the cell to (CellStates.FIRE, CellStates.FUEL, or CellStates.BURNT) if set to CellStates.FIRE, fire_type will default to FireTypes.WILD

  • fire_type (FireTypes, optional) – type of fire, only relevant if state = CellStates.FIRE, options: (FireTypes.WILD, FireTypes.PRESCRIBED), defaults to FireTypes.WILD

Raises:

  • TypeError – if ‘cell’ is not of type Cell

  • ValueError – if ‘cell’ is not a valid Cell in the current fire Sim

  • TypeError – if ‘state’ is not a valid CellStates value

  • TypeError – if ‘fire_type’ is not a valid FireTypes value

set_state_at_indices(row: int, col: int, state: CellStates)#

Set the state of the cell at the indices [row, col] in cell_grid.

Columns increase left to right in the sim window, rows increase bottom to top.

Parameters:

  • row (int) – row index of the desired cell

  • col (int) – col index of the desired cell

  • state (CellStates) – desired state to set the cell to (CellStates.FIRE, CellStates.FUEL, or CellStates.BURNT) if set to CellStates.FIRE, fire_type will default to FireTypes.WILD

set_state_at_xy(x_m: float, y_m: float, state: CellStates)#

Set the state of the cell at the point (x_m, y_m) in the Cartesian plane.

Parameters:

  • x_m (float) – x position of the desired point in meters

  • y_m (float) – y position of the desired point in meters

  • state (CellStates) – desired state to set the cell to (CellStates.FIRE, CellStates.FUEL, or CellStates.BURNT) if set to CellStates.FIRE, fire_type will default to FireTypes.WILD

set_wild_fire_at_cell(cell: Cell)#

Set a wild fire at a specific cell

Parameters:

cell (Cell) – Cell object to set a wildfire in

set_wild_fire_at_indices(row: int, col: int)#

Set a wild fire in the cell at indices [row, col] in cell_grid

Parameters:

  • row (int) – row index of the desired wildfire ignition cell

  • col (int) – col index of the desired wildfire ignition cell

set_wild_fire_at_xy(x_m: float, y_m: float)#

Set a wild fire in the cell at position (x_m, y_m) in the Cartesian plane.

Parameters:

  • x_m (float) – x position of the desired wildfire ignition point in meters

  • y_m (float) – y position of the desired wildfire ignition point in meters

property shape: Tuple[int, int]#

Shape of the sim’s backing array in (rows, cols)

property sim_duration: float#

Duration of time (in seconds) the simulation should run for, the sim will run for this duration unless the fire is extinguished before the duration has passed.

property size: Tuple[float, float]#

Size of the sim region (width_m, height_m)

property time_step: int#

Time-step of the sim. Number of seconds per iteration

property topography_map: ndarray#

2D array that represents the elevation in meters at each point in space

property topography_res: float#

Resolution of the topography map in meters

property updated_cells: dict#

Dictionary containing cells updated since last time real-time visualization was updated. Dict keys are the ids of the Cell objects.

property wind_vec: Wind#

Wind object which defines the wind conditions for the current sim.

property x_lim: float#

Max x coordinate in the sim’s map in meters

property y_lim: float#

Max y coordinate in the sim’s map in meters

Classes

BaseFireSim(fuel_map, fuel_res, ...[, ...])

Base class implementation of fire simulation.