Mesa 3.0.3__py3-none-any.whl → 3.1.0__py3-none-any.whl

mesa/experimental/mesa_signals/observable_collections.py

@@ -0,0 +1,133 @@
+"""Observable collection types that emit signals when modified.
+
+This module extends Mesa's reactive programming capabilities to collection types like
+lists. Observable collections emit signals when items are added, removed, or modified,
+allowing other components to react to changes in the collection's contents.
+
+The module provides:
+- ObservableList: A list descriptor that emits signals on modifications
+- SignalingList: The underlying list implementation that manages signal emission
+
+These classes enable building models where components need to track and react to
+changes in collections of agents, resources, or other model elements.
+"""
+
+from collections.abc import Iterable, MutableSequence
+from typing import Any
+
+from .mesa_signal import BaseObservable, HasObservables
+
+__all__ = [
+    "ObservableList",
+]
+
+
+class ObservableList(BaseObservable):
+    """An ObservableList that emits signals on changes to the underlying list."""
+
+    def __init__(self):
+        """Initialize the ObservableList."""
+        super().__init__()
+        self.signal_types: set = {"remove", "replace", "change", "insert", "append"}
+        self.fallback_value = []
+
+    def __set__(self, instance: "HasObservables", value: Iterable):
+        """Set the value of the descriptor attribute.
+
+        Args:
+            instance: The instance on which to set the attribute.
+            value: The value to set the attribute to.
+
+        """
+        super().__set__(instance, value)
+        setattr(
+            instance,
+            self.private_name,
+            SignalingList(value, instance, self.public_name),
+        )
+
+
+class SignalingList(MutableSequence[Any]):
+    """A basic lists that emits signals on changes."""
+
+    __slots__ = ["data", "name", "owner"]
+
+    def __init__(self, iterable: Iterable, owner: HasObservables, name: str):
+        """Initialize a SignalingList.
+
+        Args:
+            iterable: initial values in the list
+            owner: the HasObservables instance on which this list is defined
+            name: the attribute name to which  this list is assigned
+
+        """
+        self.owner: HasObservables = owner
+        self.name: str = name
+        self.data = list(iterable)
+
+    def __setitem__(self, index: int, value: Any) -> None:
+        """Set item to index.
+
+        Args:
+            index: the index to set item to
+            value: the item to set
+
+        """
+        old_value = self.data[index]
+        self.data[index] = value
+        self.owner.notify(self.name, old_value, value, "replace", index=index)
+
+    def __delitem__(self, index: int) -> None:
+        """Delete item at index.
+
+        Args:
+            index: The index of the item to remove
+
+        """
+        old_value = self.data
+        del self.data[index]
+        self.owner.notify(self.name, old_value, None, "remove", index=index)
+
+    def __getitem__(self, index) -> Any:
+        """Get item at index.
+
+        Args:
+            index: The index of the item to retrieve
+
+        Returns:
+            the item at index
+        """
+        return self.data[index]
+
+    def __len__(self) -> int:
+        """Return the length of the list."""
+        return len(self.data)
+
+    def insert(self, index, value):
+        """Insert value at index.
+
+        Args:
+            index: the index to insert value into
+            value: the value to insert
+
+        """
+        self.data.insert(index, value)
+        self.owner.notify(self.name, None, value, "insert", index=index)
+
+    def append(self, value):
+        """Insert value at index.
+
+        Args:
+            index: the index to insert value into
+            value: the value to insert
+
+        """
+        index = len(self.data)
+        self.data.append(value)
+        self.owner.notify(self.name, None, value, "append", index=index)
+
+    def __str__(self):
+        return self.data.__str__()
+
+    def __repr__(self):
+        return self.data.__repr__()

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,12 +17,15 @@ from typing import Any
 import numpy as np
 
 from mesa.agent import Agent, AgentSet
-from mesa.datacollection import DataCollector
+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.
 
@@ -33,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
@@ -45,6 +46,7 @@ class Model:
 
     """
 
+    @method_logger(__name__)
     def __init__(
         self,
         *args: Any,
@@ -103,23 +105,22 @@ 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)
 
-    def next_id(self) -> int:  # noqa: D102
-        warnings.warn(
-            "using model.next_id() is deprecated and will be removed in Mesa 3.1. Agents track their unique ID automatically",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return 0
-
     @property
     def agents(self) -> AgentSet:
         """Provides an AgentSet of all agents in the model, combining agents from all types."""
@@ -143,26 +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 get_agents_of_type(self, agenttype: type[Agent]) -> AgentSet:
-        """Deprecated: Retrieves an AgentSet containing all agents of the specified type."""
-        warnings.warn(
-            f"Model.get_agents_of_type() is deprecated and will be removed in Mesa 3.1."
-            f"Please replace get_agents_of_type({agenttype}) with the property agents_by_type[{agenttype}].",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.agents_by_type[agenttype]
-
-    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.
 
@@ -174,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
@@ -199,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.
@@ -213,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.
@@ -245,38 +220,6 @@ class Model:
         self.rng = np.random.default_rng(rng)
         self._rng = self.rng.bit_generator.state
 
-    def initialize_data_collector(
-        self,
-        model_reporters=None,
-        agent_reporters=None,
-        agenttype_reporters=None,
-        tables=None,
-    ) -> None:
-        """Initialize the data collector for the model.
-
-        Args:
-            model_reporters: model reporters to collect
-            agent_reporters: agent reporters to collect
-            agenttype_reporters: agent type reporters to collect
-            tables: tables to collect
-
-        """
-        warnings.warn(
-            "initialize_data_collector() is deprecated and will be removed in Mesa 3.1. Please use the DataCollector class directly. "
-            "by using `self.datacollector = DataCollector(...)`.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-        self.datacollector = DataCollector(
-            model_reporters=model_reporters,
-            agent_reporters=agent_reporters,
-            agenttype_reporters=agenttype_reporters,
-            tables=tables,
-        )
-        # Collect data for the first time during initialization.
-        self.datacollector.collect(self)
-
     def remove_all_agents(self):
         """Remove all agents from the model.
 

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

@@ -178,7 +178,7 @@ 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)
@@ -186,7 +186,7 @@ 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)
+        width, height = data.shape  # if space is None else (space.width, space.height)
 
         if space and data.shape != (width, height):
             warnings.warn(

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]
@@ -200,18 +204,25 @@ def ModelController(
         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
@@ -394,6 +405,7 @@ def ModelCreator(
         [],
     )
 
+    @function_logger(__name__)
     def on_change(name, value):
         model_parameters.value = {**model_parameters.value, name: value}
 

{mesa-3.0.3.dist-info → mesa-3.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.3
+Version: 3.1.0
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -13,14 +13,13 @@ 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.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 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.10
+Requires-Python: >=3.11
 Requires-Dist: numpy
 Requires-Dist: pandas
 Requires-Dist: tqdm
@@ -81,7 +80,7 @@ Description-Content-Type: text/markdown
 | --- | --- |
 | CI/CD | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |
 | Package | [![PyPI - Version](https://img.shields.io/pypi/v/mesa.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mesa.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mesa.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/Mesa/) |
-| 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) |
+| 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) [![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/) |
 | Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
 
 Mesa allows users to quickly create agent-based models using built-in