Mesa 3.1.4__tar.gz → 3.1.5__tar.gz

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

@@ -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.1.5}/HISTORY.md

@@ -1,11 +1,28 @@
 ---
 title: Release History
 ---
+# 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Mesa
-Version: 3.1.4
+Version: 3.1.5
 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.1.5/docs/getting_started.md

@@ -0,0 +1,54 @@
+# Getting started
+Mesa is a modular framework for building, analyzing and visualizing agent-based models.
+
+**Agent-based models** are computer simulations involving multiple entities (the agents) acting and interacting with one another based on their programmed behavior. Agents can be used to represent living cells, animals, individual humans, even entire organizations or abstract entities. Sometimes, we may have an understanding of how the individual components of a system behave, and want to see what system-level behaviors and effects emerge from their interaction. Other times, we may have a good idea of how the system overall behaves, and want to figure out what individual behaviors explain it. Or we may want to see how to get agents to cooperate or compete most effectively. Or we may just want to build a cool toy with colorful little dots moving around.
+
+## Tutorials
+If you want to get a quick start on how to build agent based models with MESA, check the overview and tutorials:
+
+- [Overview of the MESA library](overview): Learn about the core concepts and components of Mesa.
+- [Introductory Tutorial](tutorials/intro_tutorial): Learn how to create your first Mesa model.
+- [Visualization Tutorial](tutorials/visualization_tutorial): Learn how to create interactive visualizations for your models.
+
+## Examples
+Mesa ships with a collection of example models. These are classic ABMs, so if you are familiar with ABMs and want to get a quick sense of how MESA works, these examples are great place to start. You can find them [here](examples).
+
+## Further resources
+To further explore Mesa and its features, we have the following resources available:
+
+### Best practices
+- [Mesa best practices](best-practices): an overview of tips and guidelines for using MESA.
+
+### API documentation
+- [Mesa API reference](apis): Detailed documentation of Mesa's classes and functions.
+
+### Repository of models built using MESA
+- [Mesa Examples repository](https://github.com/projectmesa/mesa-examples): A collection of example models demonstrating various Mesa features and modeling techniques.
+
+### Migration guide
+- [Mesa 3.0 Migration guide](migration_guide): If you're upgrading from an earlier version of Mesa, this guide will help you navigate the changes in Mesa 3.0.
+
+### Source Ccode and development
+- [Mesa GitHub repository](https://github.com/projectmesa/mesa): Access the full source code of Mesa, contribute to its development, or report issues.
+- [Mesa release notes](https://github.com/projectmesa/mesa/releases): View the detailed changelog of Mesa, including all past releases and their features.
+
+### Community and support
+- [Mesa GitHub Discussions](https://github.com/projectmesa/mesa/discussions): Join discussions, ask questions, and connect with other Mesa users.
+- [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org): Real-time chat for quick questions and community interaction.
+
+Enjoy modelling with Mesa, and feel free to reach out!
+
+
+
+
+
+```{toctree}
+:hidden: true
+:maxdepth: 7
+
+tutorials/intro_tutorial
+tutorials/visualization_tutorial
+Best Practices <best-practices>
+
+
+```

{mesa-3.1.4 → mesa-3.1.5}/docs/index.md

@@ -43,10 +43,11 @@ To also install our recommended dependencies:
 pip install -U mesa[rec]
 ```
 
+The `[rec]` option installs additional recommended dependencies needed for visualization, plotting, and network modeling capabilities.
+
 On a Mac, this command might cause an error stating `zsh: no matches found: mesa[all]`.
 In that case, change the command to `pip install -U "mesa[rec]"`.
 
-
 ### Resources
 
 For help getting started with Mesa, check out these resources:
@@ -73,6 +74,7 @@ The original Mesa conference paper is [available here](http://conference.scipy.o
 :maxdepth: 7
 
 Getting started <getting_started>
+Overview <overview>
 Examples <examples>
 Migration guide <migration_guide>
 API Documentation <apis/api_main>

mesa-3.1.4/docs/getting_started.md → mesa-3.1.5/docs/overview.md

@@ -1,19 +1,3 @@
-# Getting started
-Mesa is a modular framework for building, analyzing and visualizing agent-based models.
-
-**Agent-based models** are computer simulations involving multiple entities (the agents) acting and interacting with one another based on their programmed behavior. Agents can be used to represent living cells, animals, individual humans, even entire organizations or abstract entities. Sometimes, we may have an understanding of how the individual components of a system behave, and want to see what system-level behaviors and effects emerge from their interaction. Other times, we may have a good idea of how the system overall behaves, and want to figure out what individual behaviors explain it. Or we may want to see how to get agents to cooperate or compete most effectively. Or we may just want to build a cool toy with colorful little dots moving around.
-
-
-## Tutorials
-If you want to get a quick start on how to build agent based models with MESA, check the tutorials:
-
-- [Introductory Tutorial](tutorials/intro_tutorial): Learn how to create your first Mesa model.
-- [Visualization Tutorial](tutorials/visualization_tutorial): Learn how to create interactive visualizations for your models.
-
-## Examples
-Mesa ships with a collection of example models. These are classic ABMs, so if you are familiar with ABMs and want to get a quick sense of how MESA works, these examples are great place to start. You can find them [here](examples).
-
-
 ## Overview of the MESA library
 
 Mesa is modular, meaning that its modeling, analysis and visualization components are kept separate but intended to work together. The modules are grouped into three categories:
@@ -59,15 +43,102 @@ class MyModel(mesa.Model):
         self.agents.shuffle_do("step")
 ```
 
-If you instantiate a model and run it for one step, like so:
+### Spaces in Mesa
+
+Mesa provides several types of spaces where agents can exist and interact:
+
+#### Discrete Spaces
+Mesa implements discrete spaces using a doubly-linked structure where each cell maintains connections to its neighbors. Available variants include:
+
+1. **Grid-based Spaces:**
+   ```python
+   # Create a Von Neumann grid (4 neighbors per cell)
+   grid = mesa.space.OrthogonalVonNeumannGrid((width, height), torus=False)
+
+   # Create a Moore grid (8 neighbors per cell)
+   grid = mesa.space.OrthogonalMooreGrid((width, height), torus=True)
+
+   # Create a hexagonal grid
+   grid = mesa.space.HexGrid((width, height), torus=False)
+   ```
+
+2. **Network Space:**
+   ```python
+   # Create a network-based space
+   network = mesa.space.NetworkGrid(network)
+   ```
+
+3. **Voronoi Space:**
+   ```python
+   # Create an irregular tessellation
+   mesh = mesa.space.VoronoiMesh(points)
+   ```
+
+#### Property Layers
+Discrete spaces support PropertyLayers - efficient numpy-based arrays for storing cell-level properties:
+
+```python
+# Create and use a property layer
+grid.create_property_layer("elevation", default_value=10)
+high_ground = grid.elevation.select_cells(lambda x: x > 50)
+```
+
+#### Continuous Space
+For models requiring continuous movement:
 
 ```python
-model = MyModel(5)
-model.step()
+# Create a continuous space
+space = mesa.space.ContinuousSpace(x_max, y_max, torus=True)
+
+# Move an agent to specific coordinates
+space.move_agent(agent, (new_x, new_y))
+```
+
+### Time Advancement and Agent Activation
+
+Mesa supports multiple approaches to advancing time and activating agents:
+
+#### Basic Time Steps
+The simplest approach runs the model for a specified number of steps:
+
+```python
+model = MyModel(seed=42)
+for _ in range(100):
+    model.step()
 ```
 
-You should see agents 1-5, activated in random order. See the [tutorial](tutorials/intro_tutorial) or API documentation for more detail on how to add model functionality.
+#### Agent Activation Patterns
+Mesa 3.0 provides flexible agent activation through the AgentSet API:
 
+```python
+# Sequential activation
+model.agents.do("step")
+
+# Random activation
+model.agents.shuffle_do("step")
+
+# Multi-stage activation
+for stage in ["move", "eat", "reproduce"]:
+    model.agents.do(stage)
+
+# Activation by agent type
+for klass in model.agent_types:
+    model.agents_by_type[klass].do("step")
+```
+
+#### Event-Based Scheduling
+Mesa also supports event-based time progression (experimental):
+
+```python
+# Pure event-based
+simulator = mesa.experimental.DiscreteEventSimulator()
+model = MyModel(seed=42, simulator=simulator)
+simulator.schedule_event_relative(some_function, 3.1415)
+
+# Hybrid time-step and event scheduling
+model = MyModel(seed=42, simulator=mesa.experimental.ABMSimulator())
+model.simulator.schedule_event_next_tick(some_function)
+```
 
 ### AgentSet and model.agents
 Mesa 3.0 makes `model.agents` and the AgentSet class central in managing and activating agents.
@@ -169,6 +240,7 @@ results = mesa.batch_run(
     iterations=5,
     max_steps=100,
     data_collection_period=1,
+    number_processes=1  # Change to use multiple CPU cores for parallel execution
 )
 ```
 
@@ -228,43 +300,3 @@ This will create an interactive visualization of your model, including:
 - A slider to adjust the number of agents
 
 You can also create custom visualization components using Matplotlib. For more advanced usage and customization options, please refer to the [visualization tutorial](tutorials/visualization_tutorial).
-
-## Further resources
-To further explore Mesa and its features, we have the following resources available:
-
-### Best practices
-- [Mesa best practices](best-practices): an overview of tips and guidelines for using MESA.
-
-### API documentation
-- [Mesa API reference](apis): Detailed documentation of Mesa's classes and functions.
-
-### Repository of models built using MESA
-- [Mesa Examples repository](https://github.com/projectmesa/mesa-examples): A collection of example models demonstrating various Mesa features and modeling techniques.
-
-### Migration guide
-- [Mesa 3.0 Migration guide](migration_guide): If you're upgrading from an earlier version of Mesa, this guide will help you navigate the changes in Mesa 3.0.
-
-### Source Ccode and development
-- [Mesa GitHub repository](https://github.com/projectmesa/mesa): Access the full source code of Mesa, contribute to its development, or report issues.
-- [Mesa release notes](https://github.com/projectmesa/mesa/releases): View the detailed changelog of Mesa, including all past releases and their features.
-
-### Community and support
-- [Mesa GitHub Discussions](https://github.com/projectmesa/mesa/discussions): Join discussions, ask questions, and connect with other Mesa users.
-- [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org): Real-time chat for quick questions and community interaction.
-
-Enjoy modelling with Mesa, and feel free to reach out!
-
-
-
-
-
-```{toctree}
-:hidden: true
-:maxdepth: 7
-
-tutorials/intro_tutorial
-tutorials/visualization_tutorial
-Best Practices <best-practices>
-
-
-```

{mesa-3.1.4 → mesa-3.1.5}/mesa/__init__.py

@@ -22,7 +22,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "3.1.4"
+__version__ = "3.1.5"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.UTC).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

{mesa-3.1.4 → mesa-3.1.5}/mesa/batchrunner.py

@@ -3,7 +3,12 @@
 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
+jupyter notebook). This is because Jupyter notebooks have a different execution
+model that can cause issues with Python's multiprocessing module, especially on
+Windows. The main problems include the lack of a traditional __main__ entry
+point, serialization issues, and potential deadlocks.
+
+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
@@ -21,8 +26,6 @@ put the code inside an ``if __name__ == '__main__':`` code black as shown below:
             display_progress=True,
         )
 
-
-
 """
 
 import itertools

{mesa-3.1.4 → mesa-3.1.5}/mesa/examples/README.md

@@ -1,7 +1,12 @@
-# Mesa core examples
-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.
+# Mesa Core Examples
+This repository contains a curated set of classic agent-based models implemented using Mesa. These core examples are maintained by the Mesa development team and serve as both demonstrations of Mesa's capabilities and starting points for your own models.
 
-More user examples and showcases can be found in the [mesa-examples](https://github.com/projectmesa/mesa-examples) repository.
+## Overview
+The examples are categorized into two groups:
+1. **Basic Examples** - Simpler models that use only stable Mesa features; ideal for beginners
+2. **Advanced Examples** - More complex models that demonstrate additional concepts and may use some experimental features
+
+> **Note:** Looking for more examples? Visit the [mesa-examples](https://github.com/projectmesa/mesa-examples) repository for user-contributed models and showcases.
 
 ## 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.
@@ -34,4 +39,4 @@ Grid-based demographic prisoner's dilemma model, demonstrating how simple rules
 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](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.
+Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation) model.

mesa-3.1.4/docs/_static/switcher.json

@@ -1,12 +0,0 @@
-[
-    {
-        "name": "Stable",
-        "version": "stable",
-        "url": "https://mesa.readthedocs.io/stable/"
-    },
-    {
-        "name": "Latest",
-        "version": "latest",
-        "url": "https://mesa.readthedocs.io/latest/"
-    }
-]