Mesa 3.0.0b0__tar.gz → 3.0.0b2__tar.gz

mesa-3.0.0b2/.github/pull_request_template.md

@@ -0,0 +1,4 @@
+Thanks for opening a PR! Please click the `Preview` tab and select a PR template:
+
+- [🐛 Bug fix](?expand=1&template=bug.md)
+- [🛠 Feature/enhancement](?expand=1&template=feature.md)

{mesa-3.0.0b0 → mesa-3.0.0b2}/.github/release.yml

@@ -19,6 +19,9 @@ changelog:
     - title: 🐛 Bugs fixed
       labels:
         - bug
+    - title: 🔍 Examples updated
+      labels:
+        - example
     - title: 📜 Documentation improvements
       labels:
         - docs

{mesa-3.0.0b0 → mesa-3.0.0b2}/.github/workflows/benchmarks.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: '3.13'
       - name: Add project directory to PYTHONPATH
         run: echo "PYTHONPATH=$PYTHONPATH:$(pwd)" >> $GITHUB_ENV
       - name: Install dependencies

{mesa-3.0.0b0 → mesa-3.0.0b2}/.github/workflows/build_lint.yml

@@ -31,10 +31,10 @@ jobs:
       fail-fast: False
       matrix:
         os: [windows, ubuntu, macos]
-        python-version: ["3.12"]
+        python-version: ["3.13"]
         include:
           - os: ubuntu
-            python-version: "3.13"
+            python-version: "3.12"
           - os: ubuntu
             python-version: "3.11"
           - os: ubuntu
@@ -60,6 +60,9 @@ jobs:
     - if: matrix.os == 'ubuntu'
       name: Codecov
       uses: codecov/codecov-action@v4
+      with:
+        fail_ci_if_error: true
+        token: ${{ secrets.CODECOV_TOKEN }}
 
   examples:
     runs-on: ubuntu-latest
@@ -68,7 +71,8 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.12"
+        python-version: "3.13"
+        allow-prereleases: true
         cache: 'pip'
     - name: Install uv
       run: pip install uv

{mesa-3.0.0b0 → mesa-3.0.0b2}/.github/workflows/release.yml

@@ -32,7 +32,8 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
+          allow-prereleases: true
           cache: 'pip'
       - name: Install dependencies
         run: pip install -U pip hatch

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

@@ -1,6 +1,9 @@
 # Benchmarking
 benchmarks/**/*.pickle
 
+# exampledocs
+docs/examples/*.md
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

{mesa-3.0.0b0 → mesa-3.0.0b2}/CONTRIBUTING.md

@@ -119,6 +119,24 @@ ruff .
 
 The license of this project is located in [LICENSE].  By submitting a contribution to this project, you are agreeing that your contribution will be released under the terms of this license.
 
+## Maintainers
+Some notes useful for Mesa maintainers.
+
+### Releases
+To create a new release, follow these steps:
+
+1. Ensure all pull requests (PRs) have a clear title and are labeled with at least one label. Check [this link](https://github.com/projectmesa/mesa/pulls?q=is%3Apr+is%3Amerged+no%3Alabel+merged%3A%3E%3D2024-03-01+) to see if all PRs are labeled. These labels will be used when drafting the changelog using the [`.github/release.yml`](https://github.com/projectmesa/mesa/blob/main/.github/release.yml) configuration.
+2. Navigate to the [Releases](https://github.com/projectmesa/mesa/releases) section in the GitHub UI and click the _Draft a new release_ button.
+3. Specify the upcoming tag in the _Choose a tag_ and _Release title_ fields (e.g., `v3.0.0`).
+   - For pre-releases, add a `a`, `b` or `rc` and a number behind the version tag (see [Versioning](https://packaging.python.org/en/latest/discussions/versioning/)), and check the box _Set as a pre-release_.
+4. Use the _Generate release notes_ button to automatically create release notes. Review them carefully for accuracy, and update labels and edit PR titles if necessary (step 1).
+5. Write a _Highlights_ section summarizing the most important features or changes in this release.
+6. Copy the release notes and save them by clicking the grey _Save draft_ button.
+7. Open a new PR to update the version number in [`mesa/__init__.py`](https://github.com/projectmesa/mesa/blob/main/mesa/__init__.py) and add the copied release notes to the [`HISTORY.md`](https://github.com/projectmesa/mesa/blob/main/HISTORY.md).
+8. Once this PR is merged, return to the _Releases_ section and publish the draft release.
+9. The [`release.yml`](https://github.com/projectmesa/mesa/blob/main/.github/workflows/release.yml) CI workflow should automatically create and upload the package to PyPI. Verify this on [PyPI.org](https://pypi.org/project/mesa/).
+10. Finally, after release, open a new PR to update the version number in [`mesa/__init__.py`](https://github.com/projectmesa/mesa/blob/main/mesa/__init__.py) for the next release (e.g., `"3.1.0.dev"`).
+
 ## Special Thanks
 
 A special thanks to the following projects who offered inspiration for this contributing file.

{mesa-3.0.0b0 → mesa-3.0.0b2}/HISTORY.md

@@ -1,6 +1,108 @@
 ---
 title: Release History
 ---
+# 3.0.0b2 (2024-10-26)
+## Highlights
+Mesa 3.0 beta 2 includes major work on the example models, docs, a new tutorial and visualisation.
+
+The included example models are now part of the Mesa package itself and directly importable, using:
+```Python
+from mesa.examples import BoidFlockers, BoltzmannWealthModel, ConwaysGameOfLife, ...
+```
+The advanced examples were also restructured and cleaned up.
+
+The tutorial was completely rewritten for Mesa 3.0, including it's latest features and practices. Many of our other docs also received some love, and almost everything is now ready for Mesa 3.0.
+
+A new feature to remove all agents from the model was added, and the visualisation now supports drawing the experimental discrete spaces in both matplotlib and altair. All agents which are in a space can now conveniently be accessed with `.agents`.
+
+The rarely used `mesa startproject` cookiecutter feature was removed. We updated our best-practice guide to include how to structure a modern Mesa project, which is now very straightforward.
+
+## What's Changed
+### ⚠️ Breaking changes
+* remove cookiecutter by @quaquel in https://github.com/projectmesa/mesa/pull/2421
+### 🧪 Experimental features
+* Add support for drawing discrete grids by @quaquel in https://github.com/projectmesa/mesa/pull/2386
+* Altair spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2397
+### 🎉 New features added
+* remove_all_agents method added to model by @quaquel in https://github.com/projectmesa/mesa/pull/2394
+* Pass through model.rgn in agent analogous to model.random by @quaquel in https://github.com/projectmesa/mesa/pull/2400
+* add agents property to all spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2418
+### 🛠 Enhancements made
+* update_tutorial environment by @tpike3 in https://github.com/projectmesa/mesa/pull/2411
+### 🐛 Bugs fixed
+* Fix for mistaken removal of _draw_grid by @quaquel in https://github.com/projectmesa/mesa/pull/2398
+* fixes weakref bug in shuffe_do by @quaquel in https://github.com/projectmesa/mesa/pull/2399
+### 🔍 Examples updated
+* refactor: Simplify Schelling code by @rht in https://github.com/projectmesa/mesa/pull/2353
+* Move examples into mesa by @Corvince in https://github.com/projectmesa/mesa/pull/2387
+* Explicitly test basic examples by @quaquel in https://github.com/projectmesa/mesa/pull/2390
+* Make example import absolute by @quaquel in https://github.com/projectmesa/mesa/pull/2402
+* Cleanup and restructure EpsteinCivilViolence and PdGrid examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2408
+* Reorganize advanced examples: wolf_sheep and sugarscape_g1mt by @quaquel in https://github.com/projectmesa/mesa/pull/2410
+* reactivate ruff for advanced examples and include them in tests by @quaquel in https://github.com/projectmesa/mesa/pull/2414
+### 📜 Documentation improvements
+* Include examples in readthedocs (port) by @EwoutH in https://github.com/projectmesa/mesa/pull/2392
+* Update into_tutorial by @tpike3 in https://github.com/projectmesa/mesa/pull/2372
+* Update Schelling Readme.md by @quaquel in https://github.com/projectmesa/mesa/pull/2406
+* Update Conway example by @quaquel in https://github.com/projectmesa/mesa/pull/2403
+* Boltzman readme by @quaquel in https://github.com/projectmesa/mesa/pull/2405
+* Update Readme.md of Boid flockers by @quaquel in https://github.com/projectmesa/mesa/pull/2404
+* add advanced examples to rtd by @quaquel in https://github.com/projectmesa/mesa/pull/2413
+* Tutorial Improvements by @tpike3 in https://github.com/projectmesa/mesa/pull/2415
+* space: Add note that Grids are maintenance only by @EwoutH in https://github.com/projectmesa/mesa/pull/2420
+* Migration guide: Update automatic unique_id assignment examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2419
+* Update docstring of SimEvent by @quaquel in https://github.com/projectmesa/mesa/pull/2417
+* best-practices: Update Model Layout section by @EwoutH in https://github.com/projectmesa/mesa/pull/2424
+* docs: Clean-up index.md by @EwoutH in https://github.com/projectmesa/mesa/pull/2422
+### 🔧 Maintenance
+* Add empty `pull_request_template.md` to enable PR template chooser by @EwoutH in https://github.com/projectmesa/mesa/pull/2409
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0b1...v3.0.0b2
+
+# 3.0.0b1 (2024-10-17)
+## Highlights
+Mesa 3.0 beta 1 is our last beta release before the Mesa 3.0 stable release. We are restructuring our examples and have move 9 core examples from [mesa-examples](https://github.com/projectmesa/mesa-examples) to mesa itself ([#2358](https://github.com/projectmesa/mesa/pull/2358)). The 5 basic examples are now directly importable ([#2381](https://github.com/projectmesa/mesa/pull/2381)):
+```Python
+from examples.basic import BoidFlockers, BoltzmannWealthModel, ConwaysGameOfLife, Schelling, VirusOnNetwork
+```
+The 5 basic examples will always use stable Mesa features, we are also working on 4 more advanced example which can also include experimental features.
+
+All our core examples can now be viewed in the [`examples`](https://github.com/projectmesa/mesa/tree/main/examples) folder. [mesa-examples](https://github.com/projectmesa/mesa-examples) will continue to exists for user showcases. We're also working on making the examples visible in the ReadtheDocs ([#2382](https://github.com/projectmesa/mesa/pull/2382)) and on an website ([mesa-examples#139](https://github.com/projectmesa/mesa-examples/issues/139)). Follow all our work on the examples in this tracking issue [#2364](https://github.com/projectmesa/mesa/issues/2364).
+
+Furthermore, the visualizations are improved by making visualization elements scalable and more clearly labeling the plots, and the Model now has an `rng` argument for an [SPEC 7](https://scientific-python.org/specs/spec-0007/) compliant NumPy random number generator ([#2352](https://github.com/projectmesa/mesa/pull/2352)). Following SPEC 7, you have to pass either `seed` or `rng`. Whichever one you pass will be used to seed both `random.Random`, and `numpy.random.Generator.`
+
+## What's Changed
+### ⚠️ Breaking changes
+* replace model with random in AgentSet init by @quaquel in https://github.com/projectmesa/mesa/pull/2350
+### 🧪 Experimental features
+* cell space: Add convenience properties for grid width and height by @quaquel in https://github.com/projectmesa/mesa/pull/2348
+* Bugfix for deepcopy / pickling discrete spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2378
+### 🎉 New features added
+* Move core example models back (v2) by @EwoutH in https://github.com/projectmesa/mesa/pull/2358
+* Add Model.rng for SPEC-7 compliant numpy random number generation by @quaquel in https://github.com/projectmesa/mesa/pull/2352
+### 🛠 Enhancements made
+* use GridDraggable instead of Column in SolaraViz by @wang-boyu in https://github.com/projectmesa/mesa/pull/2344
+* update legend, xlabel & format of matplotlib plots by @wang-boyu in https://github.com/projectmesa/mesa/pull/2346
+* __init__.py: Import mesa.experimental by @EwoutH in https://github.com/projectmesa/mesa/pull/2374
+* Importable examples by @Corvince in https://github.com/projectmesa/mesa/pull/2381
+### 🐛 Bugs fixed
+* experimental init: Fix Solara import by making it lazy by @EwoutH in https://github.com/projectmesa/mesa/pull/2357
+* fix: pass `model.random` to schedulers by @quaquel in https://github.com/projectmesa/mesa/pull/2359
+* fix: register agent after creating unique_id and pos attributes by @wang-boyu in https://github.com/projectmesa/mesa/pull/2368
+* solara: viz tutorial: fix histogram code by @Corvince in https://github.com/projectmesa/mesa/pull/2379
+### 🔍 Examples updated
+* Cleanup and restructure basic example models by @EwoutH in https://github.com/projectmesa/mesa/pull/2365
+* Ruff basic examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2370
+### 📜 Documentation improvements
+* Update migration_guide.md by @quaquel in https://github.com/projectmesa/mesa/pull/2347
+### 🔧 Maintenance
+* Code coverage: ignore experimental and visualization by @Corvince in https://github.com/projectmesa/mesa/pull/2361
+* add codecov token, fixes #2363 by @Corvince in https://github.com/projectmesa/mesa/pull/2366
+* add test_time back by @quaquel in https://github.com/projectmesa/mesa/pull/2367
+* Release notes: Add example category by @EwoutH in https://github.com/projectmesa/mesa/pull/2369
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0b0...v3.0.0b1
+
 # 3.0.0b0 (2024-10-04)
 ## Highlights
 We're proud to release the first Mesa 3.0 beta! This pre-release announces that we're ready for Mesa 3.0 to be tested by all our regular users. We try to not making breaking changes anymore, but focus on resolving bugs and imperfections.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0b0
+Version: 3.0.0b2
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -27,7 +27,6 @@ Requires-Dist: numpy
 Requires-Dist: pandas
 Requires-Dist: tqdm
 Provides-Extra: all
-Requires-Dist: cookiecutter; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
 Requires-Dist: matplotlib; extra == 'all'
 Requires-Dist: myst-nb; extra == 'all'
@@ -43,7 +42,6 @@ Requires-Dist: seaborn; extra == 'all'
 Requires-Dist: solara; extra == 'all'
 Requires-Dist: sphinx; extra == 'all'
 Provides-Extra: dev
-Requires-Dist: cookiecutter; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
 Requires-Dist: networkx; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'

{mesa-3.0.0b0 → mesa-3.0.0b2}/benchmarks/BoltzmannWealth/boltzmann_wealth.py

@@ -70,7 +70,7 @@ class BoltzmannWealth(mesa.Model):
             n: the number of steps for which to run the model
 
         """
-        for _i in range(n):
+        for _ in range(n):
             self.step()
 
 

{mesa-3.0.0b0 → mesa-3.0.0b2}/benchmarks/Schelling/schelling.py

@@ -34,11 +34,10 @@ class SchellingAgent(CellAgent):
 
     def step(self):
         """Run one step of the agent."""
-        similar = 0
-        neighborhood = self.cell.get_neighborhood(radius=self.radius)
-        for neighbor in neighborhood.agents:
-            if neighbor.type == self.type:
-                similar += 1
+        neighbors = self.cell.get_neighborhood(radius=self.radius).agents
+        similar = len(
+            [neighbor for neighbor in neighbors if neighbor.type == self.type]
+        )
 
         # If unhappy, move:
         if similar < self.homophily:
@@ -76,7 +75,6 @@ class Schelling(Model):
         """
         super().__init__(seed=seed)
         self.simulator = simulator
-        self.minority_pc = minority_pc
         self.happy = 0
 
         self.grid = OrthogonalMooreGrid(
@@ -92,7 +90,7 @@ class Schelling(Model):
         # its contents. (coord_iter)
         for cell in self.grid:
             if self.random.random() < density:
-                agent_type = 1 if self.random.random() < self.minority_pc else 0
+                agent_type = 1 if self.random.random() < minority_pc else 0
                 SchellingAgent(self, agent_type, radius, homophily, cell)
 
     def step(self):

mesa-3.0.0b2/binder/environment.yml

@@ -0,0 +1,14 @@
+name: example-environment
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - numpy
+  - pip
+  - pip:
+    - nbgitpuller
+    - pandas
+    - matplotlib
+    - seaborn
+    - solara
+    - mesa[rec]==3.0.0b1

{mesa-3.0.0b0 → mesa-3.0.0b2}/codecov.yaml

@@ -2,11 +2,12 @@ coverage:
   status:
     project:
       default:
-        target: 90%
+        target: 80%
         threshold: 1%
 
 ignore:
-  - "**experimental/"
   - "benchmarks/**"
+  - "mesa/experimental/**"
+  - "mesa/visualization/**"
 
 comment: off

{mesa-3.0.0b0 → mesa-3.0.0b2}/docs/README.md

@@ -1,15 +1,14 @@
-Docs for Mesa
-=============
+# Docs for Mesa
 
 The readable version of the docs is hosted at [mesa.readthedocs.org](http://mesa.readthedocs.org/).
 
 This folder contains the docs that build the docs for the core mesa code on readthdocs.
 
-### How to publish updates to the docs
+## How to publish updates to the docs
 
 Updating docs can be confusing. Here are the basic setups.
 
-##### Submit a pull request with updates
+#### Submit a pull request with updates
 1. Create branch (either via branching or fork of repo) -- try to use a descriptive name.
     * `git checkout -b doc-updates`
 1. Update the docs. Save.
@@ -23,7 +22,7 @@ Updating docs can be confusing. Here are the basic setups.
     * `git push origin doc-updates`
 1. From here you will want to submit a pull request to main.
 
-##### Update read the docs
+#### Update read the docs
 
 From this point, you will need to find someone that has access to readthedocs. Currently, that is [@jackiekazil](https://github.com/jackiekazil), [@rht](https://github.com/rht), and [@tpike3](https://github.com/dmasad).
 

{mesa-3.0.0b0 → mesa-3.0.0b2}/docs/apis/experimental.md

@@ -3,11 +3,6 @@ This namespace contains experimental features. These are under development, and
 
 ## Cell Space
 
-```{eval-rst}
-.. automodule:: experimental.cell_space.__init__
-   :members:
-```
-
 ```{eval-rst}
 .. automodule:: experimental.cell_space.cell
    :members:
@@ -40,11 +35,6 @@ This namespace contains experimental features. These are under development, and
 
 ## Devs
 
-```{eval-rst}
-.. automodule:: experimental.devs.__init__
-   :members:
-```
-
 ```{eval-rst}
 .. automodule:: experimental.devs.eventlist
    :members:

{mesa-3.0.0b0 → mesa-3.0.0b2}/docs/best-practices.md

@@ -5,26 +5,21 @@ Here are some general principles that have proven helpful for developing models.
 ## Model Layout
 
 A model should be contained in a folder named with lower-case letters and
-underscores, such as `thunder_cats`. Within that directory:
-
-- `README.md` describes the model, how to use it, and any other details.
-  Github will automatically show this file to anyone visiting the directory.
-- `model.py` should contain the model class.  If the file gets large, it may
-  make sense to move the complex bits into other files, but this is the first
-  place readers will look to figure out how the model works.
-- `server.py` should contain the visualization support, including the server
-  class.
-- `run.py` is a Python script that will run the model when invoked via
-  `mesa runserver`.
-
-After the number of files grows beyond a half-dozen, try to use sub-folders to
-organize them. For example, if the visualization uses image files, put those in
-an `images` directory.
-
-The [Schelling](https://github.com/projectmesa/mesa-examples/tree/main/examples/schelling) model is
-a good example of a small well-packaged model.
-
-It's easy to create a cookiecutter mesa model by running `mesa startproject`
+underscores, such as `wolf_sheep`. Within that directory:
+
+- `Readme.md` describes the model, how to use it, and any other details.
+- `model.py` should contain the model class.
+- `agents.py` should contain the agent class(es).
+- `app.py` should contain the Solara-based visualization code (optional).
+
+You can add more files as needed, for example:
+- `run.py` could contain the code to run the model.
+- `batch_run.py` could contain the code to run the model multiple times.
+- `analysis.py` could contain any analysis code.
+
+Input data can be stored in a `data` directory, output data in an `output`, processed results in a `results` directory, images in an `images` directory, etc.
+
+All our [examples](examples) follow this layout.
 
 ## Randomization
 

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

@@ -14,14 +14,17 @@
 # serve to show the default.
 
 import os
+import os.path as osp
+import pathlib
 import sys
+import string
 from datetime import date
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
+HERE = osp.abspath(osp.dirname(__file__))
 sys.path.insert(0, os.path.abspath("."))
-sys.path.insert(0, "../examples")
 sys.path.insert(0, "../mesa")
 
 
@@ -289,3 +292,69 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+
+
+def write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template):
+    with open(agent_filename) as content_file:
+        agent_file = content_file.read()
+    with open(model_filename) as content_file:
+        model_file = content_file.read()
+    with open(readme_filename) as content_file:
+        readme_file = content_file.read()
+    with open(app_filename) as content_file:
+        app_file = content_file.read()
+
+    with open(md_filepath, "w") as fh:
+        content = template.substitute(
+            dict(agent_file=agent_file, model_file=model_file,
+                 readme_file=readme_file, app_file=app_file)
+        )
+        fh.write(content)
+
+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("__")]
+    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)
+
+    examples_md = []
+    for example in examples:
+        base_name = os.path.basename(os.path.normpath(example))
+
+        agent_filename = os.path.join(example, "agents.py")
+        model_filename = os.path.join(example, "model.py")
+        readme_filename = os.path.join(example, "Readme.md")
+        app_filename = os.path.join(example, "app.py")
+
+        md_filename = f"{base_name}.md"
+        examples_md.append(base_name)
+
+        md_filepath = os.path.join(HERE, "examples", 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(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]),
+            )
+        )
+        fh.write(content)
+
+def setup(app):
+    setup_examples_pages()
+
+#
+if __name__ == "__main__":
+    setup_examples_pages()

mesa-3.0.0b2/docs/example_template.txt

@@ -0,0 +1,22 @@
+
+$readme_file
+
+## Agents
+
+```python
+$agent_file
+```
+
+
+## Model
+
+```python
+$model_file
+```
+
+
+## App
+
+```python
+$app_file
+```

mesa-3.0.0b2/docs/examples.md

@@ -0,0 +1,14 @@
+
+# Examples
+
+
+```{toctree}
+:maxdepth: 1
+
+boid flockers </examples/boid_flockers>
+virus on network </examples/virus_on_network>
+conways game of life </examples/conways_game_of_life>
+schelling </examples/schelling>
+boltzmann wealth model </examples/boltzmann_wealth_model>
+
+```

mesa-3.0.0b2/docs/examples_overview_template.txt

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

{mesa-3.0.0b0 → mesa-3.0.0b2}/docs/howto.md

@@ -2,6 +2,45 @@
 
 This guide provides concise instructions and examples to help you start with common tasks in Mesa.
 
+## Implementing Different Activation Regimes
+
+
+### Random Activation
+
+self.agents.shuffle_do("<agent function>")
+
+### Random Activation By Type
+
+```python
+for agent_class in self.agent_types:
+    self.agents_by_type[agent_class].shuffle_do("<agent function>")
+```
+### Only Activating Certain Agent Types
+
+```python
+self.agents_by_type[AgentType].shuffle_do("<agent function>")
+```
+
+### Staged Activation
+
+```python
+for stage in ["stage1", "stage2", "stage3"]:
+    self.agents.do(stage)
+```
+
+If you want to  `shuffle` and/or `shuffle_between_stages` options:
+```python
+
+stages = ["stage1", "stage2", "stage3"]
+if shuffle:
+    self.random.shuffle(stages)
+for stage in stages:
+    if shuffle_between_stages:
+        self.agents.shuffle_do(stage)
+    else:
+        self.agents.do(stage)
+```
+
 ## Models with Discrete Time
 
 For models involving agents of multiple types, including those with a time attribute, you can construct a discrete-time model. This setup allows each agent to perform actions in steps that correspond to the model's discrete time.