Mesa 3.0.0b2__tar.gz → 3.0.1__tar.gz

{mesa-3.0.0b2 → mesa-3.0.1}/.gitignore

@@ -2,7 +2,8 @@
 benchmarks/**/*.pickle
 
 # exampledocs
-docs/examples/*.md
+docs/examples/*
+docs/example.md
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

{mesa-3.0.0b2 → mesa-3.0.1}/.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.0b2 → mesa-3.0.1}/HISTORY.md

@@ -1,6 +1,202 @@
 ---
 title: Release History
 ---
+# 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.
+
+## What's Changed
+### 🧪 Experimental features
+* Bugfixes to DEVS by @quaquel in https://github.com/projectmesa/mesa/pull/2478
+* Support simulators in SolaraViz by @quaquel in https://github.com/projectmesa/mesa/pull/2470
+### 🛠 Enhancements made
+* issue a user warning if random is None by @quaquel in https://github.com/projectmesa/mesa/pull/2479
+### 🔍 Examples updated
+* Integrate benchmarks and example models by @EwoutH in https://github.com/projectmesa/mesa/pull/2473
+### 📜 Documentation improvements
+* docs/tutorial: Replace scheduler in MoneyModel by @EwoutH in https://github.com/projectmesa/mesa/pull/2475
+* docs: update migration_guide.md by @eltociear in https://github.com/projectmesa/mesa/pull/2480
+* Update some DeprecationWarnings to note they are removed in Mesa 3.1 by @EwoutH in https://github.com/projectmesa/mesa/pull/2481
+
+## New Contributors
+* @eltociear made their first contribution in https://github.com/projectmesa/mesa/pull/2480
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0...v3.0.1
+
+# 3.0.0 (2024-11-09)
+## Highlights
+Mesa 3.0 brings major improvements to agent-based modeling, making it more intuitive and powerful while reducing complexity. This release modernizes core functionalities and introduces new capabilities for both beginners and advanced users.
+
+### Streamlined agent management
+The centerpiece of Mesa 3.0 is its new agent management system. Agents are now automatically tracked and assigned unique IDs, eliminating common boilerplate code. The new AgentSet functionality provides an elegant and flexible way to work with agents, for example:
+
+```python
+# Find agents meeting specific criteria
+wealthy_agents = model.agents.select(lambda a: a.wealth > 1000)
+
+# Group and analyze agents
+grouped = model.agents.groupby("state")
+state_stats = grouped.agg({
+     "count": len,
+     "avg_age": ("age", np.mean),
+     "total_wealth": ("wealth", sum)
+ })
+
+# Activate agents in different patterns
+model.agents.shuffle_do("step")  # Random activation
+model.agents.select(lambda a: a.energy > 0).do("move")  # Conditional activation
+```
+
+The AgentSet provides powerful methods for filtering, grouping, and analyzing agents, making it easier to express complex model logic. Each model automatically maintains an AgentSet containing all agents (`model.agents`) and separate AgentSets for each agent type (`model.agents_by_type`). See the full [AgentSet docs](https://mesa.readthedocs.io/latest/apis/agent.html#mesa.agent.AgentSet) here.
+
+### Modern Visualization with SolaraViz
+Mesa 3.0's new experimental visualization system, SolaraViz, provides a modern, interactive interface for model exploration:
+
+```python
+from mesa.visualization import SolaraViz, make_space_component, make_plot_component
+
+visualization = SolaraViz(
+    model,
+    [
+        make_space_component(agent_portrayal),
+        make_plot_component(["population", "average_wealth"]),
+        lambda m: f"Step {m.steps}: {len(m.agents)} agents"  # Custom text component
+    ],
+    model_params=parameter_controls
+)
+```
+
+Key visualization features:
+- Interactive browser-based interface with real-time updates
+- Support for both grid-based and network models
+- Visualization of PropertyLayers and hexagonal grids
+- Custom components using Matplotlib or text
+- Improved performance and responsiveness
+
+Check out the [Visualization Tutorial](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html) to get started.
+
+*Note: SolaraViz is in active development. We might make API breaking changes between Mesa 3.0 and 3.1.*
+
+### Enhanced data collection
+The DataCollector now supports collecting different metrics for different agent types, using  `agenttype_reporters`:
+
+```python
+self.datacollector = DataCollector(
+    model_reporters={"total_wealth": lambda m: m.agents.agg("wealth", sum)},
+    agent_reporters={"age": "age", "wealth": "wealth"},
+    agenttype_reporters={
+        Predator: {"kills": "kills_count"},
+        Prey: {"distance_fled": "total_flight_distance"}
+    }
+)
+```
+
+### Experimental features
+Mesa 3.0 introduces several experimental features for advanced modeling:
+- [Cell Space](https://mesa.readthedocs.io/latest/apis/experimental.html#module-experimental.cell_space.cell) with integrated PropertyLayers and improved agent movement capabilities
+- Voronoi grid implementation
+- [Event-scheduling simulation](https://mesa.readthedocs.io/latest/apis/experimental.html#module-experimental.devs.eventlist) capabilities
+
+These experimental features are in active development and might break API between releases.
+
+## Breaking changes
+_See our [Mesa 3.0 migration guide](https://mesa.readthedocs.io/latest/migration_guide.html#mesa-3-0) for a full overview._
+
+If you want to move existing models from Mesa 2.x to 3.0, there are a few things you have to change.
+
+1. Models must explicitly initialize the Mesa base class:
+```python
+class MyModel(mesa.Model):
+    def __init__(self, n_agents, seed=None):
+        super().__init__(seed=seed)  # Required in Mesa 3.0
+```
+
+2. Agents are created without manual ID assignment:
+```python
+# Old
+agent = MyAgent(unique_id=1, model=self)
+# New
+agent = MyAgent(model=self)
+```
+
+3. Scheduler replacement with AgentSet operations:
+```python
+# Old (RandomActivation)
+self.schedule = RandomActivation(self)
+self.schedule.step()
+
+# New
+self.agents.shuffle_do("step")
+
+# Old (SimultaneousActivation)
+self.schedule = SimultaneousActivation(self)
+self.schedule.step()
+
+# New
+self.agents.do("step")
+self.agents.do("advance")
+```
+
+Furthermore:
+- Steps counter automatically increments
+- `mesa.flat` namespace removed
+- Python 3.10+ required
+- Reserved model variables (`agents`, `steps`, etc.) protected
+- Simplified DataCollector initialization
+- Old visualization system replaced by SolaraViz
+
+## Getting Started
+Install Mesa 3.0:
+```bash
+pip install --upgrade mesa
+```
+
+If building a new model, we recommend checking out the updated [Mesa Overview](https://mesa.readthedocs.io/latest/overview.html) and [Introductory Tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html).
+
+For updating existing models, we recommend upgrading in steps:
+1. Update to latest Mesa 2.x
+2. Address deprecation warnings
+3. Upgrade to Mesa 3.0
+4. Replace schedulers with AgentSet functionality
+
+A detailed [migration guide](https://mesa.readthedocs.io/latest/migration_guide.html#mesa-3-0) is available to help moving to Mesa 3.0. For questions or support, join our [GitHub Discussions](https://github.com/projectmesa/mesa/discussions) or [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org).
+
+We would love to hear what you think about Mesa 3.0! [Say hello here](https://github.com/projectmesa/mesa/discussions/2465) and leave any [feedback on 3.0 here](https://github.com/projectmesa/mesa/discussions/2338).
+
+# 3.0.0rc0 (2024-11-06)
+## Highlights
+We're releasing the Mesa 3.0 Release Candidate, ready for final testing before we release Mesa 3.0 later this week!
+
+In this last 3.0 pre-release, the visualisation has been thoroughly updated, with a brand new API. Visualizing the experimental Cell Space, including PropertyLayers and hexogonal grids, is now also supported.
+
+We're still working very active on the visualisation, so we have marked that experimental for Mesa 3.0. We will stabilize SolaraViz in Mesa 3.1.
+
+Any feedback and last-minute bug reports are welcome [here](https://github.com/projectmesa/mesa/discussions/2338).
+
+## What's Changed
+### ⚠️ Breaking changes
+* Viz: Refactor Matplotlib plotting by @quaquel in https://github.com/projectmesa/mesa/pull/2430
+* api reorganization by @quaquel in https://github.com/projectmesa/mesa/pull/2447
+### 🧪 Experimental features
+* Mark SolaraViz as experimental for Mesa 3.0 by @EwoutH in https://github.com/projectmesa/mesa/pull/2459
+### 🛠 Enhancements made
+* expand ax.scatter kwargs that can be used by @quaquel in https://github.com/projectmesa/mesa/pull/2445
+### 🐛 Bugs fixed
+* Fix #2452 - handle solara viz model params better by @Corvince in https://github.com/projectmesa/mesa/pull/2454
+* Update MoneyModel.py by @quaquel in https://github.com/projectmesa/mesa/pull/2458
+### 🔍 Examples updated
+* Updates to Epstein example by @quaquel in https://github.com/projectmesa/mesa/pull/2429
+* Update examples to use updated space drawing by @quaquel in https://github.com/projectmesa/mesa/pull/2442
+### 📜 Documentation improvements
+* Update wolf-sheep png and fix typo in file name by @quaquel in https://github.com/projectmesa/mesa/pull/2444
+* Include main examples readme in docs by @quaquel in https://github.com/projectmesa/mesa/pull/2448
+* remove how-to guide and update docs in places by @quaquel in https://github.com/projectmesa/mesa/pull/2449
+### 🔧 Maintenance
+* remove deprecated HexGrid class by @quaquel in https://github.com/projectmesa/mesa/pull/2441
+* rename make_plot_measure to make_plot_component and add some kwargs by @quaquel in https://github.com/projectmesa/mesa/pull/2446
+
+**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0b2...v3.0.0rc0
+
 # 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.

{mesa-3.0.0b2 → mesa-3.0.1}/PKG-INFO

@@ -1,13 +1,11 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0b2
+Version: 3.0.1
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
 Author-email: Project Mesa Team <projectmesa@googlegroups.com>
 License: Apache 2.0
-License-File: LICENSE
-License-File: NOTICE
 Keywords: ABM,agent,based,model,modeling,multi-agent,simulation
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
@@ -93,9 +91,9 @@ interface; and analyze their results using Python's data analysis
 tools. Its goal is to be the Python-based alternative to NetLogo,
 Repast, or MASON.
 
-![A screenshot of the Schelling Model in Mesa](https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/Mesa_Screenshot.png)
+![A screenshot of the WolfSheep Model in Mesa](https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/wolf_sheep.png)
 
-*Above: A Mesa implementation of the Schelling segregation model, this
+*Above: A Mesa implementation of the WolfSheep model, this
 can be displayed in browser windows or Jupyter.*
 
 ## Features
@@ -107,18 +105,18 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-To install our latest stable release (2.4.x), run:
+To install our latest stable release (3.0.x), run:
 
 ``` bash
 pip install -U mesa
 ```
 
-To install our latest pre-release (3.0.0 alpha), run:
+To install our latest pre-release, run:
 
 ``` bash
 pip install -U --pre mesa
 ```
-With Mesa 3.0, we don't install all our dependencies anymore by default.
+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 --pre mesa[network,viz]

{mesa-3.0.0b2 → mesa-3.0.1}/README.md

@@ -14,9 +14,9 @@ interface; and analyze their results using Python's data analysis
 tools. Its goal is to be the Python-based alternative to NetLogo,
 Repast, or MASON.
 
-![A screenshot of the Schelling Model in Mesa](https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/Mesa_Screenshot.png)
+![A screenshot of the WolfSheep Model in Mesa](https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/wolf_sheep.png)
 
-*Above: A Mesa implementation of the Schelling segregation model, this
+*Above: A Mesa implementation of the WolfSheep model, this
 can be displayed in browser windows or Jupyter.*
 
 ## Features
@@ -28,18 +28,18 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-To install our latest stable release (2.4.x), run:
+To install our latest stable release (3.0.x), run:
 
 ``` bash
 pip install -U mesa
 ```
 
-To install our latest pre-release (3.0.0 alpha), run:
+To install our latest pre-release, run:
 
 ``` bash
 pip install -U --pre mesa
 ```
-With Mesa 3.0, we don't install all our dependencies anymore by default.
+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 --pre mesa[network,viz]

{mesa-3.0.0b2 → mesa-3.0.1}/benchmarks/configurations.py

@@ -1,9 +1,6 @@
 """configurations for benchmarks."""
 
-from BoltzmannWealth.boltzmann_wealth import BoltzmannWealth
-from Flocking.flocking import BoidFlockers
-from Schelling.schelling import Schelling
-from WolfSheep.wolf_sheep import WolfSheep
+from mesa.examples import BoidFlockers, BoltzmannWealth, Schelling, WolfSheep
 
 configurations = {
     # Schelling Model Configurations

{mesa-3.0.0b2 → mesa-3.0.1}/benchmarks/global_benchmark.py

@@ -28,21 +28,21 @@ def run_model(model_class, seed, parameters):
     Returns:
         startup time and run time
     """
-    no_simulator = ["BoltzmannWealth"]
+    uses_simulator = ["WolfSheep"]
     start_init = timeit.default_timer()
-    if model_class.__name__ in no_simulator:
-        model = model_class(seed=seed, **parameters)
-    else:
+    if model_class.__name__ in uses_simulator:
         simulator = ABMSimulator()
         model = model_class(simulator=simulator, seed=seed, **parameters)
-        simulator.setup(model)
+    else:
+        model = model_class(seed=seed, **parameters)
 
     end_init_start_run = timeit.default_timer()
 
-    if model_class.__name__ in no_simulator:
-        model.run_model(config["steps"])
-    else:
+    if model_class.__name__ in uses_simulator:
         simulator.run_for(config["steps"])
+    else:
+        for _ in range(config["steps"]):
+            model.step()
 
     end_run = timeit.default_timer()
 

{mesa-3.0.0b2 → mesa-3.0.1}/docs/apis/experimental.md

@@ -3,6 +3,11 @@ 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:
@@ -33,6 +38,11 @@ This namespace contains experimental features. These are under development, and
    :members:
 ```
 
+```{eval-rst}
+.. automodule:: experimental.cell_space.voronoi
+   :members:
+```
+
 ## Devs
 
 ```{eval-rst}

mesa-3.0.1/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.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:
+```

{mesa-3.0.0b2 → mesa-3.0.1}/docs/best-practices.md

@@ -24,7 +24,7 @@ All our [examples](examples) follow this layout.
 ## Randomization
 
 If your model involves some random choice, you can use the built-in `random`
-property that Mesa `Model` and `Agent` objects have. This works exactly
+property that many Mesa objects have, including `Model`, `Agent`, and `AgentSet`. This works exactly
 like the built-in `random` library.
 
 ```python
@@ -45,20 +45,24 @@ class AwesomeAgent(Agent):
     random_number = self.random.randint(0, 100)
 ```
 
-(The agent's random property is just a reference to its parent model's
-`random` property).
+`Agent.random` is just a convenient shorthand in the Agent class to `self.model.random`. If you create your own `AgentSet`
+instances, you have to pass `random` explicitly. Typically, you can simply do, in a Model instance,
+`my_agentset = AgentSet([], random=self.random)`. This ensures that `my_agentset` uses the same random
+number generator as the rest of the model.
+
 
 When a model object is created, its random property is automatically seeded
 with the current time. The seed determines the sequence of random numbers; if
 you instantiate a model with the same seed, you will get the same results.
 To allow you to set the seed, make sure your model has a `seed` argument in its
-constructor.
+`__init__`.
 
 ```python
 class AwesomeModel(Model):
 
   def __init__(self, seed=None):
-    pass
+    super().__init__(seed=seed)
+    ...
 
   def cool_method(self):
     interesting_number = self.random.random()

{mesa-3.0.0b2 → mesa-3.0.1}/docs/conf.py

@@ -175,7 +175,9 @@ html_static_path = ["_static"]
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    'migration_guide': [],  # No sidebar migration
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -316,17 +318,20 @@ 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 = [f.path for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() and not f.name.startswith("__") ]
-    advanced_examples = [f.path for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir() and not f.name.startswith("__")]
+    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())
 
-    pathlib.Path(os.path.join(HERE, "examples")).mkdir(parents=True, exist_ok=True)
+    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 example in examples:
+    for kind, example in examples:
         base_name = os.path.basename(os.path.normpath(example))
 
         agent_filename = os.path.join(example, "agents.py")
@@ -335,19 +340,23 @@ def setup_examples_pages():
         app_filename = os.path.join(example, "app.py")
 
         md_filename = f"{base_name}.md"
-        examples_md.append(base_name)
+        examples_md.append((base_name, f"{kind}/{base_name}"))
 
-        md_filepath = os.path.join(HERE, "examples", md_filename)
+        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(
-                examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
+                readme=readme_md,
+                example_paths="\n".join([f"{' '.join(a.split('_'))} </examples/{b}>" for a, b in examples_md]),
             )
         )
         fh.write(content)

mesa-3.0.1/docs/examples_overview_template.txt

@@ -0,0 +1,13 @@
+
+$readme
+
+
+
+```{toctree}
+:hidden: true
+:maxdepth: 2
+
+$example_paths
+
+
+```

mesa-3.0.0b2/docs/overview.md → mesa-3.0.1/docs/getting_started.md

@@ -1,9 +1,20 @@
-# Mesa Overview
+# Getting started
 Mesa is a modular framework for building, analyzing and visualizing agent-based models.
 
 **Agent-based models** are computer simulations involving multiple entities (the agents) acting and interacting with one another based on their programmed behavior. Agents can be used to represent living cells, animals, individual humans, even entire organizations or abstract entities. Sometimes, we may have an understanding of how the individual components of a system behave, and want to see what system-level behaviors and effects emerge from their interaction. Other times, we may have a good idea of how the system overall behaves, and want to figure out what individual behaviors explain it. Or we may want to see how to get agents to cooperate or compete most effectively. Or we may just want to build a cool toy with colorful little dots moving around.
 
-## Mesa Modules
+
+## Tutorials
+If you want to get a quick start on how to build agent based models with MESA, check the tutorials:
+
+- [Introductory Tutorial](tutorials/intro_tutorial): Learn how to create your first Mesa model.
+- [Visualization Tutorial](tutorials/visualization_tutorial): Learn how to create interactive visualizations for your models.
+
+## Examples
+Mesa ships with a collection of example models. These are classic ABMs, so if you are familiar with ABMs and want to get a quick sense of how MESA works, these examples are great place to start. You can find them [here](examples).
+
+
+## Overview of the MESA library
 
 Mesa is modular, meaning that its modeling, analysis and visualization components are kept separate but intended to work together. The modules are grouped into three categories:
 
@@ -165,14 +176,22 @@ results = mesa.batch_run(
 The results are returned as a list of dictionaries, which can be easily converted to a pandas DataFrame for further analysis.
 
 ### Visualization
-Mesa now uses a new browser-based visualization system called SolaraViz. This allows for interactive, customizable visualizations of your models. Here's a basic example of how to set up a visualization:
+Mesa now uses a new browser-based visualization system called SolaraViz. This allows for interactive, customizable visualizations of your models.
+
+> **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.
+
+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:
 
 ```python
-from mesa.visualization import SolaraViz, make_space_matplotlib, make_plot_measure
+from mesa.visualization import SolaraViz, make_space_component, make_plot_component
+
 
 def agent_portrayal(agent):
     return {"color": "blue", "size": 50}
 
+
 model_params = {
     "N": {
         "type": "SliderInt",
@@ -181,14 +200,14 @@ model_params = {
         "min": 10,
         "max": 100,
         "step": 1,
-    }
+   }
 }
 
 page = SolaraViz(
     MyModel,
     [
-        make_space_matplotlib(agent_portrayal),
-        make_plot_measure("mean_age")
+        make_space_component(agent_portrayal),
+        make_plot_component("mean_age")
     ],
     model_params=model_params
 )
@@ -202,28 +221,42 @@ This will create an interactive visualization of your model, including:
 
 You can also create custom visualization components using Matplotlib. For more advanced usage and customization options, please refer to the [visualization tutorial](tutorials/visualization_tutorial).
 
-### Further resources
+## Further resources
 To further explore Mesa and its features, we have the following resources available:
 
-#### Tutorials
-- [Introductory Tutorial](tutorials/intro_tutorial): Learn how to create your first Mesa model.
-- [Visualization Tutorial](tutorials/visualization_tutorial.html): Learn how to create interactive visualizations for your models.
+### Best practices
+- [Mesa best practices](best-practices): an overview of tips and guidelines for using MESA.
 
-#### API documentation
+### API documentation
 - [Mesa API reference](apis): Detailed documentation of Mesa's classes and functions.
 
-#### Example models
+### Repository of models built using MESA
 - [Mesa Examples repository](https://github.com/projectmesa/mesa-examples): A collection of example models demonstrating various Mesa features and modeling techniques.
 
-#### Migration guide
+### Migration guide
 - [Mesa 3.0 Migration guide](migration_guide): If you're upgrading from an earlier version of Mesa, this guide will help you navigate the changes in Mesa 3.0.
 
-#### Source Ccode and development
+### Source Ccode and development
 - [Mesa GitHub repository](https://github.com/projectmesa/mesa): Access the full source code of Mesa, contribute to its development, or report issues.
 - [Mesa release notes](https://github.com/projectmesa/mesa/releases): View the detailed changelog of Mesa, including all past releases and their features.
 
-#### Community and support
+### Community and support
 - [Mesa GitHub Discussions](https://github.com/projectmesa/mesa/discussions): Join discussions, ask questions, and connect with other Mesa users.
 - [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org): Real-time chat for quick questions and community interaction.
 
 Enjoy modelling with Mesa, and feel free to reach out!
+
+
+
+
+
+```{toctree}
+:hidden: true
+:maxdepth: 7
+
+tutorials/intro_tutorial
+tutorials/visualization_tutorial
+Best Practices <best-practices>
+
+
+```