Mesa 2.3.0.dev0__py3-none-any.whl → 2.3.1__py3-none-any.whl

mesa/experimental/cell_space/network.py

@@ -0,0 +1,40 @@
+from random import Random
+from typing import Any, Optional
+
+from mesa.experimental.cell_space.cell import Cell
+from mesa.experimental.cell_space.discrete_space import DiscreteSpace
+
+
+class Network(DiscreteSpace):
+    """A networked discrete space"""
+
+    def __init__(
+        self,
+        G: Any,  # noqa: N803
+        capacity: Optional[int] = None,
+        random: Optional[Random] = None,
+        cell_klass: type[Cell] = Cell,
+    ) -> None:
+        """A Networked grid
+
+        Args:
+            G: a NetworkX Graph instance.
+            capacity (int) : the capacity of the cell
+            random (Random):
+            CellKlass (type[Cell]): The base Cell class to use in the Network
+
+        """
+        super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
+        self.G = G
+
+        for node_id in self.G.nodes:
+            self._cells[node_id] = self.cell_klass(
+                node_id, capacity, random=self.random
+            )
+
+        for cell in self.all_cells:
+            self._connect_single_cell(cell)
+
+    def _connect_single_cell(self, cell):
+        for node_id in self.G.neighbors(cell.coordinate):
+            cell.connect(self._cells[node_id])

mesa/experimental/components/altair.py

@@ -20,7 +20,7 @@ def SpaceAltair(model, agent_portrayal, dependencies: Optional[list[any]] = None
 def _draw_grid(space, agent_portrayal):
     def portray(g):
         all_agent_data = []
-        for content, (x, y) in space.coord_iter():
+        for content, (x, y) in g.coord_iter():
             if not content:
                 continue
             if not hasattr(content, "__iter__"):
@@ -35,11 +35,18 @@ def _draw_grid(space, agent_portrayal):
         return all_agent_data
 
     all_agent_data = portray(space)
+    invalid_tooltips = ["color", "size", "x", "y"]
+
     encoding_dict = {
         # no x-axis label
         "x": alt.X("x", axis=None, type="ordinal"),
         # no y-axis label
         "y": alt.Y("y", axis=None, type="ordinal"),
+        "tooltip": [
+            alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
+            for key, value in all_agent_data[0].items()
+            if key not in invalid_tooltips
+        ],
     }
     has_color = "color" in all_agent_data[0]
     if has_color:
@@ -56,5 +63,10 @@ def _draw_grid(space, agent_portrayal):
         .properties(width=280, height=280)
         # .configure_view(strokeOpacity=0)  # hide grid/chart lines
     )
+    # This is the default value for the marker size, which auto-scales
+    # according to the grid area.
+    if not has_size:
+        length = min(space.width, space.height)
+        chart = chart.mark_point(size=30000 / length**2, filled=True)
 
     return chart

mesa/experimental/components/matplotlib.py

@@ -48,6 +48,9 @@ def _draw_grid(space, space_ax, agent_portrayal):
                     if "color" in data:
                         c.append(data["color"])
         out = {"x": x, "y": y}
+        # This is the default value for the marker size, which auto-scales
+        # according to the grid area.
+        out["s"] = (180 / min(g.width, g.height)) ** 2
         if len(s) > 0:
             out["s"] = s
         if len(c) > 0:

mesa/experimental/devs/__init__.py

@@ -0,0 +1,4 @@
+from .eventlist import Priority, SimulationEvent
+from .simulator import ABMSimulator, DEVSimulator
+
+__all__ = ["ABMSimulator", "DEVSimulator", "SimulationEvent", "Priority"]

mesa/experimental/devs/eventlist.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import itertools
+from enum import IntEnum
+from heapq import heapify, heappop, heappush
+from types import MethodType
+from typing import Any, Callable
+from weakref import WeakMethod, ref
+
+
+class Priority(IntEnum):
+    LOW = 10
+    DEFAULT = 5
+    HIGH = 1
+
+
+class SimulationEvent:
+    """A simulation event
+
+    the callable is wrapped using weakref, so there is no need to explicitly cancel event if e.g., an agent
+    is removed from the simulation.
+
+    Attributes:
+        time (float): The simulation time of the event
+        fn (Callable): The function to execute for this event
+        priority (Priority): The priority of the event
+        unique_id (int) the unique identifier of the event
+        function_args (list[Any]): Argument for the function
+        function_kwargs (Dict[str, Any]): Keyword arguments for the function
+
+    """
+
+    _ids = itertools.count()
+
+    @property
+    def CANCELED(self) -> bool:
+        return self._canceled
+
+    def __init__(
+        self,
+        time: int | float,
+        function: Callable,
+        priority: Priority = Priority.DEFAULT,
+        function_args: list[Any] | None = None,
+        function_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__()
+        if not callable(function):
+            raise Exception()
+
+        self.time = time
+        self.priority = priority.value
+        self._canceled = False
+
+        if isinstance(function, MethodType):
+            function = WeakMethod(function)
+        else:
+            function = ref(function)
+
+        self.fn = function
+        self.unique_id = next(self._ids)
+        self.function_args = function_args if function_args else []
+        self.function_kwargs = function_kwargs if function_kwargs else {}
+
+    def execute(self):
+        """execute this event"""
+        if not self._canceled:
+            fn = self.fn()
+            if fn is not None:
+                fn(*self.function_args, **self.function_kwargs)
+
+    def cancel(self) -> None:
+        """cancel this event"""
+        self._canceled = True
+        self.fn = None
+        self.function_args = []
+        self.function_kwargs = {}
+
+    def __lt__(self, other):
+        # Define a total ordering for events to be used by the heapq
+        return (self.time, self.priority, self.unique_id) < (
+            other.time,
+            other.priority,
+            other.unique_id,
+        )
+
+
+class EventList:
+    """An event list
+
+    This is a heap queue sorted list of events. Events are always removed from the left, so heapq is a performant and
+    appropriate data structure. Events are sorted based on their time stamp, their priority, and their unique_id
+    as a tie-breaker, guaranteeing a complete ordering.
+
+    """
+
+    def __init__(self):
+        self._events: list[SimulationEvent] = []
+        heapify(self._events)
+
+    def add_event(self, event: SimulationEvent):
+        """Add the event to the event list
+
+        Args:
+            event (SimulationEvent): The event to be added
+
+        """
+
+        heappush(self._events, event)
+
+    def peak_ahead(self, n: int = 1) -> list[SimulationEvent]:
+        """Look at the first n non-canceled event in the event list
+
+        Args:
+            n (int): The number of events to look ahead
+
+        Returns:
+            list[SimulationEvent]
+
+        Raises:
+            IndexError: If the eventlist is empty
+
+        Notes:
+            this method can return a list shorted then n if the number of non-canceled events on the event list
+            is less than n.
+
+        """
+        # look n events ahead
+        if self.is_empty():
+            raise IndexError("event list is empty")
+
+        peek: list[SimulationEvent] = []
+        for event in self._events:
+            if not event.CANCELED:
+                peek.append(event)
+            if len(peek) >= n:
+                return peek
+        return peek
+
+    def pop_event(self) -> SimulationEvent:
+        """pop the first element from the event list"""
+        while self._events:
+            event = heappop(self._events)
+            if not event.CANCELED:
+                return event
+        raise IndexError("Event list is empty")
+
+    def is_empty(self) -> bool:
+        return len(self) == 0
+
+    def __contains__(self, event: SimulationEvent) -> bool:
+        return event in self._events
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+    def remove(self, event: SimulationEvent) -> None:
+        """remove an event from the event list"""
+        # we cannot simply remove items from _eventlist because this breaks
+        # heap structure invariant. So, we use a form of lazy deletion.
+        # SimEvents have a CANCELED flag that we set to True, while popping and peak_ahead
+        # silently ignore canceled events
+        event.cancel()
+
+    def clear(self):
+        self._events.clear()

mesa/experimental/devs/examples/epstein_civil_violence.py

@@ -0,0 +1,273 @@
+import enum
+import math
+
+from mesa import Agent, Model
+from mesa.experimental.devs.simulator import ABMSimulator
+from mesa.space import SingleGrid
+
+
+class EpsteinAgent(Agent):
+    def __init__(self, unique_id, model, vision, movement):
+        super().__init__(unique_id, model)
+        self.vision = vision
+        self.movement = movement
+
+
+class AgentState(enum.IntEnum):
+    QUIESCENT = enum.auto()
+    ARRESTED = enum.auto()
+    ACTIVE = enum.auto()
+
+
+class Citizen(EpsteinAgent):
+    """
+    A member of the general population, may or may not be in active rebellion.
+    Summary of rule: If grievance - risk > threshold, rebel.
+
+    Attributes:
+        unique_id: unique int
+        model :
+        hardship: Agent's 'perceived hardship (i.e., physical or economic
+            privation).' Exogenous, drawn from U(0,1).
+        regime_legitimacy: Agent's perception of regime legitimacy, equal
+            across agents.  Exogenous.
+        risk_aversion: Exogenous, drawn from U(0,1).
+        threshold: if (grievance - (risk_aversion * arrest_probability)) >
+            threshold, go/remain Active
+        vision: number of cells in each direction (N, S, E and W) that agent
+            can inspect
+        condition: Can be "Quiescent" or "Active;" deterministic function of
+            greivance, perceived risk, and
+        grievance: deterministic function of hardship and regime_legitimacy;
+            how aggrieved is agent at the regime?
+        arrest_probability: agent's assessment of arrest probability, given
+            rebellion
+    """
+
+    def __init__(
+        self,
+        unique_id,
+        model,
+        vision,
+        movement,
+        hardship,
+        regime_legitimacy,
+        risk_aversion,
+        threshold,
+        arrest_prob_constant,
+    ):
+        """
+        Create a new Citizen.
+        Args:
+            unique_id: unique int
+            model : model instance
+            hardship: Agent's 'perceived hardship (i.e., physical or economic
+                privation).' Exogenous, drawn from U(0,1).
+            regime_legitimacy: Agent's perception of regime legitimacy, equal
+                across agents.  Exogenous.
+            risk_aversion: Exogenous, drawn from U(0,1).
+            threshold: if (grievance - (risk_aversion * arrest_probability)) >
+                threshold, go/remain Active
+            vision: number of cells in each direction (N, S, E and W) that
+                agent can inspect. Exogenous.
+        """
+        super().__init__(unique_id, model, vision, movement)
+        self.hardship = hardship
+        self.regime_legitimacy = regime_legitimacy
+        self.risk_aversion = risk_aversion
+        self.threshold = threshold
+        self.condition = AgentState.QUIESCENT
+        self.grievance = self.hardship * (1 - self.regime_legitimacy)
+        self.arrest_probability = None
+        self.arrest_prob_constant = arrest_prob_constant
+
+    def step(self):
+        """
+        Decide whether to activate, then move if applicable.
+        """
+        self.update_neighbors()
+        self.update_estimated_arrest_probability()
+        net_risk = self.risk_aversion * self.arrest_probability
+        if self.grievance - net_risk > self.threshold:
+            self.condition = AgentState.ACTIVE
+        else:
+            self.condition = AgentState.QUIESCENT
+        if self.movement and self.empty_neighbors:
+            new_pos = self.random.choice(self.empty_neighbors)
+            self.model.grid.move_agent(self, new_pos)
+
+    def update_neighbors(self):
+        """
+        Look around and see who my neighbors are
+        """
+        self.neighborhood = self.model.grid.get_neighborhood(
+            self.pos, moore=True, radius=self.vision
+        )
+        self.neighbors = self.model.grid.get_cell_list_contents(self.neighborhood)
+        self.empty_neighbors = [
+            c for c in self.neighborhood if self.model.grid.is_cell_empty(c)
+        ]
+
+    def update_estimated_arrest_probability(self):
+        """
+        Based on the ratio of cops to actives in my neighborhood, estimate the
+        p(Arrest | I go active).
+        """
+        cops_in_vision = len([c for c in self.neighbors if isinstance(c, Cop)])
+        actives_in_vision = 1.0  # citizen counts herself
+        for c in self.neighbors:
+            if isinstance(c, Citizen) and c.condition == AgentState.ACTIVE:
+                actives_in_vision += 1
+        self.arrest_probability = 1 - math.exp(
+            -1 * self.arrest_prob_constant * (cops_in_vision / actives_in_vision)
+        )
+
+    def sent_to_jail(self, value):
+        self.model.active_agents.remove(self)
+        self.condition = AgentState.ARRESTED
+        self.model.simulator.schedule_event_relative(self.release_from_jail, value)
+
+    def release_from_jail(self):
+        self.model.active_agents.add(self)
+        self.condition = AgentState.QUIESCENT
+
+
+class Cop(EpsteinAgent):
+    """
+    A cop for life.  No defection.
+    Summary of rule: Inspect local vision and arrest a random active agent.
+
+    Attributes:
+        unique_id: unique int
+        x, y: Grid coordinates
+        vision: number of cells in each direction (N, S, E and W) that cop is
+            able to inspect
+    """
+
+    def __init__(self, unique_id, model, vision, movement, max_jail_term):
+        super().__init__(unique_id, model, vision, movement)
+        self.max_jail_term = max_jail_term
+
+    def step(self):
+        """
+        Inspect local vision and arrest a random active agent. Move if
+        applicable.
+        """
+        self.update_neighbors()
+        active_neighbors = []
+        for agent in self.neighbors:
+            if isinstance(agent, Citizen) and agent.condition == "Active":
+                active_neighbors.append(agent)
+        if active_neighbors:
+            arrestee = self.random.choice(active_neighbors)
+            arrestee.sent_to_jail(self.random.randint(0, self.max_jail_term))
+        if self.movement and self.empty_neighbors:
+            new_pos = self.random.choice(self.empty_neighbors)
+            self.model.grid.move_agent(self, new_pos)
+
+    def update_neighbors(self):
+        """
+        Look around and see who my neighbors are.
+        """
+        self.neighborhood = self.model.grid.get_neighborhood(
+            self.pos, moore=True, radius=self.vision
+        )
+        self.neighbors = self.model.grid.get_cell_list_contents(self.neighborhood)
+        self.empty_neighbors = [
+            c for c in self.neighborhood if self.model.grid.is_cell_empty(c)
+        ]
+
+
+class EpsteinCivilViolence(Model):
+    """
+    Model 1 from "Modeling civil violence: An agent-based computational
+    approach," by Joshua Epstein.
+    http://www.pnas.org/content/99/suppl_3/7243.full
+    Attributes:
+        height: grid height
+        width: grid width
+        citizen_density: approximate % of cells occupied by citizens.
+        cop_density: approximate % of cells occupied by cops.
+        citizen_vision: number of cells in each direction (N, S, E and W) that
+            citizen can inspect
+        cop_vision: number of cells in each direction (N, S, E and W) that cop
+            can inspect
+        legitimacy:  (L) citizens' perception of regime legitimacy, equal
+            across all citizens
+        max_jail_term: (J_max)
+        active_threshold: if (grievance - (risk_aversion * arrest_probability))
+            > threshold, citizen rebels
+        arrest_prob_constant: set to ensure agents make plausible arrest
+            probability estimates
+        movement: binary, whether agents try to move at step end
+        max_iters: model may not have a natural stopping point, so we set a
+            max.
+    """
+
+    def __init__(
+        self,
+        width=40,
+        height=40,
+        citizen_density=0.7,
+        cop_density=0.074,
+        citizen_vision=7,
+        cop_vision=7,
+        legitimacy=0.8,
+        max_jail_term=1000,
+        active_threshold=0.1,
+        arrest_prob_constant=2.3,
+        movement=True,
+        max_iters=1000,
+        seed=None,
+    ):
+        super().__init__(seed)
+        if cop_density + citizen_density > 1:
+            raise ValueError("Cop density + citizen density must be less than 1")
+
+        self.width = width
+        self.height = height
+        self.citizen_density = citizen_density
+        self.cop_density = cop_density
+
+        self.max_iters = max_iters
+
+        self.grid = SingleGrid(self.width, self.height, torus=True)
+
+        for _, pos in self.grid.coord_iter():
+            if self.random.random() < self.cop_density:
+                agent = Cop(
+                    self.next_id(),
+                    self,
+                    cop_vision,
+                    movement,
+                    max_jail_term,
+                )
+            elif self.random.random() < (self.cop_density + self.citizen_density):
+                agent = Citizen(
+                    self.next_id(),
+                    self,
+                    citizen_vision,
+                    movement,
+                    hardship=self.random.random(),
+                    regime_legitimacy=legitimacy,
+                    risk_aversion=self.random.random(),
+                    threshold=active_threshold,
+                    arrest_prob_constant=arrest_prob_constant,
+                )
+            else:
+                continue
+            self.grid.place_agent(agent, pos)
+
+        self.active_agents = self.agents
+
+    def step(self):
+        self.active_agents.shuffle(inplace=True).do("step")
+
+
+if __name__ == "__main__":
+    model = EpsteinCivilViolence(seed=15)
+    simulator = ABMSimulator()
+
+    simulator.setup(model)
+
+    simulator.run(time_delta=100)