docs: Update Readme and tutorial to mention Mesa 3.0 pre-releases

Note that the updated tutorials will only be pushed to the latest version of Readthedocs, not to the stable version we normally link to.

Author: EwoutH

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

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",

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",