Mesa 3.1.2__py3-none-any.whl → 3.1.4__py3-none-any.whl

mesa/visualization/mpl_space_drawing.py

@@ -8,9 +8,10 @@ for a paper.
 
 import contextlib
 import itertools
-import math
 import warnings
 from collections.abc import Callable
+from functools import lru_cache
+from itertools import pairwise
 from typing import Any
 
 import networkx as nx
@@ -18,9 +19,9 @@ import numpy as np
 from matplotlib import pyplot as plt
 from matplotlib.axes import Axes
 from matplotlib.cm import ScalarMappable
-from matplotlib.collections import PatchCollection
+from matplotlib.collections import LineCollection, PatchCollection, PolyCollection
 from matplotlib.colors import LinearSegmentedColormap, Normalize, to_rgba
-from matplotlib.patches import RegularPolygon
+from matplotlib.patches import Polygon
 
 import mesa
 from mesa.experimental.cell_space import (
@@ -143,7 +144,10 @@ def draw_space(
             draw_orthogonal_grid(space, agent_portrayal, ax=ax, **space_drawing_kwargs)
         case mesa.space.NetworkGrid() | mesa.experimental.cell_space.Network():
             draw_network(space, agent_portrayal, ax=ax, **space_drawing_kwargs)
-        case mesa.space.ContinuousSpace():
+        case (
+            mesa.space.ContinuousSpace()
+            | mesa.experimental.continuous_space.ContinuousSpace()
+        ):
             draw_continuous_space(space, agent_portrayal, ax=ax)
         case VoronoiGrid():
             draw_voronoi_grid(space, agent_portrayal, ax=ax)
@@ -156,6 +160,40 @@ def draw_space(
     return ax
 
 
+@lru_cache(maxsize=1024, typed=True)
+def _get_hexmesh(
+    width: int, height: int, size: float = 1.0
+) -> list[tuple[float, float]]:
+    """Generate hexagon vertices for the mesh. Yields list of vertex coordinates for each hexagon."""
+
+    # Helper function for getting the vertices of a hexagon given the center and size
+    def _get_hex_vertices(
+        center_x: float, center_y: float, size: float = 1.0
+    ) -> list[tuple[float, float]]:
+        """Get vertices for a hexagon centered at (center_x, center_y)."""
+        vertices = [
+            (center_x, center_y + size),  # top
+            (center_x + size * np.sqrt(3) / 2, center_y + size / 2),  # top right
+            (center_x + size * np.sqrt(3) / 2, center_y - size / 2),  # bottom right
+            (center_x, center_y - size),  # bottom
+            (center_x - size * np.sqrt(3) / 2, center_y - size / 2),  # bottom left
+            (center_x - size * np.sqrt(3) / 2, center_y + size / 2),  # top left
+        ]
+        return vertices
+
+    x_spacing = np.sqrt(3) * size
+    y_spacing = 1.5 * size
+    hexagons = []
+
+    for row, col in itertools.product(range(height), range(width)):
+        # Calculate center position with offset for even rows
+        x = col * x_spacing + (row % 2 == 0) * (x_spacing / 2)
+        y = row * y_spacing
+        hexagons.append(_get_hex_vertices(x, y, size))
+
+    return hexagons
+
+
 def draw_property_layers(
     space, propertylayer_portrayal: dict[str, dict[str, Any]], ax: Axes
 ):
@@ -188,11 +226,10 @@ def draw_property_layers(
             continue
 
         data = layer.data.astype(float) if layer.data.dtype == bool else layer.data
-        width, height = data.shape  # if space is None else (space.width, space.height)
 
-        if space and data.shape != (width, height):
+        if (space.width, space.height) != data.shape:
             warnings.warn(
-                f"Layer {layer_name} dimensions ({data.shape}) do not match space dimensions ({width}, {height}).",
+                f"Layer {layer_name} dimensions ({data.shape}) do not match space dimensions ({space.width}, {space.height}).",
                 UserWarning,
                 stacklevel=2,
             )
@@ -203,45 +240,75 @@ def draw_property_layers(
         vmax = portrayal.get("vmax", np.max(data))
         colorbar = portrayal.get("colorbar", True)
 
-        # Draw the layer
+        # Prepare colormap
         if "color" in portrayal:
             rgba_color = to_rgba(portrayal["color"])
-            normalized_data = (data - vmin) / (vmax - vmin)
-            rgba_data = np.full((*data.shape, 4), rgba_color)
-            rgba_data[..., 3] *= normalized_data * alpha
-            rgba_data = np.clip(rgba_data, 0, 1)
             cmap = LinearSegmentedColormap.from_list(
                 layer_name, [(0, 0, 0, 0), (*rgba_color[:3], alpha)]
             )
-            im = ax.imshow(
-                rgba_data,
-                origin="lower",
-            )
-            if colorbar:
-                norm = Normalize(vmin=vmin, vmax=vmax)
-                sm = ScalarMappable(norm=norm, cmap=cmap)
-                sm.set_array([])
-                ax.figure.colorbar(sm, ax=ax, orientation="vertical")
-
         elif "colormap" in portrayal:
             cmap = portrayal.get("colormap", "viridis")
             if isinstance(cmap, list):
                 cmap = LinearSegmentedColormap.from_list(layer_name, cmap)
-            im = ax.imshow(
-                data,
-                cmap=cmap,
-                alpha=alpha,
-                vmin=vmin,
-                vmax=vmax,
-                origin="lower",
-            )
-            if colorbar:
-                plt.colorbar(im, ax=ax, label=layer_name)
+            elif isinstance(cmap, str):
+                cmap = plt.get_cmap(cmap)
         else:
             raise ValueError(
                 f"PropertyLayer {layer_name} portrayal must include 'color' or 'colormap'."
             )
 
+        if isinstance(space, OrthogonalGrid):
+            if "color" in portrayal:
+                data = data.T
+                normalized_data = (data - vmin) / (vmax - vmin)
+                rgba_data = np.full((*data.shape, 4), rgba_color)
+                rgba_data[..., 3] *= normalized_data * alpha
+                rgba_data = np.clip(rgba_data, 0, 1)
+                ax.imshow(rgba_data, origin="lower")
+            else:
+                ax.imshow(
+                    data.T,
+                    cmap=cmap,
+                    alpha=alpha,
+                    vmin=vmin,
+                    vmax=vmax,
+                    origin="lower",
+                )
+
+        elif isinstance(space, HexGrid):
+            width, height = data.shape
+
+            # Generate hexagon mesh
+            hexagons = _get_hexmesh(width, height)
+
+            # Normalize colors
+            norm = Normalize(vmin=vmin, vmax=vmax)
+            colors = data.ravel()  # flatten data to 1D array
+
+            if "color" in portrayal:
+                normalized_colors = np.clip(norm(colors), 0, 1)
+                rgba_colors = np.full((len(colors), 4), rgba_color)
+                rgba_colors[:, 3] = normalized_colors * alpha
+            else:
+                rgba_colors = cmap(norm(colors))
+                rgba_colors[..., 3] *= alpha
+
+            # Draw hexagons
+            collection = PolyCollection(hexagons, facecolors=rgba_colors, zorder=-1)
+            ax.add_collection(collection)
+
+        else:
+            raise NotImplementedError(
+                f"PropertyLayer visualization not implemented for {type(space)}."
+            )
+
+        # Add colorbar if requested
+        if colorbar:
+            norm = Normalize(vmin=vmin, vmax=vmax)
+            sm = ScalarMappable(norm=norm, cmap=cmap)
+            sm.set_array([])
+            plt.colorbar(sm, ax=ax, label=layer_name)
+
 
 def draw_orthogonal_grid(
     space: OrthogonalGrid,
@@ -305,13 +372,6 @@ def draw_hex_grid(
         ax: a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots
         draw_grid: whether to draw the grid
         kwargs: additional keyword arguments passed to ax.scatter
-
-    Returns:
-        Returns the Axes object with the plot drawn onto it.
-
-    ``agent_portrayal`` is called with an agent and should return a dict. Valid fields in this dict are "color",
-    "size", "marker", and "zorder". Other field are ignored and will result in a user warning.
-
     """
     if ax is None:
         fig, ax = plt.subplots()
@@ -320,62 +380,54 @@ def draw_hex_grid(
     s_default = (180 / max(space.width, space.height)) ** 2
     arguments = collect_agent_data(space, agent_portrayal, size=s_default)
 
-    # for hexgrids we have to go from logical coordinates to visual coordinates
-    # this is a bit messy.
-
-    # give all even rows an offset in the x direction
-    # give all rows an offset in the y direction
-
-    # numbers here are based on a distance of 1 between centers of hexes
-    offset = math.sqrt(0.75)
+    # Parameters for hexagon grid
+    size = 1.0
+    x_spacing = np.sqrt(3) * size
+    y_spacing = 1.5 * size
 
     loc = arguments["loc"].astype(float)
-
-    logical = np.mod(loc[:, 1], 2) == 0
-    loc[:, 0][logical] += 0.5
-    loc[:, 1] *= offset
-    arguments["loc"] = loc
-
-    # plot the agents
-    _scatter(ax, arguments, **kwargs)
-
-    # further styling and adding of grid
-    ax.set_xlim(-1, space.width + 0.5)
-    ax.set_ylim(-offset, space.height * offset)
-
-    def setup_hexmesh(
-        width,
-        height,
-    ):
-        """Helper function for creating the hexmaesh."""
-        # fixme: this should be done once, rather than in each update
-        # fixme check coordinate system in hexgrid (see https://www.redblobgames.com/grids/hexagons/#coordinates-offset)
-
-        patches = []
-        for x, y in itertools.product(range(width), range(height)):
-            if y % 2 == 0:
-                x += 0.5  # noqa: PLW2901
-            y *= offset  # noqa: PLW2901
-            hex = RegularPolygon(
-                (x, y),
-                numVertices=6,
-                radius=math.sqrt(1 / 3),
-                orientation=np.radians(120),
-            )
-            patches.append(hex)
-        mesh = PatchCollection(
-            patches, edgecolor="k", facecolor=(1, 1, 1, 0), linestyle="dotted", lw=1
-        )
-        return mesh
+    # Calculate hexagon centers for agents if agents are present and plot them.
+    if loc.size > 0:
+        loc[:, 0] = loc[:, 0] * x_spacing + ((loc[:, 1] - 1) % 2) * (x_spacing / 2)
+        loc[:, 1] = loc[:, 1] * y_spacing
+        arguments["loc"] = loc
+
+        # plot the agents
+        _scatter(ax, arguments, **kwargs)
+
+    # Calculate proper bounds that account for the full hexagon width and height
+    x_max = space.width * x_spacing + (space.height % 2) * (x_spacing / 2)
+    y_max = space.height * y_spacing
+
+    # Add padding that accounts for the hexagon points
+    x_padding = (
+        size * np.sqrt(3) / 2
+    )  # Distance from center to rightmost point of hexagon
+    y_padding = size  # Distance from center to topmost point of hexagon
+
+    # Plot limits to perfectly contain the hexagonal grid
+    # Determined through physical testing.
+    ax.set_xlim(-2 * x_padding, x_max + x_padding)
+    ax.set_ylim(-2 * y_padding, y_max + y_padding)
+
+    def setup_hexmesh(width, height):
+        """Helper function for creating the hexmesh with unique edges."""
+        edges = set()
+
+        # Generate edges for each hexagon
+        hexagons = _get_hexmesh(width, height)
+        for vertices in hexagons:
+            # Edge logic, connecting each vertex to the next
+            for v1, v2 in pairwise([*vertices, vertices[0]]):
+                # Sort vertices to ensure consistent edge representation and avoid duplicates.
+                edge = tuple(sorted([tuple(np.round(v1, 6)), tuple(np.round(v2, 6))]))
+                edges.add(edge)
+
+        return LineCollection(edges, linestyle=":", color="black", linewidth=1, alpha=1)
 
     if draw_grid:
-        # add grid
-        ax.add_collection(
-            setup_hexmesh(
-                space.width,
-                space.height,
-            )
-        )
+        ax.add_collection(setup_hexmesh(space.width, space.height))
+
     return ax
 
 
@@ -498,7 +550,11 @@ def draw_continuous_space(
 
 
 def draw_voronoi_grid(
-    space: VoronoiGrid, agent_portrayal: Callable, ax: Axes | None = None, **kwargs
+    space: VoronoiGrid,
+    agent_portrayal: Callable,
+    ax: Axes | None = None,
+    draw_grid: bool = True,
+    **kwargs,
 ):
     """Visualize a voronoi grid.
 
@@ -506,6 +562,7 @@ def draw_voronoi_grid(
         space: the space to visualize
         agent_portrayal: a callable that is called with the agent and returns a dict
         ax: a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots
+        draw_grid: whether to draw the grid or not
         kwargs: additional keyword arguments passed to ax.scatter
 
     Returns:
@@ -538,16 +595,18 @@ def draw_voronoi_grid(
 
     _scatter(ax, arguments, **kwargs)
 
-    for cell in space.all_cells:
-        polygon = cell.properties["polygon"]
-        ax.fill(
-            *zip(*polygon),
-            alpha=min(1, cell.properties[space.cell_coloring_property]),
-            c="red",
-            zorder=0,
-        )  # Plot filled polygon
-        ax.plot(*zip(*polygon), color="black")  # Plot polygon edges in black
+    def setup_voroinoimesh(cells):
+        patches = []
+        for cell in cells:
+            patch = Polygon(cell.properties["polygon"])
+            patches.append(patch)
+        mesh = PatchCollection(
+            patches, edgecolor="k", facecolor=(1, 1, 1, 0), linestyle="dotted", lw=1
+        )
+        return mesh
 
+    if draw_grid:
+        ax.add_collection(setup_voroinoimesh(space.all_cells.cells))
     return ax
 
 

mesa/visualization/solara_viz.py

@@ -52,6 +52,7 @@ def SolaraViz(
     | Literal["default"] = "default",
     *,
     play_interval: int = 100,
+    render_interval: int = 1,
     simulator: Simulator | None = None,
     model_params=None,
     name: str | None = None,
@@ -72,6 +73,8 @@ def SolaraViz(
             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.
+        render_interval (int, optional): Controls how often plots are updated during a simulation,
+            allowing users to skip intermediate steps and update graphs less frequently.
         simulator: A simulator that controls the model (optional)
         model_params (dict, optional): Parameters for (re-)instantiating a model.
             Can include user-adjustable parameters and fixed parameters. Defaults to None.
@@ -90,9 +93,15 @@ def SolaraViz(
           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.
+        - The `render_interval` argument determines how often plots are updated during simulation. Higher values
+          reduce update frequency,resulting in faster execution.
     """
     if components == "default":
-        components = [components_altair.make_altair_space()]
+        components = [
+            components_altair.make_altair_space(
+                agent_portrayal=None, propertylayer_portrayal=None, post_process=None
+            )
+        ]
     if model_params is None:
         model_params = {}
 
@@ -103,7 +112,7 @@ def SolaraViz(
     # set up reactive model_parameters shared by ModelCreator and ModelController
     reactive_model_parameters = solara.use_reactive({})
     reactive_play_interval = solara.use_reactive(play_interval)
-
+    reactive_render_interval = solara.use_reactive(render_interval)
     with solara.AppBar():
         solara.AppBarTitle(name if name else model.value.__class__.__name__)
 
@@ -117,11 +126,20 @@ def SolaraViz(
                 max=500,
                 step=10,
             )
+            solara.SliderInt(
+                label="Render Interval (steps)",
+                value=reactive_render_interval,
+                on_value=lambda v: reactive_render_interval.set(v),
+                min=1,
+                max=100,
+                step=2,
+            )
             if not isinstance(simulator, Simulator):
                 ModelController(
                     model,
                     model_parameters=reactive_model_parameters,
                     play_interval=reactive_play_interval,
+                    render_interval=reactive_render_interval,
                 )
             else:
                 SimulatorController(
@@ -129,6 +147,7 @@ def SolaraViz(
                     simulator,
                     model_parameters=reactive_model_parameters,
                     play_interval=reactive_play_interval,
+                    render_interval=reactive_render_interval,
                 )
         with solara.Card("Model Parameters"):
             ModelCreator(
@@ -189,6 +208,7 @@ def ModelController(
     *,
     model_parameters: dict | solara.Reactive[dict] = None,
     play_interval: int | solara.Reactive[int] = 100,
+    render_interval: int | solara.Reactive[int] = 1,
 ):
     """Create controls for model execution (step, play, pause, reset).
 
@@ -196,7 +216,7 @@ def ModelController(
         model: Reactive model instance
         model_parameters: Reactive parameters for (re-)instantiating a model.
         play_interval: Interval for playing the model steps in milliseconds.
-
+        render_interval: Controls how often the plots are updated during simulation steps.Higher value reduce update frequency.
     """
     playing = solara.use_reactive(False)
     running = solara.use_reactive(True)
@@ -215,9 +235,12 @@ def ModelController(
 
     @function_logger(__name__)
     def do_step():
-        """Advance the model by one step."""
-        model.value.step()
+        """Advance the model by the number of steps specified by the render_interval slider."""
+        for _ in range(render_interval.value):
+            model.value.step()
+
         running.value = model.value.running
+
         force_update()
 
     @function_logger(__name__)
@@ -259,6 +282,7 @@ def SimulatorController(
     *,
     model_parameters: dict | solara.Reactive[dict] = None,
     play_interval: int | solara.Reactive[int] = 100,
+    render_interval: int | solara.Reactive[int] = 1,
 ):
     """Create controls for model execution (step, play, pause, reset).
 
@@ -267,7 +291,11 @@ def SimulatorController(
         simulator: Simulator instance
         model_parameters: Reactive parameters for (re-)instantiating a model.
         play_interval: Interval for playing the model steps in milliseconds.
+        render_interval: Controls how often the plots are updated during simulation steps.Higher values reduce update frequency.
 
+    Notes:
+        The `step button` increments the step by the value specified in the `render_interval` slider.
+        This behavior ensures synchronization between simulation steps and plot updates.
     """
     playing = solara.use_reactive(False)
     running = solara.use_reactive(True)
@@ -285,8 +313,8 @@ def SimulatorController(
     )
 
     def do_step():
-        """Advance the model by one step."""
-        simulator.run_for(1)
+        """Advance the model by the number of steps specified by the render_interval slider."""
+        simulator.run_for(render_interval.value)
         running.value = model.value.running
         force_update()
 
@@ -390,7 +418,6 @@ def ModelCreator(
           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 = {}

{mesa-3.1.2.dist-info → mesa-3.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Mesa
-Version: 3.1.2
+Version: 3.1.4
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -24,8 +24,10 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Life
 Requires-Python: >=3.11
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: scipy
 Requires-Dist: tqdm
 Provides-Extra: all
+Requires-Dist: altair; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
 Requires-Dist: matplotlib; extra == 'all'
 Requires-Dist: myst-nb; extra == 'all'
@@ -40,7 +42,9 @@ Requires-Dist: scipy; extra == 'all'
 Requires-Dist: seaborn; extra == 'all'
 Requires-Dist: solara; extra == 'all'
 Requires-Dist: sphinx; extra == 'all'
+Requires-Dist: sphinx-copybutton; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: altair; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
 Requires-Dist: networkx; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
@@ -50,6 +54,7 @@ Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: solara; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: altair; extra == 'docs'
 Requires-Dist: ipython; extra == 'docs'
 Requires-Dist: matplotlib; extra == 'docs'
 Requires-Dist: myst-nb; extra == 'docs'
@@ -59,7 +64,9 @@ Requires-Dist: pydata-sphinx-theme; extra == 'docs'
 Requires-Dist: seaborn; extra == 'docs'
 Requires-Dist: solara; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-copybutton; extra == 'docs'
 Provides-Extra: examples
+Requires-Dist: altair; extra == 'examples'
 Requires-Dist: matplotlib; extra == 'examples'
 Requires-Dist: networkx; extra == 'examples'
 Requires-Dist: pytest; extra == 'examples'
@@ -68,10 +75,12 @@ Requires-Dist: solara; extra == 'examples'
 Provides-Extra: network
 Requires-Dist: networkx; extra == 'network'
 Provides-Extra: rec
+Requires-Dist: altair; extra == 'rec'
 Requires-Dist: matplotlib; extra == 'rec'
 Requires-Dist: networkx; extra == 'rec'
 Requires-Dist: solara; extra == 'rec'
 Provides-Extra: viz
+Requires-Dist: altair; extra == 'viz'
 Requires-Dist: matplotlib; extra == 'viz'
 Requires-Dist: solara; extra == 'viz'
 Description-Content-Type: text/markdown
@@ -106,27 +115,22 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-To install our latest stable release (3.0.x), run:
+To install our latest stable release, run:
 
 ``` bash
 pip install -U mesa
 ```
 
-To install our latest pre-release, run:
-
-``` bash
-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]
+pip install -U mesa[network,viz]
 
 # This is equivalent to our recommended dependencies:
-pip install -U --pre mesa[rec]
+pip install -U mesa[rec]
 
 # To install all, including developer, dependencies:
-pip install -U --pre mesa[all]
+pip install -U mesa[all]
 ```
 
 You can also use `pip` to install the latest GitHub version: