Mesa 3.0.0b2__tar.gz → 3.0.0rc0__tar.gz

{mesa-3.0.0b2 → mesa-3.0.0rc0}/.gitignore

@@ -2,7 +2,8 @@
 benchmarks/**/*.pickle
 
 # exampledocs
-docs/examples/*.md
+docs/examples/*
+docs/example.md
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

{mesa-3.0.0b2 → mesa-3.0.0rc0}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.6.3
+  rev: v0.7.2
   hooks:
     # Run the linter.
     - id: ruff
@@ -14,12 +14,12 @@ repos:
     - id: ruff-format
       types_or: [ python, pyi, jupyter ]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.17.0
+    rev: v3.19.0
     hooks:
     -   id: pyupgrade
         args: [--py310-plus]
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0  # Use the ref you want to point at
+    rev: v5.0.0  # Use the ref you want to point at
     hooks:
     -   id: trailing-whitespace
     -   id: check-toml

{mesa-3.0.0b2 → mesa-3.0.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0b2
+Version: 3.0.0rc0
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa

mesa-3.0.0rc0/docs/apis/visualization.md

@@ -0,0 +1,47 @@
+# Visualization
+
+For a detailed tutorial, please refer to our [Visualization Tutorial](../tutorials/visualization_tutorial.ipynb).
+
+## Jupyter Visualization
+
+```{eval-rst}
+.. automodule:: mesa.visualization.solara_viz
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## User Parameters
+
+```{eval-rst}
+.. automodule:: mesa.visualization.UserParam
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Matplotlib-based visualizations
+
+```{eval-rst}
+.. automodule:: mesa.visualization.components.matplotlib_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.mpl_space_drawing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Altair-based visualizations
+
+```{eval-rst}
+.. automodule:: mesa.visualization.components.altair_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/conf.py

@@ -316,17 +316,20 @@ def setup_examples_pages():
     # create md files for all examples
     # check what examples exist
     examples_folder = osp.abspath(osp.join(HERE, "..", "mesa", "examples"))
-    basic_examples = [f.path for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() and not f.name.startswith("__") ]
-    advanced_examples = [f.path for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir() and not f.name.startswith("__")]
+    basic_examples = [("basic", f.path) for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() and not f.name.startswith("__") ]
+    advanced_examples = [("advanced", f.path) for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir() and not f.name.startswith("__")]
     examples = basic_examples + advanced_examples
 
     with open(os.path.join(HERE, "example_template.txt")) as fh:
         template = string.Template(fh.read())
 
-    pathlib.Path(os.path.join(HERE, "examples")).mkdir(parents=True, exist_ok=True)
+    root_folder = pathlib.Path(os.path.join(HERE, "examples"))
+    root_folder.mkdir(parents=True, exist_ok=True)
+    pathlib.Path(os.path.join(root_folder, "basic")).mkdir(parents=True, exist_ok=True)
+    pathlib.Path(os.path.join(root_folder, "advanced")).mkdir(parents=True, exist_ok=True)
 
     examples_md = []
-    for example in examples:
+    for kind, example in examples:
         base_name = os.path.basename(os.path.normpath(example))
 
         agent_filename = os.path.join(example, "agents.py")
@@ -337,17 +340,21 @@ def setup_examples_pages():
         md_filename = f"{base_name}.md"
         examples_md.append(base_name)
 
-        md_filepath = os.path.join(HERE, "examples", md_filename)
+        md_filepath = os.path.join(HERE, "examples", kind, md_filename)
         write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template)
 
     # create overview of examples.md
     with open(os.path.join(HERE, "examples_overview_template.txt")) as fh:
         template = string.Template(fh.read())
 
+    with open(os.path.join(examples_folder, "README.md")) as fh:
+        readme_md = fh.read()
+
     with open(os.path.join(HERE, "examples.md"), "w") as fh:
         content = template.substitute(
             dict(
-                examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
+                readme=readme_md,
+            #     examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
             )
         )
         fh.write(content)

mesa-3.0.0rc0/docs/examples_overview_template.txt

@@ -0,0 +1,3 @@
+
+$readme
+

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/index.md

@@ -20,7 +20,7 @@
 
 Mesa allows users to quickly create agent-based models using built-in core components (such as spatial grids and agent schedulers) or customized implementations; visualize them using a browser-based interface; and analyze their results using Python's data analysis tools. Its goal is to be the Python-based counterpart to NetLogo, Repast, or MASON.
 
-![A screenshot of the Wolf Sheep model in Mesa|100%](images/wolf_scheep.png)
+![A screenshot of the Wolf Sheep model in Mesa|100%](images/wolf_sheep.png)
 *A visualisation of the Wolf Sheep model build with Mesa.*
 
 ## Features
@@ -78,7 +78,6 @@ tutorials/visualization_tutorial
 Examples <examples>
 Migration guide <migration_guide>
 Best Practices <best-practices>
-How-to Guide <howto>
 API Documentation <apis/api_main>
 Mesa Packages <packages>
 ```

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/migration_guide.md

@@ -253,6 +253,8 @@ Ref: Original discussion [#1912](https://github.com/projectmesa/mesa/discussions
 Mesa has adopted a new API for our frontend. If you already migrated to the experimental new SolaraViz you can still use
 the import from mesa.experimental. Otherwise here is a list of things you need to change.
 
+> **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.
+
 #### Model Initialization
 
 Previously SolaraViz was initialized by providing a `model_cls` and a `model_params`. This has changed to expect a model instance `model`. You can still provide (user-settable) `model_params`, but only if users should be able to change them. It is now also possible to pass in a "reactive model" by first calling `model = solara.reactive(model)`. This is useful for notebook environments. It allows you to pass the model to the SolaraViz Module, but continue to use the model. For example calling `model.value.step()` (notice the extra .value) will automatically update the plots. This currently only automatically works for the step method, you can force visualization updates by calling `model.value.force_update()`.
@@ -268,9 +270,9 @@ from mesa.experimental import SolaraViz
 SolaraViz(model_cls, model_params, agent_portrayal=agent_portrayal)
 
 # new
-from mesa.visualization import SolaraViz, make_space_matplotlib
+from mesa.visualization import SolaraViz, make_space_component
 
-SolaraViz(model, components=[make_space_matplotlib(agent_portrayal)])
+SolaraViz(model, components=[make_space_component(agent_portrayal)])
 ```
 
 #### Plotting "measures"
@@ -281,15 +283,17 @@ SolaraViz(model, components=[make_space_matplotlib(agent_portrayal)])
 # old
 from mesa.experimental import SolaraViz
 
+
 def make_plot(model):
     ...
 
+
 SolaraViz(model_cls, model_params, measures=[make_plot, "foo", ["bar", "baz"]])
 
 # new
-from mesa.visualization import SolaraViz, make_plot_measure
+from mesa.visualization import SolaraViz, make_plot_component
 
-SolaraViz(model, components=[make_plot, make_plot_measure("foo"), make_plot_measure("bar", "baz")])
+SolaraViz(model, components=[make_plot, make_plot_component("foo"), make_plot_component("bar", "baz")])
 ```
 
 #### Plotting text

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/overview.md

@@ -167,12 +167,16 @@ 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. Here's a basic example of how to set up a visualization:
 
+> **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.
+
 ```python
-from mesa.visualization import SolaraViz, make_space_matplotlib, make_plot_measure
+from mesa.visualization import SolaraViz, make_space_component, make_plot_component
+
 
 def agent_portrayal(agent):
     return {"color": "blue", "size": 50}
 
+
 model_params = {
     "N": {
         "type": "SliderInt",
@@ -181,14 +185,14 @@ model_params = {
         "min": 10,
         "max": 100,
         "step": 1,
-    }
+   }
 }
 
 page = SolaraViz(
     MyModel,
     [
-        make_space_matplotlib(agent_portrayal),
-        make_plot_measure("mean_age")
+        make_space_component(agent_portrayal),
+        make_plot_component("mean_age")
     ],
     model_params=model_params
 )

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/tutorials/MoneyModel.py

@@ -49,7 +49,7 @@ class MoneyAgent(mesa.Agent):
 class MoneyModel(mesa.Model):
     """A model with some number of agents."""
 
-    def __init__(self, n, width, height, seed=None):
+    def __init__(self, n=10, width=10, height=10, seed=None):
         """Initialize a MoneyModel instance.
 
         Args:

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/tutorials/intro_tutorial.ipynb

@@ -259,7 +259,7 @@
     "\n",
     "With the basics of the Agent class and Model class created we can no activate the agents to `do` things\n",
     "\n",
-    "**Background:** Mesa's `do` function calls agent functions the grow your ABM. A step is the smallest unit of time in the model, and is often referred to as a tick. The `do` function and Python functionality can be configured to activate agents in different orders. This can be important as the order in which agents are activated can impact the results of the model [Comer2014]. At each step of the model, one or more of the agents -- usually all of them -- are activated and take their own step, changing internally and/or interacting with one another or the environment. A overview of different ways to employ the `do` function for different activation regimes can be found in the [\"How To\" Guide](https://mesa.readthedocs.io/latest/howto.html).\n",
+    "**Background:** Mesa's `do` function calls agent functions the grow your ABM. A step is the smallest unit of time in the model, and is often referred to as a tick. The `do` function and Python functionality can be configured to activate agents in different orders. This can be important as the order in which agents are activated can impact the results of the model [Comer2014]. At each step of the model, one or more of the agents -- usually all of them -- are activated and take their own step, changing internally and/or interacting with one another or the environment.\n",
     "\n",
     "**Model-specific information:** For this section we will randomly reorder the Agent activation order using  `mesa.Agent.shuffle_do` and have the agents `step` function print the agent unique id they are assigned during the agent creation process. \n",
     "\n",
@@ -1498,9 +1498,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "**note for Windows OS users:** If you are running this tutorial in Jupyter, make sure that you set `number_processes = 1` (single process). If `number_processes` is greater than 1, it is less straightforward to set up. You can read [Mesa's how-to guide](https://github.com/projectmesa/mesa/blob/main/docs/howto.md), in 'Using multi-process `batch_run` on Windows' section for how to do it."
-   ]
+   "source": "**note for Windows OS users:** If you are running this tutorial in Jupyter, make sure that you set `number_processes = 1` (single process). If `number_processes` is greater than 1, it is less straightforward to set up. For details on how to use multiprocessing on windows, see [multiprocessing's programming guidelines](https://docs.python.org/3/library/multiprocessing.html#multiprocessing-programming). "
   },
   {
    "cell_type": "code",

{mesa-3.0.0b2 → mesa-3.0.0rc0}/docs/tutorials/visualization_tutorial.ipynb

@@ -3,9 +3,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "# Visualization Tutorial"
-   ]
+   "source": "# Visualization Tutorial"
   },
   {
    "cell_type": "markdown",
@@ -13,6 +11,8 @@
    "source": [
     "*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/stable/tutorials/visualization_tutorial.html) of this tutorial on Readthedocs.*\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",
+    "\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",
     "- If you want to see the dashboard in an interactive notebook try [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/projectmesa/mesa/main?labpath=docs%2Ftutorials%2Fvisualization_tutorial.ipynb)\n",
@@ -51,34 +51,25 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 1,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Mesa version: 3.0.0b1\n"
-     ]
-    }
-   ],
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
    "source": [
     "import mesa\n",
     "print(f\"Mesa version: {mesa.__version__}\")\n",
     "\n",
-    "from mesa.visualization import SolaraViz, make_plot_measure, make_space_matplotlib\n",
+    "from mesa.visualization import SolaraViz, make_plot_component, make_space_component\n",
+    "\n",
     "# Import the local MoneyModel.py\n",
     "from MoneyModel import MoneyModel\n"
    ]
   },
   {
+   "metadata": {},
    "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
    "outputs": [],
+   "execution_count": null,
    "source": [
     "def agent_portrayal(agent):\n",
     "    return {\n",
@@ -88,17 +79,15 @@
    ]
   },
   {
-   "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": "markdown",
+   "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": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "model_params = {\n",
     "    \"n\": {\n",
@@ -115,8 +104,8 @@
    ]
   },
   {
-   "cell_type": "markdown",
    "metadata": {},
+   "cell_type": "markdown",
    "source": [
     "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",
@@ -129,18 +118,16 @@
    ]
   },
   {
+   "metadata": {},
    "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
    "outputs": [],
+   "execution_count": null,
    "source": [
     "# Create initial model instance\n",
     "model1 = MoneyModel(50, 10, 10)\n",
     "\n",
-    "SpaceGraph = make_space_matplotlib(agent_portrayal)\n",
-    "GiniPlot = make_plot_measure(\"Gini\")\n",
+    "SpaceGraph = make_space_component(agent_portrayal)\n",
+    "GiniPlot = make_plot_component(\"Gini\")\n",
     "\n",
     "page = SolaraViz(\n",
     "    model1,\n",
@@ -153,8 +140,8 @@
    ]
   },
   {
-   "cell_type": "markdown",
    "metadata": {},
+   "cell_type": "markdown",
    "source": [
     "## Part 2 - Dynamic Agent Representation \n",
     "\n",
@@ -168,24 +155,24 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "import mesa\n",
     "print(f\"Mesa version: {mesa.__version__}\")\n",
     "\n",
-    "from mesa.visualization import SolaraViz, make_plot_measure, make_space_matplotlib\n",
+    "from mesa.visualization import SolaraViz, make_plot_component, make_space_component\n",
     "# Import the local MoneyModel.py\n",
     "from MoneyModel import MoneyModel\n"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "def agent_portrayal(agent):\n",
     "    size = 10\n",
@@ -210,16 +197,16 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "# Create initial model instance\n",
     "model1 = MoneyModel(50, 10, 10)\n",
     "\n",
-    "SpaceGraph = make_space_matplotlib(agent_portrayal)\n",
-    "GiniPlot = make_plot_measure(\"Gini\")\n",
+    "SpaceGraph = make_space_component(agent_portrayal)\n",
+    "GiniPlot = make_plot_component(\"Gini\")\n",
     "\n",
     "page = SolaraViz(\n",
     "    model1,\n",
@@ -232,8 +219,8 @@
    ]
   },
   {
-   "cell_type": "markdown",
    "metadata": {},
+   "cell_type": "markdown",
    "source": [
     "## Part 3 - Custom Components \n",
     "\n",
@@ -249,10 +236,10 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "import mesa\n",
     "print(f\"Mesa version: {mesa.__version__}\")\n",
@@ -260,16 +247,16 @@
     "from matplotlib.figure import Figure\n",
     "\n",
     "from mesa.visualization.utils import update_counter\n",
-    "from mesa.visualization import SolaraViz, make_plot_measure, make_space_matplotlib\n",
+    "from mesa.visualization import SolaraViz, make_plot_component, make_space_component\n",
     "# Import the local MoneyModel.py\n",
     "from MoneyModel import MoneyModel\n"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "def agent_portrayal(agent):\n",
     "    size = 10\n",
@@ -294,17 +281,15 @@
    ]
   },
   {
-   "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "Next, we update our solara frontend to use this new component"
-   ]
+   "cell_type": "markdown",
+   "source": "Next, we update our solara frontend to use this new component"
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "@solara.component\n",
     "def Histogram(model):\n",
@@ -321,23 +306,26 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "# Create initial model instance\n",
     "model1 = MoneyModel(50, 10, 10)\n",
     "\n",
-    "SpaceGraph = make_space_matplotlib(agent_portrayal)\n",
-    "GiniPlot = make_plot_measure(\"Gini\")"
+    "SpaceGraph = make_space_component(agent_portrayal)\n",
+    "GiniPlot = make_plot_component(\"Gini\")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-10-29T19:38:49.471838Z",
+     "start_time": "2024-10-29T19:38:47.897295Z"
+    }
+   },
    "source": [
     "page = SolaraViz(\n",
     "    model1,\n",
@@ -347,7 +335,27 @@
     ")\n",
     "# This is required to render the visualization in the Jupyter notebook\n",
     "page"
-   ]
+   ],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Cannot show ipywidgets in text"
+      ],
+      "text/html": [
+       "Cannot show widget. You probably want to rerun the code cell above (<i>Click in the code cell, and press Shift+Enter <kbd>⇧</kbd>+<kbd>↩</kbd></i>)."
+      ],
+      "application/vnd.jupyter.widget-view+json": {
+       "version_major": 2,
+       "version_minor": 0,
+       "model_id": "bc71b89ee5684038a194eee4c36f4a4c"
+      }
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "execution_count": 12
   },
   {
    "cell_type": "markdown",
@@ -358,12 +366,35 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-10-29T19:38:49.505725Z",
+     "start_time": "2024-10-29T19:38:49.472599Z"
+    }
+   },
    "source": [
     "Histogram(model1)"
-   ]
+   ],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Cannot show ipywidgets in text"
+      ],
+      "text/html": [
+       "Cannot show widget. You probably want to rerun the code cell above (<i>Click in the code cell, and press Shift+Enter <kbd>⇧</kbd>+<kbd>↩</kbd></i>)."
+      ],
+      "application/vnd.jupyter.widget-view+json": {
+       "version_major": 2,
+       "version_minor": 0,
+       "model_id": "0491f167a1434a92b78535078bd082a8"
+      }
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "execution_count": 13
   },
   {
    "cell_type": "markdown",

{mesa-3.0.0b2 → mesa-3.0.0rc0}/mesa/__init__.py

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

{mesa-3.0.0b2 → mesa-3.0.0rc0}/mesa/batchrunner.py

@@ -1,4 +1,29 @@
-"""batchrunner for running a factorial experiment design over a model."""
+"""batchrunner for running a factorial experiment design over a model.
+
+To take advantage of parallel execution of experiments, `batch_run` uses
+multiprocessing if ``number_processes`` is larger than 1. It is strongly advised
+to only run in parallel using a normal python file (so don't try to do it in a
+jupyter notebook). Moreover, best practice when using multiprocessing is to
+put the code inside an ``if __name__ == '__main__':`` code black as shown below::
+
+    from mesa.batchrunner import batch_run
+
+    params = {"width": 10, "height": 10, "N": range(10, 500, 10)}
+
+    if __name__ == '__main__':
+        results = batch_run(
+            MoneyModel,
+            parameters=params,
+            iterations=5,
+            max_steps=100,
+            number_processes=None,
+            data_collection_period=1,
+            display_progress=True,
+        )
+
+
+
+"""
 
 import itertools
 import multiprocessing