Merge remote-tracking branch 'upstream/main'

Author: quaquel

.github/workflows/build_lint.yml

@@ -77,7 +77,7 @@ jobs:
     - name: Install uv
       run: pip install uv
     - name: Install Mesa
-      run: uv pip install --system .[dev]
+      run: uv pip install --system .[examples]
     - name: Checkout mesa-examples
       uses: actions/checkout@v4
       with:
@@ -86,4 +86,4 @@ jobs:
     - name: Test examples
       run: |
         cd mesa-examples
-        pytest -rA -Werror test_examples.py
+        pytest -rA -Werror -Wdefault::FutureWarning test_examples.py

CONTRIBUTING.md

@@ -36,6 +36,40 @@ discuss via [Matrix] OR via [an issue].
 - Describe the change w/ ticket number(s) that the code fixes.
 - Format your commit message as per [Tim Pope's guideline].
 
+## I have no idea where to start
+That's fine! Here's a rough outline where you could start, depending on your experience:
+
+### I'm a modeller (but not an experienced developer)
+You already know how to build Mesa models (if not skip below), and probably have found things Mesa can't do (elegantly). You want to improve that. Awesome!
+
+First step is to install some proper tools, if you haven't already.
+- A good IDE helps for code development, testing and formatting. [PyCharm](https://www.jetbrains.com/pycharm/) or [VSCode](https://code.visualstudio.com/) for example.
+- Dive into Git and GitHub. Watch some videos, this takes some time to click. [GitHub Desktop](https://desktop.github.com/) is great.
+- [`https://github.dev/projectmesa/mesa`](https://github.dev/projectmesa/mesa) is great for small changes (to docs).
+
+Learn the tools, talk to us about what you want to change, and open a small PR. Or update an [example model](https://github.com/projectmesa/mesa-examples) (check open [issues](https://github.com/projectmesa/mesa-examples/issues))!
+
+### I'm a developer (but not a modeller)
+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/en/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.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)
+- Go though multiple of our [examples](https://github.com/projectmesa/mesa-examples). Play with them, modify things and get a feel for Mesa and ABMs.
+  - Check our open [issues](https://github.com/projectmesa/mesa-examples/issues) for the examples.
+  - If you see anything you want to improve, feel free to open a (small) PR!
+- If you have a feel for Mesa, check our [discussions](https://github.com/projectmesa/mesa/discussions) and [issues](https://github.com/projectmesa/mesa/issues).
+  - Also go thought our [release notes](https://github.com/projectmesa/mesa/releases) to see what we recently have been working on, and see some examples of successful PRs.
+- Once you found or thought of a nice idea, comment on the issue/discussion (or open a new one) and get to work!
+
+### I'm both
+That's great! You can just start working on things, reach out to us. Skim to the list above if you feel you're missing anything. Start small but don't be afraid to dream big!
+
+### I'm neither
+Start with creating your own models, for fun. Once you have some experience, move to the topics above.
+
 ## Testing and Code Standards
 
 ```{image} https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg

HISTORY.md

@@ -1,6 +1,54 @@
 ---
 title: Release History
 ---
+# 3.0.0a3 (2024-08-30)
+## Highlights
+Developments toward Mesa 3.0 are steaming ahead, and our fourth alpha release is packed with features and updates - only 8 days after our third.
+
+Mesa 3.0.0a3 contains one breaking change: We now automatically increase the `steps` counter by one at the beginning of each `Model.steps()` call. That means increasing `steps` by hand isn't necessary anymore.
+
+The big new features is the experimental Voronoi grid that @vitorfrois implemented in #2084. It allows creating cells in a [Voronoi](https://en.wikipedia.org/wiki/Voronoi_diagram) layout as part of the experimental cell space. An example using it to model Cholera spread can be [found here](https://github.com/projectmesa/mesa-examples/pull/118).
+
+The AgentSet got a lot of love with two brand new methods: `.groupby()` to split in groups (#2220) and `.set()` to easily assign variables to all agents in that set (#2254). The `select()` method is improved by allowing to select at most a fraction of the agents (#2253), and we split the `do()` method in `do()` and `map()` to make a distinction between the return types (#2237).
+
+Furthermore, we improved the performance of accessing `Model.agents`, squashed a bug in SolaraViz, started testing on Python 3.13 and added a new benchmark model.
+
+Our example models also got more love: We removed the `RandomActivation` scheduler in 14 models and removed SimultaneousActivation in 3 models ([examples#183](https://github.com/projectmesa/mesa-examples/pull/183)). They now use the automatic step increase and AgentSet functionality. We started testing our GIS model in CI ([examples#171](https://github.com/projectmesa/mesa-examples/pull/171)) and resolved a lot of bugs in them ([examples#172](https://github.com/projectmesa/mesa-examples/issues/172), help appreciated!).
+
+Finally, we have two brand new examples: An Ant Colony Optimization model using an Ant System approach to the Traveling Salesman problem, a Mesa NetworkGrid, and a custom visualisation with SolaraViz ([examples#157](https://github.com/projectmesa/mesa-examples/pull/157) by @zjost). The first example using the `PropertyLayer` was added, a very fast implementation of Conway's Game of Life ([examples#182](https://github.com/projectmesa/mesa-examples/pull/182)).
+
+To help the transition to Mesa 3.0, we started writing a [migration guide](https://mesa.readthedocs.io/en/latest/migration_guide.html). Progress is tracked in #2233, feedback and help is appreciated! Finally, we also added a new section to our [contributor guide](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md#i-have-no-idea-where-to-start) to get new contributors up to speed.
+
+This pre-release can be installed as always with `pip install --pre mesa`
+
+## What's Changed
+### ⚠️ Breaking changes
+* model: Automatically increase `steps` counter by @EwoutH in https://github.com/projectmesa/mesa/pull/2223
+### 🧪 Experimental features
+* Voronoi Tessellation based Discrete Space by @vitorfrois in https://github.com/projectmesa/mesa/pull/2084
+### 🎉 New features added
+* Add AgentSet.groupby by @quaquel in https://github.com/projectmesa/mesa/pull/2220
+* AgentSet: Add `set` method by @EwoutH in https://github.com/projectmesa/mesa/pull/2254
+### 🛠 Enhancements made
+* Split AgentSet into map and do to separate return types by @quaquel in https://github.com/projectmesa/mesa/pull/2237
+* Performance enhancements for Model.agents by @quaquel in https://github.com/projectmesa/mesa/pull/2251
+* AgentSet: Allow selecting a fraction of agents in the AgentSet by @EwoutH in https://github.com/projectmesa/mesa/pull/2253
+### 🐛 Bugs fixed
+* SolaraViz: Reset components when params are changed by @rht in https://github.com/projectmesa/mesa/pull/2240
+### 📜 Documentation improvements
+* Contribution: Add "I have no idea where to start" section by @EwoutH in https://github.com/projectmesa/mesa/pull/2258
+* Write initial Mesa Migration guide by @EwoutH in https://github.com/projectmesa/mesa/pull/2257
+### 🔧 Maintenance
+* CI: Add test job for Python 3.13 by @EwoutH in https://github.com/projectmesa/mesa/pull/2173
+* Add pull request templates by @EwoutH in https://github.com/projectmesa/mesa/pull/2217
+* benchmarks: Add BoltzmannWealth model by @EwoutH in https://github.com/projectmesa/mesa/pull/2252
+* CI: Add optional dependency for examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2261
+
+## New Contributors
+* @vitorfrois made their first contribution in https://github.com/projectmesa/mesa/pull/2084
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a2...v3.0.0a3
+
 # 3.0.0a2 (2024-08-21)
 ## Highlights
 In Mesa 3.0 alpha 2 (`v3.0.0a2`) we've done more clean-up in preparation for Mesa 3.0. We now [require](https://github.com/projectmesa/mesa/pull/2218) `super().__init__()`  to run on initializing a Mesa model subclass, `Model.agents` is now fully reserved for the Model's internal AgentSet and we fixed a bug in our Solara space_drawer.

README.md

@@ -52,15 +52,18 @@ Or any other (development) branch on this repo or your own fork:
 pip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa
 ```
 
+## Resources
 For resources or help on using Mesa, check out the following:
 
 -   [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann
     Wealth Model, for beginners or those new to Mesa.)
+-   [Visualization Tutorial](https://mesa.readthedocs.io/en/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
 -   [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,
     SugarScape with Traders, with instructional videos)
 -   [Mesa Examples](https://github.com/projectmesa/mesa-examples/tree/main/examples) (A repository of seminal ABMs using Mesa and
     examples of employing specific Mesa Features)
 -   [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)
+    -   [Development version docs](https://mesa.readthedocs.io/en/latest/) (the latest version docs if you're using a pre-release Mesa version)
 -   [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa)
 -   [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa)
 

docs/index.md

@@ -81,6 +81,7 @@ ABM features users have shared that you may want to use in your model
 Mesa Overview <overview>
 tutorials/intro_tutorial
 tutorials/visualization_tutorial
+Migration guide <migration_guide>
 Best Practices <best-practices>
 How-to Guide <howto>
 API Documentation <apis/api_main>

docs/migration_guide.md

@@ -0,0 +1,67 @@
+# Mesa Migration guide
+This guide contains breaking changes between major Mesa versions and how to resolve them.
+
+Non-breaking changes aren't included, for those see our [Release history](https://github.com/projectmesa/mesa/releases).
+
+## Mesa 3.0
+<!-- TODO small introduction-->
+
+_This guide is a work in progress. The development of it is tracked in [Issue #2233](https://github.com/projectmesa/mesa/issues/2233)._
+
+### Reserved and private variables
+<!-- TODO: Update this section based on https://github.com/projectmesa/mesa/discussions/2230 -->
+
+#### Reserved variables
+Currently, we have reserved the following variables:
+  - Model: `agents`, `current_id`, `random`, `running`, `steps`, `time`.
+  - Agent: `unique_id`, `model`.
+
+You can use (read) any reserved variable, but Mesa may update them automatically and rely on them, so modify/update at your own risk.
+#### Private variables
+Any variables starting with an underscore (`_`) are considered private and for Mesa's internal use. We might use any of those. Modifying or overwriting any private variable is at your own risk.
+
+- Ref: [Discussion #2230](https://github.com/projectmesa/mesa/discussions/2230), [PR #2225](https://github.com/projectmesa/mesa/pull/2225)
+
+
+### Removal of `mesa.flat` namespace
+The `mesa.flat` namespace is removed. Use the full namespace for your imports.
+
+- Ref: [PR #2091](https://github.com/projectmesa/mesa/pull/2091)
+
+
+### Automatic assignment of `unique_id` to Agents
+<!-- TODO -->
+
+- Ref: [PR #2226](https://github.com/projectmesa/mesa/pull/2226)
+
+
+### AgentSet and `Model.agents`
+#### AgentSet
+<!-- TODO  -->
+
+#### `Model.agents`
+<!-- TODO  -->
+
+
+### Time and schedulers
+<!-- TODO general explanation-->
+
+#### Automatic increase of the `steps` counter
+The `steps` counter is now automatically increased. With each call to `Model.steps()` it's increased by 1, at the beginning of the step.
+
+You can access it by `Model.steps`, and it's internally in the datacollector, batchrunner and the visualisation.
+
+- Ref: [PR #2223](https://github.com/projectmesa/mesa/pull/2223), Mesa-examples [PR #161](https://github.com/projectmesa/mesa-examples/pull/161)
+
+#### Removal of `Model._time` and rename `._steps`
+- `Model._time` is removed. You can define your own time variable if needed.
+- `Model._steps` steps is renamed to `Model.steps`.
+
+#### Removal of `Model._advance_time()`
+- The `Model._advance_time()` method is removed. This now happens automatically.
+
+<!-- TODO deprecate all schedulers? -->
+
+
+### Visualisation
+<!-- TODO -->

mesa/__init__.py

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

mesa/agent.py

@@ -114,39 +114,58 @@ def __contains__(self, agent: Agent) -> bool:
     def select(
         self,
         filter_func: Callable[[Agent], bool] | None = None,
-        n: int = 0,
+        at_most: int | float = float("inf"),
         inplace: bool = False,
         agent_type: type[Agent] | None = None,
+        n: int | None = None,
     ) -> AgentSet:
         """
         Select a subset of agents from the AgentSet based on a filter function and/or quantity limit.
 
         Args:
             filter_func (Callable[[Agent], bool], optional): A function that takes an Agent and returns True if the
                 agent should be included in the result. Defaults to None, meaning no filtering is applied.
-            n (int, optional): The number of agents to select. If 0, all matching agents are selected. Defaults to 0.
+            at_most (int | float, optional): The maximum amount of agents to select. Defaults to infinity.
+              - If an integer, at most the first number of matching agents are selected.
+              - If a float between 0 and 1, at most that fraction of original the agents are selected.
             inplace (bool, optional): If True, modifies the current AgentSet; otherwise, returns a new AgentSet. Defaults to False.
             agent_type (type[Agent], optional): The class type of the agents to select. Defaults to None, meaning no type filtering is applied.
 
         Returns:
             AgentSet: A new AgentSet containing the selected agents, unless inplace is True, in which case the current AgentSet is updated.
+
+        Notes:
+            - at_most just return the first n or fraction of agents. To take a random sample, shuffle() beforehand.
+            - at_most is an upper limit. When specifying other criteria, the number of agents returned can be smaller.
         """
+        if n is not None:
+            warnings.warn(
+                "The parameter 'n' is deprecated. Use 'at_most' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            at_most = n
 
-        if filter_func is None and agent_type is None and n == 0:
+        inf = float("inf")
+        if filter_func is None and agent_type is None and at_most == inf:
             return self if inplace else copy.copy(self)
 
-        def agent_generator(filter_func=None, agent_type=None, n=0):
+        # Check if at_most is of type float
+        if at_most <= 1.0 and isinstance(at_most, float):
+            at_most = int(len(self) * at_most)  # Note that it rounds down (floor)
+
+        def agent_generator(filter_func, agent_type, at_most):
             count = 0
             for agent in self:
+                if count >= at_most:
+                    break
                 if (not filter_func or filter_func(agent)) and (
                     not agent_type or isinstance(agent, agent_type)
                 ):
                     yield agent
                     count += 1
-                    if 0 < n <= count:
-                        break
 
-        agents = agent_generator(filter_func, agent_type, n)
+        agents = agent_generator(filter_func, agent_type, at_most)
 
         return AgentSet(agents, self.model) if not inplace else self._update(agents)
 

mesa/experimental/cell_space/__init__.py

@@ -9,6 +9,7 @@
     OrthogonalVonNeumannGrid,
 )
 from mesa.experimental.cell_space.network import Network
+from mesa.experimental.cell_space.voronoi import VoronoiGrid
 
 __all__ = [
     "CellCollection",
@@ -20,4 +21,5 @@
     "OrthogonalMooreGrid",
     "OrthogonalVonNeumannGrid",
     "Network",
+    "VoronoiGrid",
 ]