Skip to content

Anneal

dissmodel.models.ca.anneal.Anneal

Bases: CellularAutomaton

Cellular automaton implementing the Anneal rule.

The Anneal rule is a majority-vote variant that produces smooth, blob-like regions. Each cell's next state depends on the count of neighbors (including itself) in state L:

  • count ≤ 3 → R
  • count == 4 → L
  • count == 5 → R
  • count ≥ 6 → L

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=(20, 20), resolution=1, attrs={"state": 0})
>>> env = Environment(end_time=10)
>>> ca = Anneal(gdf=gdf)
>>> ca.initialize()
Source code in dissmodel/models/ca/anneal.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
class Anneal(CellularAutomaton):
    """
    Cellular automaton implementing the Anneal rule.

    The Anneal rule is a majority-vote variant that produces smooth,
    blob-like regions. Each cell's next state depends on the count of
    neighbors (including itself) in state ``L``:

    - count ≤ 3  → ``R``
    - count == 4 → ``L``
    - count == 5 → ``R``
    - count ≥ 6  → ``L``

    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=(20, 20), resolution=1, attrs={"state": 0})
    >>> env = Environment(end_time=10)
    >>> ca = Anneal(gdf=gdf)
    >>> ca.initialize()
    """

    def setup(self) -> None:
        """Build the Queen neighborhood for the grid."""
        self.create_neighborhood(strategy=Queen, use_index=True)

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

        Each cell is assigned ``L`` or ``R`` with equal probability.
        """
        self.gdf["state"] = [
            random.choice([AnnealState.L, AnnealState.R])
            for _ in range(len(self.gdf))
        ]

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

        Counts the number of cells in state ``L`` among the cell's
        neighbors plus the cell itself, then applies the threshold rule.

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

        Returns
        -------
        int
            New state for the cell (``L`` or ``R``).
        """
        state = self.gdf.loc[idx, self.state_attr]

        # Count neighbors in state L, including the cell itself
        count = (self.neighbor_values(idx, self.state_attr) == AnnealState.L).sum()
        if state == AnnealState.L:
            count += 1

        if count <= 3:
            return AnnealState.R
        if count == 4:
            return AnnealState.L
        if count == 5:
            return AnnealState.R
        return AnnealState.L  # count >= 6

initialize()

Fill the grid with a random initial state.

Each cell is assigned L or R with equal probability.

Source code in dissmodel/models/ca/anneal.py 
62
63
64
65
66
67
68
69
70
71
def initialize(self) -> None:
    """
    Fill the grid with a random initial state.

    Each cell is assigned ``L`` or ``R`` with equal probability.
    """
    self.gdf["state"] = [
        random.choice([AnnealState.L, AnnealState.R])
        for _ in range(len(self.gdf))
    ]

rule(idx)

Apply the Anneal transition rule to cell idx.

Counts the number of cells in state L among the cell's neighbors plus the cell itself, then applies the threshold rule.

Parameters:

Name Type Description Default
idx any

Index of the cell being evaluated.

 required

Returns:

Type Description
int

New state for the cell (L or R).
Source code in dissmodel/models/ca/anneal.py 
 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
def rule(self, idx: Any) -> int:
    """
    Apply the Anneal transition rule to cell ``idx``.

    Counts the number of cells in state ``L`` among the cell's
    neighbors plus the cell itself, then applies the threshold rule.

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

    Returns
    -------
    int
        New state for the cell (``L`` or ``R``).
    """
    state = self.gdf.loc[idx, self.state_attr]

    # Count neighbors in state L, including the cell itself
    count = (self.neighbor_values(idx, self.state_attr) == AnnealState.L).sum()
    if state == AnnealState.L:
        count += 1

    if count <= 3:
        return AnnealState.R
    if count == 4:
        return AnnealState.L
    if count == 5:
        return AnnealState.R
    return AnnealState.L  # count >= 6

setup()

Build the Queen neighborhood for the grid.

Source code in dissmodel/models/ca/anneal.py 
58
59
60
def setup(self) -> None:
    """Build the Queen neighborhood for the grid."""
    self.create_neighborhood(strategy=Queen, use_index=True)

dissmodel.models.ca.anneal.AnnealState

Bases: IntEnum

Possible states for a cell in :class:Anneal.

Attributes:

Name Type Description
L int

Left state (0).
R int

Right state (1).
Source code in dissmodel/models/ca/anneal.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
class AnnealState(IntEnum):
    """
    Possible states for a cell in :class:`Anneal`.

    Attributes
    ----------
    L : int
        Left state (0).
    R : int
        Right state (1).
    """
    L = 0
    R = 1