FEAT: Add class-level subscribe to HasEmitters by Nithurshen · Pull Request #3368 · mesa/mesa

Nithurshen · 2026-02-24T03:01:56Z

Summary

This PR introduces the ability to subscribe to observable events at the class level via a new @classmethod subscribe. Subscriptions made this way are inherited by all instances of that class, meaning any instance emitting the specified signal will trigger the registered handler.

Motive

This addresses a specific enhancement requested in the Mesa Signals tracking issue #3227. Previously, observing agents globally required relying on model.register_agent or manually binding observe to every instantiated object at runtime. This feature makes global data collection, UI updates, and logging significantly easier and more intuitive by allowing a one time class level binding.

Implementation

Modified HasObservables.__init_subclass__ to initialize a distinct _class_subscribers dictionary for every subclass. This ensures that subscribing to a specific Agent subclass doesn't accidentally bind handlers to all other reactive classes.
Added @classmethod subscribe(...) which mirrors the signature of the instance-level observe method but registers the handler globally for the class.
Strictly utilized create_weakref(handler) for class-level subscribers. This directly addresses the concern raised in the tracking issue by ensuring that the global observer doesn't prevent model instances from being properly garbage-collected during large experiments or parameter sweeps.
Updated _has_subscribers and _mesa_notify to seamlessly aggregate and dispatch messages to both instance-level and class-level listeners.
Added test_class_level_subscribe to tests/experimental/test_mesa_signals.py to verify functionality across multiple instances.

Usage Examples

You can now easily observe all instances of an agent class without needing to register handlers on them individually:

from mesa.experimental.mesa_signals import HasObservables, Observable
from mesa.experimental.mesa_signals.signal_types import ObservableSignals

class MyAgent(HasObservables):
    state = Observable()

def state_change_handler(msg):
    agent = msg.owner
    old_val = msg.additional_kwargs.get("old")
    new_val = msg.additional_kwargs.get("new")
    print(f"Agent {agent} changed state from {old_val} to {new_val}")

MyAgent.subscribe("state", ObservableSignals.CHANGED, state_change_handler)

agent1 = MyAgent()
agent2 = MyAgent()

agent1.state = "active"   # Prints: Agent <...> changed state from None to active
agent2.state = "waiting"  # Prints: Agent <...> changed state from None to waiting

Additional Notes

This fulfills the third bullet point of tracking issue Mesa Signals improvements (tracking issue) #3227.
This PR is currently built using the existing HasObservables name. If the concurrent PR renaming this to HasEmitters is merged first (Refactor: Rename HasObservables to HasEmitters #3367), I am happy to rebase and resolve the naming conflict.

github-actions · 2026-02-24T03:17:26Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +0.2% [-0.2%, +0.6%]	🔵 -0.4% [-0.5%, -0.2%]
BoltzmannWealth	large	🔵 +0.7% [+0.4%, +1.0%]	🟢 -4.7% [-5.6%, -3.6%]
Schelling	small	🔵 +0.4% [+0.2%, +0.7%]	🔵 +0.2% [-0.0%, +0.4%]
Schelling	large	🔵 +0.8% [+0.4%, +1.3%]	🔵 +1.8% [+0.1%, +3.5%]
WolfSheep	small	🔵 +1.4% [+1.2%, +1.5%]	🔵 +0.7% [+0.5%, +1.0%]
WolfSheep	large	🔵 +1.4% [+0.9%, +2.0%]	🔵 +1.4% [+0.6%, +2.3%]
BoidFlockers	small	🔵 +1.1% [+0.8%, +1.3%]	🔵 -0.8% [-0.9%, -0.6%]
BoidFlockers	large	🔵 +1.5% [+1.2%, +2.0%]	🔵 -0.4% [-0.5%, -0.2%]

github-actions · 2026-02-24T03:19:05Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +1.1% [+0.7%, +1.5%]	🔵 -1.9% [-2.1%, -1.6%]
BoltzmannWealth	large	🔵 +0.9% [+0.5%, +1.1%]	🔵 -1.1% [-1.4%, -0.8%]
Schelling	small	🔵 +1.6% [+1.3%, +1.9%]	🔵 -0.3% [-0.5%, -0.1%]
Schelling	large	🔵 +0.6% [+0.2%, +0.9%]	🔵 +2.7% [+2.1%, +3.5%]
WolfSheep	small	🔵 +2.6% [+2.4%, +2.8%]	🔵 +1.0% [+0.8%, +1.2%]
WolfSheep	large	🔵 +2.6% [+1.9%, +3.3%]	🔵 +2.2% [+1.6%, +2.9%]
BoidFlockers	small	🔵 +0.3% [+0.1%, +0.5%]	🔵 -0.1% [-0.3%, +0.1%]
BoidFlockers	large	🔵 -0.6% [-0.9%, -0.3%]	🔵 -0.2% [-0.3%, -0.0%]

quaquel · 2026-02-24T12:50:24Z

mesa/experimental/mesa_signals/core.py

+            key in self.subscribers and len(self.subscribers[key]) > 0
+        )
+        has_class_subscribers = (
+            hasattr(self, "_class_subscribers")


this check should not be needed if _class_subscribers is implemented correctly.

quaquel · 2026-02-24T12:51:38Z

mesa/experimental/mesa_signals/core.py

-                active_observer(signal)
-                active_observers.append(observer)
-            # use iteration to also remove inactive observers
+        if key in self.subscribers:


this check seems redundant.

quaquel · 2026-02-24T12:52:56Z

mesa/experimental/mesa_signals/core.py

+            class_observers = self._class_subscribers[key]
+            active_class_observers = []
+            for observer in class_observers:
+                if active_class_observer := observer():
+                    active_class_observer(signal)
+                    active_class_observers.append(observer)
+
+            if active_class_observers:
+                self._class_subscribers[key] = active_class_observers
+            else:
+                del self._class_subscribers[key]


This seems like code repetition. I am wondering whether this could not be implemented in a way that would avoid the apparent code duplication.

quaquel · 2026-02-24T12:55:34Z

mesa/experimental/mesa_signals/core.py

            return signal_type

+    @classmethod
+    def subscribe(


not sure about the naming here. We now have Class.subcribe and Instance.observe. What about e.g., Class.observe_class or something along those lines?

quaquel · 2026-02-24T12:56:42Z

mesa/experimental/mesa_signals/core.py

+        names = (
+            [observable_name]
+            if isinstance(observable_name, str)
+            else (cls.observables.keys() if observable_name is ALL else observable_name)
+        )


please refactor this into something more readable.

quaquel · 2026-02-24T12:58:03Z

mesa/experimental/mesa_signals/core.py

+            for st in signal_types:
+                cls._class_subscribers[(name, st)].append(ref)
+



there seems to be overlap with observe code, so can this be simplified in a way that avoids code duplications?

…rshen/mesa into pr/3368

quaquel · 2026-02-25T09:37:54Z

What about unobserve_class? At a minimum, this class method should be there to mimic the instance level observe and unobserve.
What about clear_all_subscriptions? This currently clears everything at the instance level. How do we want to handle class level subscriptions in this?

This second question points to a wider architectural question. At the moment, this PR maintains two lists of subscribers: instance-level subscriptions and class-level subscriptions. To me this is a sensible design. However, an alternative would be to let the instance at creation "inherit" all class-level subscriptions by adding these to the instance subscription dict. The advantage of this is that clear_all_subscriptions then does wat is says. However, it also means that any class level new subscriptions that happen after instantiation are not well defined. Thoughs on this are welcome.

…r observers

Nithurshen · 2026-02-25T10:38:44Z

Regarding the architectural question, I definitely think keeping the two list design is the most robust approach. If we were to let instances inherit class-level subscriptions by copying them into the instance dictionary during __init__, we would run into a few major issues:

If a user calls observe_class after some instances are already created, those older instances wouldn't receive the new subscription since their __init__ has already run.
If a user later calls unobserve_class, we would have no way to remove that observer from already-instantiated objects without tracking every single instance in memory.
If a user calls agent1.clear_all_subscriptions(), it shouldn't unexpectedly wipe out a global class-level observer (like a DataCollector or UI renderer) that the rest of the model relies on.

To resolve this and address the rest of your feedback, I have made the following changes:

Added unobserve_class and clear_all_class_subscriptions to ensure class-level observers have the same lifecycle controls as instance-level ones.
Refactored the internal logic into shared _register_observer and _unregister_observer helpers to keep the code DRY and eliminate the overlap between the class and instance methods.
Merged the dispatch logic in _mesa_notify into a single loop over (self.subscribers, self._class_subscribers), utilizing .get() to remove the redundant if key in... checks.
Typed _class_subscribers as a ClassVar and initialized it on the base class, completely removing the need for the hasattr check overhead.
Renamed the method to observe_class for consistency, and refactored _process_name and _process_signal_type into @classmethods to remove the nested ternary operators.

Let me know if this implementation aligns with your vision.

quaquel · 2026-03-02T13:14:27Z

mesa/experimental/mesa_signals/core.py

-                    else:
-                        del self.subscribers[key]
+    @classmethod
+    def _clear_all_subscriptions_from_dict(cls, subs_dict: dict, name: ObservableName):


Suggested change

def _clear_all_subscriptions_from_dict(cls, subs_dict: dict, name: ObservableName):

def _clear_all_subscriptions(cls, subs_dict: dict, name: ObservableName):

mesa/experimental/mesa_signals/core.py

Nithurshen · 2026-03-04T14:22:39Z

@quaquel, Is there still anything you wish to be changed?

quaquel · 2026-03-04T15:42:38Z

mesa/experimental/mesa_signals/core.py


-            signal_types = target_signals or self.observables[name]
+        for name in names:
+            signal_types = target_signals or cls.observables[name]


You might want to clarify the logic here. If signal_type is ALL, target_signals returns None and that is handled nex in this statement.

quaquel · 2026-03-04T15:45:24Z

Sorry took me a while to review the code. It looks fine with one remaining request.

Feat: Add class-level subscribe to HasObservables (mesa#3227)

ade8eff

Nithurshen marked this pull request as ready for review February 24, 2026 03:03

quaquel reviewed Feb 24, 2026

View reviewed changes

Nithurshen and others added 2 commits February 24, 2026 22:43

Merge branch 'main' into feat/class-level-subscribe

94c82b3

Refactor: Address review feedback for observe_class

49fd4db

Nithurshen changed the title ~~FEAT: Add class-level subscribe to HasObservables~~ FEAT: Add class-level subscribe to HasEmitters Feb 24, 2026

Nithurshen requested a review from quaquel February 24, 2026 17:52

quaquel added 2 commits February 25, 2026 10:18

Merge remote-tracking branch 'upstream/main' into pr/3368

6e2f5e6

Merge branch 'feat/class-level-subscribe' of https://github.com/Nithu…

c62cd6c

…rshen/mesa into pr/3368

Feat: Add unobserve_class, clear_all_class_subscriptions, and refacto…

155e616

…r observers

Merge branch 'main' into feat/class-level-subscribe

15801bd

quaquel reviewed Mar 2, 2026

View reviewed changes

mesa/experimental/mesa_signals/core.py Show resolved Hide resolved

quaquel reviewed Mar 2, 2026

View reviewed changes

mesa/experimental/mesa_signals/core.py Show resolved Hide resolved

Nithurshen and others added 5 commits March 2, 2026 21:06

Refactor: _clear_all_subscriptions

c9f4507

Merge branch 'main' into feat/class-level-subscribe

6982b87

Merge branch 'main' into feat/class-level-subscribe

fe8019c

Merge branch 'main' into feat/class-level-subscribe

944a9bc

Merge branch 'main' into feat/class-level-subscribe

832297c

quaquel reviewed Mar 4, 2026

View reviewed changes

Nithurshen and others added 2 commits March 5, 2026 07:11

Fix: target_signals return None

b84d33a

Merge branch 'main' into feat/class-level-subscribe

3588d9e

Nithurshen requested a review from quaquel March 5, 2026 01:43

Merge branch 'main' into feat/class-level-subscribe

4a1675f

quaquel approved these changes Mar 5, 2026

View reviewed changes

quaquel merged commit 42c95d1 into mesa:main Mar 5, 2026
14 checks passed

Nithurshen deleted the feat/class-level-subscribe branch March 5, 2026 12:04

EwoutH added the experimental Release notes label label Mar 13, 2026

		for st in signal_types:
		cls._class_subscribers[(name, st)].append(ref)

	def _clear_all_subscriptions_from_dict(cls, subs_dict: dict, name: ObservableName):
	def _clear_all_subscriptions(cls, subs_dict: dict, name: ObservableName):

Uh oh!

Conversation

Nithurshen commented Feb 24, 2026

Summary

Motive

Implementation

Usage Examples

Additional Notes

Uh oh!

github-actions bot commented Feb 24, 2026

Uh oh!

github-actions bot commented Feb 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quaquel commented Feb 25, 2026

Uh oh!

Nithurshen commented Feb 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Nithurshen commented Mar 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quaquel commented Mar 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants