Mesa 3.1.4__tar.gz → 3.2.0__tar.gz

{mesa-3.1.4 → mesa-3.2.0}/.github/workflows/build_lint.yml

@@ -84,4 +84,4 @@ jobs:
     - name: Test examples
       run: |
         cd mesa-examples
-        pytest -rA -Werror -Wdefault::FutureWarning test_examples.py
+        pytest -rA -Werror -Wdefault::FutureWarning -Wi::DeprecationWarning test_examples.py

{mesa-3.1.4 → mesa-3.2.0}/.gitignore

@@ -69,6 +69,7 @@ target/
 
 # Jupyter and iPython notebook checkpoints
 *.ipynb_checkpoints
+*.virtual_documents
 
 # Spyder app workspace config file
 .spyderworkspace

{mesa-3.1.4 → mesa-3.2.0}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.9.4
+  rev: v0.9.9
   hooks:
     # Run the linter.
     - id: ruff

mesa-3.2.0/CITATION.cff

@@ -0,0 +1,62 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Hoeven
+  given-names: Ewout
+  name-particle: ter
+  orcid: "https://orcid.org/0009-0002-0805-3425"
+- family-names: Kwakkel
+  given-names: Jan
+  orcid: "https://orcid.org/0000-0001-9447-2954"
+- family-names: Hess
+  given-names: Vincent
+  orcid: "https://orcid.org/0000-0002-9242-8500"
+- family-names: Pike
+  given-names: Thomas
+  orcid: "https://orcid.org/0000-0003-1576-0283"
+- family-names: Wang
+  given-names: Boyu
+  orcid: "https://orcid.org/0000-0001-9879-2138"
+- family-names: rht
+  orcid: "https://orcid.org/0009-0002-6902-111X"
+- family-names: Kazil
+  given-names: Jackie
+  orcid: "https://orcid.org/0000-0002-8300-7384"
+doi: 10.5281/zenodo.15090710
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Hoeven
+    given-names: Ewout
+    name-particle: ter
+    orcid: "https://orcid.org/0009-0002-0805-3425"
+  - family-names: Kwakkel
+    given-names: Jan
+    orcid: "https://orcid.org/0000-0001-9447-2954"
+  - family-names: Hess
+    given-names: Vincent
+    orcid: "https://orcid.org/0000-0002-9242-8500"
+  - family-names: Pike
+    given-names: Thomas
+    orcid: "https://orcid.org/0000-0003-1576-0283"
+  - family-names: Wang
+    given-names: Boyu
+    orcid: "https://orcid.org/0000-0001-9879-2138"
+  - family-names: rht
+    orcid: "https://orcid.org/0009-0002-6902-111X"
+  - family-names: Kazil
+    given-names: Jackie
+    orcid: "https://orcid.org/0000-0002-8300-7384"
+  date-published: 2025-03-28
+  doi: 10.21105/joss.07668
+  issn: 2475-9066
+  issue: 107
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 7668
+  title: "Mesa 3: Agent-based modeling with Python in 2025"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.07668"
+  volume: 10
+title: "Mesa 3: Agent-based modeling with Python in 2025"

{mesa-3.1.4 → mesa-3.2.0}/CONTRIBUTING.md

@@ -53,7 +53,7 @@ Learn the tools, talk to us about what you want to change, and open a small PR.
 Awesome! You have the basics of open-source software development (if not check above), but not much modelling experience.
 
 First step is to start thinking like a modeller. To understand the fine details about our library and contribute meaningfully, get some modelling experience:
-- Go though our [Introductory Tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html). While going through them, dive into the source code to really see what everything does.
+- Go though our series of introductory tutorials at [Getting Started](https://mesa.readthedocs.io/latest/getting_started.html). While going through them, dive into the source code to really see what everything does.
 - Follow an ABM course (if possible). They might be a bit outdated programming language wise, but conceptual they're sound.
   - This MOOC on ABM concepts: [Agent Based Modeling](https://ocw.tudelft.nl/course-lectures/agent-based-modeling/)
   - This MOOC on practical ABM modelling: [Agent-Based Models with Python: An Introduction to Mesa](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa)
@@ -119,7 +119,63 @@ 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
+## Roles in Mesa
+Mesa has several roles to help structure our collaboration and recognize great work. They also form a progression path for community members to that want to take on increasing responsibility in the project. Since we're all volunteers, everyone contributes what they can when they can - there are no minimum time commitments. Also, the best ideas and contributions can come from anyone, these roles are just a way to coordinate our efforts.
+
+Feel free to reach out to us anytime to discuss your interests and ambitions in the project. We're always happy to chat about how you can grow your involvement in Mesa!
+
+### Contributor
+Contributors help improve Mesa through:
+- Code contributions
+- Documentation improvements
+- Bug reports and fixes
+- Example models
+- Tutorial improvements
+- Answering questions
+- Participating in discussions
+- Testing pre-releases
+- Sharing Mesa with others
+
+Everyone can contribute what they can, when they can. No contribution is too small! Contributors who have a PR successfully merged receive the "Contributor" label on GitHub.
+
+### Collaborator
+When contributors consistently demonstrate technical skills and community mindset through their contributions, they may be invited to become collaborators. Collaborators help coordinate by:
+
+- Reviewing pull requests
+- Triaging issues and discussions
+- Coordinating between contributors
+- Leading specific areas of development
+- Helping new contributors
+- Participating in project planning
+- Building community
+
+The collaborator role recognizes people who help Mesa grow through both their technical contributions and community involvement. Collaborators receive GitHub triage permissions and the "Collaborator" label.
+
+### Maintainer
+Maintainers help guide Mesa's overall development while ensuring the project remains sustainable and welcoming. They focus on:
+- Project vision and roadmap
+- Major architectural decisions
+- Release management
+- Community governance
+- Mentoring collaborators
+- Setting community standards
+- Long-term sustainability
+
+Maintainers are selected based on their technical expertise, project understanding, and community leadership. Maintainers receive full repository permissions and the "Member" label.
+
+### Special Roles
+In some cases, special roles may be created for specific purposes, such as leading particular initiatives or components within Mesa. These roles are created as needed based on project requirements and may come with specific permissions and labels.
+
+All roles are expected to:
+- Follow Mesa's code of conduct
+- Communicate respectfully
+- Work collaboratively
+- Help maintain a welcoming community
+- Make decisions transparently
+
+Mesa grows through good ideas and contributions. We're all volunteers working together to make Mesa better. Don't hesitate to reach out to any maintainer to discuss your interests and potential growth within the project!
+
+## Maintainers' notes
 Some notes useful for Mesa maintainers.
 
 ### Releases

{mesa-3.1.4 → mesa-3.2.0}/HISTORY.md

@@ -1,11 +1,124 @@
 ---
 title: Release History
 ---
+# 3.2.0 (2025-05-04)
+## Highlights
+Mesa 3.2.0 is a feature-packed release, which stabilizes our discrete space, improves many of our visualisation capabilities, improves our tutorial organization, adds the experimental meta-agents, and includes other quality of life enhancements.
+
+We also celebrate the publication of our peer-reviewed [Mesa 3 paper](https://doi.org/10.21105/joss.07668) in JOSS. See the updated [Citing Mesa](https://github.com/projectmesa/mesa?tab=readme-ov-file#citing-mesa) section on how to cite us.
+
+### Stabilization of Discrete Space
+The experimental Cell Space system has been stabilized and is now available as `mesa.discrete_space` ([#2610](https://github.com/projectmesa/mesa/pull/2610)). This powerful spatial modeling framework enables cell-centric simulations with integrated PropertyLayers and improved agent movement capabilities. Key improvements include:
+
+- Support for dynamic modifications to discrete spaces during simulation ([#2755](https://github.com/projectmesa/mesa/pull/2755))
+- Methods to add/remove cells and connections in real-time
+- Full integration with PropertyLayers ([#2440](https://github.com/projectmesa/mesa/pull/2440)) for representing environmental variables
+- Compatible with all examples and existing visualizations
+
+The PropertyLayer itself has also been stabilized, allowing for efficient management of spatial environmental properties like terrain, resources, or any grid-based variables. Core examples including [Schelling](https://github.com/projectmesa/mesa/tree/main/mesa/examples/basic/schelling), [Game of Life](https://github.com/projectmesa/mesa/tree/main/mesa/examples/basic/conways_game_of_life), [Boltzmann Wealth](https://github.com/projectmesa/mesa/tree/main/mesa/examples/basic/boltzmann_wealth_model), and [Virus on Network](https://github.com/projectmesa/mesa/tree/main/mesa/examples/basic/virus_on_network) have been updated to use the new discrete space system.
+
+### Enhanced Visualization Experience
+The SolaraViz visualization system has received substantial upgrades:
+
+- **Command Console** ([#2697](https://github.com/projectmesa/mesa/pull/2697)): An interactive Python console embedded directly in the visualization, allowing real-time model inspection and manipulation
+- **Asynchronous Updates** ([#2656](https://github.com/projectmesa/mesa/pull/2656)): Visualization now runs in a separate thread, dramatically improving performance for complex models
+- **Dark Mode** ([#2689](https://github.com/projectmesa/mesa/pull/2689)): Support for Solara Dark theme, automatically matching system preferences
+- **Improved Error Handling** ([#2747](https://github.com/projectmesa/mesa/pull/2747), [#2753](https://github.com/projectmesa/mesa/pull/2753)): Better visualization of errors with options to view detailed traceback information
+- **Enhanced UI**: Arrow key navigation ([#2725](https://github.com/projectmesa/mesa/pull/2725)), movable input field with auto-scroll ([#2710](https://github.com/projectmesa/mesa/pull/2710)), and other quality-of-life improvements
+- **PropertyLayer visualisation in Altair** ([#2643](https://github.com/projectmesa/mesa/pull/2643)): Support for visualising PropertyLayers using the Altair frontend in Solara.
+
+### Restructured and updated tutorial
+Our [introduction tutorial](https://mesa.readthedocs.io/latest/overview.html) has been completely restructured ([#2731](https://github.com/projectmesa/mesa/pull/2731)). Instead of one huge notebook, the tutorial is now divided into smaller, focused modules that build progressively:
+
+- **Creating Your First Model**: Essential basics to get started
+- **Adding Space**: Learn how to use the new discrete space system
+- **Collecting Data**: Effectively gather model statistics
+- **AgentSet**: Master agent management techniques
+- **Visualization**: Series of modules covering basic to advanced visualization
+
+
+### Introducing Meta-Agents
+Complex systems often have multiple levels of components. An organization is not one entity, but is made of departments, sub-departments, and people. A person is not a single entity, but it is made of micro biomes, organs and cells. A city is not a single entity, but it is made of districts, neighborhoods, buildings, and people. A forest comprises an ecosystem of trees, plants, animals, and microorganisms.
+
+This reality is the motivation for meta-agents. It allows users to represent these multiple levels, where each level can have meta-agents with constituting agents.
+- **Meta agents** [#2748](https://github.com/projectmesa/mesa/pull/2748)
+
+To demonstrate meta-agents capability there are two examples:
+
+1.  Dynamic meta-agent creation - [Alliance formation](https://mesa.readthedocs.io/latest/examples/advanced/alliance_formation.html), which shows emergent meta-agent formation through a game theoretic based alliance formation.
+2. Deliberate meta-agent creation - [Warehouse model](https://github.com/projectmesa/mesa-examples/tree/main/examples/warehouse), which provides a pseudo warehouse model to demonstrate meta-agent functionality.
+
+Let us know what you think on our [Matrix Channel](https://matrix.to/#/#project-mesa:matrix.org)
+
+### Other improvements
+- AgentSet's `agg` method now supports multiple aggregation functions in a single call ([#2743](https://github.com/projectmesa/mesa/pull/2743))
+- Many documentation improvements have been made based on feedback by our JOSS reviewers
+
+## What's Changed
+### 🎉 New features added
+* Stabilize experimental Cell Space as `mesa.discrete_space` by @quaquel in https://github.com/projectmesa/mesa/pull/2610
+* Feat: Added Command Console by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2697
+* Stabilize PropertyLayer by @EwoutH in https://github.com/projectmesa/mesa/pull/2440
+### 🛠 Enhancements made
+* Visualisation: Add dark mode by @sanika-n in https://github.com/projectmesa/mesa/pull/2689
+* Creating threads to update visualization asynchronously  by @HMNS19 in https://github.com/projectmesa/mesa/pull/2656
+* Movable Input Field with auto-scroll by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2710
+* Feat: Added arrow key navigation by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2725
+* added property_layer with altair by @sanika-n in https://github.com/projectmesa/mesa/pull/2643
+* Debug option for errors in visualisation by @colinfrisch in https://github.com/projectmesa/mesa/pull/2747
+* Debug option for errors in visualisation front end by @colinfrisch in https://github.com/projectmesa/mesa/pull/2753
+* Add support for dynamic discrete spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2755
+* Support multiple functions in AgentSet `agg` method by @EwoutH in https://github.com/projectmesa/mesa/pull/2743
+### 🔍 Examples updated
+* Move boltzmann to cell spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2680
+* Move Game of life to cell space by @quaquel in https://github.com/projectmesa/mesa/pull/2681
+* Move Schelling to discrete space by @quaquel in https://github.com/projectmesa/mesa/pull/2684
+* Move virus_on_a_network to discrete_space by @quaquel in https://github.com/projectmesa/mesa/pull/2688
+* Update boid_flockers example include flight direction by @sanika-n in https://github.com/projectmesa/mesa/pull/2696
+### 📜 Documentation improvements
+* docs: Split off the overview page, extend with spaces/activation by @EwoutH in https://github.com/projectmesa/mesa/pull/2673
+* docs: Add Roles section to CONTRIBUTING.md by @EwoutH in https://github.com/projectmesa/mesa/pull/2694
+* [JOSS] Docs: Clarify difference between core and user examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2706
+* [JOSS] docs: Improve batch_run documentation for parallel processing by @EwoutH in https://github.com/projectmesa/mesa/pull/2707
+* JOSS Tutorial Fixes by @tpike3 in https://github.com/projectmesa/mesa/pull/2708
+* Clean-up old images, compress wolf-sheep image, remove version switch artifact by @EwoutH in https://github.com/projectmesa/mesa/pull/2717
+* docs: Update citation to JOSS article by @EwoutH in https://github.com/projectmesa/mesa/pull/2740
+* update intro tutorial discrete space by @tpike3 in https://github.com/projectmesa/mesa/pull/2731
+* docs: fix broken links to Readthedocs in example descriptions by @reyan-singh in https://github.com/projectmesa/mesa/pull/2757
+### 🧪 Experimental features
+* Meta agents by @tpike3 in https://github.com/projectmesa/mesa/pull/2748
+### 🐛 Bugs fixed
+* Minor (bug) fixes to discrete_space by @quaquel in https://github.com/projectmesa/mesa/pull/2687
+* Fixed Marker in mpl by @sanika-n in https://github.com/projectmesa/mesa/pull/2670
+
+## New Contributors
+* @colinfrisch made their first contribution in https://github.com/projectmesa/mesa/pull/2747
+* @reyan-singh made their first contribution in https://github.com/projectmesa/mesa/pull/2757
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.1.4...v3.2.0
+
+# 3.1.5 (2025-03-26)
+## Highlights
+Mesa 3.1.5 is a maintenance release focused on improving documentation and cleaning up our resources. This update includes no breaking changes and is compatible with previous 3.1.x releases.
+
+The documentation improvements include enhanced explanations for batch run parallel processing, a significantly expanded overview section covering spaces, property layers and time advancement methods with practical code examples, and a clearer installation guide detailing what the optional `[rec]` dependencies provide. We've also improved our examples documentation to better distinguish between core and user-contributed examples, and added a new "Roles" section to the contributing guide that outlines the project's community structure and progression paths.
+
+On the maintenance side, we've cleaned up unused images and compressed existing ones, reducing the repository size by over 2MB and distribution size from 3.2MB to 1.2MB.
+
+## What's Changed
+### 📜 Documentation improvements
+* docs: Split off the overview page, extend with spaces/activation by @EwoutH in https://github.com/projectmesa/mesa/pull/2673
+* docs: Add Roles section to CONTRIBUTING.md by @EwoutH in https://github.com/projectmesa/mesa/pull/2694
+* [JOSS] Docs: Clarify difference between core and user examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2706
+* [JOSS] docs: Improve batch_run documentation for parallel processing by @EwoutH in https://github.com/projectmesa/mesa/pull/2707
+* Clean-up old images, compress wolf-sheep image, remove version switch artifact by @EwoutH in https://github.com/projectmesa/mesa/pull/2717
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.1.4...v3.1.5
+
 # 3.1.4 (2025-02-09)
 ## Highlights
 This release contains various improvements and bugfixes to the matplotlib-based visualization of spaces. Hexgrids are now fully supported, including property layers. In making this possible, various minor bugs were encountered and also fixed. In addition to the visualization improvements, there are various minor convenience improvements to the docs.
 
-
 ## What's Changed
 ### 🛠 Enhancements made
 * Fixed hex-space draw function to avoid overlaps by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2609
@@ -367,7 +480,7 @@ Install Mesa 3.0:
 pip install --upgrade mesa
 ```
 
-If building a new model, we recommend checking out the updated [Mesa Overview](https://mesa.readthedocs.io/latest/overview.html) and [Introductory Tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html).
+If building a new model, we recommend checking out the updated [Mesa Overview](https://mesa.readthedocs.io/latest/overview.html) and [Introductory Tutorial](https://mesa.readthedocs.io/latest/tutorials/0_first_model.html).
 
 For updating existing models, we recommend upgrading in steps:
 1. Update to latest Mesa 2.x

{mesa-3.1.4 → mesa-3.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: Mesa
-Version: 3.1.4
+Version: 3.2.0
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
-Author-email: Project Mesa Team <projectmesa@googlegroups.com>
+Author-email: Project Mesa Team <maintainers@projectmesa.dev>
 License: Apache 2.0
 License-File: LICENSE
 License-File: NOTICE
@@ -87,12 +87,13 @@ Description-Content-Type: text/markdown
 
 # Mesa: Agent-based modeling in Python
 
-| | |
-| --- | --- |
-| CI/CD | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |
+|         | |
+|---------| --- |
+| CI/CD   | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |
 | Package | [![PyPI - Version](https://img.shields.io/pypi/v/mesa.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mesa.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mesa.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/Mesa/) |
-| Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/) |
-| Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
+| Meta    | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/) |
+| Chat    | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
+| Cite    | [![DOI](https://joss.theoj.org/papers/10.21105/joss.07668/status.svg)](https://doi.org/10.21105/joss.07668) |
 
 Mesa allows users to quickly create agent-based models using built-in
 core components (such as spatial grids and agent schedulers) or
@@ -220,4 +221,7 @@ Don't forget to checkout the [Contributors guide](https://github.com/projectmesa
 
 ## Citing Mesa
 
-To cite Mesa in your publication, you can use the [CITATION.bib](https://github.com/projectmesa/mesa/blob/main/CITATION.bib).
+To cite Mesa in your publication, you can refer to our peer-reviewed article in the Journal of Open Source Software (JOSS):
+- ter Hoeven, E., Kwakkel, J., Hess, V., Pike, T., Wang, B., rht, & Kazil, J. (2025). Mesa 3: Agent-based modeling with Python in 2025. Journal of Open Source Software, 10(107), 7668. https://doi.org/10.21105/joss.07668
+
+Our [CITATION.cff](https://github.com/projectmesa/mesa/blob/main/CITATION.cff) can be used to generate APA, BibTeX and other citation formats.

{mesa-3.1.4 → mesa-3.2.0}/README.md

@@ -1,11 +1,12 @@
 # Mesa: Agent-based modeling in Python
 
-| | |
-| --- | --- |
-| CI/CD | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |
+|         | |
+|---------| --- |
+| CI/CD   | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |
 | Package | [![PyPI - Version](https://img.shields.io/pypi/v/mesa.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mesa.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mesa.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/Mesa/) |
-| Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/) |
-| Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
+| Meta    | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/) |
+| Chat    | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
+| Cite    | [![DOI](https://joss.theoj.org/papers/10.21105/joss.07668/status.svg)](https://doi.org/10.21105/joss.07668) |
 
 Mesa allows users to quickly create agent-based models using built-in
 core components (such as spatial grids and agent schedulers) or
@@ -133,4 +134,7 @@ Don't forget to checkout the [Contributors guide](https://github.com/projectmesa
 
 ## Citing Mesa
 
-To cite Mesa in your publication, you can use the [CITATION.bib](https://github.com/projectmesa/mesa/blob/main/CITATION.bib).
+To cite Mesa in your publication, you can refer to our peer-reviewed article in the Journal of Open Source Software (JOSS):
+- ter Hoeven, E., Kwakkel, J., Hess, V., Pike, T., Wang, B., rht, & Kazil, J. (2025). Mesa 3: Agent-based modeling with Python in 2025. Journal of Open Source Software, 10(107), 7668. https://doi.org/10.21105/joss.07668
+
+Our [CITATION.cff](https://github.com/projectmesa/mesa/blob/main/CITATION.cff) can be used to generate APA, BibTeX and other citation formats.

{mesa-3.1.4 → mesa-3.2.0}/docs/apis/api_main.md

@@ -7,6 +7,7 @@ model
 agent
 time
 space
+discrete_space
 datacollection
 batchrunner
 visualization

mesa-3.2.0/docs/apis/discrete_space.md

@@ -0,0 +1,41 @@
+## Discrete Space
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.__init__
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.cell
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.cell_agent
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.cell_collection
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.discrete_space
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.grid
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.network
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: mesa.discrete_space.voronoi
+   :members:
+```

mesa-3.2.0/docs/apis/experimental.md

@@ -0,0 +1,39 @@
+# Experimental
+This namespace contains experimental features. These are under development, and their API is not necessarily stable.
+
+
+## Devs
+
+```{eval-rst}
+.. automodule:: experimental.devs.eventlist
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: experimental.devs.simulator
+   :members:
+```
+
+## Continuous Space
+
+```{eval-rst}
+.. automodule:: experimental.continuous_space.continuous_space
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: experimental.continuous_space.continuous_space_agents
+   :members:
+```
+
+## Continuous Space
+
+```{eval-rst}
+.. automodule:: experimental.continuous_space.continuous_space
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: experimental.continuous_space.continuous_space_agents
+   :members:
+```

{mesa-3.1.4 → mesa-3.2.0}/docs/apis/visualization.md

@@ -52,4 +52,13 @@ For a detailed tutorial, please refer to our [Visualization Tutorial](../tutoria
    :members:
    :undoc-members:
    :show-inheritance:
+```
+
+## Command Console
+
+```{eval-rst}
+.. automodule:: mesa.visualization.command_console
+   :members:
+   :undoc-members:
+   :show-inheritance:
 ```

{mesa-3.1.4 → mesa-3.2.0}/docs/conf.py

@@ -1,4 +1,3 @@
-# noqa: D100
 #!/usr/bin/env python3
 #
 # Mesa documentation build configuration file, created by
@@ -16,8 +15,8 @@
 import os
 import os.path as osp
 import pathlib
-import sys
 import string
+import sys
 from datetime import date
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -47,7 +46,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",  # for google style docstrings
     "myst_nb",  # For Markdown and Jupyter notebooks
-    "sphinx_copybutton" # For copying the code in the documentation
+    "sphinx_copybutton",  # For copying the code in the documentation
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -131,11 +130,7 @@ html_theme = "pydata_sphinx_theme"
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    "navbar_start": ["navbar-logo", "version-switcher"],  # Show switcher in navbar
-    "switcher": {
-        "json_url": "https://mesa.readthedocs.io/latest/_static/switcher.json",  # URL of your switcher.json file
-        "version_match": version  # Automatically matches the current version
-    }
+    "navbar_start": ["navbar-logo"],
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -177,7 +172,7 @@ html_static_path = ["_static"]
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-    'migration_guide': [],  # No sidebar migration
+    "migration_guide": [],  # No sidebar migration
 }
 
 # Additional templates that should be rendered to pages, maps page names to
@@ -297,8 +292,9 @@ texinfo_documents = [
 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):
+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:
@@ -310,17 +306,30 @@ def write_example_md_file(agent_filename, model_filename, readme_filename, app_f
 
     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)
+            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 = [("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("__")]
+    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:
@@ -329,7 +338,9 @@ def setup_examples_pages():
     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)
+    pathlib.Path(os.path.join(root_folder, "advanced")).mkdir(
+        parents=True, exist_ok=True
+    )
 
     examples_md = []
     for kind, example in examples:
@@ -344,7 +355,14 @@ def setup_examples_pages():
         examples_md.append((base_name, f"{kind}/{base_name}"))
 
         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)
+        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:
@@ -357,14 +375,21 @@ def setup_examples_pages():
         content = template.substitute(
             dict(
                 readme=readme_md,
-                example_paths="\n".join([f"{' '.join(a.split('_'))} </examples/{b}>" for a, b in examples_md]),
+                example_paths="\n".join(
+                    [
+                        f"{' '.join(a.split('_'))} </examples/{b}>"
+                        for a, b in examples_md
+                    ]
+                ),
             )
         )
         fh.write(content)
 
+
 def setup(app):
     setup_examples_pages()
 
+
 #
 if __name__ == "__main__":
-    setup_examples_pages()
+    setup_examples_pages()