Mesa 3.1.3__tar.gz → 3.1.4__tar.gz

{mesa-3.1.3 → mesa-3.1.4}/.github/workflows/benchmarks.yml

@@ -28,8 +28,10 @@ jobs:
           python-version: '3.13'
       - name: Add project directory to PYTHONPATH
         run: echo "PYTHONPATH=$PYTHONPATH:$(pwd)" >> $GITHUB_ENV
+      - name: Install uv
+        run: pip install uv
       - name: Install dependencies
-        run: pip install numpy pandas tqdm tabulate matplotlib solara networkx
+        run: uv pip install --system numpy pandas tqdm tabulate matplotlib solara networkx scipy
       # Benchmarks on the projectmesa main branch
       - name: Checkout main branch
         uses: actions/checkout@v4

{mesa-3.1.3 → mesa-3.1.4}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.8.6
+  rev: v0.9.4
   hooks:
     # Run the linter.
     - id: ruff
@@ -25,7 +25,7 @@ repos:
     -   id: check-toml
     -   id: check-yaml
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.3.0
+  rev: v2.4.1
   hooks:
     - id: codespell
       args: [

{mesa-3.1.3 → mesa-3.1.4}/HISTORY.md

@@ -1,6 +1,44 @@
 ---
 title: Release History
 ---
+# 3.1.4 (2025-02-09)
+## Highlights
+This release contains various improvements and bugfixes to the matplotlib-based visualization of spaces. Hexgrids are now fully supported, including property layers. In making this possible, various minor bugs were encountered and also fixed. In addition to the visualization improvements, there are various minor convenience improvements to the docs.
+
+
+## What's Changed
+### 🛠 Enhancements made
+* Fixed hex-space draw function to avoid overlaps by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2609
+* Fix: Property layer visualization for HexGrid by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2646
+* Enhance DataCollector to validate model_reporters functions by @peter-kinger in https://github.com/projectmesa/mesa/pull/2605
+* Implemented post_process in Altair based components by @sanika-n in https://github.com/projectmesa/mesa/pull/2641
+### 🐛 Bugs fixed
+* bugfix for draw_property_layer by @quaquel in https://github.com/projectmesa/mesa/pull/2639
+* Uses array for hex grid property layer fix by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2651
+* Update Binder environment to use latest Mesa version (#2652) by @aarav-shukla07 in https://github.com/projectmesa/mesa/pull/2655
+* Change Hexgrid._connect_cells_2d to use x,y coordinates by @quaquel in https://github.com/projectmesa/mesa/pull/2632
+### 🔍 Examples updated
+* Added property layer viz to sugarscape by @sanika-n in https://github.com/projectmesa/mesa/pull/2653
+* added color-bar for spice by @sanika-n in https://github.com/projectmesa/mesa/pull/2622
+### 📜 Documentation improvements
+* remove any reference to using --pre by @quaquel in https://github.com/projectmesa/mesa/pull/2618
+* Updated Docs by @sanika-n in https://github.com/projectmesa/mesa/pull/2624
+* Fixed 404 error for Examples Tab in Introductory Tutorial (#2662) by @aarav-shukla07 in https://github.com/projectmesa/mesa/pull/2664
+* Documentation by @Spartan-71 in https://github.com/projectmesa/mesa/pull/2630
+* Adding a copy option at the top of the code written in the docs by @PrashantChoudhary13579 in https://github.com/projectmesa/mesa/pull/2628
+* Adding Mesa Extension page by @PrashantChoudhary13579 in https://github.com/projectmesa/mesa/pull/2627
+### 🔧 Maintenance
+* remove remnants of mesa cli by @quaquel in https://github.com/projectmesa/mesa/pull/2617
+* benchmarks.yml: Install SciPy and use uv for pip install by @EwoutH in https://github.com/projectmesa/mesa/pull/2633
+* [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/projectmesa/mesa/pull/2659
+
+## New Contributors
+* @PrashantChoudhary13579 made their first contribution in https://github.com/projectmesa/mesa/pull/2628
+* @aarav-shukla07 made their first contribution in https://github.com/projectmesa/mesa/pull/2655
+* @peter-kinger made their first contribution in https://github.com/projectmesa/mesa/pull/2605
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.1.3...v3.1.4
+
 # 3.1.3 (2025-01-11)
 ## Highlights
 Mesa 3.1.3 introduces a major experimental reimplementation of Mesa's continuous space, providing an intuitive agent-centric API and significant performance improvements. The new implementation supports n-dimensional spaces and offers streamlined methods for agent movement and neighbor calculations.

{mesa-3.1.3 → mesa-3.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Mesa
-Version: 3.1.3
+Version: 3.1.4
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -27,6 +27,7 @@ Requires-Dist: pandas
 Requires-Dist: scipy
 Requires-Dist: tqdm
 Provides-Extra: all
+Requires-Dist: altair; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
 Requires-Dist: matplotlib; extra == 'all'
 Requires-Dist: myst-nb; extra == 'all'
@@ -41,7 +42,9 @@ Requires-Dist: scipy; extra == 'all'
 Requires-Dist: seaborn; extra == 'all'
 Requires-Dist: solara; extra == 'all'
 Requires-Dist: sphinx; extra == 'all'
+Requires-Dist: sphinx-copybutton; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: altair; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
 Requires-Dist: networkx; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
@@ -51,6 +54,7 @@ Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: solara; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: altair; extra == 'docs'
 Requires-Dist: ipython; extra == 'docs'
 Requires-Dist: matplotlib; extra == 'docs'
 Requires-Dist: myst-nb; extra == 'docs'
@@ -60,7 +64,9 @@ Requires-Dist: pydata-sphinx-theme; extra == 'docs'
 Requires-Dist: seaborn; extra == 'docs'
 Requires-Dist: solara; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-copybutton; extra == 'docs'
 Provides-Extra: examples
+Requires-Dist: altair; extra == 'examples'
 Requires-Dist: matplotlib; extra == 'examples'
 Requires-Dist: networkx; extra == 'examples'
 Requires-Dist: pytest; extra == 'examples'
@@ -69,10 +75,12 @@ Requires-Dist: solara; extra == 'examples'
 Provides-Extra: network
 Requires-Dist: networkx; extra == 'network'
 Provides-Extra: rec
+Requires-Dist: altair; extra == 'rec'
 Requires-Dist: matplotlib; extra == 'rec'
 Requires-Dist: networkx; extra == 'rec'
 Requires-Dist: solara; extra == 'rec'
 Provides-Extra: viz
+Requires-Dist: altair; extra == 'viz'
 Requires-Dist: matplotlib; extra == 'viz'
 Requires-Dist: solara; extra == 'viz'
 Description-Content-Type: text/markdown
@@ -107,27 +115,22 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-To install our latest stable release (3.0.x), run:
+To install our latest stable release, run:
 
 ``` bash
 pip install -U mesa
 ```
 
-To install our latest pre-release, run:
-
-``` bash
-pip install -U --pre mesa
-```
 Starting with Mesa 3.0, we don't install all our dependencies anymore by default.
 ```bash
 # You can customize the additional dependencies you need, if you want. Available are:
-pip install -U --pre mesa[network,viz]
+pip install -U mesa[network,viz]
 
 # This is equivalent to our recommended dependencies:
-pip install -U --pre mesa[rec]
+pip install -U mesa[rec]
 
 # To install all, including developer, dependencies:
-pip install -U --pre mesa[all]
+pip install -U mesa[all]
 ```
 
 You can also use `pip` to install the latest GitHub version:

{mesa-3.1.3 → mesa-3.1.4}/README.md

@@ -28,27 +28,22 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-To install our latest stable release (3.0.x), run:
+To install our latest stable release, run:
 
 ``` bash
 pip install -U mesa
 ```
 
-To install our latest pre-release, run:
-
-``` bash
-pip install -U --pre mesa
-```
 Starting with Mesa 3.0, we don't install all our dependencies anymore by default.
 ```bash
 # You can customize the additional dependencies you need, if you want. Available are:
-pip install -U --pre mesa[network,viz]
+pip install -U mesa[network,viz]
 
 # This is equivalent to our recommended dependencies:
-pip install -U --pre mesa[rec]
+pip install -U mesa[rec]
 
 # To install all, including developer, dependencies:
-pip install -U --pre mesa[all]
+pip install -U mesa[all]
 ```
 
 You can also use `pip` to install the latest GitHub version:

{mesa-3.1.3 → mesa-3.1.4}/binder/environment.yml

@@ -1,4 +1,4 @@
-name: example-environment
+name: mesa-tutorials
 channels:
   - conda-forge
 dependencies:
@@ -11,4 +11,4 @@ dependencies:
     - matplotlib
     - seaborn
     - solara
-    - mesa[rec]==3.0.0b1
+    - mesa[rec]

{mesa-3.1.3 → mesa-3.1.4}/docs/README.md

@@ -15,6 +15,7 @@ Updating docs can be confusing. Here are the basic setups.
 1. Build the docs, from the inside of the docs folder.
     * **Requires** sphinx: `pip install sphinx`
     * **Requires** nbsphinx: `pip install nbsphinx` (this will render the images from jupyter in the docs)
+    * **Requires** sphinx-copybutton: `pip install sphinx-copybutton` (this will enable a copy option at the top of the code written in the docs)
     * `make html`
 1. Commit the changes. If there are new files, you will have to explicit add them.
     * `git commit -am "Updating docs."`
@@ -32,5 +33,5 @@ From this point, you will need to find someone that has access to readthedocs. C
 ### Helpful Sphnix tips
 * Build html from docs:
   * `make html`
-* Autogenerate / update sphninx from docstrings (replace your name as the author:
+* Autogenerate / update sphninx from docstrings (replace your name as the author):
   * `sphinx-apidoc -A "Jackie Kazil" -F -o docs mesa/`

{mesa-3.1.3 → mesa-3.1.4}/docs/apis/visualization.md

@@ -11,6 +11,13 @@ For a detailed tutorial, please refer to our [Visualization Tutorial](../tutoria
    :show-inheritance:
 ```
 
+```{eval-rst}
+.. automodule:: mesa.visualization.components.__init__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
 ## User Parameters
 
 ```{eval-rst}
@@ -37,6 +44,7 @@ For a detailed tutorial, please refer to our [Visualization Tutorial](../tutoria
    :show-inheritance:
 ```
 
+
 ## Altair-based visualizations
 
 ```{eval-rst}

{mesa-3.1.3 → mesa-3.1.4}/docs/conf.py

@@ -47,6 +47,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",  # for google style docstrings
     "myst_nb",  # For Markdown and Jupyter notebooks
+    "sphinx_copybutton" # For copying the code in the documentation
 ]
 
 # Add any paths that contain templates here, relative to this directory.

{mesa-3.1.3 → mesa-3.1.4}/docs/getting_started.md

@@ -68,7 +68,6 @@ model.step()
 
 You should see agents 1-5, activated in random order. See the [tutorial](tutorials/intro_tutorial) or API documentation for more detail on how to add model functionality.
 
-To bootstrap a new model install mesa and run `mesa startproject`
 
 ### AgentSet and model.agents
 Mesa 3.0 makes `model.agents` and the AgentSet class central in managing and activating agents.
@@ -178,8 +177,7 @@ The results are returned as a list of dictionaries, which can be easily converte
 ### Visualization
 Mesa now uses a new browser-based visualization system called SolaraViz. This allows for interactive, customizable visualizations of your 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. There won't be breaking changes between Mesa 3.0.x patch releases.
-
+Note: 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.
 > **Note:** SolaraViz instantiates new models using `**model_parameters.value`, so all model inputs must be keyword arguments.
 
 Ensure your model's `__init__` method accepts keyword arguments matching the `model_params` keys.
@@ -189,8 +187,8 @@ class MyModel(Model):
     def __init__(self, n_agents=10, seed=None):
         super().__init__(seed=seed)
         # Initialize the model with N agents
-
-The core functionality for building your own visualizations resides in the [`mesa.visualization`](apis/visualization) namespace
+```
+The core functionality for building your own visualizations resides in the [`mesa.visualization`](apis/visualization) namespace.
 
 Here's a basic example of how to set up a visualization:
 

{mesa-3.1.3 → mesa-3.1.4}/docs/index.md

@@ -33,7 +33,7 @@ Mesa allows users to quickly create agent-based models using built-in core compo
 
 ## Using Mesa
 ### Installation Options
-To install our latest stable release (3.0.x), run:
+To install our latest stable release, run:
 
 ```bash
 pip install -U mesa
@@ -47,12 +47,6 @@ On a Mac, this command might cause an error stating `zsh: no matches found: mesa
 In that case, change the command to `pip install -U "mesa[rec]"`.
 
 
-To install our latest pre-release:
-
-```bash
-pip install -U --pre mesa[rec]
-```
-
 ### Resources
 
 For help getting started with Mesa, check out these resources:
@@ -60,6 +54,7 @@ For help getting started with Mesa, check out these resources:
 - [Getting started] - Learn about Mesa's core concepts and components
 - [Migration Guide] - Upgrade to Mesa 3.0
 - [Mesa Examples] - Browse user-contributed models and implementations
+- [Mesa Extensions] - Overview of mesa's Extensions
 - [GitHub Discussions] - Ask questions and discuss Mesa
 - [Matrix Chat Room] - Real-time chat with the Mesa community
 
@@ -97,9 +92,9 @@ API Documentation <apis/api_main>
 [matrix chat room]: https://matrix.to/#/#project-mesa:matrix.org
 [mesa]: https://github.com/projectmesa/mesa/
 [mesa overview]: overview
-[mesa examples]: https://github.com/projectmesa/mesa-examples
+[mesa examples]: https://mesa.readthedocs.io/stable/examples.html
 [mesa introductory tutorial]: tutorials/intro_tutorial
 [mesa visualization tutorial]: tutorials/visualization_tutorial
 [migration guide]: migration_guide
 [Getting started]: getting_started
-
+[Mesa Extensions]: mesa_extension.md

mesa-3.1.4/docs/mesa_extension.md

@@ -0,0 +1,97 @@
+# Mesa Extensions Overview
+
+This contains an overview of Mesa Extensions. Mesa's extensibility is a key feature that allows users to enhance functionality, improve scalability, and foster innovation in agent-based modeling.
+
+
+## Mesa-Geo 🌍
+
+**Field:** Geographic Information Systems (GIS)
+
+---
+**Description:**
+Mesa-Geo is an extension of the Mesa framework designed to facilitate working with geographic data in agent-based modeling. It introduces a **GeoSpace** to host **GeoAgents**, which are enhanced agents that include a `geometry` attribute ([a Shapely object](https://shapely.readthedocs.io/en/latest/manual.html)) and a `crs` attribute (Coordinate Reference System). These attributes enable the integration of geographic and spatial data into simulations. Geometries can be defined manually using Shapely or imported from various sources, such as vector data files (e.g., shapefiles), GeoJSON objects, or GeoPandas GeoDataFrames.
+
+---
+**Key Features:**
+- **Spatial Reference Systems Support:** Mesa-Geo handles coordinate reference systems (CRS), which is essential for working with geographic data in various projections.
+- **Geometric Operations Support:** Mesa-Geo utilizes Shapely, which provides robust tools for creating and manipulating geometric shapes like points, polygons, and lines.
+- **Topological Operations Support:** Functions for analyzing spatial relationships between geometries.
+
+---
+**Author(s):** Wang Boyu
+
+---
+**Additional Resources:**
+For more information, visit the official [Mesa-Geo repository](https://github.com/projectmesa/mesa-geo?tab=readme-ov-file).
+
+---
+
+## Mesa Examples 📊
+
+**Description:**
+Mesa Examples provide a collection of models and use cases demonstrating the features and capabilities of the Mesa framework for agent-based modeling. These examples include core and user-submitted models covering a variety of domains like grid spaces, networks, visualization, and GIS.
+
+---
+
+**Key Features:**
+- **Core Examples:** Fully tested and updated models included directly with the Mesa framework.
+- **User Examples:** Community-contributed models showcasing advanced and diverse use cases.
+- **Extensive Coverage:** Examples for grid spaces, GIS integration, networks, visualization, and more.
+- **Easy Access:** Available directly from the Mesa package or via installation from the repository.
+
+---
+
+**Author(s):** Contributions from the Mesa developer community.
+
+---
+
+**Examples Include:**
+- **Grid Space:** Models like Bank Reserves, Conway’s Game of Life, and Forest Fire.
+- **GIS:** GeoSchelling Models, Urban Growth, and Population Models.
+- **Network:** Boltzmann Wealth Model and Ant System for the Traveling Salesman Problem.
+- **Visualization:** Charting tools and grid displays.
+
+---
+
+**For More Information:**
+For more Detail, Visit the [Mesa Examples Repository](https://github.com/projectmesa/mesa/tree/main/mesa/examples).
+
+---
+
+## **Mesa-Frames** 🚀
+
+**Description:**
+Mesa-Frames is an extension of the Mesa framework designed to handle complex simulations with thousands of agents. By utilizing DataFrames (pandas or Polars), it enhances scalability and performance while maintaining a syntax similar to Mesa.
+
+---
+
+**Key Features:**
+- **Enhanced Performance:** Uses DataFrames for SIMD processing and vectorized functions to speed up simulations.
+- **Backend Support:** Supports `pandas` (ease of use) and `Polars` (performance innovations with Rust-based backend).
+- **Seamless Integration:** Maintains a similar API and functionality as the base Mesa framework for easier adoption.
+- **In-Place Operations:** Functional programming and fast memory-efficient copy methods.
+- **Future Plans:** GPU functionality, automatic model vectorization, and backend-independent AgentSet class.
+
+---
+
+**Usage:**
+- Define agents using `AgentSetPandas` or `AgentSetPolars`.
+- Implement models by subclassing `ModelDF`.
+- Perform vectorized operations to enhance simulation performance.
+
+---
+
+**Author(s):**
+Developed and maintained by the Mesa development community.
+
+---
+
+**License:**
+Distributed under the MIT License.
+
+---
+
+**More Information:**
+Visit the [GitHub Repository](https://github.com/projectmesa/mesa-frames).
+
+---

{mesa-3.1.3 → mesa-3.1.4}/docs/tutorials/intro_tutorial.ipynb

@@ -15,7 +15,7 @@
    "source": [
     "**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/intro_tutorial.ipynb) or if you do not have a Google account you can use [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/projectmesa/mesa/main?labpath=docs%2Ftutorials%2Fintro_tutorial.ipynb) (This can take 30 seconds to 5 minutes to load)\n",
-    "- If you have installed mesa and are running locally, please ensure that your Mesa version is greater than or equal to 3.0.0b1.\n",
+    "- If you are running locally, please ensure you have the latest Mesa version installed.\n",
     "\n",
     "## Tutorial Description\n",
     "\n",
@@ -44,7 +44,7 @@
     "If you are looking for other Mesa models or tools here are some additional resources. \n",
     "\n",
     "- Interactive Dashboard: There is a separate [visualization tutorial](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html) that will take users through building a dashboard for this model (aka Boltzmann Wealth Model).\n",
-    "- Classic ABMs: You can also find canonical examples of ABMs written in Mesa in the [Examples Tab](https://mesa.readthedocs.io/latest/tutorials/examples.html)\n",
+    "- Classic ABMs: You can also find canonical examples of ABMs written in Mesa in the [Examples Tab](https://mesa.readthedocs.io/stable/examples.html)\n",
     "- More Examples: Want to integrate Reinforcement Learning or work on the Traveling Salesman Problem checkout  [Mesa Examples](https://github.com/projectmesa/mesa-examples/)\n",
     "- Mesa-Geo: If you need an ABM with Geographic Information Systems (GIS) checkout [Mesa-Geo](https://mesa-geo.readthedocs.io/latest/)\n",
     "- Mesa Frames: Have a large complex model that you need to speed up, check out [Mesa Frames](https://github.com/projectmesa/mesa-frames)"
@@ -85,12 +85,6 @@
     "pip install --upgrade mesa[rec] \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[rec]\n",
-    "```\n",
-    "\n",
     "Install Jupyter notebook (optional):\n",
     "\n",
     "```bash\n",
@@ -118,7 +112,7 @@
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "pip install --quiet --upgrade --pre mesa[rec] #installs Mesa 3.0"
+    "pip install --quiet --upgrade mesa[rec] #installs Mesa 3.1.3"
    ]
   },
   {
@@ -615,8 +609,8 @@
     "        # Create agents\n",
     "        agents = MoneyAgent.create_agents(model=self, n=n)\n",
     "        # Create x and y positions for agents\n",
-    "        x = self.rng.randint(0, self.grid.width, size=(n,))\n",
-    "        y = self.rng.randint(0, self.grid.height, size=(n,))\n",
+    "        x = self.rng.integers(0, self.grid.width, size=(n,))\n",
+    "        y = self.rng.integers(0, self.grid.height, size=(n,))\n",
     "        for a, i, j in zip(agents, x, y):\n",
     "            # Add the agent to a random grid cell\n",
     "            self.grid.place_agent(a, (i, j))"

{mesa-3.1.3 → mesa-3.1.4}/docs/tutorials/visualization_tutorial.ipynb

@@ -11,9 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "*This version of the visualisation tutorial is updated for Mesa 3.0, and works with Mesa `3.0.0` and above.*\n",
-    "\n",
-    "> **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.\n",
+    "*This version of the visualisation tutorial is updated for Mesa 3.1, and works with Mesa `3.1.0` and above.*\n",
     "\n",
     "**Important:** \n",
     "- If you are just exploring Mesa and want the fastest way to the the dashboard and code checkout [![py.cafe](https://img.shields.io/badge/launch-py.cafe-blue)](https://py.cafe/app/tpike3/boltzmann-wealth-model) (click \"Editor\" to see the code)\n",

{mesa-3.1.3 → mesa-3.1.4}/mesa/__init__.py

@@ -22,7 +22,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "3.1.3"
+__version__ = "3.1.4"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.UTC).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

{mesa-3.1.3 → mesa-3.1.4}/mesa/datacollection.py

@@ -117,6 +117,9 @@ class DataCollector:
         self._agenttype_records = {}
         self.tables = {}
 
+        # add the signal of the validation of model reporter
+        self._validated = False
+
         if model_reporters is not None:
             for name, reporter in model_reporters.items():
                 self._new_model_reporter(name, reporter)
@@ -134,13 +137,66 @@ class DataCollector:
             for name, columns in tables.items():
                 self._new_table(name, columns)
 
+    def _validate_model_reporter(self, name, reporter, model):
+        """Validate model reporter and handle validation results appropriately.
+
+        Args:
+            name: Name of the reporter
+            reporter: Reporter definition (lambda/method/attribute/function list)
+            model: Model instance
+
+        Raises:
+            ValueError: If reporter is None or has invalid format
+            AttributeError: If model attribute doesn't exist
+            TypeError: If reporter type is not supported
+            RuntimeError: If reporter execution fails
+        """
+        self._validated = True  # put the change of signal firstly avoid losing efficacy
+
+        # Type 1: Lambda function
+        if isinstance(reporter, types.LambdaType):
+            try:
+                reporter(model)
+            except Exception as e:
+                raise RuntimeError(
+                    f"Lambda reporter '{name}' failed validation: {e!s}\n"
+                    f"Example: lambda m: len(m.agents)"
+                ) from e
+
+        # Type 2: Method of class/instance
+        if not callable(reporter) and not isinstance(reporter, types.LambdaType):
+            pass
+
+        # Type 3: Model attribute (string)
+        if isinstance(reporter, str):
+            try:
+                if not hasattr(model, reporter):
+                    raise AttributeError(
+                        f"Model reporter '{name}' references non-existent attribute '{reporter}'\n"
+                    )
+                getattr(model, reporter)  # 验证属性是否可访问
+            except AttributeError as e:
+                raise AttributeError(
+                    f"Model reporter '{name}' attribute validation failed: {e!s}\n"
+                ) from e
+
+        # Type 4: Function with parameters in list
+        if isinstance(reporter, list) and (not reporter or not callable(reporter[0])):
+            raise ValueError(
+                f"Invalid function list format for reporter '{name}'\n"
+                f"Expected: [function, [param1, param2]], got: {reporter}"
+            )
+
     def _new_model_reporter(self, name, reporter):
         """Add a new model-level reporter to collect.
 
         Args:
             name: Name of the model-level variable to collect.
-            reporter: Attribute string, or function object that returns the
-                      variable when given a model instance.
+            reporter: Can be one of four types:
+                1. Attribute name (str): "attribute_name"
+                2. Lambda function: lambda m: len(m.agents)
+                3. Method: model.get_count or Model.get_count
+                4. List of [function, [parameters]]
         """
         self.model_reporters[name] = reporter
         self.model_vars[name] = []
@@ -262,6 +318,10 @@ class DataCollector:
     def collect(self, model):
         """Collect all the data for the given model object."""
         if self.model_reporters:
+            if not self._validated:
+                for name, reporter in self.model_reporters.items():
+                    self._validate_model_reporter(name, reporter, model)
+
             for var, reporter in self.model_reporters.items():
                 # Check if lambda or partial function
                 if isinstance(reporter, types.LambdaType | partial):

{mesa-3.1.3 → mesa-3.1.4}/mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -1,46 +1,24 @@
-import numpy as np
-import solara
-from matplotlib.figure import Figure
-
 from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
 from mesa.visualization import Slider, SolaraViz, make_plot_component
+from mesa.visualization.components.matplotlib_components import make_mpl_space_component
+
 
+def agent_portrayal(agent):
+    return {"marker": "o", "color": "red", "size": 10}
 
-def SpaceDrawer(model):
-    def portray(g):
-        layers = {
-            "trader": {"x": [], "y": [], "c": "tab:red", "marker": "o", "s": 10},
-        }
 
-        for agent in g.all_cells.agents:
-            i, j = agent.cell.coordinate
-            layers["trader"]["x"].append(i)
-            layers["trader"]["y"].append(j)
-        return layers
+propertylayer_portrayal = {
+    "sugar": {"color": "blue", "alpha": 0.8, "colorbar": True, "vmin": 0, "vmax": 10},
+    "spice": {"color": "red", "alpha": 0.8, "colorbar": True, "vmin": 0, "vmax": 10},
+}
 
-    fig = Figure()
-    ax = fig.subplots()
-    out = portray(model.grid)
-    # Sugar
-    # Important note: imshow by default draws from upper left. You have to
-    # always explicitly specify origin="lower".
-    im = ax.imshow(
-        np.ma.masked_where(model.grid.sugar.data <= 1, model.grid.sugar.data),
-        cmap="spring",
-        origin="lower",
-    )
-    fig.colorbar(im, orientation="vertical")
-    # Spice
-    ax.imshow(
-        np.ma.masked_where(model.grid.spice.data <= 1, model.grid.spice.data),
-        cmap="winter",
-        origin="lower",
-    )
-    # Trader
-    ax.scatter(**out["trader"])
-    ax.set_axis_off()
-    return solara.FigureMatplotlib(fig)
 
+sugarscape_space = make_mpl_space_component(
+    agent_portrayal=agent_portrayal,
+    propertylayer_portrayal=propertylayer_portrayal,
+    post_process=None,
+    draw_grid=False,
+)
 
 model_params = {
     "seed": {
@@ -72,7 +50,7 @@ model = SugarscapeG1mt()
 page = SolaraViz(
     model,
     components=[
-        SpaceDrawer,
+        sugarscape_space,
         make_plot_component("#Traders"),
         make_plot_component("Price"),
     ],