Mesa 3.1.1__py3-none-any.whl → 3.1.3__py3-none-any.whl

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/examples/basic/schelling/analysis.ipynb

@@ -17,7 +17,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "import matplotlib.pyplot as plt\n",
     "import pandas as pd\n",
@@ -25,9 +27,7 @@
     "%matplotlib inline\n",
     "\n",
     "from model import Schelling"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -38,10 +38,14 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": "model = Schelling(height=10, width=10, homophily=3, density=0.8, minority_pc=0.2)",
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "schelling_model = Schelling(\n",
+    "    height=10, width=10, homophily=3, density=0.8, minority_pc=0.2\n",
+    ")"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -52,14 +56,14 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": [
-    "while model.running and model.steps < 100:\n",
-    "    model.step()\n",
-    "print(model.steps)  # Show how many steps have actually run"
-   ],
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "while schelling_model.running and schelling_model.steps < 100:\n",
+    "    schelling_model.step()\n",
+    "print(schelling_model.steps)  # Show how many steps have actually run"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -70,21 +74,21 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": [
-    "model_out = model.datacollector.get_model_vars_dataframe()"
-   ],
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "model_out = schelling_model.datacollector.get_model_vars_dataframe()"
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "model_out.head()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -95,12 +99,12 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "model_out.happy.plot()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -115,10 +119,12 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": "from mesa.batchrunner import batch_run",
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "from mesa.batchrunner import batch_run"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -129,18 +135,20 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "fixed_params = {\"height\": 10, \"width\": 10, \"density\": 0.8, \"minority_pc\": 0.2}\n",
     "variable_parms = {\"homophily\": range(1, 9)}\n",
     "all_params = fixed_params | variable_parms"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "results = batch_run(\n",
     "    Schelling,\n",
@@ -148,23 +156,23 @@
     "    iterations=10,\n",
     "    max_steps=200,\n",
     ")"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "df = pd.DataFrame(results)\n",
     "df"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "plt.scatter(df.homophily, df.happy)\n",
     "plt.xlabel(\"Homophily\")\n",
@@ -172,9 +180,7 @@
     "plt.grid()\n",
     "plt.title(\"Effect of Homophily on segregation\")\n",
     "plt.show()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   }
  ],
  "metadata": {

mesa/examples/basic/schelling/app.py

@@ -26,7 +26,7 @@ model_params = {
     },
     "density": Slider("Agent density", 0.8, 0.1, 1.0, 0.1),
     "minority_pc": Slider("Fraction minority", 0.2, 0.0, 1.0, 0.05),
-    "homophily": Slider("Homophily", 0.3, 0.0, 0.8, 0.1),
+    "homophily": Slider("Homophily", 0.4, 0.0, 1.0, 0.125),
     "width": 20,
     "height": 20,
 }

mesa/examples/basic/schelling/model.py

@@ -9,11 +9,11 @@ class Schelling(Model):
 
     def __init__(
         self,
-        height: int = 40,
-        width: int = 40,
+        height: int = 20,
+        width: int = 20,
         density: float = 0.8,
         minority_pc: float = 0.5,
-        homophily: int = 3,
+        homophily: float = 0.4,
         radius: int = 1,
         seed=None,
     ):

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/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"]

mesa/experimental/continuous_space/continuous_space.py

@@ -0,0 +1,273 @@
+"""A Continuous Space class."""
+
+import warnings
+from collections.abc import Iterable
+from itertools import compress
+from random import Random
+
+import numpy as np
+from numpy.typing import ArrayLike
+from scipy.spatial.distance import cdist
+
+from mesa.agent import Agent, AgentSet
+
+
+class ContinuousSpace:
+    """Continuous space where each agent can have an arbitrary position."""
+
+    @property
+    def x_min(self):  # noqa: D102
+        # compatibility with solara_viz
+        return self.dimensions[0, 0]
+
+    @property
+    def x_max(self):  # noqa: D102
+        # compatibility with solara_viz
+        return self.dimensions[0, 1]
+
+    @property
+    def y_min(self):  # noqa: D102
+        # compatibility with solara_viz
+        return self.dimensions[1, 0]
+
+    @property
+    def y_max(self):  # noqa: D102
+        # compatibility with solara_viz
+        return self.dimensions[1, 1]
+
+    @property
+    def width(self):  # noqa: D102
+        # compatibility with solara_viz
+        return self.size[0]
+
+    @property
+    def height(self):  # noqa: D102
+        # compatibility with solara_viz
+        return self.size[1]
+
+    def __init__(
+        self,
+        dimensions: ArrayLike,
+        torus: bool = False,
+        random: Random | None = None,
+        n_agents: int = 100,
+    ) -> None:
+        """Create a new continuous space.
+
+        Args:
+            dimensions: a numpy array like object where each row specifies the minimum and maximum value of that dimension.
+            torus: boolean for whether the space wraps around or not
+            random: a seeded stdlib random.Random instance
+            n_agents: the expected number of agents in the space
+
+        Internally, a numpy array is used to store the positions of all agents. This is resized if needed,
+        but you can control the initial size explicitly by passing n_agents.
+
+
+        """
+        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()
+        self.random = random
+
+        self.dimensions: np.array = np.asanyarray(dimensions)
+        self.ndims: int = self.dimensions.shape[0]
+        self.size: np.array = self.dimensions[:, 1] - self.dimensions[:, 0]
+        self.center: np.array = np.sum(self.dimensions, axis=1) / 2
+
+        self.torus: bool = torus
+
+        # self._agent_positions is the array containing all agent positions
+        # plus potential extra empty rows
+        # agent_positions is a view into _agent_positions containing only the filled rows
+        self._agent_positions: np.array = np.empty(
+            (n_agents, self.dimensions.shape[0]), dtype=float
+        )
+        self.agent_positions: (
+            np.array
+        )  # a view on _agent_positions containing all active positions
+
+        # the list of agents in the space
+        self.active_agents = []
+        self._n_agents = 0  # the number of active agents in the space
+
+        #  a mapping from agents to index and vice versa
+        self._index_to_agent: dict[int, Agent] = {}
+        self._agent_to_index: dict[Agent, int | None] = {}
+
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        return AgentSet(self.active_agents, random=self.random)
+
+    def _add_agent(self, agent: Agent) -> int:
+        """Helper method for adding an agent to the space.
+
+        This method manages the numpy array with the agent positions and ensuring it is
+        enlarged if and when needed. It is called automatically by ContinousSpaceAgent when created.
+
+        """
+        index = self._n_agents
+        self._n_agents += 1
+
+        if self._agent_positions.shape[0] <= index:
+            # we are out of space
+            fraction = 0.2  # we add 20%  Fixme
+            n = int(round(fraction * self._n_agents))
+            self._agent_positions = np.vstack(
+                [
+                    self._agent_positions,
+                    np.empty(
+                        (n, self.dimensions.shape[0]),
+                    ),
+                ]
+            )
+
+        self._agent_to_index[agent] = index
+        self._index_to_agent[index] = agent
+
+        # we want to maintain a view rather than a copy on the active agents and positions
+        # this is essential for the performance of the rest of this code
+        self.active_agents.append(agent)
+        self.agent_positions = self._agent_positions[0 : self._n_agents]
+
+        return index
+
+    def _remove_agent(self, agent: Agent) -> None:
+        """Remove an agent from the space.
+
+        This method is automatically called by ContinuousSpaceAgent.remove.
+
+        """
+        index = self._agent_to_index[agent]
+        self._agent_to_index.pop(agent, None)
+        self._index_to_agent.pop(index, None)
+        del self.active_agents[index]
+
+        # we update all indices
+        for agent in self.active_agents[index::]:
+            old_index = self._agent_to_index[agent]
+            self._agent_to_index[agent] = old_index - 1
+            self._index_to_agent[old_index - 1] = agent
+
+        # we move all data below the removed agent one row up
+        self._agent_positions[index : self._n_agents - 1] = self._agent_positions[
+            index + 1 : self._n_agents
+        ]
+        self._n_agents -= 1
+        self.agent_positions = self._agent_positions[0 : self._n_agents]
+
+    def calculate_difference_vector(self, point: np.ndarray, agents=None) -> np.ndarray:
+        """Calculate the difference vector between the point and all agenents.
+
+        Args:
+            point: the point to calculate the difference vector for
+            agents: the agents to calculate the difference vector of point with. By default,
+                    all agents are considered.
+
+
+        """
+        point = np.asanyarray(point)
+        positions = (
+            self.agent_positions
+            if agents is None
+            else self._agent_positions[[self._agent_to_index[a] for a in agents]]
+        )
+
+        delta = positions - point
+
+        if self.torus:
+            inverse_delta = delta - np.sign(delta) * self.size
+
+            # we need to use the lowest absolute value from delta and inverse delta
+            logical = np.abs(delta) < np.abs(inverse_delta)
+
+            out = np.zeros(delta.shape)
+            out[logical] = delta[logical]
+            out[~logical] = inverse_delta[~logical]
+
+            delta = out
+
+        return delta
+
+    def calculate_distances(
+        self, point: ArrayLike, agents: Iterable[Agent] | None = None, **kwargs
+    ) -> tuple[np.ndarray, list]:
+        """Calculate the distance between the point and all agents.
+
+        Args:
+            point: the point to calculate the difference vector for
+            agents: the agents to calculate the difference vector of point with. By default,
+                    all agents are considered.
+            kwargs: any additional keyword arguments are passed to scipy's cdist, which is used
+                    only if torus is False. This allows for non-Euclidian distance measures.
+
+        """
+        point = np.asanyarray(point)
+
+        if agents is None:
+            positions = self.agent_positions
+            agents = self.active_agents
+        else:
+            positions = self._agent_positions[[self._agent_to_index[a] for a in agents]]
+            agents = np.asarray(agents)
+
+        if self.torus:
+            delta = np.abs(point - positions)
+            delta = np.minimum(delta, self.size - delta, out=delta)
+
+            # + is much faster than np.sum or array.sum
+            dists = delta[:, 0] ** 2
+            for i in range(1, self.ndims):
+                dists += delta[:, i] ** 2
+            dists = np.sqrt(dists)
+        else:
+            dists = cdist(point[np.newaxis, :], positions, **kwargs)[0, :]
+        return dists, agents
+
+    def get_agents_in_radius(
+        self, point: ArrayLike, radius: float | int = 1
+    ) -> tuple[list, np.ndarray]:
+        """Return the agents and their distances within a radius for the point."""
+        distances, agents = self.calculate_distances(point)
+        logical = distances <= radius
+        agents = list(compress(agents, logical))
+        return (
+            agents,
+            distances[logical],
+        )
+
+    def get_k_nearest_agents(
+        self, point: ArrayLike, k: int = 1
+    ) -> tuple[list, np.ndarray]:
+        """Return the k nearest agents and their distances to the point.
+
+        Notes:
+            This method returns exactly k agents, ignoring ties. In case of ties, the
+            earlier an agent is inserted the higher it will rank.
+
+        """
+        dists, agents = self.calculate_distances(point)
+
+        indices = np.argpartition(dists, k)[:k]
+        agents = [agents[i] for i in indices]
+        return agents, dists[indices]
+
+    def in_bounds(self, point: ArrayLike) -> bool:
+        """Check if point is inside the bounds of the space."""
+        return bool(
+            (
+                (np.asanyarray(point) >= self.dimensions[:, 0])
+                & (point <= self.dimensions[:, 1])
+            ).all()
+        )
+
+    def torus_correct(self, point: ArrayLike) -> np.ndarray:
+        """Apply a torus correction to the point."""
+        return self.dimensions[:, 0] + np.mod(
+            np.asanyarray(point) - self.dimensions[:, 0], self.size
+        )