Mesa 3.1.0.dev0__tar.gz → 3.1.1__tar.gz

{mesa-3.1.0.dev0 → mesa-3.1.1}/.codespellignore

@@ -7,3 +7,4 @@ ue
 fpr
 falsy
 assertIn
+nD

{mesa-3.1.0.dev0 → mesa-3.1.1}/.github/PULL_REQUEST_TEMPLATE/bug.md

@@ -1,16 +1,16 @@
-## Summary
+### Summary
 <!-- Provide a brief summary of the bug and its impact. -->
 
-## Bug / Issue
+### Bug / Issue
 <!-- Link to the related issue(s) and describe the bug. Include details like the context, what was expected, and what actually happened. -->
 
-## Implementation
+### Implementation
 <!-- Describe the changes made to resolve the issue. Highlight any important parts of the code that were modified. -->
 
-## Testing
+### Testing
 <!-- Detail the testing performed to verify the fix. Include information on test cases, steps taken, and any relevant results.
 
 If you're fixing the visualisation, add before/after screenshots. -->
 
-## Additional Notes
+### Additional Notes
 <!-- Add any additional information that may be relevant for the reviewers, such as potential side effects, dependencies, or related work.

{mesa-3.1.0.dev0 → mesa-3.1.1}/.github/PULL_REQUEST_TEMPLATE/feature.md

@@ -1,16 +1,16 @@
-## Summary
+### Summary
 <!-- Provide a concise summary of the feature and its purpose. -->
 
-## Motive
+### Motive
 <!-- Explain the reasoning behind this feature. Include details on the problem it addresses or the enhancement it provides. -->
 
-## Implementation
+### Implementation
 <!-- Describe how the feature was implemented. Include details on the approach taken, important decisions made, and code changes. -->
 
-## Usage Examples
+### Usage Examples
 <!-- Provide code snippets or examples demonstrating how to use the new feature. Highlight key scenarios where this feature will be beneficial.
 
 If you're modifying the visualisation, add before/after screenshots. -->
 
-## Additional Notes
+### Additional Notes
 <!-- Add any additional information that may be relevant for the reviewers, such as potential side effects, dependencies, or related work. -->

{mesa-3.1.0.dev0 → mesa-3.1.1}/.github/workflows/build_lint.yml

@@ -57,7 +57,7 @@ jobs:
       run: pytest --durations=10 --cov=mesa tests/ --cov-report=xml
     - if: matrix.os == 'ubuntu'
       name: Codecov
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5
       with:
         fail_ci_if_error: true
         token: ${{ secrets.CODECOV_TOKEN }}

{mesa-3.1.0.dev0 → mesa-3.1.1}/.pre-commit-config.yaml

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

{mesa-3.1.0.dev0 → mesa-3.1.1}/Dockerfile

@@ -1,14 +1,12 @@
 # We can't use slim because we need either git/wget/curl to
 # download mesa-examples, and so installing them requires
 # updating the system anyway.
-# We can't use alpine because NumPy doesn't support musllinux yet.
-# But it's in the RC version https://github.com/numpy/numpy/issues/20089.
 FROM python:bookworm
-LABEL maintainer="rht <rhtbot@protonmail.com>"
+LABEL maintainer="projectmesa maintainers@projectmesa.dev"
 
 # To use this Dockerfile:
-# 1. `docker build . -t mymesa_image`
-# 2. `docker run --name mymesa_instance -p 8765:8765 -it mymesa_image`
+# 1. `docker build . -t mesa_image`
+# 2. `docker run --name mesa_instance -p 8765:8765 -it mesa_image`
 # 3. In your browser, visit http://127.0.0.1:8765
 #
 # Currently, this Dockerfile defaults to running the Schelling model, as an
@@ -19,7 +17,7 @@ LABEL maintainer="rht <rhtbot@protonmail.com>"
 # `docker run --name mymesa_instance -p 8765:8765 -e MODEL_DIR=/mesa-examples/examples/sugarscape_cg -it mymesa_image`
 # Note: the model directory MUST contain an app.py file.
 
-ENV MODEL_DIR=/mesa-examples/examples/schelling_experimental
+ENV MODEL_DIR=/opt/mesa/mesa/examples/basic/schelling
 
 # Don't buffer output:
 # https://docs.python.org/3.10/using/cmdline.html?highlight=pythonunbuffered#envvar-PYTHONUNBUFFERED
@@ -29,10 +27,11 @@ WORKDIR /opt/mesa
 
 COPY . /opt/mesa
 
-RUN cd / && git clone https://github.com/projectmesa/mesa-examples.git
-
 EXPOSE 8765/tcp
 
-RUN pip3 install -e /opt/mesa
+RUN pip3 install -e /opt/mesa[rec]
 
 CMD ["sh", "-c", "cd $MODEL_DIR && solara run app.py --host=0.0.0.0"]
+
+# To check file system:
+# docker exec -it mesa_instance bash

{mesa-3.1.0.dev0 → mesa-3.1.1}/HISTORY.md

@@ -1,6 +1,110 @@
 ---
 title: Release History
 ---
+# 3.1.1 (2024-12-14)
+## Highlights
+Mesa 3.1.1 is a maintenance release that includes visualization improvements and documentation updates. The key enhancement is the addition of an interactive play interval control to the visualization interface, allowing users to dynamically adjust simulation speed between 1ms and 500ms through a slider in the Controls panel.
+
+Several example models were updated to use Mesa 3.1's recommended practices, particularly the `create_agents()` method for more efficient agent creation and NumPy's `rng.integers()` for random number generation. The Sugarscape example was modernized to use PropertyLayers.
+
+Bug fixes include improvements to PropertyLayer visualization and a correction to the Schelling model's neighbor similarity calculation. The tutorials were also updated to reflect current best practices in Mesa 3.1.
+
+## What's Changed
+### 🎉 New features added
+* Add Interactive Play Interval Control to Mesa Visualization by @AdamZh0u in https://github.com/projectmesa/mesa/pull/2540
+### 🐛 Bugs fixed
+* bug fixes for draw_property_layers by @quaquel in https://github.com/projectmesa/mesa/pull/2548
+### 🔍 Examples updated
+* Wolf-sheep to use `create_agent` by @quaquel in https://github.com/projectmesa/mesa/pull/2543
+* Shift sugarscape example to using create_agent by @quaquel in https://github.com/projectmesa/mesa/pull/2544
+* Fix: Schelling Model Neighbor Similarity Calculation by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2518
+* Change pd_grid example to use create_agents by @quaquel in https://github.com/projectmesa/mesa/pull/2545
+* Switch sugarscape to using property layers by @quaquel in https://github.com/projectmesa/mesa/pull/2546
+### 📜 Documentation improvements
+* Updated docs and check_model param by @nissu99 in https://github.com/projectmesa/mesa/pull/2510
+* Update tutorials to use `create_agents` and `rng.integers` by @DarshPareek in https://github.com/projectmesa/mesa/pull/2541
+
+## New Contributors
+* @nissu99 made their first contribution in https://github.com/projectmesa/mesa/pull/2510
+* @DarshPareek made their first contribution in https://github.com/projectmesa/mesa/pull/2541
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.1.0...3.1.1
+
+# 3.1.0 (2024-12-04)
+## Highlights
+With Mesa 3.1.0 we're back on our regular release schedule after the big Mesa 3.0 release, with some exciting new features.
+
+This release adds experimental support for Observables and Computed, enabling a more reactive and responsive programming model for agent-based simulations. The new `Observable` and `Computable` classes allow developers to declaratively define attributes that automatically emit signals when their values change, and compute derived values that update dynamically. This lays the groundwork for more advanced event handling and data visualization features in future releases (#2291).
+
+The experimental cell space module has been updated with full support for n-dimensional property layers. These allow agents to easily interact with and modify spatial properties of the environment, such as terrain, resources, or environmental conditions. The new implementation provides a more intuitive attribute-based API and ensures tight integration with the cell space architecture (#2512).
+
+Mesa now includes built-in support for logging using the standard Python `logging` module. This provides developers with a flexible and powerful way to add structured diagnostic and debug output to their simulations, without the need for custom logging solutions. The logging system is integrated throughout the library, including the new SolaraViz visualization system (#2506).
+
+Creating multiple agents with varying initialization parameters is now significantly easier with the new `Agent.create_agents` class method. This factory function supports both uniform and per-agent parameters, simplifying the code required to set up a simulation with a large number of heterogeneous agents (#2351).
+
+In addition to the major new features, this release includes a number of smaller enhancements and bug fixes that improve the overall developer experience. These include removing deprecated functionality, cleaning up examples, and addressing various edge cases reported by the community. Mesa 3.1 requires Python 3.11 or higher.
+
+## What's Changed
+### 🧪 Experimental features
+* Add support for Observables to MESA by @quaquel in https://github.com/projectmesa/mesa/pull/2291
+* Add full support for property layers to cell spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2512
+### 🎉 New features added
+* Add logging to MESA by @quaquel in https://github.com/projectmesa/mesa/pull/2506
+* Add `create_agents` factory method to Agent by @quaquel in https://github.com/projectmesa/mesa/pull/2351
+### 🔍 Examples updated
+* Add seed control to all examples by @quaquel in https://github.com/projectmesa/mesa/pull/2496
+### 📜 Documentation improvements
+* doc fix for pip install error on mac by @quaquel in https://github.com/projectmesa/mesa/pull/2508
+* Refactored docs for Introductory Tutorial by @Spartan-71 in https://github.com/projectmesa/mesa/pull/2511
+* Add module-level docstring to experimental features by @EwoutH in https://github.com/projectmesa/mesa/pull/2532
+### 🔧 Maintenance
+* Remove deprecated time module by @EwoutH in https://github.com/projectmesa/mesa/pull/2476
+* Drop support for Python 3.10, require Python >= 3.11 by @EwoutH in https://github.com/projectmesa/mesa/pull/2474
+* Remove deprecated functionality by @EwoutH in https://github.com/projectmesa/mesa/pull/2483
+* Remove visualization modules from `mesa.experimental` by @quaquel in https://github.com/projectmesa/mesa/pull/2495
+* Cleanup two occurrences of removed scheduler by @EwoutH in https://github.com/projectmesa/mesa/pull/2499
+* move _setup_agent_registration into `Model.__init__` by @quaquel in https://github.com/projectmesa/mesa/pull/2501
+* remove devs related examples from devs/examples by @quaquel in https://github.com/projectmesa/mesa/pull/2507
+* added empty iterable checks and updated tests by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2523
+* Fix: running Mesa in Docker with Schelling model by @AdamZh0u in https://github.com/projectmesa/mesa/pull/2524
+
+## New Contributors
+* @Spartan-71 made their first contribution in https://github.com/projectmesa/mesa/pull/2511
+* @Sahil-Chhoker made their first contribution in https://github.com/projectmesa/mesa/pull/2523
+* @AdamZh0u made their first contribution in https://github.com/projectmesa/mesa/pull/2524
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.3...v3.1.0
+
+# 3.0.3 (2024-11-14)
+## Highlights
+A small bugfix release that fixes two bugs.
+
+## What's Changed
+### 🧪 Experimental features
+* cell_space: Allow CellCollection to be empty by @EwoutH in https://github.com/projectmesa/mesa/pull/2502
+### 🐛 Bugs fixed
+* Only set model_parameters once by @Corvince in https://github.com/projectmesa/mesa/pull/2505
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.2...v3.0.3
+
+# 3.0.2 (2024-11-11)
+## Highlighst
+Mesa 3.0.2 is a small follow-up patch release, in which we fixed a lot of small bugs in the example models their visualisation, and improved their testing.
+
+## What's Changed
+### 🐛 Bugs fixed
+* allow components as a positional argument again by @Corvince in https://github.com/projectmesa/mesa/pull/2488
+### 🔍 Examples updated
+* examples: Add required components keyword by @EwoutH in https://github.com/projectmesa/mesa/pull/2485
+* examples: Fix boid_flockers viz by @EwoutH in https://github.com/projectmesa/mesa/pull/2492
+* examples: Fix schelling viz by @EwoutH in https://github.com/projectmesa/mesa/pull/2490
+* example: Add input sliders to Sugerscape viz by @EwoutH in https://github.com/projectmesa/mesa/pull/2487
+* examples/gol: Add initial fraction alive, add sliders to viz by @EwoutH in https://github.com/projectmesa/mesa/pull/2489
+### 🔧 Maintenance
+* test app init of examples by @Corvince in https://github.com/projectmesa/mesa/pull/2491
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.1...v3.0.2
+
 # 3.0.1 (2024-11-11)
 ## Highlights
 After our huge [3.0.0 release](https://github.com/projectmesa/mesa/releases/tag/v3.0.0), Mesa 3.0.1 follows up with two improvements to experimental features, examples and docs.

{mesa-3.1.0.dev0 → mesa-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.1.0.dev0
+Version: 3.1.1
 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.0.dev0 → mesa-3.1.1}/codecov.yaml

@@ -7,7 +7,6 @@ coverage:
 
 ignore:
   - "benchmarks/**"
-  - "mesa/experimental/**"
   - "mesa/visualization/**"
 
 comment: off

{mesa-3.1.0.dev0 → mesa-3.1.1}/docker-compose.yml

@@ -16,6 +16,6 @@ services:
       # within the current directory.
       # E.g. if it is at my-model, then you specify it as
       # /opt/mesa/my-model.
-      MODEL_DIR: /mesa-examples/examples/schelling_experimental
+      MODEL_DIR: /opt/mesa/mesa/examples/basic/schelling
     ports:
       - 8765:8765

{mesa-3.1.0.dev0 → mesa-3.1.1}/docs/apis/api_main.md

@@ -10,5 +10,6 @@ space
 datacollection
 batchrunner
 visualization
+logging
 experimental
 ```

mesa-3.1.1/docs/apis/mesa_logging.md

@@ -0,0 +1,7 @@
+# logging
+
+```{eval-rst}
+.. automodule:: mesa.mesa_logging
+   :members:
+   :inherited-members:
+```

{mesa-3.1.0.dev0 → mesa-3.1.1}/docs/getting_started.md

@@ -180,6 +180,16 @@ Mesa now uses a new browser-based visualization system called SolaraViz. This al
 
 > **Note:** SolaraViz is experimental and still in active development for Mesa 3.0. While we attempt to minimize them, there might be API breaking changes between Mesa 3.0 and 3.1. There won't be breaking changes between Mesa 3.0.x patch releases.
 
+> **Note:** SolaraViz instantiates new models using `**model_parameters.value`, so all model inputs must be keyword arguments.
+
+Ensure your model's `__init__` method accepts keyword arguments matching the `model_params` keys.
+
+```python
+class MyModel(Model):
+    def __init__(self, n_agents=10, seed=None):
+        super().__init__(seed=seed)
+        # Initialize the model with N agents
+
 The core functionality for building your own visualizations resides in the [`mesa.visualization`](apis/visualization) namespace
 
 Here's a basic example of how to set up a visualization:

{mesa-3.1.0.dev0 → mesa-3.1.1}/docs/index.md

@@ -43,6 +43,10 @@ To also install our recommended dependencies:
 pip install -U mesa[rec]
 ```
 
+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]"`.
+
+
 To install our latest pre-release:
 
 ```bash

{mesa-3.1.0.dev0 → mesa-3.1.1}/docs/migration_guide.md

@@ -259,6 +259,17 @@ the import from mesa.experimental. Otherwise here is a list of things you need t
 
 Previously SolaraViz was initialized by providing a `model_cls` and a `model_params`. This has changed to expect a model instance `model`. You can still provide (user-settable) `model_params`, but only if users should be able to change them. It is now also possible to pass in a "reactive model" by first calling `model = solara.reactive(model)`. This is useful for notebook environments. It allows you to pass the model to the SolaraViz Module, but continue to use the model. For example calling `model.value.step()` (notice the extra .value) will automatically update the plots. This currently only automatically works for the step method, you can force visualization updates by calling `model.value.force_update()`.
 
+### Model Initialization with Keyword Arguments
+
+With the introduction of SolaraViz in Mesa 3.0, models are now instantiated using `**model_parameters.value`. This means all inputs for initializing a new model must be keyword arguments. Ensure your model's `__init__` method accepts keyword arguments matching the keys in `model_params`.
+
+```python
+class MyModel(mesa.Model):
+    def __init__(self, n_agents=10, seed=None):
+        super().__init__(seed=seed)
+        # Initialize the model with N agents
+```
+
 #### Default space visualization
 
 Previously we included a default space drawer that you could configure with an `agent_portrayal` function. You now have to explicitly create a space drawer with the `agent_portrayal` function

{mesa-3.1.0.dev0 → mesa-3.1.1}/docs/tutorials/MoneyModel.py

@@ -62,12 +62,13 @@ class MoneyModel(mesa.Model):
         self.grid = mesa.space.MultiGrid(width, height, True)
 
         # Create agents
-        for _ in range(self.num_agents):
-            a = MoneyAgent(self)
+        agents = MoneyAgent.create_agents(model=self, n=n)
+        # Create x and y positions for agents
+        x = self.rng.integers(0, self.grid.width, size=(n,))
+        y = self.rng.integers(0, self.grid.height, size=(n,))
+        for a, i, j in zip(agents, x, y):
             # Add the agent to a random grid cell
-            x = self.random.randrange(self.grid.width)
-            y = self.random.randrange(self.grid.height)
-            self.grid.place_agent(a, (x, y))
+            self.grid.place_agent(a, (i, j))
 
         self.datacollector = mesa.DataCollector(
             model_reporters={"Gini": compute_gini}, agent_reporters={"Wealth": "wealth"}