diff --git a/docs/migration_guide.md b/docs/migration_guide.md index 28bd90c4a46..06d2b9f65c9 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -3,13 +3,114 @@ This guide contains breaking changes between major Mesa versions and how to reso Non-breaking changes aren't included, for those see our [Release history](https://github.com/projectmesa/mesa/releases). +## Mesa 3.3.0 + +Mesa 3.3.0 is a visualization upgrade introducing a new and improved API, full support for both `altair` and `matplotlib` backends, and resolving several recurring issues from previous versions. +For full details on how to visualize your model, refer to the [Mesa Documentation](https://mesa.readthedocs.io/latest/tutorials/4_visualization_basic.html). -## Mesa 3.0 -Mesa 3.0 introduces significant changes to core functionalities, including agent and model initialization, scheduling, and visualization. The guide below outlines these changes and provides instructions for migrating your existing Mesa projects to version 3.0. _This guide is a work in progress. The development of it is tracked in [Issue #2233](https://github.com/projectmesa/mesa/issues/2233)._ +### Defining Portrayal Components +Previously, `agent_portrayal` returned a dictionary. Now, it returns an instance of a dedicated portrayal component called `AgentPortrayalStyle`. + +```python +# Old +def agent_portrayal(agent): + return { + "color": "white" if agent.state == 0 else "black", + "marker": "s", + "size": "30" + } + +# New +def agent_portrayal(agent): + return AgentPortrayalStyle( + color="white" if agent.state == 0 else "black", + marker="s", + size=30, + ) +``` + +Similarly, `propertylayer_portrayal` has moved from a dictionary-based interface to a function-based one, following the same pattern as `agent_portrayal`. It now returns a `PropertyLayerStyle` instance instead of a dictionary. + +```python +# Old +propertylayer_portrayal = { + "sugar": { + "colormap": "pastel1", + "alpha": 0.75, + "colorbar": True, + "vmin": 0, + "vmax": 10, + } +} + +# New +def propertylayer_portrayal(layer): + if layer.name == "sugar": + return PropertyLayerStyle( + color="pastel1", alpha=0.75, colorbar=True, vmin=0, vmax=10 + ) +``` + +* Ref: [PR #2786](https://github.com/projectmesa/mesa/pull/2786) + +### Default Space Visualization +While the visualization methods from Mesa versions before 3.3.0 still work, version 3.3.0 introduces `SpaceRenderer`, which changes how space visualizations are rendered. Check out the updated [Mesa documentation](https://mesa.readthedocs.io/latest/tutorials/4_visualization_basic.html) for guidance on upgrading your model’s visualization using `SpaceRenderer`. + +A basic example of how `SpaceRenderer` works: + +```python +# Old +from mesa.visualization import SolaraViz, make_space_component + +SolaraViz(model, components=[make_space_component(agent_portrayal)]) + +# New +from mesa.visualization import SolaraViz, SpaceRenderer + +renderer = SpaceRenderer(model, backend="matplotlib").render( + agent_portrayal=agent_portrayal, + ... +) + +SolaraViz( + model, + renderer, + components=[], + ... +) +``` + +* Ref: [PR #2803](https://github.com/projectmesa/mesa/pull/2803), [PR #2810](https://github.com/projectmesa/mesa/pull/2810) + +### Page Tab View + +Version 3.3.0 adds support for defining pages for different plot components. Learn more in the [Mesa documentation](https://mesa.readthedocs.io/latest/tutorials/6_visualization_rendering_with_space_renderer.html). + +In short, you can define multiple pages using the following syntax: + +```python +from mesa.visualization import SolaraViz, make_plot_component + +SolaraViz( + model, + components=[ + make_plot_component("foo", page=1), + make_plot_component("bar", "baz", page=2), + ], +) +``` + +* Ref: [PR #2827](https://github.com/projectmesa/mesa/pull/2827) + + +## Mesa 3.0 +Mesa 3.0 introduces significant changes to core functionalities, including agent and model initialization, scheduling, and visualization. The guide below outlines these changes and provides instructions for migrating your existing Mesa projects to version 3.0. + + ### Upgrade strategy We recommend the following upgrade strategy: - Update to the latest Mesa 2.x release (`mesa<3`). diff --git a/mesa/visualization/backends/altair_backend.py b/mesa/visualization/backends/altair_backend.py index e09bc02de64..35221b23a43 100644 --- a/mesa/visualization/backends/altair_backend.py +++ b/mesa/visualization/backends/altair_backend.py @@ -107,9 +107,13 @@ def collect_agent_data( if isinstance(portray_input, dict): warnings.warn( - "Returning a dict from agent_portrayal is deprecated. " - "Please return an AgentPortrayalStyle instance instead.", - PendingDeprecationWarning, + ( + "Returning a dict from agent_portrayal is deprecated. " + "Please return an AgentPortrayalStyle instance instead. " + "For more information, refer to the migration guide: " + "https://mesa.readthedocs.io/latest/migration_guide.html#defining-portrayal-components" + ), + DeprecationWarning, stacklevel=2, ) dict_data = portray_input.copy() diff --git a/mesa/visualization/backends/matplotlib_backend.py b/mesa/visualization/backends/matplotlib_backend.py index 96b4d901364..1ae407b1683 100644 --- a/mesa/visualization/backends/matplotlib_backend.py +++ b/mesa/visualization/backends/matplotlib_backend.py @@ -107,9 +107,13 @@ def collect_agent_data(self, space, agent_portrayal, default_size=None): if isinstance(portray_input, dict): warnings.warn( - "Returning a dict from agent_portrayal is deprecated. " - "Please return an AgentPortrayalStyle instance instead.", - PendingDeprecationWarning, + ( + "Returning a dict from agent_portrayal is deprecated. " + "Please return an AgentPortrayalStyle instance instead. " + "For more information, refer to the migration guide: " + "https://mesa.readthedocs.io/latest/migration_guide.html#defining-portrayal-components" + ), + DeprecationWarning, stacklevel=2, ) # Handle legacy dict input diff --git a/mesa/visualization/mpl_space_drawing.py b/mesa/visualization/mpl_space_drawing.py index e8c9a781e2e..fb3ea7b5b47 100644 --- a/mesa/visualization/mpl_space_drawing.py +++ b/mesa/visualization/mpl_space_drawing.py @@ -104,9 +104,13 @@ def get_agent_pos(agent, space): if isinstance(portray_input, dict): warnings.warn( - "Returning a dict from agent_portrayal is deprecated and will be removed " - "in a future version. Please return an AgentPortrayalStyle instance instead.", - PendingDeprecationWarning, + ( + "Returning a dict from agent_portrayal is deprecated. " + "Please return an AgentPortrayalStyle instance instead. " + "For more information, refer to the migration guide: " + "https://mesa.readthedocs.io/latest/migration_guide.html#defining-portrayal-components" + ), + DeprecationWarning, stacklevel=2, ) dict_data = portray_input.copy() @@ -297,8 +301,13 @@ def style_callable(layer_object: Any): params = propertylayer_portrayal.get(layer_name) warnings.warn( - "The propertylayer_portrayal dict is deprecated. Use a callable that returns PropertyLayerStyle instead.", - PendingDeprecationWarning, + ( + "The propertylayer_portrayal dict is deprecated. " + "Please use a callable that returns a PropertyLayerStyle instance instead. " + "For more information, refer to the migration guide: " + "https://mesa.readthedocs.io/latest/migration_guide.html#defining-portrayal-components" + ), + DeprecationWarning, stacklevel=2, ) diff --git a/mesa/visualization/space_renderer.py b/mesa/visualization/space_renderer.py index ad87b7dbc59..a517a70b9da 100644 --- a/mesa/visualization/space_renderer.py +++ b/mesa/visualization/space_renderer.py @@ -234,9 +234,13 @@ def style_callable(layer_object): params = portrayal_dict.get(layer_name) warnings.warn( - "Dict propertylayer_portrayal is deprecated. " - "Use a callable returning PropertyLayerStyle instead.", - PendingDeprecationWarning, + ( + "The propertylayer_portrayal dict is deprecated. " + "Please use a callable that returns a PropertyLayerStyle instance instead. " + "For more information, refer to the migration guide: " + "https://mesa.readthedocs.io/latest/migration_guide.html#defining-portrayal-components" + ), + DeprecationWarning, stacklevel=2, )