Initialize Solara-based adv_tutorial

.readthedocs.yml

@@ -12,9 +12,13 @@ sphinx:
 formats:
   - pdf
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.9"
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: "3.8"
   install:
     - method: pip
       path: .

docs/index.rst

@@ -55,13 +55,13 @@ To launch an example model, clone the `repository <https://github.com/projectmes
 For more help on using Mesa, check out the following resources:
 
 * `Mesa Introductory Tutorial`_
-* `Mesa Advanced Tutorial`_
+* `Mesa Visualization Tutorial`_
 * `GitHub Issue Tracker`_
 * `Email list`_
 * `PyPI`_
 
 .. _`Mesa Introductory Tutorial` : tutorials/intro_tutorial.html
-.. _`Mesa Advanced Tutorial` : tutorials/adv_tutorial.html
+.. _`Mesa Visualization Tutorial` : tutorials/visualization_tutorial.html
 .. _`GitHub Issue Tracker` : https://github.com/projectmesa/mesa/issues
 .. _`Email list` : https://groups.google.com/d/forum/projectmesa
 .. _`PyPI` : https://pypi.python.org/pypi/Mesa/
@@ -96,11 +96,12 @@ ABM features users have shared that you may want to use in your model
 
    Mesa Overview <overview>
    tutorials/intro_tutorial.ipynb
-   tutorials/adv_tutorial.ipynb
+   tutorials/visualization_tutorial.ipynb
    Best Practices <best-practices>
    Useful Snippets <useful-snippets/snippets>
    API Documentation <apis/api_main>
    Mesa Packages <packages>
+   tutorials/adv_tutorial_legacy.ipynb
 
 Indices and tables
 ==================

docs/tutorials/adv_tutorial.ipynb → docs/tutorials/adv_tutorial_legacy.ipynb

@@ -4,7 +4,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Advanced Tutorial"
+    "# Advanced Tutorial\n",
+    "This is the legacy version of the advanced tutorial. We recommend you to read the newer (current) version because it is easier."
    ]
   },
   {

docs/tutorials/visualization_tutorial.ipynb

@@ -0,0 +1,269 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Visualization Tutorial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We recommend to execute this tutorial online in a Colab notebook, so that you can explore the visualization output: [![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",
+    "\n",
+    "### Adding visualization\n",
+    "\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."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Grid Visualization\n",
+    "\n",
+    "To start with, let's have a visualization where we can watch the agents moving around the grid. Let us use the same `MoneyModel` created in the [Introductory Tutorial](https://mesa.readthedocs.io/en/main/tutorials/intro_tutorial.html), which is already available when you install Mesa, but named as BoltzmannWealthModel.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "%pip install --quiet mesa\n",
+    "import mesa\n",
+    "\n",
+    "# The Boltzmann wealth model (money model) is already included in Mesa library\n",
+    "from mesa_models.boltzmann_wealth_model.model import BoltzmannWealthModel"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Mesa's grid visualizer works by looping over every cell in a grid, and generating a portrayal for every agent it finds. A portrayal is a dictionary (which can easily be turned into a JSON object) which tells Matplotlib the color and size of the scatterplot markers (each signifying an agent). The only thing we need to provide is a function which takes an agent, and returns a portrayal dictionary. Here's the simplest one: it'll draw each agent as a blue, filled circle, with a radius size of 50."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "def agent_portrayal(agent):\n",
+    "    return {\n",
+    "        \"color\": \"tab:blue\",\n",
+    "        \"size\": 50,\n",
+    "    }"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In addition to the portrayal method, we instantiate the model parameters, some of which are modifiable by user inputs. In this case, the number of agents, N, is specified as a slider of integers."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_params = {\n",
+    "    \"N\": {\n",
+    "        \"type\": \"SliderInt\",\n",
+    "        \"value\": 50,\n",
+    "        \"label\": \"Number of agents:\",\n",
+    "        \"min\": 10,\n",
+    "        \"max\": 100,\n",
+    "        \"step\": 1,\n",
+    "    },\n",
+    "    \"width\": 10,\n",
+    "    \"height\": 10,\n",
+    "}"
+   ]
+  },
+  {
+   "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",
+    "\n",
+    "There are 3 buttons:\n",
+    "- the step button, which advances the model by 1 step\n",
+    "- the play button, which advances the model indefinitely until it is paused, or until `model.running` is False (you may specify the stopping condition)\n",
+    "- the pause button, which pauses the model\n",
+    "\n",
+    "To reset the model, simply change the model parameter from the user input (e.g. the \"Number of agents\" slider)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "from mesa_models.experimental import JupyterViz\n",
+    "\n",
+    "page = JupyterViz(\n",
+    "    BoltzmannWealthModel,\n",
+    "    model_params,\n",
+    "    measures=[\"Gini\"],\n",
+    "    name=\"Money Model\",\n",
+    "    agent_portrayal=agent_portrayal,\n",
+    ")\n",
+    "# This is required to render the visualization in the Jupyter notebook\n",
+    "page"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "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",
+    "\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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def agent_portrayal(agent):\n",
+    "    size = 10\n",
+    "    color = \"tab:red\"\n",
+    "    if agent.wealth > 0:\n",
+    "        size = 50\n",
+    "        color = \"tab:blue\"\n",
+    "    return {\"size\": size, \"color\": color}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "page = JupyterViz(\n",
+    "    BoltzmannWealthModel,\n",
+    "    model_params,\n",
+    "    measures=[\"Gini\"],\n",
+    "    name=\"Money Model\",\n",
+    "    agent_portrayal=agent_portrayal,\n",
+    ")\n",
+    "# This is required to render the visualization in the Jupyter notebook\n",
+    "page"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Building your own visualization component\n",
+    "\n",
+    "**Note:** This section is for users who have a basic familiarity with Python's Matplotlib plotting library.\n",
+    "\n",
+    "If the visualization elements provided by Mesa aren't enough for you, you can build your own and plug them into the model server.\n",
+    "\n",
+    "For this example, let's build a simple histogram visualization, which can count the number of agents with each value of wealth."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import solara\n",
+    "from matplotlib.figure import Figure\n",
+    "\n",
+    "\n",
+    "def make_histogram(viz):\n",
+    "    # Note: you must initialize a figure using this method instead of\n",
+    "    # plt.figure(), for thread safety purpose\n",
+    "    fig = Figure()\n",
+    "    ax = fig.subplots()\n",
+    "    wealth_vals = [agent.wealth for agent in viz.model.schedule.agents]\n",
+    "    # Note: you have to use Matplotlib's OOP API instead of plt.hist\n",
+    "    # because plt.hist is not thread-safe.\n",
+    "    ax.hist(wealth_vals, bins=10)\n",
+    "    # You have to specify the dependencies as follows, so that the figure\n",
+    "    # auto-updates when viz.model or viz.df is changed.\n",
+    "    solara.FigureMatplotlib(fig, dependencies=[viz.model, viz.df])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, we reinitialize the visualization object, but this time with the histogram (see the measures argument)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "page = JupyterViz(\n",
+    "    BoltzmannWealthModel,\n",
+    "    model_params,\n",
+    "    measures=[\"Gini\", make_histogram],\n",
+    "    name=\"Money Model\",\n",
+    "    agent_portrayal=agent_portrayal,\n",
+    ")\n",
+    "# This is required to render the visualization in the Jupyter notebook\n",
+    "page"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Happy Modeling!\n",
+    "\n",
+    "This document is a work in progress.  If you see any errors, exclusions or have any problems please contact [us](https://github.com/projectmesa/mesa/issues)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  },
+  "nbsphinx": {
+   "execute": "never"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

setup.py

@@ -8,7 +8,16 @@
 
 from setuptools import find_packages, setup
 
-requires = ["click", "cookiecutter", "networkx", "numpy", "pandas", "tornado", "tqdm"]
+requires = [
+    "click",
+    "cookiecutter",
+    "networkx",
+    "numpy",
+    "pandas",
+    "tornado",
+    "tqdm",
+    "mesa-models @ git+https://github.com/projectmesa/mesa-examples@db2ec0383eb3b1868e91c828101e84cce97bbb63",
+]
 
 extras_require = {
     "dev": [