Mesa 3.1.0.dev0__py3-none-any.whl → 3.1.2__py3-none-any.whl

mesa/experimental/mesa_signals/signals_util.py

@@ -0,0 +1,52 @@
+"""Utility functions and classes for Mesa's signals implementation.
+
+This module provides helper functionality used by Mesa's reactive programming system:
+
+- AttributeDict: A dictionary subclass that allows attribute-style access to its contents
+- create_weakref: Helper function to properly create weak references to different types
+
+These utilities support the core signals implementation by providing reference
+management and convenient data structures used throughout the reactive system.
+"""
+
+import weakref
+
+__all__ = [
+    "AttributeDict",
+    "create_weakref",
+]
+
+
+class AttributeDict(dict):
+    """A dict with attribute like access.
+
+    Each value can be accessed as if it were an attribute with its key as attribute name
+
+    """
+
+    # I want our signals to act like traitlet signals, so this is inspired by trailets Bunch
+    # and some stack overflow posts.
+    __setattr__ = dict.__setitem__
+    __delattr__ = dict.__delitem__
+
+    def __getattr__(self, key):  # noqa: D105
+        try:
+            return self.__getitem__(key)
+        except KeyError as e:
+            # we need to go from key error to attribute error
+            raise AttributeError(key) from e
+
+    def __dir__(self):  # noqa: D105
+        # allows us to easily access all defined attributes
+        names = dir({})
+        names.extend(self.keys())
+        return names
+
+
+def create_weakref(item, callback=None):
+    """Helper function to create a correct weakref for any item."""
+    if hasattr(item, "__self__"):
+        ref = weakref.WeakMethod(item, callback)
+    else:
+        ref = weakref.ref(item, callback)
+    return ref

mesa/mesa_logging.py

@@ -0,0 +1,190 @@
+"""This provides logging functionality for MESA.
+
+It is modeled on the default `logging approach that comes with Python <https://docs.python.org/library/logging.html>`_.
+
+
+"""
+
+import inspect
+import logging
+from functools import wraps
+from logging import DEBUG, INFO
+
+__all__ = [
+    "DEBUG",
+    "DEFAULT_LEVEL",
+    "INFO",
+    "LOGGER_NAME",
+    "function_logger",
+    "get_module_logger",
+    "get_rootlogger",
+    "log_to_stderr",
+    "method_logger",
+]
+LOGGER_NAME = "MESA"
+DEFAULT_LEVEL = DEBUG
+
+
+def create_module_logger(name: str | None = None):
+    """Helper function for creating a module logger.
+
+    Args:
+        name (str): The name to be given to the logger. If the name is None, the name defaults to the name of the module.
+
+    """
+    if name is None:
+        frm = inspect.stack()[1]
+        mod = inspect.getmodule(frm[0])
+        name = mod.__name__
+    logger = logging.getLogger(f"{LOGGER_NAME}.{name}")
+
+    _module_loggers[name] = logger
+    return logger
+
+
+def get_module_logger(name: str):
+    """Helper function for getting the module logger.
+
+    Args:
+        name (str): The name of the module in which the method being decorated is located
+
+    """
+    try:
+        logger = _module_loggers[name]
+    except KeyError:
+        logger = create_module_logger(name)
+
+    return logger
+
+
+_rootlogger = None
+_module_loggers = {}
+_logger = get_module_logger(__name__)
+
+
+class MESAColorFormatter(logging.Formatter):
+    """Custom formatter for color based formatting."""
+
+    grey = "\x1b[38;20m"
+    green = "\x1b[32m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+    format = (
+        "[%(asctime)s] [%(name)s] [%(levelname)s] %(message)s [%(filename)s:%(lineno)d]"
+    )
+
+    FORMATS = {
+        logging.DEBUG: grey + format + reset,
+        logging.INFO: green + format + reset,
+        logging.WARNING: yellow + format + reset,
+        logging.ERROR: red + format + reset,
+        logging.CRITICAL: bold_red + format + reset,
+    }
+
+    def format(self, record):
+        """Format record."""
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def method_logger(name: str):
+    """Decorator for adding logging to a method.
+
+    Args:
+        name (str): The name of the module in which the method being decorated is located
+
+    """
+    logger = get_module_logger(name)
+    classname = inspect.getouterframes(inspect.currentframe())[1][3]
+
+    def real_decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # hack, because log is applied to methods, we can get
+            # object instance as first arguments in args
+            logger.debug(
+                f"calling {classname}.{func.__name__} with {args[1::]} and {kwargs}"
+            )
+            res = func(*args, **kwargs)
+            return res
+
+        return wrapper
+
+    return real_decorator
+
+
+def function_logger(name):
+    """Decorator for adding logging to a Function.
+
+    Args:
+        name (str): The name of the module in which the function being decorated is located
+
+    """
+    logger = get_module_logger(name)
+
+    def real_decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            logger.debug(f"calling {func.__name__} with {args} and {kwargs}")
+            res = func(*args, **kwargs)
+            return res
+
+        return wrapper
+
+    return real_decorator
+
+
+def get_rootlogger():
+    """Returns root logger used by MESA.
+
+    Returns:
+        the root logger of MESA
+
+    """
+    global _rootlogger  # noqa: PLW0603
+
+    if not _rootlogger:
+        _rootlogger = logging.getLogger(LOGGER_NAME)
+        _rootlogger.handlers = []
+        _rootlogger.addHandler(logging.NullHandler())
+        _rootlogger.setLevel(DEBUG)
+
+    return _rootlogger
+
+
+def log_to_stderr(level: int | None = None, pass_root_logger_level: bool = False):
+    """Turn on logging and add a handler which prints to stderr.
+
+    Args:
+        level: minimum level of the messages that will be logged
+        pass_root_logger_level: bool, optional. Default False
+                if True, all module loggers will be set to the same logging level as the root logger.
+
+    """
+    if not level:
+        level = DEFAULT_LEVEL
+
+    logger = get_rootlogger()
+
+    # avoid creation of multiple stream handlers for logging to console
+    for entry in logger.handlers:
+        if (isinstance(entry, logging.StreamHandler)) and (
+            isinstance(entry.formatter, MESAColorFormatter)
+        ):
+            return logger
+
+    formatter = MESAColorFormatter()
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False
+
+    if pass_root_logger_level:
+        for _, mod_logger in _module_loggers.items():
+            mod_logger.setLevel(level)
+
+    return logger

mesa/model.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 
 import random
 import sys
-import warnings
 from collections.abc import Sequence
 
 # mypy
@@ -18,11 +17,15 @@ from typing import Any
 import numpy as np
 
 from mesa.agent import Agent, AgentSet
+from mesa.mesa_logging import create_module_logger, method_logger
 
 SeedLike = int | np.integer | Sequence[int] | np.random.SeedSequence
 RNGLike = np.random.Generator | np.random.BitGenerator
 
 
+_mesa_logger = create_module_logger()
+
+
 class Model:
     """Base class for models in the Mesa ABM library.
 
@@ -32,7 +35,6 @@ class Model:
 
     Attributes:
         running: A boolean indicating if the model should continue running.
-        schedule: An object to manage the order and execution of agent steps.
         steps: the number of times `model.step()` has been called.
         random: a seeded python.random number generator.
         rng : a seeded numpy.random.Generator
@@ -44,6 +46,7 @@ class Model:
 
     """
 
+    @method_logger(__name__)
     def __init__(
         self,
         *args: Any,
@@ -102,12 +105,19 @@ class Model:
         self.step = self._wrapped_step
 
         # setup agent registration data structures
-        self._setup_agent_registration()
+        self._agents = {}  # the hard references to all agents in the model
+        self._agents_by_type: dict[
+            type[Agent], AgentSet
+        ] = {}  # a dict with an agentset for each class of agents
+        self._all_agents = AgentSet(
+            [], random=self.random
+        )  # an agenset with all agents
 
     def _wrapped_step(self, *args: Any, **kwargs: Any) -> None:
         """Automatically increments time and steps after calling the user's step method."""
         # Automatically increment time and step counters
         self.steps += 1
+        _mesa_logger.info(f"calling model.step for timestep {self.steps} ")
         # Call the original user-defined step method
         self._user_step(*args, **kwargs)
 
@@ -134,16 +144,6 @@ class Model:
         """A dictionary where the keys are agent types and the values are the corresponding AgentSets."""
         return self._agents_by_type
 
-    def _setup_agent_registration(self):
-        """Helper method to initialize the agent registration datastructures."""
-        self._agents = {}  # the hard references to all agents in the model
-        self._agents_by_type: dict[
-            type[Agent], AgentSet
-        ] = {}  # a dict with an agentset for each class of agents
-        self._all_agents = AgentSet(
-            [], random=self.random
-        )  # an agenset with all agents
-
     def register_agent(self, agent):
         """Register the agent with the model.
 
@@ -155,16 +155,6 @@ class Model:
             if you are subclassing Agent and calling its super in the ``__init__`` method.
 
         """
-        if not hasattr(self, "_agents"):
-            self._setup_agent_registration()
-
-            warnings.warn(
-                "The Mesa Model class was not initialized. In the future, you need to explicitly initialize "
-                "the Model by calling super().__init__() on initialization.",
-                FutureWarning,
-                stacklevel=2,
-            )
-
         self._agents[agent] = None
 
         # because AgentSet requires model, we cannot use defaultdict
@@ -180,6 +170,9 @@ class Model:
             )
 
         self._all_agents.add(agent)
+        _mesa_logger.debug(
+            f"registered {agent.__class__.__name__} with agent_id {agent.unique_id}"
+        )
 
     def deregister_agent(self, agent):
         """Deregister the agent with the model.
@@ -194,6 +187,7 @@ class Model:
         del self._agents[agent]
         self._agents_by_type[type(agent)].remove(agent)
         self._all_agents.remove(agent)
+        _mesa_logger.debug(f"deregistered agent with agent_id {agent.unique_id}")
 
     def run_model(self) -> None:
         """Run the model until the end condition is reached.

mesa/visualization/__init__.py

@@ -17,10 +17,10 @@ from .user_param import Slider
 
 __all__ = [
     "JupyterViz",
-    "SolaraViz",
     "Slider",
-    "make_space_altair",
+    "SolaraViz",
     "draw_space",
     "make_plot_component",
+    "make_space_altair",
     "make_space_component",
 ]

mesa/visualization/mpl_space_drawing.py

@@ -117,7 +117,6 @@ def draw_space(
         agent_portrayal: A callable that returns a dict specifying how to show the agent
         propertylayer_portrayal: a dict specifying how to show propertylayer(s)
         ax: the axes upon which to draw the plot
-        post_process: a callable called with the Axes instance
         space_drawing_kwargs: any additional keyword arguments to be passed on to the underlying function for drawing the space.
 
     Returns:
@@ -178,15 +177,18 @@ def draw_property_layers(
         property_layers = space.properties
     except AttributeError:
         # new style spaces
-        property_layers = space.property_layers
+        property_layers = space._mesa_property_layers
 
     for layer_name, portrayal in propertylayer_portrayal.items():
         layer = property_layers.get(layer_name, None)
-        if not isinstance(layer, PropertyLayer):
+        if not isinstance(
+            layer,
+            PropertyLayer | mesa.experimental.cell_space.property_layer.PropertyLayer,
+        ):
             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)
+        width, height = data.shape  # if space is None else (space.width, space.height)
 
         if space and data.shape != (width, height):
             warnings.warn(
@@ -212,7 +214,7 @@ def draw_property_layers(
                 layer_name, [(0, 0, 0, 0), (*rgba_color[:3], alpha)]
             )
             im = ax.imshow(
-                rgba_data.transpose(1, 0, 2),
+                rgba_data,
                 origin="lower",
             )
             if colorbar:
@@ -226,7 +228,7 @@ def draw_property_layers(
             if isinstance(cmap, list):
                 cmap = LinearSegmentedColormap.from_list(layer_name, cmap)
             im = ax.imshow(
-                data.T,
+                data,
                 cmap=cmap,
                 alpha=alpha,
                 vmin=vmin,

mesa/visualization/solara_viz.py

@@ -33,14 +33,18 @@ import solara
 
 import mesa.visualization.components.altair_components as components_altair
 from mesa.experimental.devs.simulator import Simulator
+from mesa.mesa_logging import create_module_logger, function_logger
 from mesa.visualization.user_param import Slider
 from mesa.visualization.utils import force_update, update_counter
 
 if TYPE_CHECKING:
     from mesa.model import Model
 
+_mesa_logger = create_module_logger()
+
 
 @solara.component
+@function_logger(__name__)
 def SolaraViz(
     model: Model | solara.Reactive[Model],
     components: list[reacton.core.Component]
@@ -98,24 +102,33 @@ 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)
 
     with solara.AppBar():
         solara.AppBarTitle(name if name else model.value.__class__.__name__)
 
     with solara.Sidebar(), solara.Column():
         with solara.Card("Controls"):
+            solara.SliderInt(
+                label="Play Interval (ms)",
+                value=reactive_play_interval,
+                on_value=lambda v: reactive_play_interval.set(v),
+                min=1,
+                max=500,
+                step=10,
+            )
             if not isinstance(simulator, Simulator):
                 ModelController(
                     model,
                     model_parameters=reactive_model_parameters,
-                    play_interval=play_interval,
+                    play_interval=reactive_play_interval,
                 )
             else:
                 SimulatorController(
                     model,
                     simulator,
                     model_parameters=reactive_model_parameters,
-                    play_interval=play_interval,
+                    play_interval=reactive_play_interval,
                 )
         with solara.Card("Model Parameters"):
             ModelCreator(
@@ -175,7 +188,7 @@ def ModelController(
     model: solara.Reactive[Model],
     *,
     model_parameters: dict | solara.Reactive[dict] = None,
-    play_interval: int = 100,
+    play_interval: int | solara.Reactive[int] = 100,
 ):
     """Create controls for model execution (step, play, pause, reset).
 
@@ -193,25 +206,32 @@ def ModelController(
 
     async def step():
         while playing.value and running.value:
-            await asyncio.sleep(play_interval / 1000)
+            await asyncio.sleep(play_interval.value / 1000)
             do_step()
 
     solara.lab.use_task(
         step, dependencies=[playing.value, running.value], prefer_threaded=False
     )
 
+    @function_logger(__name__)
     def do_step():
         """Advance the model by one step."""
         model.value.step()
         running.value = model.value.running
         force_update()
 
+    @function_logger(__name__)
     def do_reset():
         """Reset the model to its initial state."""
         playing.value = False
         running.value = True
+        _mesa_logger.log(
+            10,
+            f"creating new {model.value.__class__} instance with {model_parameters.value}",
+        )
         model.value = model.value = model.value.__class__(**model_parameters.value)
 
+    @function_logger(__name__)
     def do_play_pause():
         """Toggle play/pause."""
         playing.value = not playing.value
@@ -238,7 +258,7 @@ def SimulatorController(
     simulator,
     *,
     model_parameters: dict | solara.Reactive[dict] = None,
-    play_interval: int = 100,
+    play_interval: int | solara.Reactive[int] = 100,
 ):
     """Create controls for model execution (step, play, pause, reset).
 
@@ -257,7 +277,7 @@ def SimulatorController(
 
     async def step():
         while playing.value and running.value:
-            await asyncio.sleep(play_interval / 1000)
+            await asyncio.sleep(play_interval.value / 1000)
             do_step()
 
     solara.lab.use_task(
@@ -382,12 +402,19 @@ def ModelCreator(
     )
     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()},
-    }
+    # Use solara.use_effect to run the initialization code only once
+    solara.use_effect(
+        # set model_parameters to the default values for all parameters
+        lambda: model_parameters.set(
+            {
+                **fixed_params,
+                **{k: v.get("value") for k, v in user_params.items()},
+            }
+        ),
+        [],
+    )
 
+    @function_logger(__name__)
     def on_change(name, value):
         model_parameters.value = {**model_parameters.value, name: value}
 
@@ -405,6 +432,17 @@ def _check_model_params(init_func, model_params):
         ValueError: If a parameter is not valid for the model's initialization function
     """
     model_parameters = inspect.signature(init_func).parameters
+
+    has_var_positional = any(
+        param.kind == inspect.Parameter.VAR_POSITIONAL
+        for param in model_parameters.values()
+    )
+
+    if has_var_positional:
+        raise ValueError(
+            "Mesa's visualization requires the use of keyword arguments to ensure the parameters are passed to Solara correctly. Please ensure all model parameters are of form param=value"
+        )
+
     for name in model_parameters:
         if (
             model_parameters[name].default == inspect.Parameter.empty

{mesa-3.1.0.dev0.dist-info → mesa-3.1.2.dist-info}/METADATA

@@ -1,11 +1,13 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: Mesa
-Version: 3.1.0.dev0
+Version: 3.1.2
 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