Mesa 3.0.0b1__py3-none-any.whl → 3.0.0rc0__py3-none-any.whl

examples/basic/schelling/README.md → mesa/examples/basic/schelling/Readme.md

@@ -6,14 +6,6 @@ The Schelling segregation model is a classic agent-based model, demonstrating ho
 
 By default, the number of similar neighbors the agents need to be happy is set to 3. That means the agents would be perfectly happy with a majority of their neighbors being of a different color (e.g. a Blue agent would be happy with five Red neighbors and three Blue ones). Despite this, the model consistently leads to a high degree of segregation, with most agents ending up with no neighbors of a different color.
 
-## Installation
-
-To install the dependencies use pip and the requirements.txt in this directory. e.g.
-
-```
-    $ pip install -r requirements.txt
-```
-
 ## How to Run
 
 To run the model interactively, in this directory, run the following command
@@ -32,8 +24,9 @@ To run the model with the grid displayed as an ASCII text, run `python run_ascii
 
 ## Files
 
+* ``model.py``: Contains the Schelling model class
+*  ``agents.py``: Contains the Schelling agent class
 * ``app.py``: Code for the interactive visualization.
-* ``schelling.py``: Contains the agent class, and the overall model class.
 * ``analysis.ipynb``: Notebook demonstrating how to run experiments and parameter sweeps on the model.
 
 ## Further Reading

{examples → mesa/examples}/basic/schelling/app.py

@@ -1,14 +1,13 @@
 import solara
 
+from mesa.examples.basic.schelling.model import Schelling
 from mesa.visualization import (
     Slider,
     SolaraViz,
-    make_plot_measure,
-    make_space_matplotlib,
+    make_plot_component,
+    make_space_component,
 )
 
-from .model import Schelling
-
 
 def get_happy_agents(model):
     """Display a text count of how many happy agents there are."""
@@ -29,13 +28,13 @@ model_params = {
 
 model1 = Schelling(20, 20, 0.8, 0.2, 3)
 
-HappyPlot = make_plot_measure("happy")
+HappyPlot = make_plot_component({"happy": "tab:green"})
 
 page = SolaraViz(
     model1,
     components=[
-        make_space_matplotlib(agent_portrayal),
-        make_plot_measure("happy"),
+        make_space_component(agent_portrayal),
+        HappyPlot,
         get_happy_agents,
     ],
     model_params=model_params,

{examples → mesa/examples}/basic/schelling/model.py

@@ -1,7 +1,6 @@
 import mesa
 from mesa import Model
-
-from .agents import SchellingAgent
+from mesa.examples.basic.schelling.agents import SchellingAgent
 
 
 class Schelling(Model):

mesa/examples/basic/virus_on_network/app.py

@@ -0,0 +1,114 @@
+import math
+
+import solara
+
+from mesa.examples.basic.virus_on_network.model import (
+    State,
+    VirusOnNetwork,
+    number_infected,
+)
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
+
+
+def agent_portrayal(agent):
+    node_color_dict = {
+        State.INFECTED: "tab:red",
+        State.SUSCEPTIBLE: "tab:green",
+        State.RESISTANT: "tab:gray",
+    }
+    return {"color": node_color_dict[agent.state], "size": 10}
+
+
+def get_resistant_susceptible_ratio(model):
+    ratio = model.resistant_susceptible_ratio()
+    ratio_text = r"$\infty$" if ratio is math.inf else f"{ratio:.2f}"
+    infected_text = str(number_infected(model))
+
+    return solara.Markdown(
+        f"Resistant/Susceptible Ratio: {ratio_text}<br>Infected Remaining: {infected_text}"
+    )
+
+
+model_params = {
+    "num_nodes": Slider(
+        label="Number of agents",
+        value=10,
+        min=10,
+        max=100,
+        step=1,
+    ),
+    "avg_node_degree": Slider(
+        label="Avg Node Degree",
+        value=3,
+        min=3,
+        max=8,
+        step=1,
+    ),
+    "initial_outbreak_size": Slider(
+        label="Initial Outbreak Size",
+        value=1,
+        min=1,
+        max=10,
+        step=1,
+    ),
+    "virus_spread_chance": Slider(
+        label="Virus Spread Chance",
+        value=0.4,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+    "virus_check_frequency": Slider(
+        label="Virus Check Frequency",
+        value=0.4,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+    "recovery_chance": Slider(
+        label="Recovery Chance",
+        value=0.3,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+    "gain_resistance_chance": Slider(
+        label="Gain Resistance Chance",
+        value=0.5,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+}
+
+
+def post_process_lineplot(ax):
+    ax.set_ylim(ymin=0)
+    ax.set_ylabel("# people")
+    ax.legend(bbox_to_anchor=(1.05, 1.0), loc="upper left")
+
+
+SpacePlot = make_space_component(agent_portrayal)
+StatePlot = make_plot_component(
+    {"Infected": "tab:red", "Susceptible": "tab:green", "Resistant": "tab:gray"},
+    post_process=post_process_lineplot,
+)
+
+model1 = VirusOnNetwork()
+
+page = SolaraViz(
+    model1,
+    [
+        SpacePlot,
+        StatePlot,
+        get_resistant_susceptible_ratio,
+    ],
+    model_params=model_params,
+    name="Virus Model",
+)
+page  # noqa

{examples → mesa/examples}/basic/virus_on_network/model.py

@@ -4,8 +4,7 @@ import networkx as nx
 
 import mesa
 from mesa import Model
-
-from .agents import State, VirusAgent
+from mesa.examples.basic.virus_on_network.agents import State, VirusAgent
 
 
 def number_state(model, state):
@@ -36,8 +35,9 @@ class VirusOnNetwork(Model):
         virus_check_frequency=0.4,
         recovery_chance=0.3,
         gain_resistance_chance=0.5,
+        seed=None,
     ):
-        super().__init__()
+        super().__init__(seed=seed)
         self.num_nodes = num_nodes
         prob = avg_node_degree / self.num_nodes
         self.G = nx.erdos_renyi_graph(n=self.num_nodes, p=prob)
@@ -56,6 +56,7 @@ class VirusOnNetwork(Model):
                 "Infected": number_infected,
                 "Susceptible": number_susceptible,
                 "Resistant": number_resistant,
+                "R over S": self.resistant_susceptible_ratio,
             }
         )
 
@@ -93,7 +94,3 @@ class VirusOnNetwork(Model):
         self.agents.shuffle_do("step")
         # collect data
         self.datacollector.collect(self)
-
-    def run_model(self, n):
-        for _ in range(n):
-            self.step()

mesa/experimental/cell_space/discrete_space.py

@@ -7,6 +7,7 @@ from functools import cached_property
 from random import Random
 from typing import Any, Generic, TypeVar
 
+from mesa.agent import AgentSet
 from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.cell_collection import CellCollection
 from mesa.space import PropertyLayer
@@ -55,6 +56,11 @@ class DiscreteSpace(Generic[T]):
     def cutoff_empties(self):  # noqa
         return 7.953 * len(self._cells) ** 0.384
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        return AgentSet(self.all_cells.agents, random=self.random)
+
     def _connect_cells(self): ...
     def _connect_single_cell(self, cell: T): ...
 

mesa/experimental/devs/eventlist.py

@@ -33,6 +33,12 @@ class SimulationEvent:
         function_args (list[Any]): Argument for the function
         function_kwargs (Dict[str, Any]): Keyword arguments for the function
 
+
+    Notes:
+        simulation events use a weak reference to the callable. Therefore, you cannot pass a lambda function in fn.
+        A simulation event where the callable no longer exists (e.g., because the agent has been removed from the model)
+        will fail silently.
+
     """
 
     _ids = itertools.count()

mesa/model.py

@@ -276,3 +276,16 @@ class Model:
         )
         # Collect data for the first time during initialization.
         self.datacollector.collect(self)
+
+    def remove_all_agents(self):
+        """Remove all agents from the model.
+
+        Notes:
+            This method calls agent.remove for all agents in the model. If you need to remove agents from
+            e.g., a SingleGrid, you can either explicitly implement your own agent.remove method or clean this up
+            near where you are calling this method.
+
+        """
+        # we need to wrap keys in a list to avoid a RunTimeError: dictionary changed size during iteration
+        for agent in list(self._agents.keys()):
+            agent.remove()

mesa/space.py

@@ -2,10 +2,21 @@
 
 Objects used to add a spatial component to a model.
 
-* Grid: base grid, which creates a rectangular grid.
-* SingleGrid: extension to Grid which strictly enforces one agent per cell.
-* MultiGrid: extension to Grid where each cell can contain a set of agents.
-* HexGrid: extension to Grid to handle hexagonal neighbors.
+.. note::
+    All Grid classes (:class:`_Grid`, :class:`SingleGrid`, :class:`MultiGrid`,
+    :class:`HexGrid`, etc.) are now in maintenance-only mode. While these classes remain
+    fully supported, new development occurs in the experimental cell space module
+    (:mod:`mesa.experimental.cell_space`).
+
+    The :class:`PropertyLayer` and :class:`ContinuousSpace` classes remain fully supported
+    and actively developed.
+
+Classes
+-------
+* PropertyLayer: A data layer that can be added to Grids to store cell properties
+* SingleGrid: a Grid which strictly enforces one agent per cell.
+* MultiGrid: a Grid where each cell can contain a set of agents.
+* HexGrid: a Grid to handle hexagonal neighbors.
 * ContinuousSpace: a two-dimensional space where each agent has an arbitrary position of `float`'s.
 * NetworkGrid: a network where each node contains zero or more agents.
 """
@@ -32,7 +43,7 @@ import numpy as np
 import numpy.typing as npt
 
 # For Mypy
-from .agent import Agent
+from .agent import Agent, AgentSet
 
 # for better performance, we calculate the tuple to use in the is_integer function
 _types_integer = (int, np.integer)
@@ -153,6 +164,26 @@ class _Grid:
     @overload
     def __getitem__(self, index: int | Sequence[Coordinate]) -> list[GridContent]: ...
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = []
+        for entry in self:
+            if not entry:
+                continue
+            if not isinstance(entry, list):
+                entry = [entry]  # noqa PLW2901
+            for agent in entry:
+                agents.append(agent)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     @overload
     def __getitem__(
         self, index: tuple[int | slice, int | slice]
@@ -1256,36 +1287,6 @@ class HexMultiGrid(_HexGrid, MultiGrid):
     """
 
 
-class HexGrid(HexSingleGrid):
-    """Hexagonal Grid: a Grid where neighbors are computed according to a hexagonal tiling of the grid.
-
-    Functions according to odd-q rules.
-    See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
-
-    Properties:
-        width, height: The grid's width and height.
-        torus: Boolean which determines whether to treat the grid as a torus.
-    """
-
-    def __init__(self, width: int, height: int, torus: bool) -> None:
-        """Initializes a HexGrid, deprecated.
-
-        Args:
-            width: the width of the grid
-            height: the height of the grid
-            torus: whether the grid wraps
-        """
-        super().__init__(width, height, torus)
-        warn(
-            (
-                "HexGrid is being deprecated; use instead HexSingleGrid or HexMultiGrid "
-                "depending on your use case."
-            ),
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
 class ContinuousSpace:
     """Continuous space where each agent can have an arbitrary position.
 
@@ -1333,6 +1334,19 @@ class ContinuousSpace:
         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."""
+        agents = list(self._agent_to_index)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     def _build_agent_cache(self):
         """Cache agents positions to speed up neighbors calculations."""
         self._index_to_agent = {}
@@ -1506,6 +1520,27 @@ class NetworkGrid:
         for node_id in self.G.nodes:
             g.nodes[node_id]["agent"] = self.default_val()
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = []
+        for node_id in self.G.nodes:
+            entry = self.G.nodes[node_id]["agent"]
+            if not entry:
+                continue
+            if not isinstance(entry, list):
+                entry = [entry]
+            for agent in entry:
+                agents.append(agent)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     @staticmethod
     def default_val() -> list:
         """Default value for a new node."""

mesa/visualization/__init__.py

@@ -1,7 +1,17 @@
-"""Solara based visualization for Mesa models."""
+"""Solara based visualization for Mesa models.
 
-from .components.altair import make_space_altair
-from .components.matplotlib import make_plot_measure, make_space_matplotlib
+.. 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.
+
+    There won't be breaking changes between Mesa 3.0.x patch releases.
+"""
+
+from mesa.visualization.mpl_space_drawing import (
+    draw_space,
+)
+
+from .components import make_plot_component, make_space_component
+from .components.altair_components import make_space_altair
 from .solara_viz import JupyterViz, SolaraViz
 from .UserParam import Slider
 
@@ -10,6 +20,7 @@ __all__ = [
     "SolaraViz",
     "Slider",
     "make_space_altair",
-    "make_space_matplotlib",
-    "make_plot_measure",
+    "draw_space",
+    "make_plot_component",
+    "make_space_component",
 ]

mesa/visualization/components/__init__.py

@@ -0,0 +1,83 @@
+"""custom solara components."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .altair_components import SpaceAltair, make_altair_space
+from .matplotlib_components import (
+    SpaceMatplotlib,
+    make_mpl_plot_component,
+    make_mpl_space_component,
+)
+
+
+def make_space_component(
+    agent_portrayal: Callable | None = None,
+    propertylayer_portrayal: dict | None = None,
+    post_process: Callable | None = None,
+    backend: str = "matplotlib",
+    **space_drawing_kwargs,
+) -> SpaceMatplotlib | SpaceAltair:
+    """Create a Matplotlib-based space visualization component.
+
+    Args:
+        agent_portrayal: Function to portray agents.
+        propertylayer_portrayal: Dictionary of PropertyLayer portrayal specifications
+        post_process : a callable that will be called with the Axes instance. Allows for fine-tuning plots (e.g., control ticks)
+        backend: the backend to use {"matplotlib", "altair"}
+        space_drawing_kwargs : additional keyword arguments to be passed on to the underlying backend specific space drawer function. See
+                               the functions for drawing the various spaces for the appropriate backend further details.
+
+
+    Returns:
+        function: A function that creates a space component
+    """
+    if backend == "matplotlib":
+        return make_mpl_space_component(
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process,
+            **space_drawing_kwargs,
+        )
+    elif backend == "altair":
+        return make_altair_space(
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process,
+            **space_drawing_kwargs,
+        )
+    else:
+        raise ValueError(
+            f"unknown backend {backend}, must be one of matplotlib, altair"
+        )
+
+
+def make_plot_component(
+    measure: str | dict[str, str] | list[str] | tuple[str],
+    post_process: Callable | None = None,
+    backend: str = "matplotlib",
+    **plot_drawing_kwargs,
+):
+    """Create a plotting function for a specified measure using the specified backend.
+
+    Args:
+        measure (str | dict[str, str] | list[str] | tuple[str]): Measure(s) to plot.
+        post_process: a user-specified callable to do post-processing called with the Axes instance.
+        backend: the backend to use {"matplotlib", "altair"}
+        plot_drawing_kwargs: additional keyword arguments to pass onto the backend specific function for making a plotting component
+
+    Notes:
+        altair plotting backend is not yet implemented and planned for mesa 3.1.
+
+    Returns:
+        function: A function that creates a plot component
+    """
+    if backend == "matplotlib":
+        return make_mpl_plot_component(measure, post_process, **plot_drawing_kwargs)
+    elif backend == "altair":
+        raise NotImplementedError("altair line plots are not yet implemented")
+    else:
+        raise ValueError(
+            f"unknown backend {backend}, must be one of matplotlib, altair"
+        )