Mesa 3.0.0rc0__py3-none-any.whl → 3.0.1__py3-none-any.whl

mesa/__init__.py

@@ -24,7 +24,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "3.0.0rc0"
+__version__ = "3.0.1"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -110,6 +110,12 @@ class AgentSet(MutableSet, Sequence):
         without preventing garbage collection. It is associated with a specific model instance, enabling
         interactions with the model's environment and other agents.The implementation uses a WeakKeyDictionary to store agents,
         which means that agents not referenced elsewhere in the program may be automatically removed from the AgentSet.
+
+    Notes:
+        A `UserWarning` is issued if `random=None`. You can resolve this warning by explicitly
+        passing a random number generator. In most cases, this will be the seeded random number
+        generator in the model. So, you would do `random=self.random` in a `Model` or `Agent` instance.
+
     """
 
     def __init__(self, agents: Iterable[Agent], random: Random | None = None):
@@ -120,6 +126,11 @@ class AgentSet(MutableSet, Sequence):
             random (Random): the random number generator
         """
         if random is None:
+            warnings.warn(
+                "Random number generator not specified, this can make models non-reproducible. Please pass a random number generator explicitly",
+                UserWarning,
+                stacklevel=2,
+            )
             random = (
                 Random()
             )  # FIXME see issue 1981, how to get the central rng from model
@@ -167,7 +178,7 @@ class AgentSet(MutableSet, Sequence):
         """
         if n is not None:
             warnings.warn(
-                "The parameter 'n' is deprecated. Use 'at_most' instead.",
+                "The parameter 'n' is deprecated and will be removed in Mesa 3.1. Use 'at_most' instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
@@ -276,8 +287,9 @@ class AgentSet(MutableSet, Sequence):
             return_results = False
         else:
             warnings.warn(
-                "Using return_results is deprecated. Use AgenSet.do in case of return_results=False, and "
-                "AgentSet.map in case of return_results=True",
+                "Using return_results is deprecated and will be removed in Mesa 3.1."
+                "Use AgenSet.do in case of return_results=False, and AgentSet.map in case of return_results=True",
+                DeprecationWarning,
                 stacklevel=2,
             )
 

mesa/examples/__init__.py

@@ -3,14 +3,14 @@ from mesa.examples.advanced.pd_grid.model import PdGrid
 from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
 from mesa.examples.advanced.wolf_sheep.model import WolfSheep
 from mesa.examples.basic.boid_flockers.model import BoidFlockers
-from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealthModel
+from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealth
 from mesa.examples.basic.conways_game_of_life.model import ConwaysGameOfLife
 from mesa.examples.basic.schelling.model import Schelling
 from mesa.examples.basic.virus_on_network.model import VirusOnNetwork
 
 __all__ = [
     "BoidFlockers",
-    "BoltzmannWealthModel",
+    "BoltzmannWealth",
     "ConwaysGameOfLife",
     "Schelling",
     "VirusOnNetwork",

mesa/examples/advanced/pd_grid/app.py

@@ -4,11 +4,11 @@ Solara-based visualization for the Spatial Prisoner's Dilemma Model.
 
 from mesa.examples.advanced.pd_grid.model import PdGrid
 from mesa.visualization import (
+    Slider,
     SolaraViz,
     make_plot_component,
     make_space_component,
 )
-from mesa.visualization.UserParam import Slider
 
 
 def pd_agent_portrayal(agent):

mesa/examples/advanced/pd_grid/model.py

@@ -27,7 +27,7 @@ class PdGrid(mesa.Model):
         """
         super().__init__(seed=seed)
         self.activation_order = activation_order
-        self.grid = OrthogonalMooreGrid((width, height), torus=True)
+        self.grid = OrthogonalMooreGrid((width, height), torus=True, random=self.random)
 
         if payoffs is not None:
             self.payoff = payoffs

mesa/examples/advanced/sugarscape_g1mt/model.py

@@ -70,7 +70,9 @@ class SugarscapeG1mt(mesa.Model):
         self.running = True
 
         # initiate mesa grid class
-        self.grid = OrthogonalVonNeumannGrid((self.width, self.height), torus=False)
+        self.grid = OrthogonalVonNeumannGrid(
+            (self.width, self.height), torus=False, random=self.random
+        )
         # initiate datacollector
         self.datacollector = mesa.DataCollector(
             model_reporters={

mesa/examples/advanced/wolf_sheep/agents.py

@@ -5,14 +5,14 @@ class Animal(CellAgent):
     """The base animal class."""
 
     def __init__(self, model, energy, p_reproduce, energy_from_food, cell):
-        """Initializes an animal.
+        """Initialize an animal.
 
         Args:
-            model: a model instance
-            energy: starting amount of energy
-            p_reproduce: probability of sexless reproduction
-            energy_from_food: energy obtained from 1 unit of food
-            cell: the cell in which the animal starts
+            model: Model instance
+            energy: Starting amount of energy
+            p_reproduce: Probability of reproduction (asexual)
+            energy_from_food: Energy obtained from 1 unit of food
+            cell: Cell in which the animal starts
         """
         super().__init__(model)
         self.energy = energy
@@ -21,7 +21,7 @@ class Animal(CellAgent):
         self.cell = cell
 
     def spawn_offspring(self):
-        """Create offspring."""
+        """Create offspring by splitting energy and creating new instance."""
         self.energy /= 2
         self.__class__(
             self.model,
@@ -31,15 +31,19 @@ class Animal(CellAgent):
             self.cell,
         )
 
-    def feed(self): ...
+    def feed(self):
+        """Abstract method to be implemented by subclasses."""
 
     def step(self):
-        """One step of the agent."""
+        """Execute one step of the animal's behavior."""
+        # Move to random neighboring cell
         self.cell = self.cell.neighborhood.select_random_cell()
         self.energy -= 1
 
+        # Try to feed
         self.feed()
 
+        # Handle death and reproduction
         if self.energy < 0:
             self.remove()
         elif self.random.random() < self.p_reproduce:
@@ -50,53 +54,63 @@ class Sheep(Animal):
     """A sheep that walks around, reproduces (asexually) and gets eaten."""
 
     def feed(self):
-        """If possible eat the food in the current location."""
-        # If there is grass available, eat it
-        if self.model.grass:
-            grass_patch = next(
-                obj for obj in self.cell.agents if isinstance(obj, GrassPatch)
-            )
-            if grass_patch.fully_grown:
-                self.energy += self.energy_from_food
-                grass_patch.fully_grown = False
+        """If possible, eat grass at current location."""
+        grass_patch = next(
+            obj for obj in self.cell.agents if isinstance(obj, GrassPatch)
+        )
+        if grass_patch.fully_grown:
+            self.energy += self.energy_from_food
+            grass_patch.fully_grown = False
 
 
 class Wolf(Animal):
     """A wolf that walks around, reproduces (asexually) and eats sheep."""
 
     def feed(self):
-        """If possible eat the food in the current location."""
+        """If possible, eat a sheep at current location."""
         sheep = [obj for obj in self.cell.agents if isinstance(obj, Sheep)]
-        if len(sheep) > 0:
+        if sheep:  # If there are any sheep present
             sheep_to_eat = self.random.choice(sheep)
             self.energy += self.energy_from_food
-
-            # Kill the sheep
             sheep_to_eat.remove()
 
 
 class GrassPatch(FixedAgent):
-    """
-    A patch of grass that grows at a fixed rate and it is eaten by sheep
-    """
+    """A patch of grass that grows at a fixed rate and can be eaten by sheep."""
+
+    @property
+    def fully_grown(self):
+        """Whether the grass patch is fully grown."""
+        return self._fully_grown
+
+    @fully_grown.setter
+    def fully_grown(self, value: bool) -> None:
+        """Set grass growth state and schedule regrowth if eaten."""
+        self._fully_grown = value
+
+        if not value:  # If grass was just eaten
+            self.model.simulator.schedule_event_relative(
+                setattr,
+                self.grass_regrowth_time,
+                function_args=[self, "fully_grown", True],
+            )
 
-    def __init__(self, model, fully_grown, countdown):
-        """
-        Creates a new patch of grass
+    def __init__(self, model, countdown, grass_regrowth_time, cell):
+        """Create a new patch of grass.
 
         Args:
-            grown: (boolean) Whether the patch of grass is fully grown or not
-            countdown: Time for the patch of grass to be fully grown again
+            model: Model instance
+            countdown: Time until grass is fully grown again
+            grass_regrowth_time: Time needed to regrow after being eaten
+            cell: Cell to which this grass patch belongs
         """
         super().__init__(model)
-        self.fully_grown = fully_grown
-        self.countdown = countdown
+        self._fully_grown = countdown == 0
+        self.grass_regrowth_time = grass_regrowth_time
+        self.cell = cell
 
-    def step(self):
+        # Schedule initial growth if not fully grown
         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(
+                setattr, countdown, function_args=[self, "fully_grown", True]
+            )

mesa/examples/advanced/wolf_sheep/app.py

@@ -1,5 +1,6 @@
 from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
 from mesa.examples.advanced.wolf_sheep.model import WolfSheep
+from mesa.experimental.devs import ABMSimulator
 from mesa.visualization import (
     Slider,
     SolaraViz,
@@ -36,7 +37,11 @@ def wolf_sheep_portrayal(agent):
 
 
 model_params = {
-    # The following line is an example to showcase StaticText.
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "grass": {
         "type": "Select",
         "value": True,
@@ -59,26 +64,32 @@ model_params = {
 }
 
 
-def post_process(ax):
+def post_process_space(ax):
     ax.set_aspect("equal")
     ax.set_xticks([])
     ax.set_yticks([])
 
 
+def post_process_lines(ax):
+    ax.legend(loc="center left", bbox_to_anchor=(1, 0.9))
+
+
 space_component = make_space_component(
-    wolf_sheep_portrayal, draw_grid=False, post_process=post_process
+    wolf_sheep_portrayal, draw_grid=False, post_process=post_process_space
 )
 lineplot_component = make_plot_component(
-    {"Wolves": "tab:orange", "Sheep": "tab:cyan", "Grass": "tab:green"}
+    {"Wolves": "tab:orange", "Sheep": "tab:cyan", "Grass": "tab:green"},
+    post_process=post_process_lines,
 )
 
-model = WolfSheep(grass=True)
-
+simulator = ABMSimulator()
+model = WolfSheep(simulator, grass=True)
 
 page = SolaraViz(
     model,
     components=[space_component, lineplot_component],
     model_params=model_params,
     name="Wolf Sheep",
+    simulator=simulator,
 )
 page  # noqa

mesa/examples/advanced/wolf_sheep/model.py

@@ -9,30 +9,20 @@ Replication of the model found in NetLogo:
     Northwestern University, Evanston, IL.
 """
 
-import mesa
-from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
-from mesa.experimental.cell_space import OrthogonalMooreGrid
-
-
-class WolfSheep(mesa.Model):
-    """
-    Wolf-Sheep Predation Model
-    """
-
-    height = 20
-    width = 20
+import math
 
-    initial_sheep = 100
-    initial_wolves = 50
+from mesa import Model
+from mesa.datacollection import DataCollector
+from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
+from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
+from mesa.experimental.devs import ABMSimulator
 
-    sheep_reproduce = 0.04
-    wolf_reproduce = 0.05
 
-    wolf_gain_from_food = 20
+class WolfSheep(Model):
+    """Wolf-Sheep Predation Model.
 
-    grass = False
-    grass_regrowth_time = 30
-    sheep_gain_from_food = 4
+    A model for simulating wolf and sheep (predator-prey) ecosystem modelling.
+    """
 
     description = (
         "A model for simulating wolf and sheep (predator-prey) ecosystem modelling."
@@ -47,15 +37,17 @@ class WolfSheep(mesa.Model):
         sheep_reproduce=0.04,
         wolf_reproduce=0.05,
         wolf_gain_from_food=20,
-        grass=False,
+        grass=True,
         grass_regrowth_time=30,
         sheep_gain_from_food=4,
         seed=None,
+        simulator: ABMSimulator = None,
     ):
-        """
-        Create a new Wolf-Sheep model with the given parameters.
+        """Create a new Wolf-Sheep model with the given parameters.
 
         Args:
+            height: Height of the grid
+            width: Width of the grid
             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
@@ -63,75 +55,77 @@ class WolfSheep(mesa.Model):
             wolf_gain_from_food: Energy a wolf gains from eating a sheep
             grass: Whether to have the sheep eat grass for energy
             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.
+                                once it is eaten
+            sheep_gain_from_food: Energy sheep gain from grass, if enabled
+            seed: Random seed
+            simulator: ABMSimulator instance for event scheduling
         """
         super().__init__(seed=seed)
-        # Set parameters
-        self.width = width
+        self.simulator = simulator
+        self.simulator.setup(self)
+
+        # Initialize model parameters
         self.height = height
-        self.initial_sheep = initial_sheep
-        self.initial_wolves = initial_wolves
+        self.width = width
         self.grass = grass
-        self.grass_regrowth_time = grass_regrowth_time
 
-        self.grid = OrthogonalMooreGrid((self.width, self.height), torus=True)
+        # Create grid using experimental cell space
+        self.grid = OrthogonalVonNeumannGrid(
+            [self.height, self.width],
+            torus=True,
+            capacity=math.inf,
+            random=self.random,
+        )
 
-        collectors = {
+        # Set up data collection
+        model_reporters = {
             "Wolves": lambda m: len(m.agents_by_type[Wolf]),
             "Sheep": lambda m: len(m.agents_by_type[Sheep]),
-            "Grass": lambda m: len(
+        }
+        if grass:
+            model_reporters["Grass"] = lambda m: len(
                 m.agents_by_type[GrassPatch].select(lambda a: a.fully_grown)
             )
-            if m.grass
-            else -1,
-        }
 
-        self.datacollector = mesa.DataCollector(collectors)
+        self.datacollector = DataCollector(model_reporters)
 
         # Create sheep:
-        for _ in range(self.initial_sheep):
-            x = self.random.randrange(self.width)
-            y = self.random.randrange(self.height)
-            energy = self.random.randrange(2 * self.sheep_gain_from_food)
-            Sheep(
-                self, energy, sheep_reproduce, sheep_gain_from_food, self.grid[(x, y)]
+        for _ in range(initial_sheep):
+            pos = (
+                self.random.randrange(width),
+                self.random.randrange(height),
             )
+            energy = self.random.randrange(2 * sheep_gain_from_food)
+            Sheep(self, energy, sheep_reproduce, sheep_gain_from_food, self.grid[pos])
 
         # Create wolves
-        for _ in range(self.initial_wolves):
-            x = self.random.randrange(self.width)
-            y = self.random.randrange(self.height)
-            energy = self.random.randrange(2 * self.wolf_gain_from_food)
-            Wolf(self, energy, wolf_reproduce, wolf_gain_from_food, self.grid[(x, y)])
-
-        # Create grass patches
-        if self.grass:
-            for cell in self.grid.all_cells:
-                fully_grown = self.random.choice([True, False])
-
-                if fully_grown:
-                    countdown = self.grass_regrowth_time
-                else:
-                    countdown = self.random.randrange(self.grass_regrowth_time)
-
-                patch = GrassPatch(self, fully_grown, countdown)
-                patch.cell = cell
-
+        for _ in range(initial_wolves):
+            pos = (
+                self.random.randrange(width),
+                self.random.randrange(height),
+            )
+            energy = self.random.randrange(2 * wolf_gain_from_food)
+            Wolf(self, energy, wolf_reproduce, wolf_gain_from_food, self.grid[pos])
+
+        # Create grass patches if enabled
+        if grass:
+            possibly_fully_grown = [True, False]
+            for cell in self.grid:
+                fully_grown = self.random.choice(possibly_fully_grown)
+                countdown = (
+                    0 if fully_grown else self.random.randrange(0, grass_regrowth_time)
+                )
+                GrassPatch(self, countdown, grass_regrowth_time, cell)
+
+        # Collect initial data
         self.running = True
         self.datacollector.collect(self)
 
     def step(self):
-        # This replicated the behavior of the old RandomActivationByType scheduler
-        # when using step(shuffle_types=True, shuffle_agents=True).
-        # Conceptually, it can be argued that this should be modelled differently.
-        self.random.shuffle(self.agent_types)
-        for agent_type in self.agent_types:
-            self.agents_by_type[agent_type].shuffle_do("step")
-
-        # collect data
-        self.datacollector.collect(self)
+        """Execute one step of the model."""
+        # First activate all sheep, then all wolves, both in random order
+        self.agents_by_type[Sheep].shuffle_do("step")
+        self.agents_by_type[Wolf].shuffle_do("step")
 
-    def run_model(self, step_count=200):
-        for _ in range(step_count):
-            self.step()
+        # Collect data
+        self.datacollector.collect(self)

mesa/examples/basic/boid_flockers/agents.py

@@ -1,3 +1,9 @@
+"""A Boid (bird-oid) agent for implementing Craig Reynolds's Boids flocking model.
+
+This implementation uses numpy arrays to represent vectors for efficient computation
+of flocking behavior.
+"""
+
 import numpy as np
 
 from mesa import Agent
@@ -7,9 +13,9 @@ class Boid(Agent):
     """A Boid-style flocker agent.
 
     The agent follows three behaviors to flock:
-        - Cohesion: steering towards neighboring agents.
-        - Separation: avoiding getting too close to any other agent.
-        - Alignment: try to fly in the same direction as the neighbors.
+        - Cohesion: steering towards neighboring agents
+        - Separation: avoiding getting too close to any other agent
+        - Alignment: trying to fly in the same direction as neighbors
 
     Boids have a vision that defines the radius in which they look for their
     neighbors to flock with. Their speed (a scalar) and direction (a vector)
@@ -31,13 +37,14 @@ class Boid(Agent):
         """Create a new Boid flocker agent.
 
         Args:
-            speed: Distance to move per step.
-            direction: numpy vector for the Boid's direction of movement.
-            vision: Radius to look around for nearby Boids.
-            separation: Minimum distance to maintain from other Boids.
-            cohere: the relative importance of matching neighbors' positions
-            separate: the relative importance of avoiding close neighbors
-            match: the relative importance of matching neighbors' headings
+            model: Model instance the agent belongs to
+            speed: Distance to move per step
+            direction: numpy vector for the Boid's direction of movement
+            vision: Radius to look around for nearby Boids
+            separation: Minimum distance to maintain from other Boids
+            cohere: Relative importance of matching neighbors' positions (default: 0.03)
+            separate: Relative importance of avoiding close neighbors (default: 0.015)
+            match: Relative importance of matching neighbors' directions (default: 0.05)
         """
         super().__init__(model)
         self.speed = speed
@@ -47,25 +54,49 @@ class Boid(Agent):
         self.cohere_factor = cohere
         self.separate_factor = separate
         self.match_factor = match
-        self.neighbors = None
 
     def step(self):
         """Get the Boid's neighbors, compute the new vector, and move accordingly."""
-        self.neighbors = self.model.space.get_neighbors(self.pos, self.vision, False)
-        n = 0
-        match_vector, separation_vector, cohere = np.zeros((3, 2))
-        for neighbor in self.neighbors:
-            n += 1
+        neighbors = self.model.space.get_neighbors(self.pos, self.vision, False)
+
+        # If no neighbors, maintain current direction
+        if not neighbors:
+            new_pos = self.pos + self.direction * self.speed
+            self.model.space.move_agent(self, new_pos)
+            return
+
+        # Initialize vectors for the three flocking behaviors
+        cohere = np.zeros(2)  # Cohesion vector
+        match_vector = np.zeros(2)  # Alignment vector
+        separation_vector = np.zeros(2)  # Separation vector
+
+        # Calculate the contribution of each neighbor to the three behaviors
+        for neighbor in neighbors:
             heading = self.model.space.get_heading(self.pos, neighbor.pos)
+            distance = self.model.space.get_distance(self.pos, neighbor.pos)
+
+            # Cohesion - steer towards the average position of neighbors
             cohere += heading
-            if self.model.space.get_distance(self.pos, neighbor.pos) < self.separation:
+
+            # Separation - avoid getting too close
+            if distance < self.separation:
                 separation_vector -= heading
+
+            # Alignment - match neighbors' flying direction
             match_vector += neighbor.direction
-        n = max(n, 1)
+
+        # Weight each behavior by its factor and normalize by number of neighbors
+        n = len(neighbors)
         cohere = cohere * self.cohere_factor
         separation_vector = separation_vector * self.separate_factor
         match_vector = match_vector * self.match_factor
+
+        # Update direction based on the three behaviors
         self.direction += (cohere + separation_vector + match_vector) / n
+
+        # Normalize direction vector
         self.direction /= np.linalg.norm(self.direction)
+
+        # Move boid
         new_pos = self.pos + self.direction * self.speed
         self.model.space.move_agent(self, new_pos)