Mesa 3.0.0a1__tar.gz → 3.0.0a2__tar.gz

{mesa-3.0.0a1 → mesa-3.0.0a2}/.github/workflows/build_lint.yml

@@ -80,4 +80,4 @@ jobs:
     - name: Test examples
       run: |
         cd mesa-examples
-        pytest test_examples.py
+        pytest -rA -Werror test_examples.py

{mesa-3.0.0a1 → mesa-3.0.0a2}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.5.0
+  rev: v0.5.6
   hooks:
     # Run the linter.
     - id: ruff
@@ -14,7 +14,7 @@ repos:
     - id: ruff-format
       types_or: [ python, pyi, jupyter ]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.16.0
+    rev: v3.17.0
     hooks:
     -   id: pyupgrade
         args: [--py310-plus]

{mesa-3.0.0a1 → mesa-3.0.0a2}/HISTORY.md

@@ -1,6 +1,37 @@
 ---
 title: Release History
 ---
+# 3.0.0a2 (2024-08-21)
+## Highlights
+In Mesa 3.0 alpha 2 (`v3.0.0a2`) we've done more clean-up in preparation for Mesa 3.0. We now [require](https://github.com/projectmesa/mesa/pull/2218) `super().__init__()`  to run on initializing a Mesa model subclass, `Model.agents` is now fully reserved for the Model's internal AgentSet and we fixed a bug in our Solara space_drawer.
+
+A new feature was added in [#2219](https://github.com/projectmesa/mesa/pull/2219), which now also allows `AgentSet.do()` to take any callable function, instead of only a string referencing to an Agent method. The argument name was changed from `method_name` to `method`.
+
+The new Solara visualisation now allows portraying agents in different shapes, checkout some examples in [#2214](https://github.com/projectmesa/mesa/pull/2214).
+
+We're also working hard on our [example models](https://github.com/projectmesa/mesa-examples). All model warnings were [resolved](https://github.com/projectmesa/mesa-examples/pull/153) and we've [replaced](https://github.com/projectmesa/mesa-examples/pull/161) a lot of schedulers with simpler and more flexible AgentSet functionality. Checkout our [open issues](https://github.com/projectmesa/mesa-examples/issues) if you want to help improve our example models further!
+
+## What's Changed
+### ⚠️ Breaking changes
+* breaking: Add dependencies argument to custom space_drawer by @rht in https://github.com/projectmesa/mesa/pull/2209
+* Require Mesa models to be initialized with `super().__init__()` by @EwoutH in https://github.com/projectmesa/mesa/pull/2218
+* Allow AgentSet.do() to take Callable function by @quaquel in https://github.com/projectmesa/mesa/pull/2219
+* Change warning when setting model.agents to error by @EwoutH in https://github.com/projectmesa/mesa/pull/2225
+### 🧪 Experimental features
+* devs/eventlist: Add repr method to print EventList pretty by @EwoutH in https://github.com/projectmesa/mesa/pull/2195
+### 🛠 Enhancements made
+* Visualisation: Allow specifying Agent shapes in agent_portrayal by @rmhopkins4 in https://github.com/projectmesa/mesa/pull/2214
+### 📜 Documentation improvements
+* docs/conf.py: Use modern `intersphinx_mapping` format by @EwoutH in https://github.com/projectmesa/mesa/pull/2206
+* docs: Update Readme and tutorials to mention Mesa 3.0 pre-releases by @EwoutH in https://github.com/projectmesa/mesa/pull/2203
+### 🔧 Maintenance
+* CI: Let pytest treat warnings as errors for examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2204
+
+## New Contributors
+* @rmhopkins4 made their first contribution in https://github.com/projectmesa/mesa/pull/2214
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a1...v3.0.0a2
+
 # 3.0.0a1 (2024-08-01)
 ## Highlights
 Mesa 3.0 alpha 1 (`v3.0.0a1`) is another step towards our next major version. This release introduces a name change from JupyterViz (jupyter_viz) to SolaraViz (solara_viz), to better represent the tech stack being used. It also includes two bugfixes also present in 2.3.2.

{mesa-3.0.0a1 → mesa-3.0.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0a1
+Version: 3.0.0a2
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -30,7 +30,6 @@ Requires-Dist: pandas
 Requires-Dist: solara
 Requires-Dist: tqdm
 Provides-Extra: dev
-Requires-Dist: coverage; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest-mock; extra == 'dev'
 Requires-Dist: pytest>=4.6; extra == 'dev'
@@ -75,13 +74,19 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-Getting started quickly:
+To install our latest stable release (2.3.x), run:
 
 ``` bash
-pip install mesa
+pip install -U mesa
 ```
 
-You can also use `pip` to install the github version:
+To install our latest pre-release (3.0.0 alpha), run:
+
+``` bash
+pip install -U --pre mesa
+```
+
+You can also use `pip` to install the latest GitHub version:
 
 ``` bash
 pip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa

{mesa-3.0.0a1 → mesa-3.0.0a2}/README.md

@@ -28,13 +28,19 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-Getting started quickly:
+To install our latest stable release (2.3.x), run:
 
 ``` bash
-pip install mesa
+pip install -U mesa
 ```
 
-You can also use `pip` to install the github version:
+To install our latest pre-release (3.0.0 alpha), run:
+
+``` bash
+pip install -U --pre mesa
+```
+
+You can also use `pip` to install the latest GitHub version:
 
 ``` bash
 pip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa

{mesa-3.0.0a1 → mesa-3.0.0a2}/docs/conf.py

@@ -279,4 +279,4 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

{mesa-3.0.0a1 → mesa-3.0.0a2}/docs/tutorials/intro_tutorial.ipynb

@@ -66,6 +66,12 @@
     "pip install --upgrade mesa\n",
     "```\n",
     "\n",
+    "If you want to use our newest features, you can also opt to install our latest pre-release version:\n",
+    "\n",
+    "```bash\n",
+    "pip install --upgrade --pre mesa\n",
+    "```\n",
+    "\n",
     "Install Jupyter Notebook (optional):\n",
     "\n",
     "```bash\n",
@@ -1209,15 +1215,19 @@
   },
   {
    "cell_type": "markdown",
-   "source": [
-    "We can create different kinds of plot from this filtered DataFrame. For example, a point plot with error bars."
-   ],
    "metadata": {
     "collapsed": false
-   }
+   },
+   "source": [
+    "We can create different kinds of plot from this filtered DataFrame. For example, a point plot with error bars."
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [],
    "source": [
     "# Create a point plot with error bars\n",
@@ -1228,11 +1238,7 @@
     "    ylabel=\"Gini coefficient\",\n",
     "    title=\"Gini coefficient vs. number of agents\",\n",
     ");"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -1284,16 +1290,20 @@
   },
   {
    "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
    "source": [
     "### Analyzing model reporters: Comparing 5 scenarios\n",
     "Other insights might be gathered when we compare the Gini coefficient of different scenarios. For example, we can compare the Gini coefficient of a population with 25 agents to the Gini coefficient of a population with 400 agents. While doing this, we increase the number of iterations to 25 to get a better estimate of the Gini coefficient for each population size and get usable error estimations."
-   ],
-   "metadata": {
-    "collapsed": false
-   }
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [],
    "source": [
     "params = {\"width\": 10, \"height\": 10, \"N\": [5, 10, 20, 40, 80]}\n",
@@ -1309,27 +1319,27 @@
     ")\n",
     "\n",
     "results_5s_df = pd.DataFrame(results_5s)"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [],
    "source": [
     "# Again filter the results to only contain the data of one agent (the Gini coefficient will be the same for the entire population at any time)\n",
     "results_5s_df_filtered = results_5s_df[(results_5s_df.AgentID == 0)]\n",
     "results_5s_df_filtered.head(3)"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [],
    "source": [
     "# Create a lineplot with error bars\n",
@@ -1344,35 +1354,35 @@
     "g.figure.set_size_inches(8, 4)\n",
     "plot_title = \"Gini coefficient for different population sizes\\n(mean over 100 runs, with 95% confidence interval)\"\n",
     "g.set(title=plot_title, ylabel=\"Gini coefficient\");"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
-   "source": [
-    "In this case it looks like the Gini coefficient increases slower for smaller populations. This can be because of different things, either because the Gini coefficient is a measure of inequality and the smaller the population, the more likely it is that the agents are all in the same wealth class, or because there are less interactions between agents in smaller populations, which means that the wealth of an agent is less likely to change."
-   ],
    "metadata": {
     "collapsed": false
-   }
+   },
+   "source": [
+    "In this case it looks like the Gini coefficient increases slower for smaller populations. This can be because of different things, either because the Gini coefficient is a measure of inequality and the smaller the population, the more likely it is that the agents are all in the same wealth class, or because there are less interactions between agents in smaller populations, which means that the wealth of an agent is less likely to change."
+   ]
   },
   {
    "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
    "source": [
     "### Analyzing agent reporters\n",
     "From the agents we collected the wealth and the number of consecutive rounds without a transaction. We can compare the 5 different population sizes by plotting the average number of consecutive rounds without a transaction for each population size.\n",
     "\n",
     "Note that we're aggregating multiple times here: First we take the average of all agents for each single replication. Then we plot the averages for all replications, with the error band showing the 95% confidence interval of that first average (over all agents). So this error band is representing the uncertainty of the mean value of the number of consecutive rounds without a transaction for each population size."
-   ],
-   "metadata": {
-    "collapsed": false
-   }
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [],
    "source": [
     "# Calculate the mean of the wealth and the number of consecutive rounds for all agents in each episode\n",
@@ -1382,14 +1392,14 @@
     "    .reset_index()\n",
     ")\n",
     "agg_results_df.head(3)"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [],
    "source": [
     "# Create a line plot with error bars\n",
@@ -1401,23 +1411,22 @@
     "    title=\"Average number of consecutive rounds without a transaction for different population sizes\\n(mean with 95% confidence interval)\",\n",
     "    ylabel=\"Consecutive rounds without a transaction\",\n",
     ");"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
-   "source": [
-    "It can be clearly seen that the lower the number of agents, the higher the number of consecutive rounds without a transaction. This is because the agents have fewer interactions with each other and therefore the wealth of an agent is less likely to change."
-   ],
    "metadata": {
     "collapsed": false
-   }
+   },
+   "source": [
+    "It can be clearly seen that the lower the number of agents, the higher the number of consecutive rounds without a transaction. This is because the agents have fewer interactions with each other and therefore the wealth of an agent is less likely to change."
+   ]
   },
   {
    "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
    "source": [
     "#### General steps for analyzing results\n",
     "\n",
@@ -1430,10 +1439,7 @@
     "5. Transform, filter and aggregate the results to get the data you want to analyze. Make sure it's in long format, so that each row represents a single value.\n",
     "6. Choose a plot type, what to plot on the x and y axis, which columns to use for the hue. Seaborn also has an amazing [Example Gallery](https://seaborn.pydata.org/examples/index.html).\n",
     "7. Plot the data and analyze the results."
-   ],
-   "metadata": {
-    "collapsed": false
-   }
+   ]
   },
   {
    "cell_type": "markdown",

{mesa-3.0.0a1 → mesa-3.0.0a2}/docs/tutorials/visualization_tutorial.ipynb

@@ -11,6 +11,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "*This version of the visualisation tutorial is updated for Mesa 3.0, and works with Mesa `3.0.0a1` and above. If you are using Mesa 2.3.x, check out the [stable version](https://mesa.readthedocs.io/en/stable/tutorials/visualization_tutorial.html) of this tutorial on Readthedocs.*\n",
+    "\n",
     "**Important:** \n",
     "- If you are just exploring Mesa and want the fastest way to execute the code we recommend executing this tutorial online in a Colab notebook. [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/projectmesa/mesa/blob/main/docs/tutorials/visualization_tutorial.ipynb)\n",
     "- If you have installed mesa and are running locally, please ensure that your [Mesa version](https://pypi.org/project/Mesa/) is up-to-date in order to run this tutorial.\n",
@@ -39,8 +41,10 @@
    },
    "outputs": [],
    "source": [
-    "%pip install --quiet mesa\n",
+    "# Install and import the latest Mesa pre-release version\n",
+    "%pip install --quiet --upgrade --pre mesa\n",
     "import mesa\n",
+    "print(f\"Mesa version: {mesa.__version__}\")\n",
     "\n",
     "# You can either define the BoltzmannWealthModel (aka MoneyModel) or install mesa-models:\n",
     "%pip install --quiet -U git+https://github.com/projectmesa/mesa-examples#egg=mesa-models\n",
@@ -138,7 +142,8 @@
    "source": [
     "#### Changing the agents\n",
     "\n",
-    "In the visualization above, all we could see is the agents moving around -- but not how much money they had, or anything else of interest. Let's change it so that agents who are broke (wealth 0) are drawn in red, smaller. (TODO: currently, we can't predict the drawing order of the circles, so a broke agent may be overshadowed by a wealthy agent. We should fix this by doing a hollow circle instead)\n",
+    "In the visualization above, all we could see is the agents moving around -- but not how much money they had, or anything else of interest. Let's change it so that agents who are broke (wealth 0) are drawn in red, smaller. (TODO: Currently, we can't predict the drawing order of the circles, so a broke agent may be overshadowed by a wealthy agent. We should fix this by doing a hollow circle instead)\n",
+    "In addition to size and color, an agent's shape can also be customized when using the default drawer. The allowed values for shapes can be found [here](https://matplotlib.org/stable/api/markers_api.html).\n",
     "\n",
     "To do this, we go back to our `agent_portrayal` code and add some code to change the portrayal based on the agent properties and launch the server again."
    ]

{mesa-3.0.0a1 → mesa-3.0.0a2}/mesa/__init__.py

@@ -24,7 +24,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "3.0.0a1"
+__version__ = "3.0.0a2"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

{mesa-3.0.0a1 → mesa-3.0.0a2}/mesa/agent.py

@@ -11,9 +11,7 @@ from __future__ import annotations
 import contextlib
 import copy
 import operator
-import warnings
 import weakref
-from collections import defaultdict
 from collections.abc import Callable, Iterable, Iterator, MutableSet, Sequence
 from random import Random
 
@@ -52,17 +50,11 @@ class Agent:
         # register agent
         try:
             self.model.agents_[type(self)][self] = None
-        except AttributeError:
+        except AttributeError as err:
             # model super has not been called
-            self.model.agents_ = defaultdict(dict)
-            self.model.agents_[type(self)][self] = None
-            self.model.agentset_experimental_warning_given = False
-
-            warnings.warn(
-                "The Mesa Model class was not initialized. In the future, you need to explicitly initialize the Model by calling super().__init__() on initialization.",
-                FutureWarning,
-                stacklevel=2,
-            )
+            raise RuntimeError(
+                "The Mesa Model class was not initialized. You must explicitly initialize the Model by calling super().__init__() on initialization."
+            ) from err
 
     def remove(self) -> None:
         """Remove and delete the agent from the model."""
@@ -100,8 +92,6 @@ class AgentSet(MutableSet, Sequence):
         which means that agents not referenced elsewhere in the program may be automatically removed from the AgentSet.
     """
 
-    agentset_experimental_warning_given = False
-
     def __init__(self, agents: Iterable[Agent], model: Model):
         """
         Initializes the AgentSet with a collection of agents and a reference to the model.
@@ -227,26 +217,37 @@ class AgentSet(MutableSet, Sequence):
         return self
 
     def do(
-        self, method_name: str, *args, return_results: bool = False, **kwargs
+        self, method: str | Callable, *args, return_results: bool = False, **kwargs
     ) -> AgentSet | list[Any]:
         """
-        Invoke a method on each agent in the AgentSet.
+        Invoke a method or function on each agent in the AgentSet.
 
         Args:
-            method_name (str): The name of the method to call on each agent.
+            method (str, callable): the callable to do on each agents
+
+                                        * in case of str, the name of the method to call on each agent.
+                                        * in case of callable, the function to be called with each agent as first argument
+
             return_results (bool, optional): If True, returns the results of the method calls; otherwise, returns the AgentSet itself. Defaults to False, so you can chain method calls.
-            *args: Variable length argument list passed to the method being called.
-            **kwargs: Arbitrary keyword arguments passed to the method being called.
+            *args: Variable length argument list passed to the callable being called.
+            **kwargs: Arbitrary keyword arguments passed to the callable being called.
 
         Returns:
-            AgentSet | list[Any]: The results of the method calls if return_results is True, otherwise the AgentSet itself.
+            AgentSet | list[Any]: The results of the callable calls if return_results is True, otherwise the AgentSet itself.
         """
         # we iterate over the actual weakref keys and check if weakref is alive before calling the method
-        res = [
-            getattr(agent, method_name)(*args, **kwargs)
-            for agentref in self._agents.keyrefs()
-            if (agent := agentref()) is not None
-        ]
+        if isinstance(method, str):
+            res = [
+                getattr(agent, method)(*args, **kwargs)
+                for agentref in self._agents.keyrefs()
+                if (agent := agentref()) is not None
+            ]
+        else:
+            res = [
+                method(agent, *args, **kwargs)
+                for agentref in self._agents.keyrefs()
+                if (agent := agentref()) is not None
+            ]
 
         return res if return_results else self
 

{mesa-3.0.0a1 → mesa-3.0.0a2}/mesa/experimental/devs/eventlist.py

@@ -155,6 +155,17 @@ class EventList:
     def __len__(self) -> int:
         return len(self._events)
 
+    def __repr__(self) -> str:
+        """Return a string representation of the event list"""
+        events_str = ", ".join(
+            [
+                f"Event(time={e.time}, priority={e.priority}, id={e.unique_id})"
+                for e in self._events
+                if not e.CANCELED
+            ]
+        )
+        return f"EventList([{events_str}])"
+
     def remove(self, event: SimulationEvent) -> None:
         """remove an event from the event list"""
         # we cannot simply remove items from _eventlist because this breaks

{mesa-3.0.0a1 → mesa-3.0.0a2}/mesa/model.py

@@ -10,7 +10,6 @@ from __future__ import annotations
 
 import itertools
 import random
-import warnings
 from collections import defaultdict
 
 # mypy
@@ -89,12 +88,10 @@ class Model:
 
     @agents.setter
     def agents(self, agents: Any) -> None:
-        warnings.warn(
-            "You are trying to set model.agents. In a next release, this attribute is used "
-            "by MESA itself so you cannot use it directly anymore."
-            "Please adjust your code to use a different attribute name for custom agent storage",
-            UserWarning,
-            stacklevel=2,
+        raise AttributeError(
+            "You are trying to set model.agents. In Mesa 3.0 and higher, this attribute will be "
+            "used by Mesa itself, so you cannot use it directly anymore."
+            "Please adjust your code to use a different attribute name for custom agent storage."
         )
 
         self._agents = agents

{mesa-3.0.0a1 → mesa-3.0.0a2}/mesa/space.py

@@ -586,7 +586,7 @@ class PropertyLayer:
         aggregate_property(operation): Performs an aggregate operation over all cells.
     """
 
-    agentset_experimental_warning_given = False
+    propertylayer_experimental_warning_given = False
 
     def __init__(
         self, name: str, width: int, height: int, default_value, dtype=np.float64
@@ -633,14 +633,14 @@ class PropertyLayer:
 
         self.data = np.full((width, height), default_value, dtype=dtype)
 
-        if not self.__class__.agentset_experimental_warning_given:
+        if not self.__class__.propertylayer_experimental_warning_given:
             warnings.warn(
                 "The new PropertyLayer and _PropertyGrid classes experimental. It may be changed or removed in any and all future releases, including patch releases.\n"
                 "We would love to hear what you think about this new feature. If you have any thoughts, share them with us here: https://github.com/projectmesa/mesa/discussions/1932",
                 FutureWarning,
                 stacklevel=2,
             )
-            self.__class__.agentset_experimental_warning_given = True
+            self.__class__.propertylayer_experimental_warning_given = True
 
     def set_cell(self, position: Coordinate, value):
         """