Mesa 3.2.0__tar.gz → 3.3.0__tar.gz

mesa-3.3.0/.coderabbit.yaml

@@ -0,0 +1,137 @@
+language: en-US
+tone_instructions: ''
+early_access: false
+enable_free_tier: true
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  high_level_summary_placeholder: '@coderabbitai summary'
+  high_level_summary_in_walkthrough: false
+  auto_title_placeholder: '@coderabbitai'
+  auto_title_instructions: ''
+  review_status: false
+  commit_status: true
+  fail_commit_status: false
+  collapse_walkthrough: false
+  changed_files_summary: true
+  sequence_diagrams: true
+  assess_linked_issues: true
+  related_issues: true
+  related_prs: true
+  suggested_labels: true
+  auto_apply_labels: false
+  suggested_reviewers: true
+  auto_assign_reviewers: false
+  poem: true
+  labeling_instructions: []
+  path_filters: []
+  path_instructions: []
+  abort_on_close: true
+  disable_cache: false
+  auto_review:
+    enabled: false
+    auto_incremental_review: false
+    ignore_title_keywords: []
+    labels: []
+    drafts: false
+    base_branches: []
+  finishing_touches:
+    docstrings:
+      enabled: true
+  tools:
+    ast-grep:
+      rule_dirs: []
+      util_dirs: []
+      essential_rules: true
+      packages: []
+    shellcheck:
+      enabled: true
+    ruff:
+      enabled: true
+    markdownlint:
+      enabled: true
+    github-checks:
+      enabled: true
+      timeout_ms: 180000
+    languagetool:
+      enabled: true
+      enabled_rules: []
+      disabled_rules: []
+      enabled_categories: []
+      disabled_categories: []
+      enabled_only: false
+      level: default
+    biome:
+      enabled: true
+    hadolint:
+      enabled: true
+    swiftlint:
+      enabled: true
+    phpstan:
+      enabled: true
+      level: default
+    golangci-lint:
+      enabled: true
+    yamllint:
+      enabled: true
+    gitleaks:
+      enabled: true
+    checkov:
+      enabled: true
+    detekt:
+      enabled: true
+    eslint:
+      enabled: true
+    rubocop:
+      enabled: true
+    buf:
+      enabled: true
+    regal:
+      enabled: true
+    actionlint:
+      enabled: true
+    pmd:
+      enabled: true
+    cppcheck:
+      enabled: true
+    semgrep:
+      enabled: true
+    circleci:
+      enabled: true
+    sqlfluff:
+      enabled: true
+    prismaLint:
+      enabled: true
+    oxc:
+      enabled: true
+    shopifyThemeCheck:
+      enabled: true
+chat:
+  auto_reply: true
+  create_issues: true
+  integrations:
+    jira:
+      usage: auto
+    linear:
+      usage: auto
+knowledge_base:
+  opt_out: false
+  web_search:
+    enabled: true
+  learnings:
+    scope: auto
+  issues:
+    scope: auto
+  jira:
+    usage: auto
+    project_keys: []
+  linear:
+    usage: auto
+    team_keys: []
+  pull_requests:
+    scope: auto
+code_generation:
+  docstrings:
+    language: en-US
+    path_instructions: []

{mesa-3.2.0 → mesa-3.3.0}/.github/workflows/benchmarks.yml

@@ -34,7 +34,7 @@ jobs:
         run: uv pip install --system numpy pandas tqdm tabulate matplotlib solara networkx scipy
       # Benchmarks on the projectmesa main branch
       - name: Checkout main branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: main
           repository: projectmesa/mesa
@@ -50,7 +50,7 @@ jobs:
           name: timings-main
           path: benchmarks/timings_1.pickle
       - name: Checkout PR branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         if: github.event_name == 'pull_request_target'
         with:
           ref: ${{ github.event.pull_request.head.ref }}
@@ -61,7 +61,7 @@ jobs:
       - name: Install Mesa of the PR branch
         run: pip install --no-deps .
       - name: Download benchmark results
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: timings-main
           path: benchmarks

mesa-3.3.0/.github/workflows/build_lint.yml

@@ -0,0 +1,89 @@
+name: build
+
+on:
+  push:
+    branches:
+      - main
+      - release**
+    paths-ignore:
+      - "**.md"
+  pull_request:
+    paths-ignore:
+      - "**.md"
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"
+
+# This will cancel previous run if a newer job that obsoletes the said previous
+# run, is started.
+# Based on https://github.com/zulip/zulip/commit/4a11642cee3c8aec976d305d51a86e60e5d70522
+concurrency:
+  group: "${{ github.workflow }}-${{ github.head_ref || github.run_id }}"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}-latest
+    # We need an explicit timeout because sometimes the batch_runner test never
+    # completes.
+    timeout-minutes: 6
+    strategy:
+      fail-fast: False
+      matrix:
+        os: [windows, ubuntu, macos]
+        python-version: ["3.13"]
+        include:
+          - os: ubuntu
+            python-version: "3.12"
+          - os: ubuntu
+            python-version: "3.11"
+          # Disabled for now. See https://github.com/projectmesa/mesa/issues/1253
+          #- os: ubuntu
+          #  python-version: 'pypy-3.8'
+
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+          cache: "pip"
+      - name: Install uv
+        run: pip install uv
+      - name: Install Mesa and dependencies
+        run: uv pip install --system .[dev]
+      - name: Setup Playwright
+        run: playwright install
+      - name: Test with pytest
+        run: pytest --durations=10 --cov=mesa tests/ --cov-report=xml
+      - if: matrix.os == 'ubuntu'
+        name: Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          allow-prereleases: true
+          cache: "pip"
+      - name: Install uv
+        run: pip install uv
+      - name: Install Mesa
+        run: uv pip install --system .[examples]
+      - name: Checkout mesa-examples
+        uses: actions/checkout@v5
+        with:
+          repository: projectmesa/mesa-examples
+          path: mesa-examples
+      - name: Test examples
+        run: |
+          cd mesa-examples
+          pytest -rA -Werror -Wdefault::FutureWarning -Wi::DeprecationWarning test_examples.py

{mesa-3.2.0 → mesa-3.3.0}/.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
       id-token: write
     steps:
       - name: Checkout source
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:

{mesa-3.2.0 → mesa-3.3.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.9
+  rev: v0.12.7
   hooks:
     # Run the linter.
     - id: ruff
@@ -14,7 +14,7 @@ repos:
     - id: ruff-format
       types_or: [ python, pyi, jupyter ]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.19.1
+    rev: v3.20.0
     hooks:
     -   id: pyupgrade
         args: [--py311-plus]

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

@@ -112,7 +112,7 @@ pre-commit install
 You should no longer have to worry about code formatting. If still in doubt you may run the following command. If the command generates errors, fix all errors that are returned.
 
 ```bash
-ruff .
+ruff check . --fix
 ```
 
 ## Licensing

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

@@ -1,6 +1,70 @@
 ---
 title: Release History
 ---
+# 3.3.0 (2025-09-06)
+## Highlights
+
+The major highlight of release 3.3.0 is the introduction of a new and improved visualization module. This effort was @Sahil-Chhoker's Google Summer of Code project . The new module is backwards compatible and continues to use Solara. It has several new and improved features to include:
+- `AgentPortrayalStyle`: a more user-friendly way to specify agent portrayal
+- `PropertyLayerStyle`:  Makes propertlayer and agent portrayal consistent.
+- `SpaceRender`: a new component for drawing spaces, agents and property layers with extensive customization
+- Improved support for Altair and Maplotlib
+- Multipage support (e.g., users can display simulation  on one page and charts of the model on another)
+- Updated tutorials for visualization
+
+[You can read more about the update here](https://gist.github.com/Sahil-Chhoker/470d78683664dffc05725bd858beb494)
+
+
+In addition, there were many other improvements to mesa, from bug fixes to improved CI/CD pipelines. Thanks to the PyCON sprints and the developers who supported Mesa!
+
+## What's Changed
+### 🧪 Experimental features
+* Introduction of Space Renderer by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2803
+### 🎉 New features added
+* docs/nix flake by @hussainsultan in https://github.com/projectmesa/mesa/pull/2788
+### 🛠 Enhancements made
+* Added `AgentPortrayalStyle` and `PropertyLayerStyle` by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2786
+* Allow image markers to plot agents by @Holzhauer in https://github.com/projectmesa/mesa/pull/2799
+* Renderer null check fix in solaraviz by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2809
+* Add Altair plotting functionality by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2810
+* Fix: Grid not showing in altair if both draw_structure and draw_agnets are called. by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2817
+* Allowing color mapping to integers in AgentPortrayalStyle by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2818
+* Added multipage functionality by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2827
+### 🐛 Bugs fixed
+* Bugfix ModelCreator for required model parameters and user adjusted model parameters by @Holzhauer in https://github.com/projectmesa/mesa/pull/2780
+* Remove unneeded int cast by @derkweijers in https://github.com/projectmesa/mesa/pull/2791
+* Add quotes to readme to insure multi-terminal compliance. by @jackiekazil in https://github.com/projectmesa/mesa/pull/2787
+* Fix broken docs link - Fix issue 2792 by @catherinedevlin in https://github.com/projectmesa/mesa/pull/2793
+* Bug fixes for portrayal components by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2798
+* fix : prevent breakdown when citizen_density (Initial Agent Density s… by @colinfrisch in https://github.com/projectmesa/mesa/pull/2806
+* Fix issue #2812 by @Tosiekdev in https://github.com/projectmesa/mesa/pull/2821
+### 📜 Documentation improvements
+* Benchmarks documentation by @colinfrisch in https://github.com/projectmesa/mesa/pull/2764
+* minor corrections in tutorials by @Holzhauer in https://github.com/projectmesa/mesa/pull/2778
+* Correct example code in "Overview of the MESA library" by @Holzhauer in https://github.com/projectmesa/mesa/pull/2781
+* Updating Examples and Docs inline with the new API. by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2819
+### 🔧 Maintenance
+* Add `.coderabbit.yaml` file to allow reviewing and updating our CodeRabbit configuration by @EwoutH in https://github.com/projectmesa/mesa/pull/2761
+* add nix flake by @hussainsultan in https://github.com/projectmesa/mesa/pull/2785
+* Removing Deprecations Warnings from `agent_portrayal` and `propertylayer_portrayal` until next release. by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2797
+* Added Basic Visualization tests by @Sahil-Chhoker in https://github.com/projectmesa/mesa/pull/2767
+### Other changes
+* Update __init__.py by @tpike3 in https://github.com/projectmesa/mesa/pull/2770
+* [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in https://github.com/projectmesa/mesa/pull/2751
+* [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in https://github.com/projectmesa/mesa/pull/2802
+* [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in https://github.com/projectmesa/mesa/pull/2808
+* Bump actions/download-artifact from 4 to 5 by @dependabot[bot] in https://github.com/projectmesa/mesa/pull/2826
+* Bump actions/checkout from 4 to 5 by @dependabot[bot] in https://github.com/projectmesa/mesa/pull/2825
+* [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in https://github.com/projectmesa/mesa/pull/2823
+
+## New Contributors
+* @derkweijers made their first contribution in https://github.com/projectmesa/mesa/pull/2791
+* @hussainsultan made their first contribution in https://github.com/projectmesa/mesa/pull/2785
+* @catherinedevlin made their first contribution in https://github.com/projectmesa/mesa/pull/2793
+* @Tosiekdev made their first contribution in https://github.com/projectmesa/mesa/pull/2821
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.2.0...v3.3.0
+
 # 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Mesa
-Version: 3.2.0
+Version: 3.3.0
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -24,19 +24,24 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Life
 Requires-Python: >=3.11
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: pythran>=0.17.0; sys_platform == 'darwin'
 Requires-Dist: scipy
 Requires-Dist: tqdm
 Provides-Extra: all
 Requires-Dist: altair; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
+Requires-Dist: ipython>=9.2.0; extra == 'all'
 Requires-Dist: matplotlib; extra == 'all'
 Requires-Dist: myst-nb; extra == 'all'
 Requires-Dist: myst-parser; extra == 'all'
 Requires-Dist: networkx; extra == 'all'
+Requires-Dist: playwright; extra == 'all'
 Requires-Dist: pydata-sphinx-theme; extra == 'all'
 Requires-Dist: pytest; extra == 'all'
 Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest-ipywidgets; extra == 'all'
 Requires-Dist: pytest-mock; extra == 'all'
+Requires-Dist: pytest-playwright; extra == 'all'
 Requires-Dist: ruff; extra == 'all'
 Requires-Dist: scipy; extra == 'all'
 Requires-Dist: seaborn; extra == 'all'
@@ -45,11 +50,15 @@ Requires-Dist: sphinx; extra == 'all'
 Requires-Dist: sphinx-copybutton; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: altair; extra == 'dev'
+Requires-Dist: ipython>=9.2.0; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
 Requires-Dist: networkx; extra == 'dev'
+Requires-Dist: playwright; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-ipywidgets; extra == 'dev'
 Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: pytest-playwright; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: solara; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
@@ -125,13 +134,13 @@ pip install -U mesa
 Starting with Mesa 3.0, we don't install all our dependencies anymore by default.
 ```bash
 # You can customize the additional dependencies you need, if you want. Available are:
-pip install -U mesa[network,viz]
+pip install -U "mesa[network,viz]"
 
 # This is equivalent to our recommended dependencies:
-pip install -U mesa[rec]
+pip install -U "mesa[rec]"
 
 # To install all, including developer, dependencies:
-pip install -U mesa[all]
+pip install -U "mesa[all]"
 ```
 
 You can also use `pip` to install the latest GitHub version:

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

@@ -38,13 +38,13 @@ pip install -U mesa
 Starting with Mesa 3.0, we don't install all our dependencies anymore by default.
 ```bash
 # You can customize the additional dependencies you need, if you want. Available are:
-pip install -U mesa[network,viz]
+pip install -U "mesa[network,viz]"
 
 # This is equivalent to our recommended dependencies:
-pip install -U mesa[rec]
+pip install -U "mesa[rec]"
 
 # To install all, including developer, dependencies:
-pip install -U mesa[all]
+pip install -U "mesa[all]"
 ```
 
 You can also use `pip` to install the latest GitHub version:

mesa-3.3.0/benchmarks/README.md

@@ -0,0 +1,99 @@
+# Mesa Performance Benchmarks
+
+The `/benchmarks` directory contains tools for benchmarking the Mesa library performance on the included example models. This allows to track and compare model initialisation time and runtime between different Mesa versions.
+
+MESA uses several example base models for benchmarking performance (BoltzmannWealth, Schelling, BoidFlockers, and WolfSheep) by calculating the initialization time and run time for each of these models. These example models can be found in the `/mesa/examples` directory.
+
+## Available Files
+
+- `configurations.py`: Contains model configurations for benchmarking
+- `global_benchmark.py`: Main script for running benchmarks
+- `compare_timings.py`: Tool to compare results between benchmark runs
+
+## How to Use
+
+
+### 1. Benchmark Configuration
+
+The `configurations.py` file defines which models to benchmark and their parameters. Each model has:
+
+- `small` and `large` configurations for testing different scales
+- Parameters for:
+  - `seeds`: Number of different random seeds to use
+  - `replications`: Number of times to repeat the benchmark for each seed
+  - `steps`: Number of model steps to run
+  - `parameters`: Model-specific parameters
+
+### 2. Running Benchmarks
+
+To run the benchmarks:
+
+```bash
+pip install tabulate # if you don't have it yet
+python global_benchmark.py
+```
+
+This will:
+- Run all models defined in `configurations.py` with their respective configurations
+- Measure initialization time and run time for each model
+- Save results to a pickle file named `timings_X.pickle` (where X is an incremental number)
+- Display a summary of results in the terminal
+
+
+>**Noteworthy :** the pickle file created by the benchmark is not under git control. So you can run the benchmark on the master branch first, switch to your development branch, and run the benchmarks again.
+
+#### What's being measured:
+
+- **Initialization time**: How long it takes to create model instances
+- **Run time**: How long it takes to run the model for the specified number of steps
+
+### 3. Comparing Results
+
+After running benchmarks at different times (e.g., before and after code changes), you can compare the results:
+
+1. Rename your benchmark files to distinguish them (e.g., `timings_before.pickle` and `timings_after.pickle`)
+2. Edit `compare_timings.py` to use your file names:
+   ```python
+   filename1 = "timings_1" # Or the name of your 1st timings file
+   filename2 = "timings_2" # Or the name of your 2nd timings file
+   ```
+3. Run the comparison:
+   ```bash
+   python compare_timings.py
+   ```
+
+The output will show:
+- Percentage changes in initialization and run times
+- 95% confidence intervals for the changes
+- Emojis indicate performance changes:
+  - 🟢 Faster performance (>3% improvement)
+  - 🔴 Slower performance (>3% regression)
+  - 🔵 Insignificant change (within ±3%)
+
+> Some care is required in the interpretation since it only shows percentage changes and not the absolute changes. The init times in general are tiny so slower performance here is not necissarily as much of an issue.
+
+
+## Example Workflow
+
+1. Run benchmarks on your current Mesa version:
+   ```bash
+   python global_benchmark.py
+   # Results saved as timings_1.pickle
+   ```
+
+2. Make code changes (add a feature in mesa, optimize a method, etc.) **OR** switch to development branch - you can do that without duplicating your pickle file in the new branch as it is not under git control
+
+
+3. Run benchmarks again:
+   ```bash
+   python global_benchmark.py
+   # Results saved as timings_2.pickle
+   ```
+
+4. Compare results:
+   ```bash
+   python compare_timings.py
+   # Shows performance change table
+   ```
+
+5. Use the results to validate your optimizations or identify regressions

mesa-3.3.0/docs/apis/visualization.md

@@ -0,0 +1,130 @@
+# Visualization
+
+For detailed tutorials, please refer to:
+
+- [Basic Visualization](../tutorials/4_visualization_basic)
+- [Dynamic Agent Visualization](../tutorials/5_visualization_dynamic_agents)
+- [Custom Agent Visualization](../tutorials/6_visualization_custom)
+
+
+## Jupyter Visualization
+
+```{eval-rst}
+.. automodule:: mesa.visualization.solara_viz
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.components.__init__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## User Parameters
+
+```{eval-rst}
+.. automodule:: mesa.visualization.user_param
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Matplotlib-based visualizations
+
+```{eval-rst}
+.. automodule:: mesa.visualization.components.matplotlib_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.mpl_space_drawing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Altair-based visualizations
+
+```{eval-rst}
+.. automodule:: mesa.visualization.components.altair_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Command Console
+
+```{eval-rst}
+.. automodule:: mesa.visualization.command_console
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Portrayal Components
+```{eval-rst}
+.. automodule:: mesa.visualization.components.portrayal_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Backends
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.__init__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.abstract_renderer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.altair_backend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.matplotlib_backend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Space Renderer
+
+```{eval-rst}
+.. automodule:: mesa.visualization.space_renderer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Space Drawers
+
+```{eval-rst}
+.. automodule:: mesa.visualization.space_drawers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```