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

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

@@ -7,8 +7,7 @@ Uses numpy arrays to represent vectors.
 import numpy as np
 
 import mesa
-
-from .agents import Boid
+from mesa.examples.basic.boid_flockers.agents import Boid
 
 
 class BoidFlockers(mesa.Model):

{examples → mesa/examples}/basic/boltzmann_wealth_model/Readme.md

@@ -12,11 +12,6 @@ As the model runs, the distribution of wealth among agents goes from being perfe
 
 To follow the tutorial example, launch the Jupyter Notebook and run the code in ``Introduction to Mesa Tutorial Code.ipynb`` which you can find in the main mesa repo [here](https://github.com/projectmesa/mesa/blob/main/docs/tutorials/intro_tutorial.ipynb)
 
-Make sure to install the requirements first:
-
-```
-    $ pip install -r requirements.txt
-```
 
 To launch the interactive server, as described in the [last section of the tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html#adding-visualization), run:
 
@@ -30,6 +25,7 @@ If your browser doesn't open automatically, point it to [http://127.0.0.1:8765/]
 ## Files
 
 * ``model.py``: Final version of the model.
+* ``agents.py``: Final version of the agent.
 * ``app.py``: Code for the interactive visualization.
 
 ## Optional

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

@@ -1,11 +1,10 @@
+from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealthModel
 from mesa.visualization import (
     SolaraViz,
     make_plot_measure,
     make_space_matplotlib,
 )
 
-from .model import BoltzmannWealthModel
-
 
 def agent_portrayal(agent):
     size = 10

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

@@ -1,6 +1,5 @@
 import mesa
-
-from .agents import MoneyAgent
+from mesa.examples.basic.boltzmann_wealth_model.agents import MoneyAgent
 
 
 class BoltzmannWealthModel(mesa.Model):
@@ -11,8 +10,8 @@ class BoltzmannWealthModel(mesa.Model):
     highly skewed distribution of wealth.
     """
 
-    def __init__(self, n=100, width=10, height=10):
-        super().__init__()
+    def __init__(self, n=100, width=10, height=10, seed=None):
+        super().__init__(seed=seed)
         self.num_agents = n
         self.grid = mesa.space.MultiGrid(width, height, True)
 

{examples → mesa/examples}/basic/conways_game_of_life/Readme.md

@@ -9,26 +9,30 @@ The "game" is a zero-player game, meaning that its evolution is determined by it
 
 ## How to Run
 
-To run the model interactively, run ``mesa runserver`` in this directory. e.g.
+To run the model interactively you can use either the streamlit or solara version. For solara, you use
 
 ```
-    $ mesa runserver
+    $ solara run app.py
 ```
 
-Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press ``run``.
+For streamlit, you need
+
+```
+    $ streamlit run st_app.py
+```
+
+This will open your browser and show you the controls. You can start the model by hitting the run button.
 
 ## Files
 
 * ``agents.py``: Defines the behavior of an individual cell, which can be in two states: DEAD or ALIVE.
 * ``model.py``: Defines the model itself, initialized with a random configuration of alive and dead cells.
-* ``portrayal.py``: Describes for the front end how to render a cell.
+* ``app.py``: Defines an interactive visualization using solara.
 * ``st_app.py``: Defines an interactive visualization using Streamlit.
 
 ## Optional
 
-*  ``conways_game_of_life/st_app.py``: can be used to run the simulation via the streamlit interface.
-* For this some additional packages like ``streamlit`` and ``altair`` needs to be installed.
-* Once installed, the app can be opened in the browser using : ``streamlit run st_app.py``
+* For the streamlit version, you need to have streamlit installed (can be done via pip install streamlit)
 
 
 ## Further Reading

{examples → mesa/examples}/basic/conways_game_of_life/agents.py

@@ -12,10 +12,10 @@ class Cell(Agent):
         super().__init__(model)
         self.x, self.y = pos
         self.state = init_state
-        self._nextState = None
+        self._next_state = None
 
     @property
-    def isAlive(self):
+    def is_alive(self):
         return self.state == self.ALIVE
 
     @property
@@ -31,17 +31,17 @@ class Cell(Agent):
         """
         # Get the neighbors and apply the rules on whether to be alive or dead
         # at the next tick.
-        live_neighbors = sum(neighbor.isAlive for neighbor in self.neighbors)
+        live_neighbors = sum(neighbor.is_alive for neighbor in self.neighbors)
 
         # Assume nextState is unchanged, unless changed below.
-        self._nextState = self.state
-        if self.isAlive:
+        self._next_state = self.state
+        if self.is_alive:
             if live_neighbors < 2 or live_neighbors > 3:
-                self._nextState = self.DEAD
+                self._next_state = self.DEAD
         else:
             if live_neighbors == 3:
-                self._nextState = self.ALIVE
+                self._next_state = self.ALIVE
 
     def assume_state(self):
         """Set the state to the new computed state -- computed in step()."""
-        self.state = self._nextState
+        self.state = self._next_state

mesa/examples/basic/conways_game_of_life/app.py

@@ -0,0 +1,39 @@
+from mesa.examples.basic.conways_game_of_life.model import ConwaysGameOfLife
+from mesa.visualization import (
+    SolaraViz,
+    make_space_matplotlib,
+)
+
+
+def agent_portrayal(agent):
+    return {"color": "white" if agent.state == 0 else "black"}
+
+
+model_params = {
+    "width": 50,
+    "height": 50,
+}
+
+# Create initial model instance
+model1 = ConwaysGameOfLife(50, 50)
+
+# Create visualization elements. The visualization elements are solara components
+# that receive the model instance as a "prop" and display it in a certain way.
+# Under the hood these are just classes that receive the model instance.
+# You can also author your own visualization elements, which can also be functions
+# that receive the model instance and return a valid solara component.
+SpaceGraph = make_space_matplotlib(agent_portrayal)
+
+
+# Create the SolaraViz page. This will automatically create a server and display the
+# visualization elements in a web browser.
+# Display it using the following command in the example directory:
+# solara run app.py
+# It will automatically update and display any changes made to this file
+page = SolaraViz(
+    model1,
+    components=[SpaceGraph],
+    model_params=model_params,
+    name="Game of Life",
+)
+page  # noqa

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

@@ -1,15 +1,14 @@
 from mesa import Model
+from mesa.examples.basic.conways_game_of_life.agents import Cell
 from mesa.space import SingleGrid
 
-from .agents import Cell
-
 
 class ConwaysGameOfLife(Model):
     """Represents the 2-dimensional array of cells in Conway's Game of Life."""
 
-    def __init__(self, width=50, height=50):
+    def __init__(self, width=50, height=50, seed=None):
         """Create a new playing area of (width, height) cells."""
-        super().__init__()
+        super().__init__(seed=seed)
         # Use a simple grid, where edges wrap around.
         self.grid = SingleGrid(width, height, torus=True)
 

{examples → mesa/examples}/basic/conways_game_of_life/st_app.py

@@ -4,7 +4,8 @@ import altair as alt
 import numpy as np
 import pandas as pd
 import streamlit as st
-from model import ConwaysGameOfLife
+
+from mesa.examples.basic.conways_game_of_life.model import ConwaysGameOfLife
 
 model = st.title("Conway's Game of Life")
 num_ticks = st.slider("Select number of Steps", min_value=1, max_value=100, value=50)

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,5 +1,6 @@
 import solara
 
+from mesa.examples.basic.schelling.model import Schelling
 from mesa.visualization import (
     Slider,
     SolaraViz,
@@ -7,8 +8,6 @@ from mesa.visualization import (
     make_space_matplotlib,
 )
 
-from .model import Schelling
-
 
 def get_happy_agents(model):
     """Display a text count of how many happy agents there are."""

{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):

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

@@ -4,10 +4,13 @@ import solara
 from matplotlib.figure import Figure
 from matplotlib.ticker import MaxNLocator
 
+from mesa.examples.basic.virus_on_network.model import (
+    State,
+    VirusOnNetwork,
+    number_infected,
+)
 from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
 
-from .model import State, VirusOnNetwork, number_infected
-
 
 def agent_portrayal(graph):
     def get_agent(node):

{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]
@@ -1333,6 +1364,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 +1550,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/components/altair.py

@@ -7,6 +7,8 @@ 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
 
 
@@ -29,35 +31,101 @@ def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
     if space is None:
         # Sometimes the space is defined as model.space instead of model.grid
         space = model.space
+
     chart = _draw_grid(space, agent_portrayal)
     solara.FigureAltair(chart)
 
 
+def _get_agent_data_old__discrete_space(space, agent_portrayal):
+    """Format agent portrayal data for old-style discrete spaces.
+
+    Args:
+        space: the mesa.space._Grid instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+
+    """
+    all_agent_data = []
+    for content, (x, y) in space.coord_iter():
+        if not content:
+            continue
+        if not hasattr(content, "__iter__"):
+            # Is a single grid
+            content = [content]  # noqa: PLW2901
+        for agent in content:
+            # use all data from agent portrayal, and add x,y coordinates
+            agent_data = agent_portrayal(agent)
+            agent_data["x"] = x
+            agent_data["y"] = y
+            all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _get_agent_data_new_discrete_space(space: DiscreteSpace, agent_portrayal):
+    """Format agent portrayal data for new-style discrete spaces.
+
+    Args:
+        space: the mesa.experiment.cell_space.Grid instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+
+    """
+    all_agent_data = []
+
+    for cell in space.all_cells:
+        for agent in cell.agents:
+            agent_data = agent_portrayal(agent)
+            agent_data["x"] = cell.coordinate[0]
+            agent_data["y"] = cell.coordinate[1]
+            all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _get_agent_data_continuous_space(space: ContinuousSpace, agent_portrayal):
+    """Format agent portrayal data for continuous space.
+
+    Args:
+        space: the ContinuousSpace instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+    """
+    all_agent_data = []
+    for agent in space._agent_to_index:
+        agent_data = agent_portrayal(agent)
+        agent_data["x"] = agent.pos[0]
+        agent_data["y"] = agent.pos[1]
+        all_agent_data.append(agent_data)
+    return all_agent_data
+
+
 def _draw_grid(space, agent_portrayal):
-    def portray(g):
-        all_agent_data = []
-        for content, (x, y) in g.coord_iter():
-            if not content:
-                continue
-            if not hasattr(content, "__iter__"):
-                # Is a single grid
-                content = [content]  # noqa: PLW2901
-            for agent in content:
-                # use all data from agent portrayal, and add x,y coordinates
-                agent_data = agent_portrayal(agent)
-                agent_data["x"] = x
-                agent_data["y"] = y
-                all_agent_data.append(agent_data)
-        return all_agent_data
-
-    all_agent_data = portray(space)
+    match space:
+        case Grid():
+            all_agent_data = _get_agent_data_new_discrete_space(space, agent_portrayal)
+        case _Grid():
+            all_agent_data = _get_agent_data_old__discrete_space(space, agent_portrayal)
+        case ContinuousSpace():
+            all_agent_data = _get_agent_data_continuous_space(space, agent_portrayal)
+        case _:
+            raise NotImplementedError(
+                f"visualizing {type(space)} is currently not supported through altair"
+            )
+
     invalid_tooltips = ["color", "size", "x", "y"]
 
+    x_y_type = "ordinal" if not isinstance(space, ContinuousSpace) else "nominal"
+
     encoding_dict = {
         # no x-axis label
-        "x": alt.X("x", axis=None, type="ordinal"),
+        "x": alt.X("x", axis=None, type=x_y_type),
         # no y-axis label
-        "y": alt.Y("y", axis=None, type="ordinal"),
+        "y": alt.Y("y", axis=None, type=x_y_type),
         "tooltip": [
             alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
             for key, value in all_agent_data[0].items()