Mesa 2.4.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

mesa/visualization/solara_viz.py

@@ -0,0 +1,458 @@
+"""Mesa visualization module for creating interactive model visualizations.
+
+This module provides components to create browser- and Jupyter notebook-based visualizations of
+Mesa models, allowing users to watch models run step-by-step and interact with model parameters.
+
+Key features:
+    - SolaraViz: Main component for creating visualizations, supporting grid displays and plots
+    - ModelController: Handles model execution controls (step, play, pause, reset)
+    - UserInputs: Generates UI elements for adjusting model parameters
+
+The module uses Solara for rendering in Jupyter notebooks or as standalone web applications.
+It supports various types of visualizations including matplotlib plots, agent grids, and
+custom visualization components.
+
+Usage:
+    1. Define an agent_portrayal function to specify how agents should be displayed
+    2. Set up model_params to define adjustable parameters
+    3. Create a SolaraViz instance with your model, parameters, and desired measures
+    4. Display the visualization in a Jupyter notebook or run as a Solara app
+
+See the Visualization Tutorial and example models for more details.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Literal
+
+import reacton.core
+import solara
+
+import mesa.visualization.components.altair_components as components_altair
+from mesa.visualization.user_param import Slider
+from mesa.visualization.utils import force_update, update_counter
+
+if TYPE_CHECKING:
+    from mesa.model import Model
+
+
+@solara.component
+def SolaraViz(
+    model: Model | solara.Reactive[Model],
+    components: list[reacton.core.Component]
+    | list[Callable[[Model], reacton.core.Component]]
+    | Literal["default"] = "default",
+    play_interval: int = 100,
+    model_params=None,
+    name: str | None = None,
+):
+    """Solara visualization component.
+
+    This component provides a visualization interface for a given model using Solara.
+    It supports various visualization components and allows for interactive model
+    stepping and parameter adjustments.
+
+    Args:
+        model (Model | solara.Reactive[Model]): A Model instance or a reactive Model.
+            This is the main model to be visualized. If a non-reactive model is provided,
+            it will be converted to a reactive model.
+        components (list[solara.component] | Literal["default"], optional): List of solara
+            components or functions that return a solara component.
+            These components are used to render different parts of the model visualization.
+            Defaults to "default", which uses the default Altair space visualization.
+        play_interval (int, optional): Interval for playing the model steps in milliseconds.
+            This controls the speed of the model's automatic stepping. Defaults to 100 ms.
+        model_params (dict, optional): Parameters for (re-)instantiating a model.
+            Can include user-adjustable parameters and fixed parameters. Defaults to None.
+        name (str | None, optional): Name of the visualization. Defaults to the models class name.
+
+    Returns:
+        solara.component: A Solara component that renders the visualization interface for the model.
+
+    Example:
+        >>> model = MyModel()
+        >>> page = SolaraViz(model)
+        >>> page
+
+    Notes:
+        - The `model` argument can be either a direct model instance or a reactive model. If a direct
+          model instance is provided, it will be converted to a reactive model using `solara.use_reactive`.
+        - The `play_interval` argument controls the speed of the model's automatic stepping. A lower
+          value results in faster stepping, while a higher value results in slower stepping.
+    """
+    if components == "default":
+        components = [components_altair.make_altair_space()]
+    if model_params is None:
+        model_params = {}
+
+    # Convert model to reactive
+    if not isinstance(model, solara.Reactive):
+        model = solara.use_reactive(model)  # noqa: SH102, RUF100
+
+    def connect_to_model():
+        # Patch the step function to force updates
+        original_step = model.value.step
+
+        def step():
+            original_step()
+            force_update()
+
+        model.value.step = step
+        # Add a trigger to model itself
+        model.value.force_update = force_update
+        force_update()
+
+    solara.use_effect(connect_to_model, [model.value])
+
+    # set up reactive model_parameters shared by ModelCreator and ModelController
+    reactive_model_parameters = solara.use_reactive({})
+
+    with solara.AppBar():
+        solara.AppBarTitle(name if name else model.value.__class__.__name__)
+
+    with solara.Sidebar(), solara.Column():
+        with solara.Card("Controls"):
+            ModelController(
+                model,
+                model_parameters=reactive_model_parameters,
+                play_interval=play_interval,
+            )
+        with solara.Card("Model Parameters"):
+            ModelCreator(
+                model, model_params, model_parameters=reactive_model_parameters
+            )
+        with solara.Card("Information"):
+            ShowSteps(model.value)
+
+    ComponentsView(components, model.value)
+
+
+def _wrap_component(
+    component: reacton.core.Component | Callable[[Model], reacton.core.Component],
+) -> reacton.core.Component:
+    """Wrap a component in an auto-updated Solara component if needed."""
+    if isinstance(component, reacton.core.Component):
+        return component
+
+    @solara.component
+    def WrappedComponent(model):
+        update_counter.get()
+        return component(model)
+
+    return WrappedComponent
+
+
+@solara.component
+def ComponentsView(
+    components: list[reacton.core.Component]
+    | list[Callable[[Model], reacton.core.Component]],
+    model: Model,
+):
+    """Display a list of components.
+
+    Args:
+        components: List of components to display
+        model: Model instance to pass to each component
+    """
+    wrapped_components = [_wrap_component(component) for component in components]
+    items = [component(model) for component in wrapped_components]
+    grid_layout_initial = make_initial_grid_layout(num_components=len(items))
+    grid_layout, set_grid_layout = solara.use_state(grid_layout_initial)
+    solara.GridDraggable(
+        items=items,
+        grid_layout=grid_layout,
+        resizable=True,
+        draggable=True,
+        on_grid_layout=set_grid_layout,
+    )
+
+
+JupyterViz = SolaraViz
+
+
+@solara.component
+def ModelController(
+    model: solara.Reactive[Model],
+    *,
+    model_parameters: dict | solara.Reactive[dict] = None,
+    play_interval: int = 100,
+):
+    """Create controls for model execution (step, play, pause, reset).
+
+    Args:
+        model: Reactive model instance
+        model_parameters: Reactive parameters for (re-)instantiating a model.
+        play_interval: Interval for playing the model steps in milliseconds.
+
+    """
+    playing = solara.use_reactive(False)
+    running = solara.use_reactive(True)
+    if model_parameters is None:
+        model_parameters = {}
+    model_parameters = solara.use_reactive(model_parameters)
+
+    async def step():
+        while playing.value and running.value:
+            await asyncio.sleep(play_interval / 1000)
+            do_step()
+
+    solara.lab.use_task(
+        step, dependencies=[playing.value, running.value], prefer_threaded=False
+    )
+
+    def do_step():
+        """Advance the model by one step."""
+        model.value.step()
+        running.value = model.value.running
+
+    def do_reset():
+        """Reset the model to its initial state."""
+        playing.value = False
+        running.value = True
+        model.value = model.value = model.value.__class__(**model_parameters.value)
+
+    def do_play_pause():
+        """Toggle play/pause."""
+        playing.value = not playing.value
+
+    with solara.Row(justify="space-between"):
+        solara.Button(label="Reset", color="primary", on_click=do_reset)
+        solara.Button(
+            label="▶" if not playing.value else "❚❚",
+            color="primary",
+            on_click=do_play_pause,
+            disabled=not running.value,
+        )
+        solara.Button(
+            label="Step",
+            color="primary",
+            on_click=do_step,
+            disabled=playing.value or not running.value,
+        )
+
+
+def split_model_params(model_params):
+    """Split model parameters into user-adjustable and fixed parameters.
+
+    Args:
+        model_params: Dictionary of all model parameters
+
+    Returns:
+        tuple: (user_adjustable_params, fixed_params)
+    """
+    model_params_input = {}
+    model_params_fixed = {}
+    for k, v in model_params.items():
+        if check_param_is_fixed(v):
+            model_params_fixed[k] = v
+        else:
+            model_params_input[k] = v
+    return model_params_input, model_params_fixed
+
+
+def check_param_is_fixed(param):
+    """Check if a parameter is fixed (not user-adjustable).
+
+    Args:
+        param: Parameter to check
+
+    Returns:
+        bool: True if parameter is fixed, False otherwise
+    """
+    if isinstance(param, Slider):
+        return False
+    if not isinstance(param, dict):
+        return True
+    if "type" not in param:
+        return True
+
+
+@solara.component
+def ModelCreator(
+    model: solara.Reactive[Model],
+    user_params: dict,
+    *,
+    model_parameters: dict | solara.Reactive[dict] = None,
+):
+    """Solara component for creating and managing a model instance with user-defined parameters.
+
+    This component allows users to create a model instance with specified parameters and seed.
+    It provides an interface for adjusting model parameters and reseeding the model's random
+    number generator.
+
+    Args:
+        model: A reactive model instance. This is the main model to be created and managed.
+        user_params: Parameters for (re-)instantiating a model. Can include user-adjustable parameters and fixed parameters. Defaults to None.
+        model_parameters: reactive parameters for reinitializing the model
+
+    Returns:
+        solara.component: A Solara component that renders the model creation and management interface.
+
+    Example:
+        >>> model = solara.reactive(MyModel())
+        >>> model_params = {
+        >>>     "param1": {"type": "slider", "value": 10, "min": 0, "max": 100},
+        >>>     "param2": {"type": "slider", "value": 5, "min": 1, "max": 10},
+        >>> }
+        >>> creator = ModelCreator(model, model_params)
+        >>> creator
+
+    Notes:
+        - The `model_params` argument should be a dictionary where keys are parameter names and values either fixed values
+          or are dictionaries containing parameter details such as type, value, min, and max.
+        - The `seed` argument ensures reproducibility by setting the initial seed for the model's random number generator.
+        - The component provides an interface for adjusting user-defined parameters and reseeding the model.
+
+    """
+    if model_parameters is None:
+        model_parameters = {}
+    model_parameters = solara.use_reactive(model_parameters)
+
+    solara.use_effect(
+        lambda: _check_model_params(model.value.__class__.__init__, fixed_params),
+        [model.value],
+    )
+    user_params, fixed_params = split_model_params(user_params)
+
+    # set model_parameters to the default values for all parameters
+    model_parameters.value = {
+        **fixed_params,
+        **{k: v.get("value") for k, v in user_params.items()},
+    }
+
+    def on_change(name, value):
+        new_model_parameters = {**model_parameters.value, name: value}
+        model.value = model.value.__class__(**new_model_parameters)
+        model_parameters.value = new_model_parameters
+
+    UserInputs(user_params, on_change=on_change)
+
+
+def _check_model_params(init_func, model_params):
+    """Check if model parameters are valid for the model's initialization function.
+
+    Args:
+        init_func: Model initialization function
+        model_params: Dictionary of model parameters
+
+    Raises:
+        ValueError: If a parameter is not valid for the model's initialization function
+    """
+    model_parameters = inspect.signature(init_func).parameters
+    for name in model_parameters:
+        if (
+            model_parameters[name].default == inspect.Parameter.empty
+            and name not in model_params
+            and name != "self"
+            and name != "kwargs"
+        ):
+            raise ValueError(f"Missing required model parameter: {name}")
+    for name in model_params:
+        if name not in model_parameters and "kwargs" not in model_parameters:
+            raise ValueError(f"Invalid model parameter: {name}")
+
+
+@solara.component
+def UserInputs(user_params, on_change=None):
+    """Initialize user inputs for configurable model parameters.
+
+    Currently supports :class:`solara.SliderInt`, :class:`solara.SliderFloat`,
+    :class:`solara.Select`, and :class:`solara.Checkbox`.
+
+    Args:
+        user_params: Dictionary with options for the input, including label, min and max values, and other fields specific to the input type.
+        on_change: Function to be called with (name, value) when the value of an input changes.
+    """
+    for name, options in user_params.items():
+
+        def change_handler(value, name=name):
+            on_change(name, value)
+
+        if isinstance(options, Slider):
+            slider_class = (
+                solara.SliderFloat if options.is_float_slider else solara.SliderInt
+            )
+            slider_class(
+                options.label,
+                value=options.value,
+                on_value=change_handler,
+                min=options.min,
+                max=options.max,
+                step=options.step,
+            )
+            continue
+
+        # label for the input is "label" from options or name
+        label = options.get("label", name)
+        input_type = options.get("type")
+        if input_type == "SliderInt":
+            solara.SliderInt(
+                label,
+                value=options.get("value"),
+                on_value=change_handler,
+                min=options.get("min"),
+                max=options.get("max"),
+                step=options.get("step"),
+            )
+        elif input_type == "SliderFloat":
+            solara.SliderFloat(
+                label,
+                value=options.get("value"),
+                on_value=change_handler,
+                min=options.get("min"),
+                max=options.get("max"),
+                step=options.get("step"),
+            )
+        elif input_type == "Select":
+            solara.Select(
+                label,
+                value=options.get("value"),
+                on_value=change_handler,
+                values=options.get("values"),
+            )
+        elif input_type == "Checkbox":
+            solara.Checkbox(
+                label=label,
+                on_value=change_handler,
+                value=options.get("value"),
+            )
+        elif input_type == "InputText":
+            solara.InputText(
+                label=label,
+                on_value=change_handler,
+                value=options.get("value"),
+            )
+        else:
+            raise ValueError(f"{input_type} is not a supported input type")
+
+
+def make_initial_grid_layout(num_components):
+    """Create an initial grid layout for visualization components.
+
+    Args:
+        num_components: Number of components to display
+
+    Returns:
+        list: Initial grid layout configuration
+    """
+    return [
+        {
+            "i": i,
+            "w": 6,
+            "h": 10,
+            "moved": False,
+            "x": 6 * (i % 2),
+            "y": 16 * (i - i % 2),
+        }
+        for i in range(num_components)
+    ]
+
+
+@solara.component
+def ShowSteps(model):
+    """Display the current step of the model."""
+    update_counter.get()
+    return solara.Text(f"Step: {model.steps}")

mesa/visualization/user_param.py

@@ -0,0 +1,69 @@
+"""Solara visualization related helper classes."""
+
+
+class UserParam:
+    """UserParam."""
+
+    _ERROR_MESSAGE = "Missing or malformed inputs for '{}' Option '{}'"
+
+    def maybe_raise_error(self, param_type, valid):  # noqa: D102
+        if valid:
+            return
+        msg = self._ERROR_MESSAGE.format(param_type, self.label)
+        raise ValueError(msg)
+
+
+class Slider(UserParam):
+    """A number-based slider input with settable increment.
+
+    Example:
+    slider_option = Slider("My Slider", value=123, min=10, max=200, step=0.1)
+
+    Args:
+        label: The displayed label in the UI
+        value: The initial value of the slider
+        min: The minimum possible value of the slider
+        max: The maximum possible value of the slider
+        step: The step between min and max for a range of possible values
+        dtype: either int or float
+    """
+
+    def __init__(
+        self,
+        label="",
+        value=None,
+        min=None,
+        max=None,
+        step=1,
+        dtype=None,
+    ):
+        """Initializes a slider.
+
+        Args:
+            label: The displayed label in the UI
+            value: The initial value of the slider
+            min: The minimum possible value of the slider
+            max: The maximum possible value of the slider
+            step: The step between min and max for a range of possible values
+            dtype: either int or float
+        """
+        self.label = label
+        self.value = value
+        self.min = min
+        self.max = max
+        self.step = step
+
+        # Validate option type to make sure values are supplied properly
+        valid = not (self.value is None or self.min is None or self.max is None)
+        self.maybe_raise_error("slider", valid)
+
+        if dtype is None:
+            self.is_float_slider = self._check_values_are_float(value, min, max, step)
+        else:
+            self.is_float_slider = dtype is float
+
+    def _check_values_are_float(self, value, min, max, step):  # D103
+        return any(isinstance(n, float) for n in (value, min, max, step))
+
+    def get(self, attr):  # noqa: D102
+        return getattr(self, attr)

mesa/visualization/utils.py

@@ -0,0 +1,9 @@
+"""Solara related utils."""
+
+import solara
+
+update_counter = solara.reactive(0)
+
+
+def force_update():  # noqa: D103
+    update_counter.value += 1

{mesa-2.4.0.dist-info → mesa-3.0.0.dist-info}/METADATA

@@ -1,12 +1,13 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 2.4.0
+Version: 3.0.0
 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
@@ -14,7 +15,6 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -22,29 +22,59 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Artificial Life
-Requires-Python: >=3.9
-Requires-Dist: click
-Requires-Dist: cookiecutter
-Requires-Dist: matplotlib
-Requires-Dist: mesa-viz-tornado>=0.1.3,~=0.1.0
-Requires-Dist: networkx
+Requires-Python: >=3.10
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: solara
 Requires-Dist: tqdm
+Provides-Extra: all
+Requires-Dist: ipython; 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: pydata-sphinx-theme; extra == 'all'
+Requires-Dist: pytest; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest-mock; extra == 'all'
+Requires-Dist: ruff; extra == 'all'
+Requires-Dist: scipy; extra == 'all'
+Requires-Dist: seaborn; extra == 'all'
+Requires-Dist: solara; extra == 'all'
+Requires-Dist: sphinx; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: networkx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest-mock; extra == 'dev'
-Requires-Dist: pytest>=4.6; extra == 'dev'
-Requires-Dist: ruff~=0.1.1; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: solara; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: ipython; extra == 'docs'
+Requires-Dist: matplotlib; extra == 'docs'
 Requires-Dist: myst-nb; extra == 'docs'
 Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: networkx; extra == 'docs'
 Requires-Dist: pydata-sphinx-theme; extra == 'docs'
 Requires-Dist: seaborn; extra == 'docs'
+Requires-Dist: solara; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: matplotlib; extra == 'examples'
+Requires-Dist: networkx; extra == 'examples'
+Requires-Dist: pytest; extra == 'examples'
+Requires-Dist: scipy; extra == 'examples'
+Requires-Dist: solara; extra == 'examples'
+Provides-Extra: network
+Requires-Dist: networkx; extra == 'network'
+Provides-Extra: rec
+Requires-Dist: matplotlib; extra == 'rec'
+Requires-Dist: networkx; extra == 'rec'
+Requires-Dist: solara; extra == 'rec'
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == 'viz'
+Requires-Dist: solara; extra == 'viz'
 Description-Content-Type: text/markdown
 
 # Mesa: Agent-based modeling in Python
@@ -56,8 +86,6 @@ Description-Content-Type: text/markdown
 | Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) |
 | Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
 
-*This is the `2.4.x-maintenance` branch. Example models for Mesa 2.x can be found [here](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples).*
-
 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
@@ -79,13 +107,30 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-Getting started quickly:
+To install our latest stable release (3.0.x), run:
+
+``` bash
+pip install -U mesa
+```
+
+To install our latest pre-release, run:
 
 ``` bash
-pip install mesa
+pip install -U --pre 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 --pre mesa[network,viz]
+
+# This is equivalent to our recommended dependencies:
+pip install -U --pre mesa[rec]
+
+# To install all, including developer, dependencies:
+pip install -U --pre mesa[all]
 ```
 
-You can also use `pip` to install the github version:
+You can also use `pip` to install the latest GitHub version:
 
 ``` bash
 pip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa
@@ -105,7 +150,7 @@ For resources or help on using Mesa, check out the following:
 -   [Visualization Tutorial](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
 -   [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,
     SugarScape with Traders, with instructional videos)
--   [Mesa Examples](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples) (A repository of seminal ABMs using Mesa and
+-   [Mesa Examples](https://github.com/projectmesa/mesa-examples) (A repository of seminal ABMs using Mesa and
     examples of employing specific Mesa Features)
 -   [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)
     -   [Development version docs](https://mesa.readthedocs.io/latest/) (the latest version docs if you're using a pre-release Mesa version)