Skip to content

Fire Model

dissmodel.models.ca.fire_model.FireModel

Bases: CellularAutomaton

Spatial cellular automaton simulating forest fire spread.

The fire spreads to any forest cell that has at least one burning neighbor (Rook neighborhood — 4 cardinal directions).

Parameters:

Name Type Description Default
gdf GeoDataFrame

GeoDataFrame with geometries and a state attribute.

 required
**kwargs Any

Extra keyword arguments forwarded to :class:~dissmodel.geo.CellularAutomaton.

 {}

Examples:

>>> from dissmodel.geo import regular_grid
>>> from dissmodel.core import Environment
>>> gdf = regular_grid(dimension=(10, 10), resolution=1, attrs={"state": 0})
>>> env = Environment(end_time=10)
>>> fire = FireModel(gdf=gdf)
>>> fire.initialize()
Source code in dissmodel/models/ca/fire_model.py 
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
class FireModel(CellularAutomaton):
    """
    Spatial cellular automaton simulating forest fire spread.

    The fire spreads to any forest cell that has at least one burning
    neighbor (Rook neighborhood — 4 cardinal directions).

    Parameters
    ----------
    gdf : geopandas.GeoDataFrame
        GeoDataFrame with geometries and a ``state`` attribute.
    **kwargs :
        Extra keyword arguments forwarded to
        :class:`~dissmodel.geo.CellularAutomaton`.

    Examples
    --------
    >>> from dissmodel.geo import regular_grid
    >>> from dissmodel.core import Environment
    >>> gdf = regular_grid(dimension=(10, 10), resolution=1, attrs={"state": 0})
    >>> env = Environment(end_time=10)
    >>> fire = FireModel(gdf=gdf)
    >>> fire.initialize()
    """

    #: Proportion of cells initially on fire (0.0 – 1.0).
    initial_fire_density: float

    def setup(
        self,
        initial_fire_density: float = 0.05,
        seed: int = 42,
    ) -> None:
        """
        Configure the model and build the neighborhood.

        Parameters
        ----------
        initial_fire_density : float, optional
            Proportion of cells that start as burning, by default 0.05.
            Must be between 0.0 and 1.0.
        seed : int, optional
            Random seed used during initialization, by default 42.
        """
        self.initial_fire_density = initial_fire_density
        self.seed = seed
        self.create_neighborhood(strategy=Rook, use_index=True)

    def initialize(self) -> None:
        """
        Fill the grid with a random initial state.

        Uses :attr:`initial_fire_density` to determine the proportion of
        cells that start as burning. The remaining cells start as forest.
        """
        fill(
            strategy=FillStrategy.RANDOM_SAMPLE,
            gdf=self.gdf,
            attr="state",
            data={
                FireState.FOREST:  1 - self.initial_fire_density,
                FireState.BURNING: self.initial_fire_density,
            },
            seed=self.seed,
        )

    def rule(self, idx: Any) -> int:
        """
        Apply the fire spread transition rule to cell ``idx``.

        Parameters
        ----------
        idx : any
            Index of the cell being evaluated.

        Returns
        -------
        int
            New state for the cell:

            - ``BURNED`` if the cell is currently burning.
            - ``BURNING`` if the cell is forest and has at least one
              burning neighbor.
            - Unchanged otherwise.
        """
        state = self.gdf.loc[idx, self.state_attr]

        if state == FireState.BURNING:
            return FireState.BURNED

        if state == FireState.FOREST:
            if (self.neighbor_values(idx, self.state_attr) == FireState.BURNING).any():
                return FireState.BURNING

        return state

initialize()

Fill the grid with a random initial state.

Uses :attr:initial_fire_density to determine the proportion of cells that start as burning. The remaining cells start as forest.

Source code in dissmodel/models/ca/fire_model.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def initialize(self) -> None:
    """
    Fill the grid with a random initial state.

    Uses :attr:`initial_fire_density` to determine the proportion of
    cells that start as burning. The remaining cells start as forest.
    """
    fill(
        strategy=FillStrategy.RANDOM_SAMPLE,
        gdf=self.gdf,
        attr="state",
        data={
            FireState.FOREST:  1 - self.initial_fire_density,
            FireState.BURNING: self.initial_fire_density,
        },
        seed=self.seed,
    )

rule(idx)

Apply the fire spread transition rule to cell idx.

Parameters:

Name Type Description Default
idx any

Index of the cell being evaluated.

 required

Returns:

Type Description
int

New state for the cell:

  • BURNED if the cell is currently burning.
  • BURNING if the cell is forest and has at least one burning neighbor.
  • Unchanged otherwise.
Source code in dissmodel/models/ca/fire_model.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def rule(self, idx: Any) -> int:
    """
    Apply the fire spread transition rule to cell ``idx``.

    Parameters
    ----------
    idx : any
        Index of the cell being evaluated.

    Returns
    -------
    int
        New state for the cell:

        - ``BURNED`` if the cell is currently burning.
        - ``BURNING`` if the cell is forest and has at least one
          burning neighbor.
        - Unchanged otherwise.
    """
    state = self.gdf.loc[idx, self.state_attr]

    if state == FireState.BURNING:
        return FireState.BURNED

    if state == FireState.FOREST:
        if (self.neighbor_values(idx, self.state_attr) == FireState.BURNING).any():
            return FireState.BURNING

    return state

setup(initial_fire_density=0.05, seed=42)

Configure the model and build the neighborhood.

Parameters:

Name Type Description Default
initial_fire_density float

Proportion of cells that start as burning, by default 0.05. Must be between 0.0 and 1.0.

 0.05
seed int

Random seed used during initialization, by default 42.

 42
Source code in dissmodel/models/ca/fire_model.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def setup(
    self,
    initial_fire_density: float = 0.05,
    seed: int = 42,
) -> None:
    """
    Configure the model and build the neighborhood.

    Parameters
    ----------
    initial_fire_density : float, optional
        Proportion of cells that start as burning, by default 0.05.
        Must be between 0.0 and 1.0.
    seed : int, optional
        Random seed used during initialization, by default 42.
    """
    self.initial_fire_density = initial_fire_density
    self.seed = seed
    self.create_neighborhood(strategy=Rook, use_index=True)

dissmodel.models.ca.fire_model.FireState

Bases: IntEnum

Possible states for a cell in :class:FireModel.

Attributes:

Name Type Description
FOREST int

Healthy tree, can catch fire.
BURNING int

Actively burning, spreads fire to neighbors.
BURNED int

Already burned, no longer spreads.
Source code in dissmodel/models/ca/fire_model.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
class FireState(IntEnum):
    """
    Possible states for a cell in :class:`FireModel`.

    Attributes
    ----------
    FOREST : int
        Healthy tree, can catch fire.
    BURNING : int
        Actively burning, spreads fire to neighbors.
    BURNED : int
        Already burned, no longer spreads.
    """
    FOREST  = 0
    BURNING = 1
    BURNED  = 2