Merge remote-tracking branch 'upstream/main' into move_spaces

HISTORY.md

@@ -1,6 +1,59 @@
 ---
 title: Release History
 ---
+# 3.0.0a4 (2024-09-09)
+## Highlights
+Mesa 3.0.0a4 contains two major breaking changes:
+1. The Agent's `unique_id` is now automatically assigned, so doesn't need to be passed to the Agent class anymore. In a subclassed custom Agent, like normally used, this now looks like this:
+    ```diff
+    class Wolf(Agent):
+    -    def __init__(self, unique_id, model, energy=None):
+    +    def __init__(self, model, energy=None):
+            # When initializing the super class (Agent), passing unique_id isn't needed anymore
+    -        super().__init__(unique_id, model)
+    +        super().__init__(model)
+
+    - wolf = Wolf(unique_id, model)
+    + wolf = Wolf(model)
+    ```
+    Example models were updated in [mesa-examples#194](https://github.com/projectmesa/mesa-examples/pull/194), which shows more examples on how to update existing models.
+
+2. Our visualisation API is being overhauled, to be more flexible and powerful. For more details, see [#2278](https://github.com/projectmesa/mesa/pull/2278).
+    - An initial update to the tutorial was made in [#2289](https://github.com/projectmesa/mesa/pull/2289) and is [available here](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.html).
+    - An initial example model was updated in [mesa-examples#195](https://github.com/projectmesa/mesa-examples/pull/195), and more examples will be updated in [mesa-examples#195](https://github.com/projectmesa/mesa-examples/pull/193).
+    - The old SolaraViz API is still available at `mesa.experimental`, but might be removed in future releases.
+
+Furthermore, the AgentSet has a new `agg` method to quickly get an aggerate value (for example `min_energy = model.agents.agg("energy", min)`) ([#2266](https://github.com/projectmesa/mesa/pull/2266)), The Model `get_agents_of_type` function is replaced by directly exposing the `agents_by_type` property (which can be accessed as a dict) ([#2267](https://github.com/projectmesa/mesa/pull/2267), [mesa-examples#190](https://github.com/projectmesa/mesa-examples/pull/190)) and the AgentSet get() methods can now handle missing values by replacing it with a default value ([#2279](https://github.com/projectmesa/mesa/pull/2279)).
+
+Finally, it fixes a bug in which the Grid's `move_agent_to_one_of` method with `selection="closest"` selected a location deterministically, instead of randomly ([#2118](https://github.com/projectmesa/mesa/pull/2118)).
+
+## What's Changed
+### ⚠️ Breaking changes
+* move solara_viz back to experimental by @Corvince in https://github.com/projectmesa/mesa/pull/2278
+* track unique_id automatically by @quaquel in https://github.com/projectmesa/mesa/pull/2260
+### 🎉 New features added
+* AgentSet: Add `agg` method by @EwoutH in https://github.com/projectmesa/mesa/pull/2266
+* Implement new SolaraViz API by @Corvince in https://github.com/projectmesa/mesa/pull/2263
+### 🛠 Enhancements made
+* Model: Replace `get_agents_of_type` method with `agents_by_type` property by @EwoutH in https://github.com/projectmesa/mesa/pull/2267
+* add default SolaraViz by @Corvince in https://github.com/projectmesa/mesa/pull/2280
+* Simplify ModelController by @Corvince in https://github.com/projectmesa/mesa/pull/2282
+* Add default values and missing value handling to `agentset.get` by @quaquel in https://github.com/projectmesa/mesa/pull/2279
+### 🐛 Bugs fixed
+* Fix deterministic behavior in `move_agent_to_one_of` with `selection="closest"` by @OrenBochman in https://github.com/projectmesa/mesa/pull/2118
+### 📜 Documentation improvements
+* docs: Fix Visualization Tutorial (main branch) by @EwoutH in https://github.com/projectmesa/mesa/pull/2271
+* Docs: Fix broken relative links by removing `.html` suffix by @EwoutH in https://github.com/projectmesa/mesa/pull/2274
+* Readthedocs: Don't let notebook failures pass silently by @EwoutH in https://github.com/projectmesa/mesa/pull/2276
+* Update viz tutorial to the new API by @Corvince in https://github.com/projectmesa/mesa/pull/2289
+### 🔧 Maintenance
+* Resolve multiprocessing warning, state Python 3.13 support by @rht in https://github.com/projectmesa/mesa/pull/2246
+
+## New Contributors
+* @OrenBochman made their first contribution in https://github.com/projectmesa/mesa/pull/2118
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a3...v3.0.0a4
+
 # 3.0.0a3 (2024-08-30)
 ## Highlights
 Developments toward Mesa 3.0 are steaming ahead, and our fourth alpha release is packed with features and updates - only 8 days after our third.

docs/tutorials/visualization_tutorial.ipynb

@@ -11,7 +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.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",
+    "*This version of the visualisation tutorial is updated for Mesa 3.0, and works with Mesa `3.0.0a4` 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",
@@ -21,7 +21,7 @@
     "\n",
     "So far, we've built a model, run it, and analyzed some output afterwards. However, one of the advantages of agent-based models is that we can often watch them run step by step, potentially spotting unexpected patterns, behaviors or bugs, or developing new intuitions, hypotheses, or insights. Other times, watching a model run can explain it to an unfamiliar audience better than static explanations. Like many ABM frameworks, Mesa allows you to create an interactive visualization of the model. In this section we'll walk through creating a visualization using built-in components, and (for advanced users) how to create a new visualization element.\n",
     "\n",
-    "First, a quick explanation of how Mesa's interactive visualization works. The visualization is done in a browser window, using the [Solara](https://solara.dev/) framework, a pure Python, React-style web framework. Running `solara run app.py` will launch a web server, which runs the model, and displays model detail at each step via the Matplotlib plotting library. Alternatively, you can execute everything inside a Jupyter environment."
+    "First, a quick explanation of how Mesa's interactive visualization works. The visualization is done in a browser window, using the [Solara](https://solara.dev/) framework, a pure Python, React-style web framework. Running `solara run app.py` will launch a web server, which runs the model, and displays model detail at each step via the Matplotlib plotting library. Alternatively, you can execute everything inside a notebook environment and display it inline."
    ]
   },
   {
@@ -105,7 +105,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we instantiate the visualization object which (by default) displays the grid containing the agents, and timeseries of of values computed by the model's data collector. In this example, we specify the Gini coefficient.\n",
+    "Next, we instantiate the visualization object which (by default) displays the grid containing the agents, and timeseries of values computed by the model's data collector. In this example, we specify the Gini coefficient.\n",
     "\n",
     "There are 3 buttons:\n",
     "- the step button, which advances the model by 1 step\n",
@@ -123,14 +123,19 @@
    },
    "outputs": [],
    "source": [
-    "from mesa.visualization import SolaraViz\n",
+    "from mesa.visualization import SolaraViz, make_plot_measure, make_space_matplotlib\n",
+    "\n",
+    "# Create initial model instance\n",
+    "model1 = BoltzmannWealthModel(50, 10, 10)\n",
+    "\n",
+    "SpaceGraph = make_space_matplotlib(agent_portrayal)\n",
+    "GiniPlot = make_plot_measure(\"Gini\")\n",
     "\n",
     "page = SolaraViz(\n",
-    "    BoltzmannWealthModel,\n",
-    "    model_params,\n",
-    "    measures=[\"Gini\"],\n",
-    "    name=\"Money Model\",\n",
-    "    agent_portrayal=agent_portrayal,\n",
+    "    model1,\n",
+    "    components=[SpaceGraph, GiniPlot],\n",
+    "    model_params=model_params,\n",
+    "    name=\"Boltzmann Wealth Model\",\n",
     ")\n",
     "# This is required to render the visualization in the Jupyter notebook\n",
     "page"
@@ -170,11 +175,10 @@
    "outputs": [],
    "source": [
     "page = SolaraViz(\n",
-    "    BoltzmannWealthModel,\n",
-    "    model_params,\n",
-    "    measures=[\"Gini\"],\n",
-    "    name=\"Money Model\",\n",
-    "    agent_portrayal=agent_portrayal,\n",
+    "    model1,\n",
+    "    components=[SpaceGraph, GiniPlot],\n",
+    "    model_params=model_params,\n",
+    "    name=\"Boltzmann Wealth Model\",\n",
     ")\n",
     "# This is required to render the visualization in the Jupyter notebook\n",
     "page"
@@ -202,8 +206,8 @@
     "import solara\n",
     "from matplotlib.figure import Figure\n",
     "\n",
-    "\n",
-    "def make_histogram(model):\n",
+    "@solara.component\n",
+    "def Histogram(model):\n",
     "    # Note: you must initialize a figure using this method instead of\n",
     "    # plt.figure(), for thread safety purpose\n",
     "    fig = Figure()\n",
@@ -219,7 +223,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we reinitialize the visualization object, but this time with the histogram (see the measures argument)."
+    "In a notebook environment we can directly display the visualization by calling it with the model instance"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Histogram(model1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, we update our solara frontend to use this new component"
    ]
   },
   {
@@ -229,11 +249,10 @@
    "outputs": [],
    "source": [
     "page = SolaraViz(\n",
-    "    BoltzmannWealthModel,\n",
-    "    model_params,\n",
-    "    measures=[\"Gini\", make_histogram],\n",
-    "    name=\"Money Model\",\n",
-    "    agent_portrayal=agent_portrayal,\n",
+    "    model1,\n",
+    "    components=[SpaceGraph, GiniPlot, Histogram],\n",
+    "    model_params=model_params,\n",
+    "    name=\"Boltzmann Wealth Model\",\n",
     ")\n",
     "# This is required to render the visualization in the Jupyter notebook\n",
     "page"

mesa/__init__.py

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