support for discrete event scheduling

benchmarks/WolfSheep/wolf_sheep.py

@@ -13,7 +13,7 @@
 
 from mesa import Model
 from mesa.experimental.cell_space import CellAgent, OrthogonalVonNeumannGrid
-from mesa.time import RandomActivationByType
+from mesa.experimental.devs import ABMSimulator
 
 
 class Animal(CellAgent):
@@ -36,7 +36,6 @@ def spawn_offspring(self):
             self.energy_from_food,
         )
         offspring.move_to(self.cell)
-        self.model.schedule.add(offspring)
 
     def feed(self):
         ...
@@ -94,26 +93,38 @@ class GrassPatch(CellAgent):
     A patch of grass that grows at a fixed rate and it is eaten by sheep
     """
 
-    def __init__(self, unique_id, model, fully_grown, countdown):
+    @property
+    def fully_grown(self):
+        return self._fully_grown
+
+    @fully_grown.setter
+    def fully_grown(self, value: bool) -> None:
+        self._fully_grown = value
+
+        if not value:
+            self.model.simulator.schedule_event_relative(
+                self.set_fully_grown, self.grass_regrowth_time
+            )
+
+    def __init__(self, unique_id, model, fully_grown, countdown, grass_regrowth_time):
         """
         Creates a new patch of grass
 
         Args:
-            fully_grown: (boolean) Whether the patch of grass is fully grown or not
+            grown: (boolean) Whether the patch of grass is fully grown or not
             countdown: Time for the patch of grass to be fully grown again
         """
         super().__init__(unique_id, model)
-        self.fully_grown = fully_grown
-        self.countdown = countdown
+        self._fully_grown = fully_grown
+        self.grass_regrowth_time = grass_regrowth_time
 
-    def step(self):
         if not self.fully_grown:
-            if self.countdown <= 0:
-                # Set as fully grown
-                self.fully_grown = True
-                self.countdown = self.model.grass_regrowth_time
-            else:
-                self.countdown -= 1
+            self.model.simulator.schedule_event_relative(
+                self.set_fully_grown, countdown
+            )
+
+    def set_fully_grown(self):
+        self.fully_grown = True
 
 
 class WolfSheep(Model):
@@ -125,6 +136,7 @@ class WolfSheep(Model):
 
     def __init__(
         self,
+        simulator,
         height,
         width,
         initial_sheep,
@@ -140,6 +152,7 @@ def __init__(
         Create a new Wolf-Sheep model with the given parameters.
 
         Args:
+            simulator: ABMSimulator instance
             initial_sheep: Number of sheep to start with
             initial_wolves: Number of wolves to start with
             sheep_reproduce: Probability of each sheep reproducing each step
@@ -149,18 +162,27 @@ def __init__(
             grass_regrowth_time: How long it takes for a grass patch to regrow
                                  once it is eaten
             sheep_gain_from_food: Energy sheep gain from grass, if enabled.
-            moore:
-            seed
+            seed : the random seed
         """
         super().__init__(seed=seed)
         # Set parameters
         self.height = height
         self.width = width
+        self.simulator = simulator
+
         self.initial_sheep = initial_sheep
         self.initial_wolves = initial_wolves
         self.grass_regrowth_time = grass_regrowth_time
 
-        self.schedule = RandomActivationByType(self)
+        self.sheep_reproduce = sheep_reproduce
+        self.wolf_reproduce = wolf_reproduce
+        self.grass_regrowth_time = grass_regrowth_time
+        self.wolf_gain_from_food = wolf_gain_from_food
+        self.sheep_gain_from_food = sheep_gain_from_food
+
+        self.grid = None
+
+    def setup(self):
         self.grid = OrthogonalVonNeumannGrid(
             [self.height, self.width],
             torus=False,
@@ -174,25 +196,31 @@ def __init__(
                 self.random.randrange(self.width),
                 self.random.randrange(self.height),
             )
-            energy = self.random.randrange(2 * sheep_gain_from_food)
+            energy = self.random.randrange(2 * self.sheep_gain_from_food)
             sheep = Sheep(
-                self.next_id(), self, energy, sheep_reproduce, sheep_gain_from_food
+                self.next_id(),
+                self,
+                energy,
+                self.sheep_reproduce,
+                self.sheep_gain_from_food,
             )
             sheep.move_to(self.grid[pos])
-            self.schedule.add(sheep)
 
         # Create wolves
         for _ in range(self.initial_wolves):
             pos = (
                 self.random.randrange(self.width),
                 self.random.randrange(self.height),
             )
-            energy = self.random.randrange(2 * wolf_gain_from_food)
+            energy = self.random.randrange(2 * self.wolf_gain_from_food)
             wolf = Wolf(
-                self.next_id(), self, energy, wolf_reproduce, wolf_gain_from_food
+                self.next_id(),
+                self,
+                energy,
+                self.wolf_reproduce,
+                self.wolf_gain_from_food,
             )
             wolf.move_to(self.grid[pos])
-            self.schedule.add(wolf)
 
         # Create grass patches
         possibly_fully_grown = [True, False]
@@ -202,20 +230,34 @@ def __init__(
                 countdown = self.grass_regrowth_time
             else:
                 countdown = self.random.randrange(self.grass_regrowth_time)
-            patch = GrassPatch(self.next_id(), self, fully_grown, countdown)
+            patch = GrassPatch(
+                self.next_id(), self, fully_grown, countdown, self.grass_regrowth_time
+            )
             patch.move_to(cell)
-            self.schedule.add(patch)
 
     def step(self):
-        self.schedule.step()
+        self.get_agents_of_type(Sheep).shuffle(inplace=True).do("step")
+        self.get_agents_of_type(Wolf).shuffle(inplace=True).do("step")
 
 
 if __name__ == "__main__":
     import time
 
-    model = WolfSheep(25, 25, 60, 40, 0.2, 0.1, 20, seed=15)
+    simulator = ABMSimulator()
+    model = WolfSheep(
+        simulator,
+        25,
+        25,
+        60,
+        40,
+        0.2,
+        0.1,
+        20,
+        seed=15,
+    )
+
+    simulator.setup(model)
 
     start_time = time.perf_counter()
-    for _ in range(100):
-        model.step()
+    simulator.run(100)
     print("Time:", time.perf_counter() - start_time)

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,191 @@
+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 InstanceCounterMeta(type):
+    """Metaclass to make instance counter not share count with descendants
+
+    TODO:: can also be used for agents.unique_id
+    """
+
+    def __init__(cls, name, bases, attrs):
+        super().__init__(name, bases, attrs)
+        cls._ids = itertools.count(1)
+
+
+class Priority(IntEnum):
+    LOW = 10
+    DEFAULT = 5
+    HIGH = 1
+
+
+class SimulationEvent(metaclass=InstanceCounterMeta):
+    """A simulation event
+
+    the callable is wrapped using weakrefs, 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
+        function  (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
+
+    """
+
+    @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__()
+        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 {}
+
+        if self.fn is None:
+            raise Exception()
+
+    def execute(self):
+        """execute this event"""
+        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 __cmp__(self, other):
+        if self.time < other.time:
+            return -1
+        if self.time > other.time:
+            return 1
+
+        if self.priority > other.priority:
+            return -1
+        if self.priority < other.priority:
+            return 1
+
+        if self.unique_id < other.unique_id:
+            return -1
+        if self.unique_id > other.unique_id:
+            return 1
+
+        # theoretically this should be impossible unless it is the
+        # exact same event
+        return 0
+
+    def _to_tuple(self):
+        return self.time, self.priority, self.unique_id, self
+
+
+class EventList:
+    """An event list
+
+    This is a heap queue sorted list of events. Events are allways removed from the left. The events are sorted
+    based on their time stamp, their priority, and their unique_id, guaranteeing a complete ordering.
+
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._event_list: list[tuple] = []
+        heapify(self._event_list)
+
+    def add_event(self, event: SimulationEvent):
+        """Add the event to the event list
+
+        Args:
+            event (SimulationEvent): The event to be added
+
+        """
+
+        heappush(self._event_list, event._to_tuple())
+
+    def peek_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 entry in self._event_list:
+            sim_event: SimulationEvent = entry[3]
+            if not sim_event.CANCELED:
+                peek.append(sim_event)
+            if len(peek) >= n:
+                return peek
+        return peek
+
+    def pop(self) -> SimulationEvent:
+        """pop the first element from the event list"""
+
+        try:
+            while True:
+                sim_event = heappop(self._event_list)[3]
+                if not sim_event.CANCELED:
+                    return sim_event
+        except IndexError as e:
+            raise Exception("event list is empty") from e
+
+    def is_empty(self) -> bool:
+        return len(self) == 0
+
+    def __contains__(self, event: SimulationEvent) -> bool:
+        return event._to_tuple() in self._event_list
+
+    def __len__(self) -> int:
+        return len(self._event_list)
+
+    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 poping and peak_ahead
+        # silently ignore canceled events
+        event.cancel()
+
+    def clear(self):
+        self._event_list.clear()