Merge branch 'projectmesa:main' into enhance-datacollector-validation

projectmesa · Feb 6, 2025 · c57bf16 · c57bf16
2 parents da478fc + 061de7a
commit c57bf16
Show file tree

Hide file tree

Showing 16 changed files with 268 additions and 85 deletions.
diff --git a/.pre-commit-config.yaml b/.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: [

diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ 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

diff --git a/binder/environment.yml b/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]
diff --git a/docs/apis/visualization.md b/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}

diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -177,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.

diff --git a/docs/index.md b/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.1.x), run:
+To install our latest stable release, run:
 
 ```bash
 pip install -U mesa
@@ -54,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
 
@@ -96,4 +97,4 @@ API Documentation <apis/api_main>
 [mesa visualization tutorial]: tutorials/visualization_tutorial
 [migration guide]: migration_guide
 [Getting started]: getting_started
-
+[Mesa Extensions]: mesa_extension.md
diff --git a/docs/mesa_extension.md b/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).
+
+---
diff --git a/docs/tutorials/intro_tutorial.ipynb b/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",

diff --git a/docs/tutorials/visualization_tutorial.ipynb b/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",

diff --git a/mesa/visualization/__init__.py b/mesa/visualization/__init__.py
@@ -1,9 +1,8 @@
 """Solara based visualization for Mesa 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.
+    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.
 
-    There won't be breaking changes between Mesa 3.0.x patch releases.
 """
 
 from mesa.visualization.mpl_space_drawing import (

diff --git a/mesa/visualization/components/altair_components.py b/mesa/visualization/components/altair_components.py
@@ -1,13 +1,10 @@
 """Altair based solara components for visualization mesa spaces."""
 
-import contextlib
 import warnings
 
+import altair as alt
 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
@@ -30,7 +27,7 @@ def make_altair_space(
     Args:
         agent_portrayal: Function to portray agents.
         propertylayer_portrayal: not yet implemented
-        post_process :not yet implemented
+        post_process :A user specified callable that will be called with the Chart instance from Altair. Allows for fine tuning plots (e.g., control ticks)
         space_drawing_kwargs : not yet implemented
 
     ``agent_portrayal`` is called with an agent and should return a dict. Valid fields in this dict are "color",
@@ -46,13 +43,15 @@ def agent_portrayal(a):
             return {"id": a.unique_id}
 
     def MakeSpaceAltair(model):
-        return SpaceAltair(model, agent_portrayal)
+        return SpaceAltair(model, agent_portrayal, post_process=post_process)
 
     return MakeSpaceAltair
 
 
 @solara.component
-def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+def SpaceAltair(
+    model, agent_portrayal, dependencies: list[any] | None = None, post_process=None
+):
     """Create an Altair-based space visualization component.
 
     Returns:
@@ -65,6 +64,9 @@ def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
         space = model.space
 
     chart = _draw_grid(space, agent_portrayal)
+    # Apply post-processing if provided
+    if post_process is not None:
+        chart = post_process(chart)
     solara.FigureAltair(chart)
 
 
@@ -159,7 +161,7 @@ def _draw_grid(space, agent_portrayal):
         # no y-axis label
         "y": alt.Y("y", axis=None, type=x_y_type),
         "tooltip": [
-            alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
+            alt.Tooltip(key, type=alt.utils.infer_vegalite_type_for_pandas([value]))
             for key, value in all_agent_data[0].items()
             if key not in invalid_tooltips
         ],