From 5a2887125d4f25e6c06c42a68ae84f3bfa64bb7d Mon Sep 17 00:00:00 2001 From: Ewout ter Hoeven Date: Tue, 5 Nov 2024 16:13:06 +0100 Subject: [PATCH] Mark SolaraViz as experimental for Mesa 3.0 Add a note at four places that marks SolaraViz as experimental in Mesa 3.0 --- docs/migration_guide.md | 2 ++ docs/overview.md | 2 ++ docs/tutorials/visualization_tutorial.ipynb | 2 ++ mesa/visualization/__init__.py | 8 +++++++- 4 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/migration_guide.md b/docs/migration_guide.md index 193e796089f..019695a118b 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -253,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()`. diff --git a/docs/overview.md b/docs/overview.md index 38f0ef9d2d0..37735760920 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -167,6 +167,8 @@ The results are returned as a list of dictionaries, which can be easily converte ### 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: +> **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. + ```python from mesa.visualization import SolaraViz, make_space_component, make_plot_component diff --git a/docs/tutorials/visualization_tutorial.ipynb b/docs/tutorials/visualization_tutorial.ipynb index dbff7b01fa6..9e072d034f7 100644 --- a/docs/tutorials/visualization_tutorial.ipynb +++ b/docs/tutorials/visualization_tutorial.ipynb @@ -11,6 +11,8 @@ "source": [ "*This version of the visualisation tutorial is updated for Mesa 3.0, and works with Mesa `3.0.0a4` and above. If you are using Mesa 2.3.x, check out the [stable version](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) of this tutorial on Readthedocs.*\n", "\n", + "> **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.\n", + "\n", "**Important:** \n", "- If you are just exploring Mesa and want the fastest way to the the dashboard and code checkout [![py.cafe](https://img.shields.io/badge/launch-py.cafe-blue)](https://py.cafe/app/tpike3/boltzmann-wealth-model) (click \"Editor\" to see the code)\n", "- If you want to see the dashboard in an interactive notebook try [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/projectmesa/mesa/main?labpath=docs%2Ftutorials%2Fvisualization_tutorial.ipynb)\n", diff --git a/mesa/visualization/__init__.py b/mesa/visualization/__init__.py index 66597b0e71d..9c2e74a2afc 100644 --- a/mesa/visualization/__init__.py +++ b/mesa/visualization/__init__.py @@ -1,4 +1,10 @@ -"""Solara based visualization for Mesa models.""" +"""Solara based visualization for Mesa 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. +""" from mesa.visualization.mpl_space_drawing import ( draw_space,