Mesa 3.1.2__py3-none-any.whl → 3.1.4__py3-none-any.whl

mesa/__init__.py

@@ -22,7 +22,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "3.1.2"
+__version__ = "3.1.4"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.UTC).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/datacollection.py

@@ -117,6 +117,9 @@ class DataCollector:
         self._agenttype_records = {}
         self.tables = {}
 
+        # add the signal of the validation of model reporter
+        self._validated = False
+
         if model_reporters is not None:
             for name, reporter in model_reporters.items():
                 self._new_model_reporter(name, reporter)
@@ -134,13 +137,66 @@ class DataCollector:
             for name, columns in tables.items():
                 self._new_table(name, columns)
 
+    def _validate_model_reporter(self, name, reporter, model):
+        """Validate model reporter and handle validation results appropriately.
+
+        Args:
+            name: Name of the reporter
+            reporter: Reporter definition (lambda/method/attribute/function list)
+            model: Model instance
+
+        Raises:
+            ValueError: If reporter is None or has invalid format
+            AttributeError: If model attribute doesn't exist
+            TypeError: If reporter type is not supported
+            RuntimeError: If reporter execution fails
+        """
+        self._validated = True  # put the change of signal firstly avoid losing efficacy
+
+        # Type 1: Lambda function
+        if isinstance(reporter, types.LambdaType):
+            try:
+                reporter(model)
+            except Exception as e:
+                raise RuntimeError(
+                    f"Lambda reporter '{name}' failed validation: {e!s}\n"
+                    f"Example: lambda m: len(m.agents)"
+                ) from e
+
+        # Type 2: Method of class/instance
+        if not callable(reporter) and not isinstance(reporter, types.LambdaType):
+            pass
+
+        # Type 3: Model attribute (string)
+        if isinstance(reporter, str):
+            try:
+                if not hasattr(model, reporter):
+                    raise AttributeError(
+                        f"Model reporter '{name}' references non-existent attribute '{reporter}'\n"
+                    )
+                getattr(model, reporter)  # 验证属性是否可访问
+            except AttributeError as e:
+                raise AttributeError(
+                    f"Model reporter '{name}' attribute validation failed: {e!s}\n"
+                ) from e
+
+        # Type 4: Function with parameters in list
+        if isinstance(reporter, list) and (not reporter or not callable(reporter[0])):
+            raise ValueError(
+                f"Invalid function list format for reporter '{name}'\n"
+                f"Expected: [function, [param1, param2]], got: {reporter}"
+            )
+
     def _new_model_reporter(self, name, reporter):
         """Add a new model-level reporter to collect.
 
         Args:
             name: Name of the model-level variable to collect.
-            reporter: Attribute string, or function object that returns the
-                      variable when given a model instance.
+            reporter: Can be one of four types:
+                1. Attribute name (str): "attribute_name"
+                2. Lambda function: lambda m: len(m.agents)
+                3. Method: model.get_count or Model.get_count
+                4. List of [function, [parameters]]
         """
         self.model_reporters[name] = reporter
         self.model_vars[name] = []
@@ -262,6 +318,10 @@ class DataCollector:
     def collect(self, model):
         """Collect all the data for the given model object."""
         if self.model_reporters:
+            if not self._validated:
+                for name, reporter in self.model_reporters.items():
+                    self._validate_model_reporter(name, reporter, model)
+
             for var, reporter in self.model_reporters.items():
                 # Check if lambda or partial function
                 if isinstance(reporter, types.LambdaType | partial):

mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -1,46 +1,24 @@
-import numpy as np
-import solara
-from matplotlib.figure import Figure
-
 from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
 from mesa.visualization import Slider, SolaraViz, make_plot_component
+from mesa.visualization.components.matplotlib_components import make_mpl_space_component
+
 
+def agent_portrayal(agent):
+    return {"marker": "o", "color": "red", "size": 10}
 
-def SpaceDrawer(model):
-    def portray(g):
-        layers = {
-            "trader": {"x": [], "y": [], "c": "tab:red", "marker": "o", "s": 10},
-        }
 
-        for agent in g.all_cells.agents:
-            i, j = agent.cell.coordinate
-            layers["trader"]["x"].append(i)
-            layers["trader"]["y"].append(j)
-        return layers
+propertylayer_portrayal = {
+    "sugar": {"color": "blue", "alpha": 0.8, "colorbar": True, "vmin": 0, "vmax": 10},
+    "spice": {"color": "red", "alpha": 0.8, "colorbar": True, "vmin": 0, "vmax": 10},
+}
 
-    fig = Figure()
-    ax = fig.subplots()
-    out = portray(model.grid)
-    # Sugar
-    # Important note: imshow by default draws from upper left. You have to
-    # always explicitly specify 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(
-        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()
-    return solara.FigureMatplotlib(fig)
 
+sugarscape_space = make_mpl_space_component(
+    agent_portrayal=agent_portrayal,
+    propertylayer_portrayal=propertylayer_portrayal,
+    post_process=None,
+    draw_grid=False,
+)
 
 model_params = {
     "seed": {
@@ -72,7 +50,7 @@ model = SugarscapeG1mt()
 page = SolaraViz(
     model,
     components=[
-        SpaceDrawer,
+        sugarscape_space,
         make_plot_component("#Traders"),
         make_plot_component("Price"),
     ],

mesa/examples/basic/boid_flockers/agents.py

@@ -6,10 +6,10 @@ of flocking behavior.
 
 import numpy as np
 
-from mesa import Agent
+from mesa.experimental.continuous_space import ContinuousSpaceAgent
 
 
-class Boid(Agent):
+class Boid(ContinuousSpaceAgent):
     """A Boid-style flocker agent.
 
     The agent follows three behaviors to flock:
@@ -26,10 +26,12 @@ class Boid(Agent):
     def __init__(
         self,
         model,
-        speed,
-        direction,
-        vision,
-        separation,
+        space,
+        position=(0, 0),
+        speed=1,
+        direction=(1, 1),
+        vision=1,
+        separation=1,
         cohere=0.03,
         separate=0.015,
         match=0.05,
@@ -46,7 +48,8 @@ class Boid(Agent):
             separate: Relative importance of avoiding close neighbors (default: 0.015)
             match: Relative importance of matching neighbors' directions (default: 0.05)
         """
-        super().__init__(model)
+        super().__init__(space, model)
+        self.position = position
         self.speed = speed
         self.direction = direction
         self.vision = vision
@@ -58,46 +61,31 @@ class Boid(Agent):
 
     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)
+        neighbors, distances = self.get_neighbors_in_radius(radius=self.vision)
+        self.neighbors = [n for n in neighbors if n is not self]
 
         # If no neighbors, maintain current direction
-        if not self.neighbors:
-            new_pos = self.pos + self.direction * self.speed
-            self.model.space.move_agent(self, new_pos)
+        if not neighbors:
+            self.position += self.direction * self.speed
             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
+        delta = self.space.calculate_difference_vector(self.position, agents=neighbors)
 
-        # Calculate the contribution of each neighbor to the three behaviors
-        for neighbor in self.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
-
-            # Separation - avoid getting too close
-            if distance < self.separation:
-                separation_vector -= heading
-
-            # Alignment - match neighbors' flying direction
-            match_vector += neighbor.direction
-
-        # Weight each behavior by its factor and normalize by number of neighbors
-        n = len(self.neighbors)
-        cohere = cohere * self.cohere_factor
-        separation_vector = separation_vector * self.separate_factor
-        match_vector = match_vector * self.match_factor
+        cohere_vector = delta.sum(axis=0) * self.cohere_factor
+        separation_vector = (
+            -1 * delta[distances < self.separation].sum(axis=0) * self.separate_factor
+        )
+        match_vector = (
+            np.asarray([n.direction for n in neighbors]).sum(axis=0) * self.match_factor
+        )
 
         # Update direction based on the three behaviors
-        self.direction += (cohere + separation_vector + match_vector) / n
+        self.direction += (cohere_vector + separation_vector + match_vector) / len(
+            neighbors
+        )
 
         # 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)
+        self.position += self.direction * self.speed

mesa/examples/basic/boid_flockers/app.py

@@ -1,3 +1,8 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../../.."))
+
 from mesa.examples.basic.boid_flockers.model import BoidFlockers
 from mesa.visualization import Slider, SolaraViz, make_space_component
 
@@ -17,7 +22,7 @@ model_params = {
         "value": 42,
         "label": "Random Seed",
     },
-    "population": Slider(
+    "population_size": Slider(
         label="Number of boids",
         value=100,
         min=10,

mesa/examples/basic/boid_flockers/model.py

@@ -5,11 +5,17 @@ A Mesa implementation of Craig Reynolds's Boids flocker model.
 Uses numpy arrays to represent vectors.
 """
 
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../../.."))
+
+
 import numpy as np
 
 from mesa import Model
 from mesa.examples.basic.boid_flockers.agents import Boid
-from mesa.space import ContinuousSpace
+from mesa.experimental.continuous_space import ContinuousSpace
 
 
 class BoidFlockers(Model):
@@ -17,7 +23,7 @@ class BoidFlockers(Model):
 
     def __init__(
         self,
-        population=100,
+        population_size=100,
         width=100,
         height=100,
         speed=1,
@@ -31,7 +37,7 @@ class BoidFlockers(Model):
         """Create a new Boids Flocking model.
 
         Args:
-            population: Number of Boids in the simulation (default: 100)
+            population_size: Number of Boids in the simulation (default: 100)
             width: Width of the space (default: 100)
             height: Height of the space (default: 100)
             speed: How fast the Boids move (default: 1)
@@ -44,48 +50,35 @@ class BoidFlockers(Model):
         """
         super().__init__(seed=seed)
 
-        # Model Parameters
-        self.population = population
-        self.vision = vision
-        self.speed = speed
-        self.separation = separation
-
         # Set up the space
-        self.space = ContinuousSpace(width, height, torus=True)
-
-        # Store flocking weights
-        self.factors = {"cohere": cohere, "separate": separate, "match": match}
+        self.space = ContinuousSpace(
+            [[0, width], [0, height]],
+            torus=True,
+            random=self.random,
+            n_agents=population_size,
+        )
 
         # Create and place the Boid agents
-        self.make_agents()
+        positions = self.rng.random(size=(population_size, 2)) * self.space.size
+        directions = self.rng.uniform(-1, 1, size=(population_size, 2))
+        Boid.create_agents(
+            self,
+            population_size,
+            self.space,
+            position=positions,
+            direction=directions,
+            cohere=cohere,
+            separate=separate,
+            match=match,
+            speed=speed,
+            vision=vision,
+            separation=separation,
+        )
 
         # For tracking statistics
         self.average_heading = None
         self.update_average_heading()
 
-    def make_agents(self):
-        """Create and place all Boid agents randomly in the space."""
-        for _ in range(self.population):
-            # Random position
-            x = self.random.random() * self.space.x_max
-            y = self.random.random() * self.space.y_max
-            pos = np.array((x, y))
-
-            # Random initial direction
-            direction = np.random.random(2) * 2 - 1  # Random vector between -1 and 1
-            direction /= np.linalg.norm(direction)  # Normalize
-
-            # Create and place the Boid
-            boid = Boid(
-                model=self,
-                speed=self.speed,
-                direction=direction,
-                vision=self.vision,
-                separation=self.separation,
-                **self.factors,
-            )
-            self.space.place_agent(boid, pos)
-
     def update_average_heading(self):
         """Calculate the average heading (direction) of all Boids."""
         if not self.agents:

mesa/experimental/__init__.py

@@ -15,6 +15,6 @@ Notes:
     - Features graduate from experimental status once their APIs are stabilized
 """
 
-from mesa.experimental import cell_space, devs, mesa_signals
+from mesa.experimental import cell_space, continuous_space, devs, mesa_signals
 
-__all__ = ["cell_space", "devs", "mesa_signals"]
+__all__ = ["cell_space", "continuous_space", "devs", "mesa_signals"]

mesa/experimental/cell_space/grid.py

@@ -273,20 +273,20 @@ class HexGrid(Grid[T]):
     def _connect_cells_2d(self) -> None:
         # fmt: off
         even_offsets = [
-                        (-1, -1), (-1, 0),
-                    ( 0, -1),        ( 0, 1),
-                        ( 1, -1), ( 1, 0),
+                        (-1, -1), (0, -1),
+                    ( -1, 0),        ( 1, 0),
+                        ( -1, 1), (0, 1),
                 ]
         odd_offsets = [
-                        (-1, 0), (-1, 1),
-                    ( 0, -1),       ( 0, 1),
-                        ( 1, 0), ( 1, 1),
+                        (0, -1), (1, -1),
+                    ( -1, 0),       ( 1, 0),
+                        ( 0, 1), ( 1, 1),
                 ]
         # fmt: on
 
         for cell in self.all_cells:
-            i = cell.coordinate[0]
-            offsets = even_offsets if i % 2 == 0 else odd_offsets
+            i = cell.coordinate[1]
+            offsets = even_offsets if i % 2 else odd_offsets
             self._connect_single_cell_2d(cell, offsets=offsets)
 
     def _connect_cells_nd(self) -> None:

mesa/experimental/cell_space/voronoi.py

@@ -186,7 +186,6 @@ class VoronoiGrid(DiscreteSpace):
         random: Random | None = None,
         cell_klass: type[Cell] = Cell,
         capacity_function: callable = round_float,
-        cell_coloring_property: str | None = None,
     ) -> None:
         """A Voronoi Tessellation Grid.
 
@@ -200,7 +199,7 @@ class VoronoiGrid(DiscreteSpace):
             random (Random): random number generator
             cell_klass (type[Cell]): type of cell class
             capacity_function (Callable): function to compute (int) capacity according to (float) area
-            cell_coloring_property (str): voronoi visualization polygon fill property
+
         """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
         self.centroids_coordinates = centroids_coordinates
@@ -215,7 +214,6 @@ class VoronoiGrid(DiscreteSpace):
         self.triangulation = None
         self.voronoi_coordinates = None
         self.capacity_function = capacity_function
-        self.cell_coloring_property = cell_coloring_property
 
         self._connect_cells()
         self._build_cell_polygons()
@@ -266,4 +264,3 @@ class VoronoiGrid(DiscreteSpace):
             polygon_area = self._compute_polygon_area(polygon)
             self._cells[region].properties["area"] = polygon_area
             self._cells[region].capacity = self.capacity_function(polygon_area)
-            self._cells[region].properties[self.cell_coloring_property] = 0

mesa/experimental/continuous_space/__init__.py

@@ -0,0 +1,8 @@
+"""Continuous space support."""
+
+from mesa.experimental.continuous_space.continuous_space import ContinuousSpace
+from mesa.experimental.continuous_space.continuous_space_agents import (
+    ContinuousSpaceAgent,
+)
+
+__all__ = ["ContinuousSpace", "ContinuousSpaceAgent"]