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

.gitignore

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

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)

docs/examples_overview_template.txt

@@ -1,10 +1,3 @@
 
-# Examples
+$readme
 
-
-```{toctree}
-:maxdepth: 1
-
-$examples
-
-```

docs/index.md

@@ -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>
 ```

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/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

mesa/examples/README.md

@@ -1,37 +1,37 @@
 # Mesa core examples
-This folder contains a collection of example models built using Mesa. These core models are maintained by the Mesa team and are intended to demonstrate the capabilities of Mesa.
+These examples are a collection of classic agent based models built using Mesa. These core examples are maintained by the Mesa team and are intended to demonstrate the capabilities of Mesa.
 
 More user examples and showcases can be found in the [mesa-examples](https://github.com/projectmesa/mesa-examples) repository.
 
 ## Basic Examples
 The basic examples are relatively simple and only use stable Mesa features. They are good starting points for learning how to use Mesa.
 
-### [Boltzmann Wealth Model](basic/boltzmann_wealth_model)
+### [Boltzmann Wealth Model](examples/basic/boltzmann_wealth_model)
 Completed code to go along with the [tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
 
-### [Boids Flockers Model](basic/boid_flockers)
+### [Boids Flockers Model](examples/basic/boid_flockers)
 [Boids](https://en.wikipedia.org/wiki/Boids)-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.
 
-### [Conway's Game of Life](basic/conways_game_of_life)
+### [Conway's Game of Life](examples/basic/conways_game_of_life)
 Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life), a cellular automata where simple rules can give rise to complex patterns.
 
-### [Schelling Segregation Model](basic/schelling)
+### [Schelling Segregation Model](examples/basic/schelling)
 Mesa implementation of the classic [Schelling segregation](http://nifty.stanford.edu/2014/mccown-schelling-model-segregation/) model.
 
-### [Virus on a Network Model](basic/virus_on_network)
+### [Virus on a Network Model](examples/basic/virus_on_network)
 This model is based on the NetLogo [Virus on a Network](https://ccl.northwestern.edu/netlogo/models/VirusonaNetwork) model.
 
 ## Advanced Examples
 The advanced examples are more complex and may use experimental Mesa features. They are good starting points for learning how to build more complex models.
 
-### [Epstein Civil Violence Model](advanced/epstein_civil_violence)
-Joshua Epstein's [model](http://www.uvm.edu/~pdodds/files/papers/others/2002/epstein2002a.pdf) of how a decentralized uprising can be suppressed or reach a critical mass of support.
+### [Epstein Civil Violence Model](examples/advanced/epstein_civil_violence)
+Joshua Epstein's [model](https://www.pnas.org/doi/10.1073/pnas.092080199) of how a decentralized uprising can be suppressed or reach a critical mass of support.
 
-### [Demographic Prisoner's Dilemma on a Grid](advanced/pd_grid)
+### [Demographic Prisoner's Dilemma on a Grid](examples/advanced/pd_grid)
 Grid-based demographic prisoner's dilemma model, demonstrating how simple rules can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
 
-### [Sugarscape Model with Traders](advanced/sugarscape_g1mt)
+### [Sugarscape Model with Traders](examples/advanced/sugarscape_g1mt)
 This is Epstein & Axtell's Sugarscape model with Traders, a detailed description is in Chapter four of *Growing Artificial Societies: Social Science from the Bottom Up (1996)*. The model shows how emergent price equilibrium can happen via decentralized dynamics.
 
-### [Wolf-Sheep Predation Model](advanced/wolf_sheep)
+### [Wolf-Sheep Predation Model](examples/advanced/wolf_sheep)
 Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation) model.