Mesa 3.1.0.dev0__py3-none-any.whl → 3.1.1__py3-none-any.whl

mesa/__init__.py

@@ -13,16 +13,16 @@ from mesa.datacollection import DataCollector
 from mesa.model import Model
 
 __all__ = [
-    "Model",
     "Agent",
-    "space",
     "DataCollector",
+    "Model",
     "batch_run",
     "experimental",
+    "space",
 ]
 
 __title__ = "mesa"
-__version__ = "3.1.0.dev"
+__version__ = "3.1.1"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.UTC).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -85,6 +85,54 @@ class Agent:
     def advance(self) -> None:  # noqa: D102
         pass
 
+    @classmethod
+    def create_agents(cls, model: Model, n: int, *args, **kwargs) -> AgentSet[Agent]:
+        """Create N agents.
+
+        Args:
+            model: the model to which the agents belong
+            args: arguments to pass onto agent instances
+                  each arg is either a single object or a sequence of length n
+            n: the number of agents to create
+            kwargs: keyword arguments to pass onto agent instances
+                   each keyword arg is either a single object or a sequence of length n
+
+        Returns:
+            AgentSet containing the agents created.
+
+        """
+
+        class ListLike:
+            """Helper class to make default arguments act as if they are in a list of length N."""
+
+            def __init__(self, value):
+                self.value = value
+
+            def __getitem__(self, i):
+                return self.value
+
+        listlike_args = []
+        for arg in args:
+            if isinstance(arg, (list | np.ndarray | tuple)) and len(arg) == n:
+                listlike_args.append(arg)
+            else:
+                listlike_args.append(ListLike(arg))
+
+        listlike_kwargs = {}
+        for k, v in kwargs.items():
+            if isinstance(v, (list | np.ndarray | tuple)) and len(v) == n:
+                listlike_kwargs[k] = v
+            else:
+                listlike_kwargs[k] = ListLike(v)
+
+        agents = []
+        for i in range(n):
+            instance_args = [arg[i] for arg in listlike_args]
+            instance_kwargs = {k: v[i] for k, v in listlike_kwargs.items()}
+            agent = cls(model, *instance_args, **instance_kwargs)
+            agents.append(agent)
+        return AgentSet(agents, random=model.random)
+
     @property
     def random(self) -> Random:
         """Return a seeded stdlib rng."""

mesa/batchrunner.py

@@ -106,7 +106,14 @@ def _make_model_kwargs(
     Parameters
     ----------
     parameters : Mapping[str, Union[Any, Iterable[Any]]]
-        Single or multiple values for each model parameter name
+        Single or multiple values for each model parameter name.
+
+        Allowed values for each parameter:
+        - A single value (e.g., `32`, `"relu"`).
+        - A non-empty iterable (e.g., `[0.01, 0.1]`, `["relu", "sigmoid"]`).
+
+        Not allowed:
+        - Empty lists or empty iterables (e.g., `[]`, `()`, etc.). These should be removed manually.
 
     Returns:
     -------
@@ -118,6 +125,12 @@ def _make_model_kwargs(
         if isinstance(values, str):
             # The values is a single string, so we shouldn't iterate over it.
             all_values = [(param, values)]
+        elif isinstance(values, list | tuple | set) and len(values) == 0:
+            # If it's an empty iterable, raise an error
+            raise ValueError(
+                f"Parameter '{param}' contains an empty iterable, which is not allowed."
+            )
+
         else:
             try:
                 all_values = [(param, value) for value in values]

mesa/datacollection.py

@@ -228,12 +228,7 @@ class DataCollector:
             reports = tuple(rep(agent) for rep in rep_funcs)
             return _prefix + reports
 
-        agent_records = map(
-            get_reports,
-            model.schedule.agents
-            if hasattr(model, "schedule") and model.schedule is not None
-            else model.agents,
-        )
+        agent_records = map(get_reports, model.agents)
         return agent_records
 
     def _record_agenttype(self, model, agent_type):

mesa/examples/__init__.py

@@ -12,10 +12,10 @@ __all__ = [
     "BoidFlockers",
     "BoltzmannWealth",
     "ConwaysGameOfLife",
-    "Schelling",
-    "VirusOnNetwork",
     "EpsteinCivilViolence",
     "PdGrid",
+    "Schelling",
     "SugarscapeG1mt",
+    "VirusOnNetwork",
     "WolfSheep",
 ]

mesa/examples/advanced/epstein_civil_violence/app.py

@@ -44,6 +44,11 @@ def post_process(ax):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "height": 40,
     "width": 40,
     "citizen_density": Slider("Initial Agent Density", 0.7, 0.0, 0.9, 0.1),

mesa/examples/advanced/pd_grid/agents.py

@@ -4,7 +4,7 @@ from mesa.experimental.cell_space import CellAgent
 class PDAgent(CellAgent):
     """Agent member of the iterated, spatial prisoner's dilemma model."""
 
-    def __init__(self, model, starting_move=None):
+    def __init__(self, model, starting_move=None, cell=None):
         """
         Create a new Prisoner's Dilemma agent.
 
@@ -15,6 +15,7 @@ class PDAgent(CellAgent):
         """
         super().__init__(model)
         self.score = 0
+        self.cell = cell
         if starting_move:
             self.move = starting_move
         else:

mesa/examples/advanced/pd_grid/app.py

@@ -24,6 +24,11 @@ def pd_agent_portrayal(agent):
 
 # Model parameters
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "width": Slider("Grid Width", value=50, min=10, max=100, step=1),
     "height": Slider("Grid Height", value=50, min=10, max=100, step=1),
     "activation_order": {

mesa/examples/advanced/pd_grid/model.py

@@ -32,11 +32,9 @@ class PdGrid(mesa.Model):
         if payoffs is not None:
             self.payoff = payoffs
 
-        # Create agents
-        for x in range(width):
-            for y in range(height):
-                agent = PDAgent(self)
-                agent.cell = self.grid[(x, y)]
+        PDAgent.create_agents(
+            self, len(self.grid.all_cells.cells), cell=self.grid.all_cells.cells
+        )
 
         self.datacollector = mesa.DataCollector(
             {

mesa/examples/advanced/sugarscape_g1mt/agents.py

@@ -1,6 +1,6 @@
 import math
 
-from mesa.experimental.cell_space import CellAgent, FixedAgent
+from mesa.experimental.cell_space import CellAgent
 
 
 # Helper function
@@ -18,31 +18,6 @@ def get_distance(cell_1, cell_2):
     return math.sqrt(dx**2 + dy**2)
 
 
-class Resource(FixedAgent):
-    """
-    Resource:
-    - contains an amount of sugar and spice
-    - grows 1 amount of sugar at each turn
-    - grows 1 amount of spice at each turn
-    """
-
-    def __init__(self, model, max_sugar, max_spice, cell):
-        super().__init__(model)
-        self.sugar_amount = max_sugar
-        self.max_sugar = max_sugar
-        self.spice_amount = max_spice
-        self.max_spice = max_spice
-        self.cell = cell
-
-    def step(self):
-        """
-        Growth function, adds one unit of sugar and spice each step up to
-        max amount
-        """
-        self.sugar_amount = min([self.max_sugar, self.sugar_amount + 1])
-        self.spice_amount = min([self.max_spice, self.spice_amount + 1])
-
-
 class Trader(CellAgent):
     """
     Trader:
@@ -70,12 +45,6 @@ class Trader(CellAgent):
         self.prices = []
         self.trade_partners = []
 
-    def get_resource(self, cell):
-        for agent in cell.agents:
-            if isinstance(agent, Resource):
-                return agent
-        raise Exception(f"Resource agent not found in the position {cell.coordinate}")
-
     def get_trader(self, cell):
         """
         helper function used in self.trade_with_neighbors()
@@ -85,17 +54,6 @@ class Trader(CellAgent):
             if isinstance(agent, Trader):
                 return agent
 
-    def is_occupied_by_other(self, cell):
-        """
-        helper function part 1 of self.move()
-        """
-
-        if cell is self.cell:
-            # agent's position is considered unoccupied as agent can stay there
-            return False
-        # get contents of each cell in neighborhood
-        return any(isinstance(a, Trader) for a in cell.agents)
-
     def calculate_welfare(self, sugar, spice):
         """
         helper function
@@ -264,15 +222,15 @@ class Trader(CellAgent):
         neighboring_cells = [
             cell
             for cell in self.cell.get_neighborhood(self.vision, include_center=True)
-            if not self.is_occupied_by_other(cell)
+            if cell.is_empty
         ]
 
         # 2. determine which move maximizes welfare
 
         welfares = [
             self.calculate_welfare(
-                self.sugar + self.get_resource(cell).sugar_amount,
-                self.spice + self.get_resource(cell).spice_amount,
+                self.sugar + cell.sugar,
+                self.spice + cell.spice,
             )
             for cell in neighboring_cells
         ]
@@ -282,6 +240,7 @@ class Trader(CellAgent):
         # find the highest welfare in welfares
         max_welfare = max(welfares)
         # get the index of max welfare cells
+        # fixme: rewrite using enumerate and single loop
         candidate_indices = [
             i for i in range(len(welfares)) if math.isclose(welfares[i], max_welfare)
         ]
@@ -296,19 +255,17 @@ class Trader(CellAgent):
             for cell in candidates
             if math.isclose(get_distance(self.cell, cell), min_dist, rel_tol=1e-02)
         ]
+
         # 4. Move Agent
         self.cell = self.random.choice(final_candidates)
 
     def eat(self):
-        patch = self.get_resource(self.cell)
-        if patch.sugar_amount > 0:
-            self.sugar += patch.sugar_amount
-            patch.sugar_amount = 0
+        self.sugar += self.cell.sugar
+        self.cell.sugar = 0
         self.sugar -= self.metabolism_sugar
 
-        if patch.spice_amount > 0:
-            self.spice += patch.spice_amount
-            patch.spice_amount = 0
+        self.spice += self.cell.spice
+        self.cell.spice = 0
         self.spice -= self.metabolism_spice
 
     def maybe_die(self):
@@ -327,18 +284,8 @@ class Trader(CellAgent):
         2- trade (2 sessions)
         3- collect data
         """
-
-        neighbor_agents = [
-            self.get_trader(cell)
-            for cell in self.cell.get_neighborhood(radius=self.vision)
-            if self.is_occupied_by_other(cell)
-        ]
-
-        if len(neighbor_agents) == 0:
-            return
-
-            # iterate through traders in neighboring cells and trade
-        for a in neighbor_agents:
+        # iterate through traders in neighboring cells and trade
+        for a in self.cell.get_neighborhood(radius=self.vision).agents:
             self.trade(a)
 
         return

mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -2,7 +2,6 @@ import numpy as np
 import solara
 from matplotlib.figure import Figure
 
-from mesa.examples.advanced.sugarscape_g1mt.agents import Trader
 from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
 from mesa.visualization import Slider, SolaraViz, make_plot_component
 
@@ -10,24 +9,13 @@ from mesa.visualization import Slider, SolaraViz, make_plot_component
 def SpaceDrawer(model):
     def portray(g):
         layers = {
-            "sugar": [[np.nan for j in range(g.height)] for i in range(g.width)],
-            "spice": [[np.nan for j in range(g.height)] for i in range(g.width)],
             "trader": {"x": [], "y": [], "c": "tab:red", "marker": "o", "s": 10},
         }
 
         for agent in g.all_cells.agents:
             i, j = agent.cell.coordinate
-            if isinstance(agent, Trader):
-                layers["trader"]["x"].append(i)
-                layers["trader"]["y"].append(j)
-            else:
-                # Don't visualize resource with value <= 1.
-                layers["sugar"][i][j] = (
-                    agent.sugar_amount if agent.sugar_amount > 1 else np.nan
-                )
-                layers["spice"][i][j] = (
-                    agent.spice_amount if agent.spice_amount > 1 else np.nan
-                )
+            layers["trader"]["x"].append(i)
+            layers["trader"]["y"].append(j)
         return layers
 
     fig = Figure()
@@ -36,10 +24,18 @@ def SpaceDrawer(model):
     # Sugar
     # Important note: imshow by default draws from upper left. You have to
     # always explicitly specify origin="lower".
-    im = ax.imshow(out["sugar"], cmap="spring", origin="lower")
+    im = ax.imshow(
+        np.ma.masked_where(model.grid.sugar.data <= 1, model.grid.sugar.data),
+        cmap="spring",
+        origin="lower",
+    )
     fig.colorbar(im, orientation="vertical")
     # Spice
-    ax.imshow(out["spice"], cmap="winter", origin="lower")
+    ax.imshow(
+        np.ma.masked_where(model.grid.spice.data <= 1, model.grid.spice.data),
+        cmap="winter",
+        origin="lower",
+    )
     # Trader
     ax.scatter(**out["trader"])
     ax.set_axis_off()
@@ -47,6 +43,11 @@ def SpaceDrawer(model):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "width": 50,
     "height": 50,
     # Population parameters
@@ -66,11 +67,15 @@ model_params = {
     "enable_trade": {"type": "Checkbox", "value": True, "label": "Enable Trading"},
 }
 
-model1 = SugarscapeG1mt()
+model = SugarscapeG1mt()
 
 page = SolaraViz(
-    model1,
-    components=[SpaceDrawer, make_plot_component(["Trader", "Price"])],
+    model,
+    components=[
+        SpaceDrawer,
+        make_plot_component("#Traders"),
+        make_plot_component("Price"),
+    ],
     model_params=model_params,
     name="Sugarscape {G1, M, T}",
     play_interval=150,

mesa/examples/advanced/sugarscape_g1mt/model.py

@@ -3,8 +3,9 @@ from pathlib import Path
 import numpy as np
 
 import mesa
-from mesa.examples.advanced.sugarscape_g1mt.agents import Resource, Trader
+from mesa.examples.advanced.sugarscape_g1mt.agents import Trader
 from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
+from mesa.experimental.cell_space.property_layer import PropertyLayer
 
 
 # Helper Functions
@@ -58,14 +59,8 @@ class SugarscapeG1mt(mesa.Model):
         # Initiate width and height of sugarscape
         self.width = width
         self.height = height
+
         # Initiate population attributes
-        self.initial_population = initial_population
-        self.endowment_min = endowment_min
-        self.endowment_max = endowment_max
-        self.metabolism_min = metabolism_min
-        self.metabolism_max = metabolism_max
-        self.vision_min = vision_min
-        self.vision_max = vision_max
         self.enable_trade = enable_trade
         self.running = True
 
@@ -76,55 +71,46 @@ class SugarscapeG1mt(mesa.Model):
         # initiate datacollector
         self.datacollector = mesa.DataCollector(
             model_reporters={
-                "Trader": lambda m: len(m.agents_by_type[Trader]),
-                "Trade Volume": lambda m: sum(
-                    len(a.trade_partners) for a in m.agents_by_type[Trader]
-                ),
+                "#Traders": lambda m: len(m.agents),
+                "Trade Volume": lambda m: sum(len(a.trade_partners) for a in m.agents),
                 "Price": lambda m: geometric_mean(
-                    flatten([a.prices for a in m.agents_by_type[Trader]])
+                    flatten([a.prices for a in m.agents])
                 ),
             },
             agent_reporters={"Trade Network": lambda a: get_trade(a)},
         )
 
-        # read in landscape file from supplmentary material
-        sugar_distribution = np.genfromtxt(Path(__file__).parent / "sugar-map.txt")
-        spice_distribution = np.flip(sugar_distribution, 1)
-
-        for cell in self.grid.all_cells:
-            max_sugar = sugar_distribution[cell.coordinate]
-            max_spice = spice_distribution[cell.coordinate]
-            Resource(self, max_sugar, max_spice, cell)
-
-        for _ in range(self.initial_population):
-            # get agent position
-            x = self.random.randrange(self.width)
-            y = self.random.randrange(self.height)
-            # see Growing Artificial Societies p. 108 for initialization
-            # give agents initial endowment
-            sugar = int(self.random.uniform(self.endowment_min, self.endowment_max + 1))
-            spice = int(self.random.uniform(self.endowment_min, self.endowment_max + 1))
-            # give agents initial metabolism
-            metabolism_sugar = int(
-                self.random.uniform(self.metabolism_min, self.metabolism_max + 1)
-            )
-            metabolism_spice = int(
-                self.random.uniform(self.metabolism_min, self.metabolism_max + 1)
-            )
-            # give agents vision
-            vision = int(self.random.uniform(self.vision_min, self.vision_max + 1))
-
-            cell = self.grid[(x, y)]
-            # create Trader object
-            Trader(
-                self,
-                cell,
-                sugar=sugar,
-                spice=spice,
-                metabolism_sugar=metabolism_sugar,
-                metabolism_spice=metabolism_spice,
-                vision=vision,
-            )
+        # read in landscape file from supplementary material
+        self.sugar_distribution = np.genfromtxt(Path(__file__).parent / "sugar-map.txt")
+        self.spice_distribution = np.flip(self.sugar_distribution, 1)
+
+        self.grid.add_property_layer(
+            PropertyLayer.from_data("sugar", self.sugar_distribution)
+        )
+        self.grid.add_property_layer(
+            PropertyLayer.from_data("spice", self.spice_distribution)
+        )
+
+        Trader.create_agents(
+            self,
+            initial_population,
+            self.random.choices(self.grid.all_cells.cells, k=initial_population),
+            sugar=self.rng.integers(
+                endowment_min, endowment_max, (initial_population,), endpoint=True
+            ),
+            spice=self.rng.integers(
+                endowment_min, endowment_max, (initial_population,), endpoint=True
+            ),
+            metabolism_sugar=self.rng.integers(
+                metabolism_min, metabolism_max, (initial_population,), endpoint=True
+            ),
+            metabolism_spice=self.rng.integers(
+                metabolism_min, metabolism_max, (initial_population,), endpoint=True
+            ),
+            vision=self.rng.integers(
+                vision_min, vision_max, (initial_population,), endpoint=True
+            ),
+        )
 
     def step(self):
         """
@@ -132,7 +118,12 @@ class SugarscapeG1mt(mesa.Model):
         and then randomly activates traders
         """
         # step Resource agents
-        self.agents_by_type[Resource].do("step")
+        self.grid.sugar.data = np.minimum(
+            self.grid.sugar.data + 1, self.sugar_distribution
+        )
+        self.grid.spice.data = np.minimum(
+            self.grid.spice.data + 1, self.spice_distribution
+        )
 
         # step trader agents
         # to account for agent death and removal we need a separate data structure to
@@ -157,6 +148,8 @@ class SugarscapeG1mt(mesa.Model):
             agent.trade_with_neighbors()
 
         # collect model level data
+        # fixme we can already collect agent class data
+        # fixme, we don't have resource agents anymore so this can be done simpler
         self.datacollector.collect(self)
         """
         Mesa is working on updating datacollector agent reporter

mesa/examples/advanced/wolf_sheep/agents.py

@@ -4,7 +4,9 @@ from mesa.experimental.cell_space import CellAgent, FixedAgent
 class Animal(CellAgent):
     """The base animal class."""
 
-    def __init__(self, model, energy, p_reproduce, energy_from_food, cell):
+    def __init__(
+        self, model, energy=8, p_reproduce=0.04, energy_from_food=4, cell=None
+    ):
         """Initialize an animal.
 
         Args:

mesa/examples/advanced/wolf_sheep/model.py

@@ -90,22 +90,23 @@ class WolfSheep(Model):
         self.datacollector = DataCollector(model_reporters)
 
         # Create sheep:
-        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(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])
+        Sheep.create_agents(
+            self,
+            initial_sheep,
+            energy=self.rng.random((initial_sheep,)) * 2 * sheep_gain_from_food,
+            p_reproduce=sheep_reproduce,
+            energy_from_food=sheep_gain_from_food,
+            cell=self.random.choices(self.grid.all_cells.cells, k=initial_sheep),
+        )
+        # Create Wolves:
+        Wolf.create_agents(
+            self,
+            initial_wolves,
+            energy=self.rng.random((initial_wolves,)) * 2 * wolf_gain_from_food,
+            p_reproduce=wolf_reproduce,
+            energy_from_food=wolf_gain_from_food,
+            cell=self.random.choices(self.grid.all_cells.cells, k=initial_wolves),
+        )
 
         # Create grass patches if enabled
         if grass:

mesa/examples/basic/boid_flockers/app.py

@@ -12,6 +12,11 @@ def boid_draw(agent):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "population": Slider(
         label="Number of boids",
         value=100,

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -1,10 +1,13 @@
 from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealth
+from mesa.mesa_logging import DEBUG, log_to_stderr
 from mesa.visualization import (
     SolaraViz,
     make_plot_component,
     make_space_component,
 )
 
+log_to_stderr(DEBUG)
+
 
 def agent_portrayal(agent):
     color = agent.wealth  # we are using a colormap to translate wealth to color
@@ -12,6 +15,11 @@ def agent_portrayal(agent):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "n": {
         "type": "SliderInt",
         "value": 50,
@@ -20,11 +28,6 @@ model_params = {
         "max": 100,
         "step": 1,
     },
-    "seed": {
-        "type": "InputText",
-        "value": 42,
-        "label": "Random Seed",
-    },
     "width": 10,
     "height": 10,
 }

mesa/examples/basic/boltzmann_wealth_model/st_app.py

@@ -68,7 +68,7 @@ if run:
     for i in range(num_ticks):
         model.step()
         my_bar.progress((i / num_ticks), text="Simulation progress")
-        placeholder.text("Step = %d" % i)
+        placeholder.text(f"Step = {i}")
         for cell in model.grid.coord_iter():
             cell_content, (x, y) = cell
             agent_count = len(cell_content)