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

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
+        )

mesa/experimental/continuous_space/continuous_space_agents.py

@@ -0,0 +1,101 @@
+"""Continuous space agents."""
+
+from __future__ import annotations
+
+from itertools import compress
+from typing import Protocol
+
+import numpy as np
+
+from mesa.agent import Agent
+from mesa.experimental.continuous_space import ContinuousSpace
+
+
+class HasPositionProtocol(Protocol):
+    """Protocol for continuous space position holders."""
+
+    position: np.ndarray
+
+
+class ContinuousSpaceAgent(Agent):
+    """A continuous space agent.
+
+    Attributes:
+        space (ContinuousSpace): the continuous space in which the agent is located
+        position (np.ndarray): the position of the agent
+
+    """
+
+    __slots__ = ["_mesa_index", "space"]
+
+    @property
+    def position(self) -> np.ndarray:
+        """Position of the agent."""
+        return self.space.agent_positions[self.space._agent_to_index[self]]
+
+    @position.setter
+    def position(self, value: np.ndarray) -> None:
+        if not self.space.in_bounds(value):
+            if self.space.torus:
+                value = self.space.torus_correct(value)
+            else:
+                raise ValueError(f"point {value} is outside the bounds of the space")
+
+        self.space.agent_positions[self.space._agent_to_index[self]] = value
+
+    @property
+    def pos(self):  # noqa: D102
+        # just here for compatibility with solara_viz.
+        return self.position
+
+    @pos.setter
+    def pos(self, value):
+        # just here for compatibility solara_viz.
+        pass
+
+    def __init__(self, space: ContinuousSpace, model):
+        """Initialize a continuous space agent.
+
+        Args:
+            space: the continuous space in which the agent is located
+            model: the model to which the agent belongs
+
+        """
+        super().__init__(model)
+        self.space: ContinuousSpace = space
+        self.space._add_agent(self)
+        # self.position[:] = np.nan
+
+    def remove(self) -> None:
+        """Remove and delete the agent from the model and continuous space."""
+        super().remove()
+        self.space._remove_agent(self)
+        self._mesa_index = None
+        self.space = None
+
+    def get_neighbors_in_radius(
+        self, radius: float | int = 1
+    ) -> tuple[list, np.ndarray]:
+        """Get neighbors within radius.
+
+        Args:
+            radius: radius within which to look for neighbors
+
+        """
+        agents, dists = self.space.get_agents_in_radius(self.position, radius=radius)
+        logical = np.asarray([agent is not self for agent in agents])
+        agents = list(compress(agents, logical))
+        return agents, dists[logical]
+
+    def get_nearest_neighbors(self, k: int = 1) -> tuple[list, np.ndarray]:
+        """Get neighbors within radius.
+
+        Args:
+            k: the number of nearest neighbors to return
+
+        """
+        # return includes self, so we need to get k+1
+        agents, dists = self.space.get_k_nearest_agents(self.position, k=k + 1)
+        logical = np.asarray([agent is not self for agent in agents])
+        agents = list(compress(agents, logical))
+        return agents, dists[logical]

mesa/model.py

@@ -94,7 +94,7 @@ class Model:
             self._seed = seed  # this allows for reproducing stdlib.random
 
             try:
-                self.rng: np.random.Generator = np.random.default_rng(rng)
+                self.rng: np.random.Generator = np.random.default_rng(seed)
             except TypeError:
                 rng = self.random.randint(0, sys.maxsize)
                 self.rng: np.random.Generator = np.random.default_rng(rng)

mesa/space.py

@@ -1415,6 +1415,13 @@ class ContinuousSpace:
                             coordinates. i.e. if you are searching for the
                             neighbors of a given agent, True will include that
                             agent in the results.
+
+        Notes:
+            If 1 or more agents are located on pos, include_center=False will remove all these agents
+            from the results. So, if you really want to get the neighbors of a given agent,
+            you should set include_center=True, and then filter the list of agents to remove
+            the given agent (i.e., self when calling it from an agent).
+
         """
         if self._agent_points is None:
             self._build_agent_cache()

mesa/visualization/__init__.py

@@ -1,9 +1,8 @@
 """Solara based visualization for Mesa models.
 
 .. note::
-    SolaraViz is experimental and still in active development for Mesa 3.0. While we attempt to minimize them, there might be API breaking changes between Mesa 3.0 and 3.1.
+    SolaraViz is experimental and still in active development in Mesa 3.x. While we attempt to minimize them, there might be API breaking changes in minor releases.
 
-    There won't be breaking changes between Mesa 3.0.x patch releases.
 """
 
 from mesa.visualization.mpl_space_drawing import (

mesa/visualization/components/altair_components.py

@@ -1,13 +1,10 @@
 """Altair based solara components for visualization mesa spaces."""
 
-import contextlib
 import warnings
 
+import altair as alt
 import solara
 
-with contextlib.suppress(ImportError):
-    import altair as alt
-
 from mesa.experimental.cell_space import DiscreteSpace, Grid
 from mesa.space import ContinuousSpace, _Grid
 from mesa.visualization.utils import update_counter
@@ -30,7 +27,7 @@ def make_altair_space(
     Args:
         agent_portrayal: Function to portray agents.
         propertylayer_portrayal: not yet implemented
-        post_process :not yet implemented
+        post_process :A user specified callable that will be called with the Chart instance from Altair. Allows for fine tuning plots (e.g., control ticks)
         space_drawing_kwargs : not yet implemented
 
     ``agent_portrayal`` is called with an agent and should return a dict. Valid fields in this dict are "color",
@@ -46,13 +43,15 @@ def make_altair_space(
             return {"id": a.unique_id}
 
     def MakeSpaceAltair(model):
-        return SpaceAltair(model, agent_portrayal)
+        return SpaceAltair(model, agent_portrayal, post_process=post_process)
 
     return MakeSpaceAltair
 
 
 @solara.component
-def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+def SpaceAltair(
+    model, agent_portrayal, dependencies: list[any] | None = None, post_process=None
+):
     """Create an Altair-based space visualization component.
 
     Returns:
@@ -65,6 +64,9 @@ def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
         space = model.space
 
     chart = _draw_grid(space, agent_portrayal)
+    # Apply post-processing if provided
+    if post_process is not None:
+        chart = post_process(chart)
     solara.FigureAltair(chart)
 
 
@@ -159,7 +161,7 @@ def _draw_grid(space, agent_portrayal):
         # no y-axis label
         "y": alt.Y("y", axis=None, type=x_y_type),
         "tooltip": [
-            alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
+            alt.Tooltip(key, type=alt.utils.infer_vegalite_type_for_pandas([value]))
             for key, value in all_agent_data[0].items()
             if key not in invalid_tooltips
         ],