Mesa 3.0.0b1__tar.gz → 3.0.0rc0__tar.gz

mesa-3.0.0rc0/.github/pull_request_template.md

@@ -0,0 +1,4 @@
+Thanks for opening a PR! Please click the `Preview` tab and select a PR template:
+
+- [🐛 Bug fix](?expand=1&template=bug.md)
+- [🛠 Feature/enhancement](?expand=1&template=feature.md)

{mesa-3.0.0b1 → mesa-3.0.0rc0}/.gitignore

@@ -1,6 +1,10 @@
 # Benchmarking
 benchmarks/**/*.pickle
 
+# exampledocs
+docs/examples/*
+docs/example.md
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

{mesa-3.0.0b1 → mesa-3.0.0rc0}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.6.3
+  rev: v0.7.2
   hooks:
     # Run the linter.
     - id: ruff
@@ -14,12 +14,12 @@ repos:
     - id: ruff-format
       types_or: [ python, pyi, jupyter ]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.17.0
+    rev: v3.19.0
     hooks:
     -   id: pyupgrade
         args: [--py310-plus]
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0  # Use the ref you want to point at
+    rev: v5.0.0  # Use the ref you want to point at
     hooks:
     -   id: trailing-whitespace
     -   id: check-toml

{mesa-3.0.0b1 → mesa-3.0.0rc0}/HISTORY.md

@@ -1,15 +1,75 @@
 ---
 title: Release History
 ---
+# 3.0.0b2 (2024-10-26)
+## Highlights
+Mesa 3.0 beta 2 includes major work on the example models, docs, a new tutorial and visualisation.
 
-# 3.0.0b1 (2024-10-17)
+The included example models are now part of the Mesa package itself and directly importable, using:
+```Python
+from mesa.examples import BoidFlockers, BoltzmannWealthModel, ConwaysGameOfLife, ...
+```
+The advanced examples were also restructured and cleaned up.
+
+The tutorial was completely rewritten for Mesa 3.0, including it's latest features and practices. Many of our other docs also received some love, and almost everything is now ready for Mesa 3.0.
+
+A new feature to remove all agents from the model was added, and the visualisation now supports drawing the experimental discrete spaces in both matplotlib and altair. All agents which are in a space can now conveniently be accessed with `.agents`.
 
+The rarely used `mesa startproject` cookiecutter feature was removed. We updated our best-practice guide to include how to structure a modern Mesa project, which is now very straightforward.
+
+## What's Changed
+### ⚠️ Breaking changes
+* remove cookiecutter by @quaquel in https://github.com/projectmesa/mesa/pull/2421
+### 🧪 Experimental features
+* Add support for drawing discrete grids by @quaquel in https://github.com/projectmesa/mesa/pull/2386
+* Altair spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2397
+### 🎉 New features added
+* remove_all_agents method added to model by @quaquel in https://github.com/projectmesa/mesa/pull/2394
+* Pass through model.rgn in agent analogous to model.random by @quaquel in https://github.com/projectmesa/mesa/pull/2400
+* add agents property to all spaces by @quaquel in https://github.com/projectmesa/mesa/pull/2418
+### 🛠 Enhancements made
+* update_tutorial environment by @tpike3 in https://github.com/projectmesa/mesa/pull/2411
+### 🐛 Bugs fixed
+* Fix for mistaken removal of _draw_grid by @quaquel in https://github.com/projectmesa/mesa/pull/2398
+* fixes weakref bug in shuffe_do by @quaquel in https://github.com/projectmesa/mesa/pull/2399
+### 🔍 Examples updated
+* refactor: Simplify Schelling code by @rht in https://github.com/projectmesa/mesa/pull/2353
+* Move examples into mesa by @Corvince in https://github.com/projectmesa/mesa/pull/2387
+* Explicitly test basic examples by @quaquel in https://github.com/projectmesa/mesa/pull/2390
+* Make example import absolute by @quaquel in https://github.com/projectmesa/mesa/pull/2402
+* Cleanup and restructure EpsteinCivilViolence and PdGrid examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2408
+* Reorganize advanced examples: wolf_sheep and sugarscape_g1mt by @quaquel in https://github.com/projectmesa/mesa/pull/2410
+* reactivate ruff for advanced examples and include them in tests by @quaquel in https://github.com/projectmesa/mesa/pull/2414
+### 📜 Documentation improvements
+* Include examples in readthedocs (port) by @EwoutH in https://github.com/projectmesa/mesa/pull/2392
+* Update into_tutorial by @tpike3 in https://github.com/projectmesa/mesa/pull/2372
+* Update Schelling Readme.md by @quaquel in https://github.com/projectmesa/mesa/pull/2406
+* Update Conway example by @quaquel in https://github.com/projectmesa/mesa/pull/2403
+* Boltzman readme by @quaquel in https://github.com/projectmesa/mesa/pull/2405
+* Update Readme.md of Boid flockers by @quaquel in https://github.com/projectmesa/mesa/pull/2404
+* add advanced examples to rtd by @quaquel in https://github.com/projectmesa/mesa/pull/2413
+* Tutorial Improvements by @tpike3 in https://github.com/projectmesa/mesa/pull/2415
+* space: Add note that Grids are maintenance only by @EwoutH in https://github.com/projectmesa/mesa/pull/2420
+* Migration guide: Update automatic unique_id assignment examples by @EwoutH in https://github.com/projectmesa/mesa/pull/2419
+* Update docstring of SimEvent by @quaquel in https://github.com/projectmesa/mesa/pull/2417
+* best-practices: Update Model Layout section by @EwoutH in https://github.com/projectmesa/mesa/pull/2424
+* docs: Clean-up index.md by @EwoutH in https://github.com/projectmesa/mesa/pull/2422
+### 🔧 Maintenance
+* Add empty `pull_request_template.md` to enable PR template chooser by @EwoutH in https://github.com/projectmesa/mesa/pull/2409
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0b1...v3.0.0b2
+
+# 3.0.0b1 (2024-10-17)
 ## Highlights
-Basic exmaples are now importable in Mesa, includes boid_flockers, boltzmann_wealth_model, conways_game_of_life, schelling, and virus_on_network models. With this change they are also integrated into the Mesa tutorial in the docs.
+Mesa 3.0 beta 1 is our last beta release before the Mesa 3.0 stable release. We are restructuring our examples and have move 9 core examples from [mesa-examples](https://github.com/projectmesa/mesa-examples) to mesa itself ([#2358](https://github.com/projectmesa/mesa/pull/2358)). The 5 basic examples are now directly importable ([#2381](https://github.com/projectmesa/mesa/pull/2381)):
+```Python
+from examples.basic import BoidFlockers, BoltzmannWealthModel, ConwaysGameOfLife, Schelling, VirusOnNetwork
+```
+The 5 basic examples will always use stable Mesa features, we are also working on 4 more advanced example which can also include experimental features.
 
-Also, in this release, visualizations are improved by making visualization elements scalable and more clearly labeling the plots.
+All our core examples can now be viewed in the [`examples`](https://github.com/projectmesa/mesa/tree/main/examples) folder. [mesa-examples](https://github.com/projectmesa/mesa-examples) will continue to exists for user showcases. We're also working on making the examples visible in the ReadtheDocs ([#2382](https://github.com/projectmesa/mesa/pull/2382)) and on an website ([mesa-examples#139](https://github.com/projectmesa/mesa-examples/issues/139)). Follow all our work on the examples in this tracking issue [#2364](https://github.com/projectmesa/mesa/issues/2364).
 
-<!-- Release notes generated using configuration in .github/release.yml at main -->
+Furthermore, the visualizations are improved by making visualization elements scalable and more clearly labeling the plots, and the Model now has an `rng` argument for an [SPEC 7](https://scientific-python.org/specs/spec-0007/) compliant NumPy random number generator ([#2352](https://github.com/projectmesa/mesa/pull/2352)). Following SPEC 7, you have to pass either `seed` or `rng`. Whichever one you pass will be used to seed both `random.Random`, and `numpy.random.Generator.`
 
 ## What's Changed
 ### ⚠️ Breaking changes

{mesa-3.0.0b1 → mesa-3.0.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0b1
+Version: 3.0.0rc0
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -27,7 +27,6 @@ Requires-Dist: numpy
 Requires-Dist: pandas
 Requires-Dist: tqdm
 Provides-Extra: all
-Requires-Dist: cookiecutter; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
 Requires-Dist: matplotlib; extra == 'all'
 Requires-Dist: myst-nb; extra == 'all'
@@ -43,7 +42,6 @@ Requires-Dist: seaborn; extra == 'all'
 Requires-Dist: solara; extra == 'all'
 Requires-Dist: sphinx; extra == 'all'
 Provides-Extra: dev
-Requires-Dist: cookiecutter; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
 Requires-Dist: networkx; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'

{mesa-3.0.0b1 → mesa-3.0.0rc0}/benchmarks/Schelling/schelling.py

@@ -34,11 +34,10 @@ class SchellingAgent(CellAgent):
 
     def step(self):
         """Run one step of the agent."""
-        similar = 0
-        neighborhood = self.cell.get_neighborhood(radius=self.radius)
-        for neighbor in neighborhood.agents:
-            if neighbor.type == self.type:
-                similar += 1
+        neighbors = self.cell.get_neighborhood(radius=self.radius).agents
+        similar = len(
+            [neighbor for neighbor in neighbors if neighbor.type == self.type]
+        )
 
         # If unhappy, move:
         if similar < self.homophily:
@@ -76,7 +75,6 @@ class Schelling(Model):
         """
         super().__init__(seed=seed)
         self.simulator = simulator
-        self.minority_pc = minority_pc
         self.happy = 0
 
         self.grid = OrthogonalMooreGrid(
@@ -92,7 +90,7 @@ class Schelling(Model):
         # its contents. (coord_iter)
         for cell in self.grid:
             if self.random.random() < density:
-                agent_type = 1 if self.random.random() < self.minority_pc else 0
+                agent_type = 1 if self.random.random() < minority_pc else 0
                 SchellingAgent(self, agent_type, radius, homophily, cell)
 
     def step(self):

mesa-3.0.0rc0/binder/environment.yml

@@ -0,0 +1,14 @@
+name: example-environment
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - numpy
+  - pip
+  - pip:
+    - nbgitpuller
+    - pandas
+    - matplotlib
+    - seaborn
+    - solara
+    - mesa[rec]==3.0.0b1

{mesa-3.0.0b1 → mesa-3.0.0rc0}/docs/README.md

@@ -1,15 +1,14 @@
-Docs for Mesa
-=============
+# Docs for Mesa
 
 The readable version of the docs is hosted at [mesa.readthedocs.org](http://mesa.readthedocs.org/).
 
 This folder contains the docs that build the docs for the core mesa code on readthdocs.
 
-### How to publish updates to the docs
+## How to publish updates to the docs
 
 Updating docs can be confusing. Here are the basic setups.
 
-##### Submit a pull request with updates
+#### Submit a pull request with updates
 1. Create branch (either via branching or fork of repo) -- try to use a descriptive name.
     * `git checkout -b doc-updates`
 1. Update the docs. Save.
@@ -23,7 +22,7 @@ Updating docs can be confusing. Here are the basic setups.
     * `git push origin doc-updates`
 1. From here you will want to submit a pull request to main.
 
-##### Update read the docs
+#### Update read the docs
 
 From this point, you will need to find someone that has access to readthedocs. Currently, that is [@jackiekazil](https://github.com/jackiekazil), [@rht](https://github.com/rht), and [@tpike3](https://github.com/dmasad).
 

{mesa-3.0.0b1 → mesa-3.0.0rc0}/docs/apis/experimental.md

@@ -3,11 +3,6 @@ This namespace contains experimental features. These are under development, and
 
 ## Cell Space
 
-```{eval-rst}
-.. automodule:: experimental.cell_space.__init__
-   :members:
-```
-
 ```{eval-rst}
 .. automodule:: experimental.cell_space.cell
    :members:
@@ -40,11 +35,6 @@ This namespace contains experimental features. These are under development, and
 
 ## Devs
 
-```{eval-rst}
-.. automodule:: experimental.devs.__init__
-   :members:
-```
-
 ```{eval-rst}
 .. automodule:: experimental.devs.eventlist
    :members:

mesa-3.0.0rc0/docs/apis/visualization.md

@@ -0,0 +1,47 @@
+# Visualization
+
+For a detailed tutorial, please refer to our [Visualization Tutorial](../tutorials/visualization_tutorial.ipynb).
+
+## Jupyter Visualization
+
+```{eval-rst}
+.. automodule:: mesa.visualization.solara_viz
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## User Parameters
+
+```{eval-rst}
+.. automodule:: mesa.visualization.UserParam
+   :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:
+```

{mesa-3.0.0b1 → mesa-3.0.0rc0}/docs/best-practices.md

@@ -5,26 +5,21 @@ Here are some general principles that have proven helpful for developing models.
 ## Model Layout
 
 A model should be contained in a folder named with lower-case letters and
-underscores, such as `thunder_cats`. Within that directory:
-
-- `README.md` describes the model, how to use it, and any other details.
-  Github will automatically show this file to anyone visiting the directory.
-- `model.py` should contain the model class.  If the file gets large, it may
-  make sense to move the complex bits into other files, but this is the first
-  place readers will look to figure out how the model works.
-- `server.py` should contain the visualization support, including the server
-  class.
-- `run.py` is a Python script that will run the model when invoked via
-  `mesa runserver`.
-
-After the number of files grows beyond a half-dozen, try to use sub-folders to
-organize them. For example, if the visualization uses image files, put those in
-an `images` directory.
-
-The [Schelling](https://github.com/projectmesa/mesa-examples/tree/main/examples/schelling) model is
-a good example of a small well-packaged model.
-
-It's easy to create a cookiecutter mesa model by running `mesa startproject`
+underscores, such as `wolf_sheep`. Within that directory:
+
+- `Readme.md` describes the model, how to use it, and any other details.
+- `model.py` should contain the model class.
+- `agents.py` should contain the agent class(es).
+- `app.py` should contain the Solara-based visualization code (optional).
+
+You can add more files as needed, for example:
+- `run.py` could contain the code to run the model.
+- `batch_run.py` could contain the code to run the model multiple times.
+- `analysis.py` could contain any analysis code.
+
+Input data can be stored in a `data` directory, output data in an `output`, processed results in a `results` directory, images in an `images` directory, etc.
+
+All our [examples](examples) follow this layout.
 
 ## Randomization
 

{mesa-3.0.0b1 → mesa-3.0.0rc0}/docs/conf.py

@@ -14,14 +14,17 @@
 # serve to show the default.
 
 import os
+import os.path as osp
+import pathlib
 import sys
+import string
 from datetime import date
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
+HERE = osp.abspath(osp.dirname(__file__))
 sys.path.insert(0, os.path.abspath("."))
-sys.path.insert(0, "../examples")
 sys.path.insert(0, "../mesa")
 
 
@@ -289,3 +292,76 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+
+
+def write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template):
+    with open(agent_filename) as content_file:
+        agent_file = content_file.read()
+    with open(model_filename) as content_file:
+        model_file = content_file.read()
+    with open(readme_filename) as content_file:
+        readme_file = content_file.read()
+    with open(app_filename) as content_file:
+        app_file = content_file.read()
+
+    with open(md_filepath, "w") as fh:
+        content = template.substitute(
+            dict(agent_file=agent_file, model_file=model_file,
+                 readme_file=readme_file, app_file=app_file)
+        )
+        fh.write(content)
+
+def setup_examples_pages():
+    # create md files for all examples
+    # check what examples exist
+    examples_folder = osp.abspath(osp.join(HERE, "..", "mesa", "examples"))
+    basic_examples = [("basic", f.path) for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() and not f.name.startswith("__") ]
+    advanced_examples = [("advanced", f.path) for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir() and not f.name.startswith("__")]
+    examples = basic_examples + advanced_examples
+
+    with open(os.path.join(HERE, "example_template.txt")) as fh:
+        template = string.Template(fh.read())
+
+    root_folder = pathlib.Path(os.path.join(HERE, "examples"))
+    root_folder.mkdir(parents=True, exist_ok=True)
+    pathlib.Path(os.path.join(root_folder, "basic")).mkdir(parents=True, exist_ok=True)
+    pathlib.Path(os.path.join(root_folder, "advanced")).mkdir(parents=True, exist_ok=True)
+
+    examples_md = []
+    for kind, example in examples:
+        base_name = os.path.basename(os.path.normpath(example))
+
+        agent_filename = os.path.join(example, "agents.py")
+        model_filename = os.path.join(example, "model.py")
+        readme_filename = os.path.join(example, "Readme.md")
+        app_filename = os.path.join(example, "app.py")
+
+        md_filename = f"{base_name}.md"
+        examples_md.append(base_name)
+
+        md_filepath = os.path.join(HERE, "examples", kind, md_filename)
+        write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template)
+
+    # create overview of examples.md
+    with open(os.path.join(HERE, "examples_overview_template.txt")) as fh:
+        template = string.Template(fh.read())
+
+    with open(os.path.join(examples_folder, "README.md")) as fh:
+        readme_md = fh.read()
+
+    with open(os.path.join(HERE, "examples.md"), "w") as fh:
+        content = template.substitute(
+            dict(
+                readme=readme_md,
+            #     examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
+            )
+        )
+        fh.write(content)
+
+def setup(app):
+    setup_examples_pages()
+
+#
+if __name__ == "__main__":
+    setup_examples_pages()

mesa-3.0.0rc0/docs/example_template.txt

@@ -0,0 +1,22 @@
+
+$readme_file
+
+## Agents
+
+```python
+$agent_file
+```
+
+
+## Model
+
+```python
+$model_file
+```
+
+
+## App
+
+```python
+$app_file
+```

mesa-3.0.0rc0/docs/examples_overview_template.txt

@@ -0,0 +1,3 @@
+
+$readme
+

mesa-3.0.0rc0/docs/index.md

@@ -0,0 +1,101 @@
+# Mesa: Agent-based modeling in Python
+
+```{image} https://github.com/projectmesa/mesa/workflows/build/badge.svg
+:target: https://github.com/projectmesa/mesa/actions
+```
+
+```{image} https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg
+:target: https://codecov.io/gh/projectmesa/mesa
+```
+
+```{image} https://img.shields.io/badge/code%20style-black-000000.svg
+:target: https://github.com/psf/black
+```
+
+```{image} https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix
+:target: https://matrix.to/#/#project-mesa:matrix.org
+```
+
+[Mesa] is an Apache2 licensed agent-based modeling (or ABM) framework in Python.
+
+Mesa allows users to quickly create agent-based models using built-in core components (such as spatial grids and agent schedulers) or customized implementations; visualize them using a browser-based interface; and analyze their results using Python's data analysis tools. Its goal is to be the Python-based counterpart to NetLogo, Repast, or MASON.
+
+![A screenshot of the Wolf Sheep model in Mesa|100%](images/wolf_sheep.png)
+*A visualisation of the Wolf Sheep model build with Mesa.*
+
+## Features
+
+- Built-in core modeling components
+- Flexible agent and model management through AgentSet
+- Browser-based Solara visualization
+- Built-in tools for data collection and analysis
+- Example model library
+
+## Using Mesa
+### Installation Options
+
+To install our latest stable release (2.4.x), run:
+
+```bash
+pip install -U mesa
+```
+
+To install our latest Mesa 3.0 beta with recommended dependencies:
+
+```bash
+pip install -U --pre mesa[rec]
+```
+
+### Resources
+
+For help getting started with Mesa, check out these resources:
+
+- [Mesa Overview] - Learn about Mesa's core concepts and components
+- [Mesa Introductory Tutorial] - Build your first agent-based model
+- [Mesa Visualization Tutorial] - Learn how to create interactive visualizations with Solara
+- [Migration Guide] - Upgrade to Mesa 3.0
+- [Mesa Examples] - Browse user-contributed models and implementations
+- [GitHub Discussions] - Ask questions and discuss Mesa
+- [Matrix Chat Room] - Real-time chat with the Mesa community
+
+### Development and Support
+
+Mesa is an open source project and welcomes contributions:
+
+- [GitHub Repository] - Access the source code
+- [Issue Tracker] - Report bugs or suggest features
+- [Contributors Guide] - Learn how to contribute
+
+The original Mesa conference paper is [available here](http://conference.scipy.org.s3-website-us-east-1.amazonaws.com/proceedings/scipy2015/jacqueline_kazil.html).
+
+```{toctree}
+:hidden: true
+:maxdepth: 7
+
+Mesa Overview <overview>
+tutorials/intro_tutorial
+tutorials/visualization_tutorial
+Examples <examples>
+Migration guide <migration_guide>
+Best Practices <best-practices>
+API Documentation <apis/api_main>
+Mesa Packages <packages>
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`
+
+[contributors guide]: https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md
+[github repository]: https://github.com/projectmesa/mesa/
+[github discussions]: https://github.com/projectmesa/mesa/discussions
+[issue tracker]: https://github.com/projectmesa/mesa/issues
+[matrix chat room]: https://matrix.to/#/#project-mesa:matrix.org
+[mesa]: https://github.com/projectmesa/mesa/
+[mesa overview]: overview
+[mesa examples]: https://github.com/projectmesa/mesa-examples
+[mesa introductory tutorial]: tutorials/intro_tutorial
+[mesa visualization tutorial]: tutorials/visualization_tutorial
+[migration guide]: migration_guide

{mesa-3.0.0b1 → mesa-3.0.0rc0}/docs/migration_guide.md

@@ -74,15 +74,32 @@ In Mesa 3.0, `unique_id` for agents is now automatically assigned, simplifying a
 1. Remove `unique_id` from agent initialization:
    ```python
    # Old
+   agent = MyAgent(unique_id=unique_id, model=self, ...)
+   agent = MyAgent(unique_id, self, ...)
    agent = MyAgent(self.next_id(), self, ...)
 
    # New
+   agent = MyAgent(model=self, ...)
    agent = MyAgent(self, ...)
    ```
-2. `Model.next_id()` is deprecated and will always return 0. Remove any calls to this method.
-3. `unique_id` is now unique relative to a Model instance and starts from 1.
-4. If you previously used custom `unique_id` values, you'll need to store that information in a separate attribute.
-5. Deprecation warning: Initializing an agent with two arguments (`unique_id` and `model`) will raise a warning. The `unique_id` argument will be ignored.
+
+2. Remove `unique_id` from Agent super() call:
+   ```python
+   # Old
+   class MyAgent(Agent):
+       def __init__(self, unique_id, model, ...):
+           super().__init__(unique_id, model)
+
+   # New
+   class MyAgent(Agent):
+       def __init__(self, model, ...):
+           super().__init__(model)
+   ```
+
+3. Important notes:
+   - `unique_id` is now automatically assigned relative to a Model instance and starts from 1
+   - `Model.next_id()` is removed
+   - If you previously used custom `unique_id` values, store that information in a separate attribute
 
 - Ref: [PR #2226](https://github.com/projectmesa/mesa/pull/2226), [PR #2260](https://github.com/projectmesa/mesa/pull/2260), Mesa-examples [PR #194](https://github.com/projectmesa/mesa-examples/pull/194), [Issue #2213](https://github.com/projectmesa/mesa/issues/2213)
 
@@ -236,6 +253,8 @@ Ref: Original discussion [#1912](https://github.com/projectmesa/mesa/discussions
 Mesa has adopted a new API for our frontend. If you already migrated to the experimental new SolaraViz you can still use
 the import from mesa.experimental. Otherwise here is a list of things you need to change.
 
+> **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.
+
 #### Model Initialization
 
 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()`.
@@ -251,9 +270,9 @@ from mesa.experimental import SolaraViz
 SolaraViz(model_cls, model_params, agent_portrayal=agent_portrayal)
 
 # new
-from mesa.visualization import SolaraViz, make_space_matplotlib
+from mesa.visualization import SolaraViz, make_space_component
 
-SolaraViz(model, components=[make_space_matplotlib(agent_portrayal)])
+SolaraViz(model, components=[make_space_component(agent_portrayal)])
 ```
 
 #### Plotting "measures"
@@ -264,15 +283,17 @@ SolaraViz(model, components=[make_space_matplotlib(agent_portrayal)])
 # old
 from mesa.experimental import SolaraViz
 
+
 def make_plot(model):
     ...
 
+
 SolaraViz(model_cls, model_params, measures=[make_plot, "foo", ["bar", "baz"]])
 
 # new
-from mesa.visualization import SolaraViz, make_plot_measure
+from mesa.visualization import SolaraViz, make_plot_component
 
-SolaraViz(model, components=[make_plot, make_plot_measure("foo"), make_plot_measure("bar", "baz")])
+SolaraViz(model, components=[make_plot, make_plot_component("foo"), make_plot_component("bar", "baz")])
 ```
 
 #### Plotting text