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

examples/basic/virus_on_network/agents.py

@@ -0,0 +1,69 @@
+from enum import Enum
+
+from mesa import Agent
+
+
+class State(Enum):
+    SUSCEPTIBLE = 0
+    INFECTED = 1
+    RESISTANT = 2
+
+
+class VirusAgent(Agent):
+    """Individual Agent definition and its properties/interaction methods."""
+
+    def __init__(
+        self,
+        model,
+        initial_state,
+        virus_spread_chance,
+        virus_check_frequency,
+        recovery_chance,
+        gain_resistance_chance,
+    ):
+        super().__init__(model)
+
+        self.state = initial_state
+
+        self.virus_spread_chance = virus_spread_chance
+        self.virus_check_frequency = virus_check_frequency
+        self.recovery_chance = recovery_chance
+        self.gain_resistance_chance = gain_resistance_chance
+
+    def try_to_infect_neighbors(self):
+        neighbors_nodes = self.model.grid.get_neighborhood(
+            self.pos, include_center=False
+        )
+        susceptible_neighbors = [
+            agent
+            for agent in self.model.grid.get_cell_list_contents(neighbors_nodes)
+            if agent.state is State.SUSCEPTIBLE
+        ]
+        for a in susceptible_neighbors:
+            if self.random.random() < self.virus_spread_chance:
+                a.state = State.INFECTED
+
+    def try_gain_resistance(self):
+        if self.random.random() < self.gain_resistance_chance:
+            self.state = State.RESISTANT
+
+    def try_remove_infection(self):
+        # Try to remove
+        if self.random.random() < self.recovery_chance:
+            # Success
+            self.state = State.SUSCEPTIBLE
+            self.try_gain_resistance()
+        else:
+            # Failed
+            self.state = State.INFECTED
+
+    def try_check_situation(self):
+        if (self.random.random() < self.virus_check_frequency) and (
+            self.state is State.INFECTED
+        ):
+            self.try_remove_infection()
+
+    def step(self):
+        if self.state is State.INFECTED:
+            self.try_to_infect_neighbors()
+        self.try_check_situation()

examples/basic/virus_on_network/app.py

@@ -0,0 +1,133 @@
+import math
+
+import solara
+from matplotlib.figure import Figure
+from matplotlib.ticker import MaxNLocator
+
+from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
+
+from .model import State, VirusOnNetwork, number_infected
+
+
+def agent_portrayal(graph):
+    def get_agent(node):
+        return graph.nodes[node]["agent"][0]
+
+    edge_width = []
+    edge_color = []
+    for u, v in graph.edges():
+        agent1 = get_agent(u)
+        agent2 = get_agent(v)
+        w = 2
+        ec = "#e8e8e8"
+        if State.RESISTANT in (agent1.state, agent2.state):
+            w = 3
+            ec = "black"
+        edge_width.append(w)
+        edge_color.append(ec)
+    node_color_dict = {
+        State.INFECTED: "tab:red",
+        State.SUSCEPTIBLE: "tab:green",
+        State.RESISTANT: "tab:gray",
+    }
+    node_color = [node_color_dict[get_agent(node).state] for node in graph.nodes()]
+    return {
+        "width": edge_width,
+        "edge_color": edge_color,
+        "node_color": node_color,
+    }
+
+
+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 f"Resistant/Susceptible Ratio: {ratio_text}<br>Infected Remaining: {infected_text}"
+
+
+def make_plot(model):
+    # This is for the case when we want to plot multiple measures in 1 figure.
+    fig = Figure()
+    ax = fig.subplots()
+    measures = ["Infected", "Susceptible", "Resistant"]
+    colors = ["tab:red", "tab:green", "tab:gray"]
+    for i, m in enumerate(measures):
+        color = colors[i]
+        df = model.datacollector.get_model_vars_dataframe()
+        ax.plot(df.loc[:, m], label=m, color=color)
+    fig.legend()
+    # Set integer x axis
+    ax.xaxis.set_major_locator(MaxNLocator(integer=True))
+    ax.set_xlabel("Step")
+    ax.set_ylabel("Number of Agents")
+    return solara.FigureMatplotlib(fig)
+
+
+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,
+    ),
+}
+
+SpacePlot = make_space_matplotlib(agent_portrayal)
+
+model1 = VirusOnNetwork()
+
+page = SolaraViz(
+    model1,
+    [
+        SpacePlot,
+        make_plot,
+        # get_resistant_susceptible_ratio,  # TODO: Fix and uncomment
+    ],
+    model_params=model_params,
+    name="Virus Model",
+)
+page  # noqa

examples/basic/virus_on_network/model.py

@@ -0,0 +1,99 @@
+import math
+
+import networkx as nx
+
+import mesa
+from mesa import Model
+
+from .agents import State, VirusAgent
+
+
+def number_state(model, state):
+    return sum(1 for a in model.grid.get_all_cell_contents() if a.state is state)
+
+
+def number_infected(model):
+    return number_state(model, State.INFECTED)
+
+
+def number_susceptible(model):
+    return number_state(model, State.SUSCEPTIBLE)
+
+
+def number_resistant(model):
+    return number_state(model, State.RESISTANT)
+
+
+class VirusOnNetwork(Model):
+    """A virus model with some number of agents."""
+
+    def __init__(
+        self,
+        num_nodes=10,
+        avg_node_degree=3,
+        initial_outbreak_size=1,
+        virus_spread_chance=0.4,
+        virus_check_frequency=0.4,
+        recovery_chance=0.3,
+        gain_resistance_chance=0.5,
+    ):
+        super().__init__()
+        self.num_nodes = num_nodes
+        prob = avg_node_degree / self.num_nodes
+        self.G = nx.erdos_renyi_graph(n=self.num_nodes, p=prob)
+        self.grid = mesa.space.NetworkGrid(self.G)
+
+        self.initial_outbreak_size = (
+            initial_outbreak_size if initial_outbreak_size <= num_nodes else num_nodes
+        )
+        self.virus_spread_chance = virus_spread_chance
+        self.virus_check_frequency = virus_check_frequency
+        self.recovery_chance = recovery_chance
+        self.gain_resistance_chance = gain_resistance_chance
+
+        self.datacollector = mesa.DataCollector(
+            {
+                "Infected": number_infected,
+                "Susceptible": number_susceptible,
+                "Resistant": number_resistant,
+            }
+        )
+
+        # Create agents
+        for node in self.G.nodes():
+            a = VirusAgent(
+                self,
+                State.SUSCEPTIBLE,
+                self.virus_spread_chance,
+                self.virus_check_frequency,
+                self.recovery_chance,
+                self.gain_resistance_chance,
+            )
+
+            # Add the agent to the node
+            self.grid.place_agent(a, node)
+
+        # Infect some nodes
+        infected_nodes = self.random.sample(list(self.G), self.initial_outbreak_size)
+        for a in self.grid.get_cell_list_contents(infected_nodes):
+            a.state = State.INFECTED
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def resistant_susceptible_ratio(self):
+        try:
+            return number_state(self, State.RESISTANT) / number_state(
+                self, State.SUSCEPTIBLE
+            )
+        except ZeroDivisionError:
+            return math.inf
+
+    def step(self):
+        self.agents.shuffle_do("step")
+        # collect data
+        self.datacollector.collect(self)
+
+    def run_model(self, n):
+        for _ in range(n):
+            self.step()

mesa/__init__.py

@@ -5,6 +5,8 @@ Core Objects: Model, and Agent.
 
 import datetime
 
+import mesa.examples as examples
+import mesa.experimental as experimental
 import mesa.space as space
 import mesa.time as time
 from mesa.agent import Agent
@@ -20,10 +22,11 @@ __all__ = [
     "DataCollector",
     "batch_run",
     "experimental",
+    "examples",
 ]
 
 __title__ = "mesa"
-__version__ = "3.0.0a5"
+__version__ = "3.0.0b1"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -46,38 +46,24 @@ class Agent:
     # so, unique_id is unique relative to a model, and counting starts from 1
     _ids = defaultdict(functools.partial(itertools.count, 1))
 
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, model: Model, *args, **kwargs) -> None:
         """Create a new agent.
 
         Args:
             model (Model): The model instance in which the agent exists.
-            args: currently ignored, to be fixed in 3.1
-            kwargs: currently ignored, to be fixed in 3.1
+            args: passed on to super
+            kwargs: passed on to super
+
+        Notes:
+            to make proper use of python's super, in each class remove the arguments and
+            keyword arguments you need and pass on the rest to super
+
         """
-        # TODO: Cleanup in future Mesa version (3.1+)
-        match args:
-            # Case 1: Only the model is provided. The new correct behavior.
-            case [model]:
-                self.model = model
-                self.unique_id = next(self._ids[model])
-            # Case 2: Both unique_id and model are provided, deprecated
-            case [_, model]:
-                warnings.warn(
-                    "unique ids are assigned automatically to Agents in Mesa 3. The use of custom unique_id is "
-                    "deprecated. Only input a model when calling `super()__init__(model)`. The unique_id inputted is not used.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
-                self.model = model
-                self.unique_id = next(self._ids[model])
-            # Case 3: Anything else, raise an error
-            case _:
-                raise ValueError(
-                    "Invalid arguments provided to initialize the Agent. Only input a model: `super()__init__(model)`."
-                )
+        super().__init__(*args, **kwargs)
 
+        self.model: Model = model
+        self.unique_id: int = next(self._ids[model])
         self.pos: Position | None = None
-
         self.model.register_agent(self)
 
     def remove(self) -> None:
@@ -113,14 +99,18 @@ class AgentSet(MutableSet, Sequence):
         which means that agents not referenced elsewhere in the program may be automatically removed from the AgentSet.
     """
 
-    def __init__(self, agents: Iterable[Agent], model: Model):
+    def __init__(self, agents: Iterable[Agent], random: Random | None = None):
         """Initializes the AgentSet with a collection of agents and a reference to the model.
 
         Args:
             agents (Iterable[Agent]): An iterable of Agent objects to be included in the set.
-            model (Model): The ABM model instance to which this AgentSet belongs.
+            random (Random): the random number generator
         """
-        self.model = model
+        if random is None:
+            random = (
+                Random()
+            )  # FIXME see issue 1981, how to get the central rng from model
+        self.random = random
         self._agents = weakref.WeakKeyDictionary({agent: None for agent in agents})
 
     def __len__(self) -> int:
@@ -191,7 +181,7 @@ class AgentSet(MutableSet, Sequence):
 
         agents = agent_generator(filter_func, agent_type, at_most)
 
-        return AgentSet(agents, self.model) if not inplace else self._update(agents)
+        return AgentSet(agents, self.random) if not inplace else self._update(agents)
 
     def shuffle(self, inplace: bool = False) -> AgentSet:
         """Randomly shuffle the order of agents in the AgentSet.
@@ -214,7 +204,7 @@ class AgentSet(MutableSet, Sequence):
             return self
         else:
             return AgentSet(
-                (agent for ref in weakrefs if (agent := ref()) is not None), self.model
+                (agent for ref in weakrefs if (agent := ref()) is not None), self.random
             )
 
     def sort(
@@ -239,7 +229,7 @@ class AgentSet(MutableSet, Sequence):
         sorted_agents = sorted(self._agents.keys(), key=key, reverse=not ascending)
 
         return (
-            AgentSet(sorted_agents, self.model)
+            AgentSet(sorted_agents, self.random)
             if not inplace
             else self._update(sorted_agents)
         )
@@ -491,7 +481,7 @@ class AgentSet(MutableSet, Sequence):
         Returns:
             dict: A dictionary representing the state of the AgentSet.
         """
-        return {"agents": list(self._agents.keys()), "model": self.model}
+        return {"agents": list(self._agents.keys()), "random": self.random}
 
     def __setstate__(self, state):
         """Set the state of the AgentSet during deserialization.
@@ -499,18 +489,9 @@ class AgentSet(MutableSet, Sequence):
         Args:
             state (dict): A dictionary representing the state to restore.
         """
-        self.model = state["model"]
+        self.random = state["random"]
         self._update(state["agents"])
 
-    @property
-    def random(self) -> Random:
-        """Provide access to the model's random number generator.
-
-        Returns:
-            Random: The random number generator associated with the model.
-        """
-        return self.model.random
-
     def groupby(self, by: Callable | str, result_type: str = "agentset") -> GroupBy:
         """Group agents by the specified attribute or return from the callable.
 
@@ -543,7 +524,7 @@ class AgentSet(MutableSet, Sequence):
 
         if result_type == "agentset":
             return GroupBy(
-                {k: AgentSet(v, model=self.model) for k, v in groups.items()}
+                {k: AgentSet(v, random=self.random) for k, v in groups.items()}
             )
         else:
             return GroupBy(groups)

mesa/batchrunner.py

@@ -38,6 +38,9 @@ def batch_run(
     Returns:
         List[Dict[str, Any]]
 
+    Notes:
+        batch_run assumes the model has a `datacollector` attribute that has a DataCollector object initialized.
+
     """
     runs_list = []
     run_id = 0
@@ -173,6 +176,10 @@ def _collect_data(
     step: int,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     """Collect model and agent data from a model using mesas datacollector."""
+    if not hasattr(model, "datacollector"):
+        raise AttributeError(
+            "The model does not have a datacollector attribute. Please add a DataCollector to your model."
+        )
     dc = model.datacollector
 
     model_data = {param: values[step] for param, values in dc.model_vars.items()}

mesa/examples.py

@@ -0,0 +1,3 @@
+"""This module is a collection of example models built using the Mesa framework."""
+
+__path__ = ["examples"]

mesa/experimental/__init__.py

@@ -2,6 +2,12 @@
 
 from mesa.experimental import cell_space
 
-from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
+try:
+    from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
 
-__all__ = ["cell_space", "JupyterViz", "SolaraViz", "make_text", "Slider"]
+    __all__ = ["cell_space", "JupyterViz", "Slider", "SolaraViz", "make_text"]
+except ImportError:
+    print(
+        "Could not import SolaraViz. If you need it, install with 'pip install --pre mesa[viz]'"
+    )
+    __all__ = ["cell_space"]

mesa/experimental/cell_space/__init__.py

@@ -6,7 +6,11 @@ expressive that the default grids available in `mesa.space`.
 """
 
 from mesa.experimental.cell_space.cell import Cell
-from mesa.experimental.cell_space.cell_agent import CellAgent
+from mesa.experimental.cell_space.cell_agent import (
+    CellAgent,
+    FixedAgent,
+    Grid2DMovingAgent,
+)
 from mesa.experimental.cell_space.cell_collection import CellCollection
 from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 from mesa.experimental.cell_space.grid import (
@@ -22,6 +26,8 @@ __all__ = [
     "CellCollection",
     "Cell",
     "CellAgent",
+    "Grid2DMovingAgent",
+    "FixedAgent",
     "DiscreteSpace",
     "Grid",
     "HexGrid",

mesa/experimental/cell_space/cell.py

@@ -2,15 +2,17 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from functools import cache, cached_property
 from random import Random
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
+from mesa.experimental.cell_space.cell_agent import CellAgent
 from mesa.experimental.cell_space.cell_collection import CellCollection
+from mesa.space import PropertyLayer
 
 if TYPE_CHECKING:
     from mesa.agent import Agent
-    from mesa.experimental.cell_space.cell_agent import CellAgent
 
 Coordinate = tuple[int, ...]
 
@@ -34,6 +36,7 @@ class Cell:
         "capacity",
         "properties",
         "random",
+        "_mesa_property_layers",
         "__dict__",
     ]
 
@@ -66,9 +69,10 @@ class Cell:
         self.agents: list[
             Agent
         ] = []  # TODO:: change to AgentSet or weakrefs? (neither is very performant, )
-        self.capacity: int = capacity
+        self.capacity: int | None = capacity
         self.properties: dict[Coordinate, object] = {}
         self.random = random
+        self._mesa_property_layers: dict[str, PropertyLayer] = {}
 
     def connect(self, other: Cell, key: Coordinate | None = None) -> None:
         """Connects this cell to another cell.
@@ -117,7 +121,6 @@ class Cell:
 
         """
         self.agents.remove(agent)
-        agent.cell = None
 
     @property
     def is_empty(self) -> bool:
@@ -133,7 +136,7 @@ class Cell:
         return f"Cell({self.coordinate}, {self.agents})"
 
     @cached_property
-    def neighborhood(self) -> CellCollection:
+    def neighborhood(self) -> CellCollection[Cell]:
         """Returns the direct neighborhood of the cell.
 
         This is equivalent to cell.get_neighborhood(radius=1)
@@ -145,7 +148,7 @@ class Cell:
     @cache  # noqa: B019
     def get_neighborhood(
         self, radius: int = 1, include_center: bool = False
-    ) -> CellCollection:
+    ) -> CellCollection[Cell]:
         """Returns a list of all neighboring cells for the given radius.
 
         For getting the direct neighborhood (i.e., radius=1) you can also use
@@ -191,3 +194,29 @@ class Cell:
             if not include_center:
                 neighborhood.pop(self, None)
             return neighborhood
+
+    # PropertyLayer methods
+    def get_property(self, property_name: str) -> Any:
+        """Get the value of a property."""
+        return self._mesa_property_layers[property_name].data[self.coordinate]
+
+    def set_property(self, property_name: str, value: Any):
+        """Set the value of a property."""
+        self._mesa_property_layers[property_name].set_cell(self.coordinate, value)
+
+    def modify_property(
+        self, property_name: str, operation: Callable, value: Any = None
+    ):
+        """Modify the value of a property."""
+        self._mesa_property_layers[property_name].modify_cell(
+            self.coordinate, operation, value
+        )
+
+    def __getstate__(self):
+        """Return state of the Cell with connections set to empty."""
+        # fixme, once we shift to 3.11, replace this with super. __getstate__
+        state = (self.__dict__, {k: getattr(self, k) for k in self.__slots__})
+        state[1][
+            "connections"
+        ] = {}  # replace this with empty connections to avoid infinite recursion error in pickle/deepcopy
+        return state