Mesa 3.0.0a3__tar.gz → 3.0.0a5__tar.gz

{mesa-3.0.0a3 → mesa-3.0.0a5}/.github/ISSUE_TEMPLATE/bug-report.md

@@ -11,7 +11,8 @@ about: Let us know if something is broken on Mesa
 <!-- A clear and concise description of what you expected to happen -->
 
 **To Reproduce**
-<!-- Steps to reproduce the bug, or a link to a project where the bug is visible -->
+<!-- Steps to reproduce the bug, or a link to a project where the bug is visible
+Include a Minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example -->
 
 **Additional context**
 <!--

mesa-3.0.0a5/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions, ideas, showcases and more
+    url: https://github.com/projectmesa/mesa/discussions
+    about: Discuss Mesa, ask questions, share ideas, and showcase your projects

{mesa-3.0.0a3 → mesa-3.0.0a5}/.github/workflows/build_lint.yml

@@ -53,12 +53,8 @@ jobs:
         cache: 'pip'
     - name: Install uv
       run: pip install uv
-    - name: Install Mesa with uv pip
+    - name: Install Mesa and dependencies
       run: uv pip install --system .[dev]
-      if: matrix.python-version != '3.13'
-    - name: Install Mesa with pip
-      run: pip install .[dev]
-      if: matrix.python-version == '3.13'
     - name: Test with pytest
       run: pytest --durations=10 --cov=mesa tests/ --cov-report=xml
     - if: matrix.os == 'ubuntu'

{mesa-3.0.0a3 → mesa-3.0.0a5}/.pre-commit-config.yaml

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

{mesa-3.0.0a3 → mesa-3.0.0a5}/HISTORY.md

@@ -1,6 +1,105 @@
 ---
 title: Release History
 ---
+# 3.0.0a5 (2024-09-21)
+## Highlights
+Mesa v3.0 alpha 5 release contains many quality of life updates, a big new feature for the DataCollector and a major deprecation.
+
+The entire `mesa.time` module, including all schedulers, has been deprecated ([#2306](https://github.com/projectmesa/mesa/pull/2306)). Users are encouraged to transition to AgentSet functionality for more flexible and explicit agent activation patterns. Check the [migration guide](https://mesa.readthedocs.io/en/latest/migration_guide.html#time-and-schedulers) on how to upgrade.
+
+The DataCollector now supports collecting data from specific Agent subclasses using the new `agenttype_reporters` parameter ([#2300](https://github.com/projectmesa/mesa/pull/2300)). This allows collecting different metrics for different agent types. For example:
+
+```python
+self.datacollector = DataCollector(
+    agenttype_reporters={
+        Wolf: {"sheep_eaten": "sheep_eaten"},
+        Sheep: {"wool": "wool_amount"}
+    }
+)
+```
+
+Furthermore, a new `shuffle_do()` method for AgentSets provides a faster way to perform `shuffle().do()` ([#2283](https://github.com/projectmesa/mesa/pull/2283)). The GroupBy class gained `count()` and `agg()` methods to count the number of agents in groups and aggregate variables of them ([#2290](https://github.com/projectmesa/mesa/pull/2290)). The `CellCollection.select` method was updated to use `at_most` instead of `n`, aligning with the AgentSet API ([#2307](https://github.com/projectmesa/mesa/pull/2307)). Additionally, the Cell class now features a dedicated `neighborhood` property for direct neighbors (default radius=1) and a `get_neighborhood` method for larger radii ([#2309](https://github.com/projectmesa/mesa/pull/2309)).
+
+Finally, SolaraViz received updates improving its interface and performance ([#2299](https://github.com/projectmesa/mesa/pull/2299), [#2304](https://github.com/projectmesa/mesa/pull/2304)). Cell connections in grids and networks are now public and named for more intuitive agent movements ([#2296](https://github.com/projectmesa/mesa/pull/2296)). The Model class initialization process was simplified by moving random seed and random object creation to `__init__` ([#1940](https://github.com/projectmesa/mesa/pull/1940)). Documentation has been extensively updated, including enforcing Google docstrings ([#2294](https://github.com/projectmesa/mesa/pull/2294)) and reorganizing the API documentation ([#2298](https://github.com/projectmesa/mesa/pull/2298)) for better clarity and navigation.
+
+While the Mesa 3.0 timeline is still being discussed, we're aiming at the first Mesa 3.0 beta in October followed by a stable release in November. Testing new features and sharing feedback is appreciated!
+
+## What's Changed
+### 🎉 New features added
+* GroupBy: Add `count` and `agg` methods by @EwoutH in https://github.com/projectmesa/mesa/pull/2290
+* datacollector: Allow collecting data from Agent (sub)classes by @EwoutH in https://github.com/projectmesa/mesa/pull/2300
+* Add optimized shuffle_do() method to AgentSet by @EwoutH in https://github.com/projectmesa/mesa/pull/2283
+### 🛠 Enhancements made
+* Make cell connections public and named by @Corvince in https://github.com/projectmesa/mesa/pull/2296
+* SolaraViz Updates by @Corvince in https://github.com/projectmesa/mesa/pull/2299
+* Solara viz: use_task for non-threaded continuous play by @Corvince in https://github.com/projectmesa/mesa/pull/2304
+* Update to CellCollection.select by @quaquel in https://github.com/projectmesa/mesa/pull/2307
+### 📜 Documentation improvements
+* Enforce google docstrings by @quaquel in https://github.com/projectmesa/mesa/pull/2294
+* Api docs by @quaquel in https://github.com/projectmesa/mesa/pull/2298
+* update migration guide to describe solaraviz updates by @Corvince in https://github.com/projectmesa/mesa/pull/2297
+* Migration Guide: Add Model initialization requirement and automatic Agent.unique_id assignment by @EwoutH in https://github.com/projectmesa/mesa/pull/2302
+* Deprecate Time module and all its Schedulers by @EwoutH in https://github.com/projectmesa/mesa/pull/2306
+### 🔧 Maintenance
+* make typing behavior of AgentSet.get explicit by @quaquel in https://github.com/projectmesa/mesa/pull/2293
+* model: Move random seed and random to __init__ by @rht in https://github.com/projectmesa/mesa/pull/1940
+* Remove schedulers from benchmark models. by @quaquel in https://github.com/projectmesa/mesa/pull/2308
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a4...v3.0.0a5
+
+# 3.0.0a4 (2024-09-09)
+## Highlights
+Mesa 3.0.0a4 contains two major breaking changes:
+1. The Agent's `unique_id` is now automatically assigned, so doesn't need to be passed to the Agent class anymore. In a subclassed custom Agent, like normally used, this now looks like this:
+    ```diff
+    class Wolf(Agent):
+    -    def __init__(self, unique_id, model, energy=None):
+    +    def __init__(self, model, energy=None):
+            # When initializing the super class (Agent), passing unique_id isn't needed anymore
+    -        super().__init__(unique_id, model)
+    +        super().__init__(model)
+
+    - wolf = Wolf(unique_id, model)
+    + wolf = Wolf(model)
+    ```
+    Example models were updated in [mesa-examples#194](https://github.com/projectmesa/mesa-examples/pull/194), which shows more examples on how to update existing models.
+
+2. Our visualisation API is being overhauled, to be more flexible and powerful. For more details, see [#2278](https://github.com/projectmesa/mesa/pull/2278).
+    - An initial update to the tutorial was made in [#2289](https://github.com/projectmesa/mesa/pull/2289) and is [available here](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.html).
+    - An initial example model was updated in [mesa-examples#195](https://github.com/projectmesa/mesa-examples/pull/195), and more examples will be updated in [mesa-examples#195](https://github.com/projectmesa/mesa-examples/pull/193).
+    - The old SolaraViz API is still available at `mesa.experimental`, but might be removed in future releases.
+
+Furthermore, the AgentSet has a new `agg` method to quickly get an aggerate value (for example `min_energy = model.agents.agg("energy", min)`) ([#2266](https://github.com/projectmesa/mesa/pull/2266)), The Model `get_agents_of_type` function is replaced by directly exposing the `agents_by_type` property (which can be accessed as a dict) ([#2267](https://github.com/projectmesa/mesa/pull/2267), [mesa-examples#190](https://github.com/projectmesa/mesa-examples/pull/190)) and the AgentSet get() methods can now handle missing values by replacing it with a default value ([#2279](https://github.com/projectmesa/mesa/pull/2279)).
+
+Finally, it fixes a bug in which the Grid's `move_agent_to_one_of` method with `selection="closest"` selected a location deterministically, instead of randomly ([#2118](https://github.com/projectmesa/mesa/pull/2118)).
+
+## What's Changed
+### ⚠️ Breaking changes
+* move solara_viz back to experimental by @Corvince in https://github.com/projectmesa/mesa/pull/2278
+* track unique_id automatically by @quaquel in https://github.com/projectmesa/mesa/pull/2260
+### 🎉 New features added
+* AgentSet: Add `agg` method by @EwoutH in https://github.com/projectmesa/mesa/pull/2266
+* Implement new SolaraViz API by @Corvince in https://github.com/projectmesa/mesa/pull/2263
+### 🛠 Enhancements made
+* Model: Replace `get_agents_of_type` method with `agents_by_type` property by @EwoutH in https://github.com/projectmesa/mesa/pull/2267
+* add default SolaraViz by @Corvince in https://github.com/projectmesa/mesa/pull/2280
+* Simplify ModelController by @Corvince in https://github.com/projectmesa/mesa/pull/2282
+* Add default values and missing value handling to `agentset.get` by @quaquel in https://github.com/projectmesa/mesa/pull/2279
+### 🐛 Bugs fixed
+* Fix deterministic behavior in `move_agent_to_one_of` with `selection="closest"` by @OrenBochman in https://github.com/projectmesa/mesa/pull/2118
+### 📜 Documentation improvements
+* docs: Fix Visualization Tutorial (main branch) by @EwoutH in https://github.com/projectmesa/mesa/pull/2271
+* Docs: Fix broken relative links by removing `.html` suffix by @EwoutH in https://github.com/projectmesa/mesa/pull/2274
+* Readthedocs: Don't let notebook failures pass silently by @EwoutH in https://github.com/projectmesa/mesa/pull/2276
+* Update viz tutorial to the new API by @Corvince in https://github.com/projectmesa/mesa/pull/2289
+### 🔧 Maintenance
+* Resolve multiprocessing warning, state Python 3.13 support by @rht in https://github.com/projectmesa/mesa/pull/2246
+
+## New Contributors
+* @OrenBochman made their first contribution in https://github.com/projectmesa/mesa/pull/2118
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a3...v3.0.0a4
+
 # 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 → mesa-3.0.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0a3
+Version: 3.0.0a5
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Artificial Life

mesa-3.0.0a5/benchmarks/BoltzmannWealth/__init__.py

@@ -0,0 +1 @@
+"""init file for BoltzmannWealth module."""

{mesa-3.0.0a3 → mesa-3.0.0a5}/benchmarks/BoltzmannWealth/boltzmann_wealth.py

@@ -1,8 +1,21 @@
-# https://github.com/projectmesa/mesa-examples/blob/main/examples/boltzmann_wealth_model_experimental/model.py
+"""boltmann wealth model for performance benchmarking.
+
+https://github.com/projectmesa/mesa-examples/blob/main/examples/boltzmann_wealth_model_experimental/model.py
+"""
+
 import mesa
 
 
 def compute_gini(model):
+    """Calculate gini for wealth in model.
+
+    Args:
+        model: a Model instance
+
+    Returns:
+        float: gini score
+
+    """
     agent_wealths = [agent.wealth for agent in model.agents]
     x = sorted(agent_wealths)
     n = model.num_agents
@@ -19,16 +32,23 @@ class BoltzmannWealth(mesa.Model):
     """
 
     def __init__(self, seed=None, n=100, width=10, height=10):
-        super().__init__()
+        """Initializes the model.
+
+        Args:
+            seed: the seed for random number generator
+            n: the number of agents
+            width: the width of the grid
+            height: the height of the grid
+        """
+        super().__init__(seed)
         self.num_agents = n
         self.grid = mesa.space.MultiGrid(width, height, True)
-        self.schedule = mesa.time.RandomActivation(self)
         self.datacollector = mesa.DataCollector(
             model_reporters={"Gini": compute_gini}, agent_reporters={"Wealth": "wealth"}
         )
         # Create agents
-        for i in range(self.num_agents):
-            a = MoneyAgent(i, self)
+        for _ in range(self.num_agents):
+            a = MoneyAgent(self)
             # Add the agent to a random grid cell
             x = self.random.randrange(self.grid.width)
             y = self.random.randrange(self.grid.height)
@@ -38,11 +58,18 @@ class BoltzmannWealth(mesa.Model):
         self.datacollector.collect(self)
 
     def step(self):
-        self.agents.shuffle().do("step")
+        """Run the model for a single step."""
+        self.agents.shuffle_do("step")
         # collect data
         self.datacollector.collect(self)
 
     def run_model(self, n):
+        """Run the model for n steps.
+
+        Args:
+            n: the number of steps for which to run the model
+
+        """
         for _i in range(n):
             self.step()
 
@@ -50,11 +77,17 @@ class BoltzmannWealth(mesa.Model):
 class MoneyAgent(mesa.Agent):
     """An agent with fixed initial wealth."""
 
-    def __init__(self, unique_id, model):
-        super().__init__(unique_id, model)
+    def __init__(self, model):
+        """Instantiate an agent.
+
+        Args:
+            model: a Model instance
+        """
+        super().__init__(model)
         self.wealth = 1
 
     def move(self):
+        """Move the agent to a random neighboring cell."""
         possible_steps = self.model.grid.get_neighborhood(
             self.pos, moore=True, include_center=False
         )
@@ -62,6 +95,7 @@ class MoneyAgent(mesa.Agent):
         self.model.grid.move_agent(self, new_position)
 
     def give_money(self):
+        """Give money to a random cell mate."""
         cellmates = self.model.grid.get_cell_list_contents([self.pos])
         cellmates.pop(
             cellmates.index(self)
@@ -72,6 +106,7 @@ class MoneyAgent(mesa.Agent):
             self.wealth -= 1
 
     def step(self):
+        """Run the agent for 1 step."""
         self.move()
         if self.wealth > 0:
             self.give_money()

mesa-3.0.0a5/benchmarks/Flocking/__init__.py

@@ -0,0 +1 @@
+"""initi for flocking benchmark model."""

{mesa-3.0.0a3 → mesa-3.0.0a5}/benchmarks/Flocking/flocking.py

@@ -1,7 +1,5 @@
-"""
-Flockers
-=============================================================
-A Mesa implementation of Craig Reynolds's Boids flocker model.
+"""A Mesa implementation of Craig Reynolds's Boids flocker model.
+
 Uses numpy arrays to represent vectors.
 """
 
@@ -11,8 +9,7 @@ import mesa
 
 
 class Boid(mesa.Agent):
-    """
-    A Boid-style flocker agent.
+    """A Boid-style flocker agent.
 
     The agent follows three behaviors to flock:
         - Cohesion: steering towards neighboring agents.
@@ -27,7 +24,6 @@ class Boid(mesa.Agent):
 
     def __init__(
         self,
-        unique_id,
         model,
         speed,
         direction,
@@ -37,11 +33,10 @@ class Boid(mesa.Agent):
         separate=0.015,
         match=0.05,
     ):
-        """
-        Create a new Boid flocker agent.
+        """Create a new Boid flocker agent.
 
         Args:
-            unique_id: Unique agent identifier.
+            model: a Model instance
             speed: Distance to move per step.
             direction: numpy vector for the Boid's direction of movement.
             vision: Radius to look around for nearby Boids.
@@ -51,7 +46,7 @@ class Boid(mesa.Agent):
             match: the relative importance of matching neighbors' directions
 
         """
-        super().__init__(unique_id, model)
+        super().__init__(model)
         self.speed = speed
         self.direction = direction
         self.vision = vision
@@ -61,10 +56,7 @@ class Boid(mesa.Agent):
         self.match_factor = match
 
     def step(self):
-        """
-        Get the Boid's neighbors, compute the new vector, and move accordingly.
-        """
-
+        """Get the Boid's neighbors, compute the new vector, and move accordingly."""
         neighbors = self.model.space.get_neighbors(self.pos, self.vision, False)
         n = 0
         match_vector, separation_vector, cohere = np.zeros((3, 2))
@@ -86,9 +78,7 @@ class Boid(mesa.Agent):
 
 
 class BoidFlockers(mesa.Model):
-    """
-    Flocker model class. Handles agent creation, placement and scheduling.
-    """
+    """Flocker model class. Handles agent creation, placement and scheduling."""
 
     def __init__(
         self,
@@ -104,18 +94,21 @@ class BoidFlockers(mesa.Model):
         match=0.05,
         simulator=None,
     ):
-        """
-        Create a new Flockers model.
+        """Create a new Flockers model.
 
         Args:
+            seed: seed for random number generator
             population: Number of Boids
-            width, height: Size of the space.
+            width: the width of the space
+            height: the height of the space
             speed: How fast should the Boids move.
             vision: How far around should each Boid look for its neighbors
-            separation: What's the minimum distance each Boid will attempt to
-                    keep from any other
-            cohere, separate, match: factors for the relative importance of
+            separation: What's the minimum distance each Boid will attempt to keep from any other
+            cohere: the relative importance of matching neighbors' positions'
+            separate: the relative importance of avoiding close neighbors
+            match: factors for the relative importance of
                     the three drives.
+            simulator: a Simulator Instance
         """
         super().__init__(seed=seed)
         self.population = population
@@ -123,7 +116,6 @@ class BoidFlockers(mesa.Model):
         self.height = height
         self.simulator = simulator
 
-        self.schedule = mesa.time.RandomActivation(self)
         self.space = mesa.space.ContinuousSpace(self.width, self.height, True)
         self.factors = {
             "cohere": cohere,
@@ -131,13 +123,12 @@ class BoidFlockers(mesa.Model):
             "match": match,
         }
 
-        for i in range(self.population):
+        for _ in range(self.population):
             x = self.random.random() * self.space.x_max
             y = self.random.random() * self.space.y_max
             pos = np.array((x, y))
             direction = np.random.random(2) * 2 - 1
             boid = Boid(
-                unique_id=i,
                 model=self,
                 speed=speed,
                 direction=direction,
@@ -146,10 +137,10 @@ class BoidFlockers(mesa.Model):
                 **self.factors,
             )
             self.space.place_agent(boid, pos)
-            self.schedule.add(boid)
 
     def step(self):
-        self.schedule.step()
+        """Run the model for one step."""
+        self.agents.shuffle_do("step")
 
 
 if __name__ == "__main__":

mesa-3.0.0a5/benchmarks/Schelling/__init__.py

@@ -0,0 +1 @@
+"""Schelling separation for performance benchmarking."""

{mesa-3.0.0a3 → mesa-3.0.0a5}/benchmarks/Schelling/schelling.py

@@ -1,29 +1,30 @@
+"""Schelling separation for performance benchmarking."""
+
 from mesa import Model
 from mesa.experimental.cell_space import CellAgent, OrthogonalMooreGrid
-from mesa.time import RandomActivation
 
 
 class SchellingAgent(CellAgent):
-    """
-    Schelling segregation agent
-    """
+    """Schelling segregation agent."""
+
+    def __init__(self, model, agent_type, radius, homophily):
+        """Create a new Schelling agent.
 
-    def __init__(self, unique_id, model, agent_type, radius, homophily):
-        """
-        Create a new Schelling agent.
         Args:
-           unique_id: Unique identifier for the agent.
-           x, y: Agent initial location.
-           agent_type: Indicator for the agent's type (minority=1, majority=0)
+            model: model instance
+            agent_type: type of agent (minority=1, majority=0)
+            radius: size of neighborhood of agent
+            homophily: fraction of neighbors of the same type that triggers movement
         """
-        super().__init__(unique_id, model)
+        super().__init__(model)
         self.type = agent_type
         self.radius = radius
         self.homophily = homophily
 
     def step(self):
+        """Run one step of the agent."""
         similar = 0
-        neighborhood = self.cell.neighborhood(radius=self.radius)
+        neighborhood = self.cell.get_neighborhood(radius=self.radius)
         for neighbor in neighborhood.agents:
             if neighbor.type == self.type:
                 similar += 1
@@ -36,9 +37,7 @@ class SchellingAgent(CellAgent):
 
 
 class Schelling(Model):
-    """
-    Model class for the Schelling segregation model.
-    """
+    """Model class for the Schelling segregation model."""
 
     def __init__(
         self,
@@ -51,22 +50,22 @@ class Schelling(Model):
         seed=None,
         simulator=None,
     ):
-        """
-        Create a new Schelling model.
+        """Create a new Schelling model.
 
         Args:
-            height, width: Size of the space.
-            density: Initial Chance for a cell to populated
-            minority_pc: Chances for an agent to be in minority class
+            height: height of the grid
+            width: width of the grid
             homophily: Minimum number of agents of same class needed to be happy
             radius: Search radius for checking similarity
-            seed: Seed for Reproducibility
+            density: Initial Chance for a cell to populated
+            minority_pc: Chances for an agent to be in minority class
+            seed: the seed for the random number generator
+            simulator: a simulator instance
         """
         super().__init__(seed=seed)
         self.minority_pc = minority_pc
         self.simulator = simulator
 
-        self.schedule = RandomActivation(self)
         self.grid = OrthogonalMooreGrid(
             [height, width],
             torus=True,
@@ -81,18 +80,13 @@ class Schelling(Model):
         for cell in self.grid:
             if self.random.random() < density:
                 agent_type = 1 if self.random.random() < self.minority_pc else 0
-                agent = SchellingAgent(
-                    self.next_id(), self, agent_type, radius, homophily
-                )
+                agent = SchellingAgent(self, agent_type, radius, homophily)
                 agent.move_to(cell)
-                self.schedule.add(agent)
 
     def step(self):
-        """
-        Run one step of the model.
-        """
+        """Run one step of the model."""
         self.happy = 0  # Reset counter of happy agents
-        self.schedule.step()
+        self.agents.shuffle_do("step")
 
 
 if __name__ == "__main__":

mesa-3.0.0a5/benchmarks/WolfSheep/__init__.py

@@ -0,0 +1 @@
+"""Wolf-Sheep Predation Model for performance benchmarking."""