Skip to content

Growth

dissmodel.models.ca.growth.Growth

Bases: CellularAutomaton

Stochastic cellular automaton simulating spatial growth from a seed.

A single live cell is placed at the center of the grid at initialization. At each step, empty cells adjacent to at least one live cell become alive with probability :attr:probability.

Parameters:

Name Type Description Default
gdf GeoDataFrame

GeoDataFrame with geometries and a state attribute. Must be created with dim=(n, n) so the center cell can be located by index.

 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=(20, 20), resolution=1, attrs={"state": 0})
>>> env = Environment(end_time=15)
>>> growth = Growth(gdf=gdf, dim=20)
>>> growth.initialize()
Source code in dissmodel/models/ca/growth.py 
 27
 28
 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
class Growth(CellularAutomaton):
    """
    Stochastic cellular automaton simulating spatial growth from a seed.

    A single live cell is placed at the center of the grid at initialization.
    At each step, empty cells adjacent to at least one live cell become alive
    with probability :attr:`probability`.

    Parameters
    ----------
    gdf : geopandas.GeoDataFrame
        GeoDataFrame with geometries and a ``state`` attribute.
        Must be created with ``dim=(n, n)`` so the center cell can be
        located by index.
    **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=(20, 20), resolution=1, attrs={"state": 0})
    >>> env = Environment(end_time=15)
    >>> growth = Growth(gdf=gdf, dim=20)
    >>> growth.initialize()
    """

    #: Probability of an empty cell becoming alive if it has at least one live neighbor.
    probability: float

    def setup(self, probability: float = 0.15) -> None:
        """
        Configure the model and build the neighborhood.

        Parameters
        ----------
        probability : float, optional
            Probability of colonization per step for empty cells adjacent
            to at least one live cell, by default 0.15.
        """
        self.probability = probability
        self.create_neighborhood(strategy=Queen, use_index=True)

    def initialize(self) -> None:
        """
        Place a single live cell at the center of the grid.

        All other cells start as empty.
        """
        assert self.dim is not None, "dim must be set — pass dim=N when instantiating"
        center = self.dim // 2
        center_idx = f"{center}-{center}"
        self.gdf.loc[:, "state"] = GrowthState.EMPTY
        self.gdf.loc[center_idx, "state"] = GrowthState.ALIVE

    def rule(self, idx: Any) -> int:
        """
        Apply the stochastic growth rule to cell ``idx``.

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

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

            - ``ALIVE`` if already alive (cells never die).
            - ``ALIVE`` with probability :attr:`probability` if empty
              and has at least one live neighbor.
            - ``EMPTY`` otherwise.
        """
        assert self.dim is not None, "dim must be set — pass dim=N when instantiating"
        state = self.gdf.loc[idx, self.state_attr]

        if state == GrowthState.ALIVE:
            return GrowthState.ALIVE


        alive_neighbors = (self.neighbor_values(idx, self.state_attr) == GrowthState.ALIVE).sum()


        if alive_neighbors > 0 and random.random() < self.probability:
            return GrowthState.ALIVE

        return GrowthState.EMPTY

initialize()

Place a single live cell at the center of the grid.

All other cells start as empty.

Source code in dissmodel/models/ca/growth.py 
71
72
73
74
75
76
77
78
79
80
81
def initialize(self) -> None:
    """
    Place a single live cell at the center of the grid.

    All other cells start as empty.
    """
    assert self.dim is not None, "dim must be set — pass dim=N when instantiating"
    center = self.dim // 2
    center_idx = f"{center}-{center}"
    self.gdf.loc[:, "state"] = GrowthState.EMPTY
    self.gdf.loc[center_idx, "state"] = GrowthState.ALIVE

rule(idx)

Apply the stochastic growth 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:

  • ALIVE if already alive (cells never die).
  • ALIVE with probability :attr:probability if empty and has at least one live neighbor.
  • EMPTY otherwise.
Source code in dissmodel/models/ca/growth.py 
 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
def rule(self, idx: Any) -> int:
    """
    Apply the stochastic growth rule to cell ``idx``.

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

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

        - ``ALIVE`` if already alive (cells never die).
        - ``ALIVE`` with probability :attr:`probability` if empty
          and has at least one live neighbor.
        - ``EMPTY`` otherwise.
    """
    assert self.dim is not None, "dim must be set — pass dim=N when instantiating"
    state = self.gdf.loc[idx, self.state_attr]

    if state == GrowthState.ALIVE:
        return GrowthState.ALIVE


    alive_neighbors = (self.neighbor_values(idx, self.state_attr) == GrowthState.ALIVE).sum()


    if alive_neighbors > 0 and random.random() < self.probability:
        return GrowthState.ALIVE

    return GrowthState.EMPTY

setup(probability=0.15)

Configure the model and build the neighborhood.

Parameters:

Name Type Description Default
probability float

Probability of colonization per step for empty cells adjacent to at least one live cell, by default 0.15.

 0.15
Source code in dissmodel/models/ca/growth.py 
58
59
60
61
62
63
64
65
66
67
68
69
def setup(self, probability: float = 0.15) -> None:
    """
    Configure the model and build the neighborhood.

    Parameters
    ----------
    probability : float, optional
        Probability of colonization per step for empty cells adjacent
        to at least one live cell, by default 0.15.
    """
    self.probability = probability
    self.create_neighborhood(strategy=Queen, use_index=True)

dissmodel.models.ca.growth.GrowthState

Bases: IntEnum

Possible states for a cell in :class:Growth.

Attributes:

Name Type Description
EMPTY int

Empty cell, not yet colonized.
ALIVE int

Live cell, can spread to neighbors.
Source code in dissmodel/models/ca/growth.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
class GrowthState(IntEnum):
    """
    Possible states for a cell in :class:`Growth`.

    Attributes
    ----------
    EMPTY : int
        Empty cell, not yet colonized.
    ALIVE : int
        Live cell, can spread to neighbors.
    """
    EMPTY = 0
    ALIVE = 1