MESA and signals

[quaquel]

I, at long last, have picked up the work on pub/sub and data collection. In the meantime, many things have changed in MESA, and good suggestions have been made on data collection and libraries that might be worth a look. Let me first try to summarize the idea.

Motivation and background

At the moment, the visualization piggybacks on the data collection. Ideally, however, MESA should offer a way of declaring at the Agent/Model level that given attributes are of interest and to be tracked by data collection and/or a GUI. This would more cleanly separate data collection and visualization and thus result in a cleaner separation of concern. Moreover, @Corvince suggested to potentially automate default datacollection. Again, this requires some way for the user to declare what data should be collected. Pub/Sub, Signals, or whatever you which to call it is a suitable design pattern for providing this mechanism.

Also, I have gotten stuck with some of my earlier work on this by trying to solve the data collection and this pub/sub stuff in one go. It might be more fruitful to approach this as has been happening with the AgentSet. First, add a simple working thing and see how it grows and can be used to solve various problems in MESA.

API considerations

Ideally, the API for declaring attributes as being of interest to something outside the model is simple. This is why I have been advocating the use of descriptors. This would allow the user to just add at the top of the class definition which attributes are of interest, and the rest is taken care of by MESA. This gives a very simple declarative API. The API would be

class BoltzmanAgent:
	wealth = Observable()


class BoltzmanWealthModel:
	gini = Observable()

Here, Observable is the descriptor that declares wealth and gini to be of interest to be tracked by, e.g., a visualization or data collection mechanism. The name is, of course, open for discussion. Ideally, this Observable descriptor behind the scenes handles all the other magic that allows one to subscribe to changes in the value of gini or wealth, as well as emiting/firing/sending a message/signal whenever there is such a change.

This other magic, however, involves at least 2 things

1. creating some message type or signal to which other code can be subscribed
2. emitting messages or signals whenever there is a value change.

So, I want to be able to do something like

agent = BoltzmanAgent()

def some_handler_func(arg):
	print(f"signal received: {arg}")

# subscribe to changes
agent.wealth_change.subscribe(some_handler_func)

# asign new values to wealth
agent.wealth = 5  # --> should result in a print statement in the console

Technical considerations

There are at least 3 options that I see for implementing this

1. build everything ourselves. A working prototype for this is available here
2. use psygnal
3. use solara.Reactive

I have started digging more into psygnal. Psygnal is a very nice library with many desirable features. For example, it is possible to temporarily pause the firing of signals. It also comes with support for various python containers. So, if you add an item to the list, a message will automatically be emitted. I can implement a minimum working version of the envisioned API quite easily with psygnal:

import psygnal

class Observable:

    def __init__(self, dtype):
        self.dtype = dtype

    def __get__(self, instance, owner):
        return getattr(instance, self.private_name)

    def __set_name__(self, owner, name):
        self.public_name = name
        self.private_name = f"_{name}"
        self.message_name = f"{name.upper()}_CHANGE"

        # dynamically add relevant Signal
        mt = psygnal.Signal(self.dtype)
        mt.__set_name__(type(owner), self.message_name)
        setattr(owner, self.message_name, mt)

    def __set__(self, instance, value):
        setattr(instance, self.private_name, value)

        getattr(instance, self.message_name).emit(value, check_types=True) # check_type enforces that value matches the specified dtype


if __name__ == '__main__':
    class A:
        a = Observable(int) #psygnal requires this and can even enforce it if desirable

    a = A()


    @a.A_CHANGE.connect  # psygnal allows for annotations to write easy handlers
    def some_handler(*args, **kwargs):
        print(*args, **kwargs)

    # this is equivalent to the annotation
    def some_other_handler(arg:int):
        print(f"other handler {arg}")
    a.A_CHANGE.connect(some_other_handler)

    a.a = 5
    a.a = 5.5 # will raise an error because emit has check_type=True

Next Steps

1. How do others now look at adding something like pub/sub or signals to MESA and use that as a building block upon which both the new Solara stuff and the new data collection can be built? And do you agree with the basic API outline?
2. I still want to explore Solara for this. Only after looking at both can we make a more informed choice on which library to use. I prefer using either of these over building it ourselves. Either option will be much more feature-complete.

[EwoutH]

Thanks for working on this. Did a little search, and it seems there aren't many reactive frameworks that are well maintained.

• RxPY had one single commit in the last ~1.5 years.
• PySignal had their latest commit 4 years ago.

So purely based on that, would point me in either going with Solara or our own implementation (or some hybrid).

[quaquel]

PySignal had their latest commit 4 years ago.

You have PySignal and psygnal. I used the latter in the example, and its last commit was 2 months ago.

[EwoutH]

Thanks, good catch.

It seems Maarten is open to actively splitting of the Reactive component of Solara, to be published as a standalone package. He already requested the PyPI reactive package to be transferred (there's an tracking issue in the Solara repo).

That would make it 1) a relatively lightweight dependency 2) gives some guarantees about API stability (assuming SemVer is going to be followed).

[quaquel]

I am not worried about psygnal for stability. The library has been around quite a while, is being used and maintained, and seems mature in terms of features. But indeed, stability is one of the criteria when making the final decision.

[Corvince]

Interesting blooper. Through the documentation of PySignal I also found blinker, which seems to be used an order of magnitude more and is also actively maintained.

But from what I have read so far about psygnal, it indeed seems very good! I especially like the evented containers, which blinker lacks.

If there would be an independent package for solaras reactive, it would be interesting to compare. But we don't know when and if that will happen. And I agree with @quaquel that so far the documentation for reactive for usage patterns outside solara components is very lacking. Currently I would vote for psygnal

[Corvince]

I really like this, thanks for the effort! I had my reservations in the past, but now I think its actually a good pattern. I especially like the evented containers of psygnal and the possibility to force runtime type checking, which just seems to be helpful things to have overall.

I would like so see an implementation of this, which is not yet coupled to datacollection or anything else.

[rht]

I looked at psygnal's API. It seems that one emits a value, which is then consumed by the subscribers. But how can I access the current value of the signal object, multiple times (could be in a loop)? In Solara I can do this:

counter = solara.reactive(0)
counter.value += 1000
for i in range(10):
    print(counter.value)
    # Or do other data collection, visualization, etc.

In psygnal, the only way to do this is to emit to a container which value is then read multiple times. But the killer feature of Solara's reactive is that, it is as if counter.value is a regular Python int, which is easy to reason with, and I can apply math functions to it, or from other numerical libraries when needed.

[quaquel]

There are 2 things happening in any signal or pub/sub setup. You (1) assign a value to an attribute, and (2) you emit a signal indicating that the attribute has changed to a new value. psygnal handles the signal, but it is up to the user to handle the attribute. All the logic to handle both simultaneously is contained in my Observable descriptor as you can also see also in the example.

So. a.a=5 means literaturally that. a.a is just a normal attribute, so print(a.a.) will just print 5.

In solara.Reactive, you have to get at the attribute value via .value or change it via .set. Both at a layer of complexity for the typical MESA user that I would want to abstract away.

Hope this clarifies what is going on. Happy to annotate the Observable descriptor in full detail if desired.

[rht]

In solara.Reactive, you have to get at the attribute value via .value or change it via .set. Both at a layer of complexity for the typical MESA user that I would want to abstract away.

But the same could be said for psygnal. In your Observable implementation, you had to define __get__ and __set__, where the latter wraps the .emit method call and stores it in a private value container. While out of the box, Solara reactive is more intuitive, I agree that the Observable wrapper makes it even more accessible. I'm not fully sold on psygnal still. At this point, since they are going to be in the backend anyway, i.e. the Observable interface is the same regardless of it is psygnal or Solara reactive, my deciding point would be which one is most performant.

[quaquel]

Performance is indeed one consideration. But for me, it is also important to know how well everything is documented, how feature-complete everything is, and how easy it is to use. Based on my testing so far, psygnal wins not just on performance but also all the other 3 key considerations.

This, of course, does not imply that we cannot switch, but for developing the API, etc. I am currently exploring psygnal further. It is well documented. It offers not just a reactive variable but much more, including evented containers (A key point made by @Corvince as being important in the past). It is also fast because it is compiled to c. And it has been easy to use in both a notebook and an IDE without having to make any changes to my debug settings.

[quaquel]

I would like so see an implementation of this, which is not yet coupled to datacollection or anything else.

What should be covered by a draft implementation?

I see a few things that would together offer a good starting point

1. Observables for numbers (so ints, floats and anything you would update using =); the provided proof of principle above basically does that already although it needs refinement
2. Observables for collections (so anything that you mutate in place by adding or removing); should be possible using evented containers in psygnal. I still have to play around with those.
3. ObservableGroup; psygnal offers SignalGroup, which is an easy way to enable subscribing to all events on an object; I played around with this today, and I have a working proof of principle that enables you to do the following:

class Agent:
    wealth = Observable(int)
    income = Observable(int)

def wealth_callback(wealth):
    print(f"new wealth is {wealth}")

def income_callback(income):
    print(f"new income is {income}")


def my_callback(signal):
    print(signal)

agent = Agent()
agent.signals.connect(my_callback)  # is called whenever either wealth or income is changed
agent.wealth_change.connect(wealth_callback)  # only called when wealth is changed
agent.income_change.connect(income_callback)  # only called when income changes

Here wealth_change and income_change are autogenerated by the Observable. agent.signals is an ObservableGroup which subclasses psygnal.SignalGroup. It is automatically created in __new__.

Any other ideas are welcome.

[Corvince]

I think your 3 points are a nice pathway that we could follow along starting with 1)
I think that alone could already go into mesa.experimental and then we can play around with the semantics and how we can use it (for example building an experimental data collector).

An open question was how to deal with mutable objects. I believe evented containers should cover 99% of that. We should still have a solution for other arbitrary objects, but this could very well just be an exception stating that such objects cannot be used for Observables.

[quaquel]

I think your 3 points are a nice pathway that we could follow along starting with 1)
I think that alone could already go into mesa.experimental and then we can play around with the semantics and how we can use it (for example building an experimental data collector).

Ok, I'll start there.

An open question was how to deal with mutable objects. I believe evented containers should cover 99% of that. We should still have a solution for other arbitrary objects, but this could very well just be an exception stating that such objects cannot be used for Observables.

Yes, and have a clear "protocol" that can be used to still subscribe to signals from arbitrary objects.

[quaquel]

A quick update: I checked the evented containers in psygnal. These are straightforward implementations on top of collection.abc with a list of signals that are being fired. So, easy to use and easy to build ourselves if not using psygnals, but they also come with substantial overhead, So you better have a good reason to use them.

I hope to open a WIP PR later this week.

[wang-boyu]

This looks a lot like the signal/slot mechanism in Qt, a C++ GUI framework: https://doc.qt.io/qt-6/signalsandslots.html. It also has a python binding: https://doc.qt.io/qtforpython-6/tutorials/basictutorial/signals_and_slots.html

Moreover, @Corvince suggested to potentially automate default data collection.

I think this will be very useful for those who are unfamiliar with Mesa or programming in general.

For instance for a model

class BoltzmanWealthModel:
    gini = Observable()

Instead of

model = BoltzmanWealthModel()
SolaraViz(
    model,
    components=[mesa.visualization.make_plot_measure("gini")]
)

we can simple write

model = BoltzmanWealthModel()
# two plots will be made: 1) a default space plot, 2) a default measure plot
SolaraViz(model)

since gini is declared as observable/measure. Lots of the self.datacollector.collect(self) can be removed from model.__init__() and model.step() too.

Looking forward!

[Corvince]

we can simple write\n\nmodel = BoltzmanWealthModel()\n# two plots will be made: 1) a default space plot, 2) a default measure plot\nSolaraViz(model)

That's probably a good default. I also would like to add the possibility to add plots dynamically. I once had a prototype and it was a bit awkward to define which measures could be selected. This would make it clear

[quaquel]

Just for my understanding: what do you mean with dynamically?

In my vision, you would have some kind of keyword argument that uses meaningful defaults if not passed explicitly. So something like components would fall back on creating default components for all defined observables, but you can control the components explicitly by passing your own list of components instead as well. The same idea can also be used for data collection.

[Corvince]

Yes, on the one hand exactly what you wrote. What I meant with dynamically is that additionally in the frontend you have a select menu where you can select (via mouse click) which components/plots you want to add

[quaquel]

And you could populate this menu again via the defined observables

[Corvince]

That is what I was trying to say :) 👍

[quaquel]

I have opend a PR: #2291. This is a first draft with a slightly refined version of the code outlined above. Feedback is very much welcome.

[Corvince]

I would like to dive a bit deeper into the observables vs signals debate. What I find super intriguing about signals how I know them is that they usually also provide a reactive context in which they auto-subscribe to other signals. Let me show what I mean (classic example of reactive programming)

# Pseudo-code
a = Signal(2)
b = Signal(a + 3)

print(b) => 5
a = 5
print(b) => 8

Do you think something like that might be feasible? This is how it would look like in Vue (JavaScript)

const a = ref(2)
const b = computed(() => a.value + 3)
console.log(b.value)

(Just to show possible semantics. here is how it works in solara.

[quaquel]

Psygnal does not support this directly while solara does have a Computed class. I have to dive a bit deeper to see how easy it would be to make this work with observables while still using psygnal. I also am monitoring this solara issue which suggests that some people at anaconda are working on a dedicated python signals library which is close to ready for broader use.

[quaquel]

There is also an excellent proposal for adding signals to JavaScript, which includes a lot of generally applicable theory about signals and the difference to observables

I have read that also. Very well written and it shows why something like this would be amazing to have in python (and for mesa since the directed graph and recomputing stuff is something that has come up repeatedly while discussing data collection).

[quaquel]

I have spend some time looking at how to make this work with psygnal. The short answer is: it should be possible but it won't be easy.

The elegance of javascript style signals is their autodiscovery and auto-updating of dependencies. In solara, this is all handled via .value. The moment you use this, you autoregister as a dependent and thus are notified of an update. The draft signal library uses essentially the same approach but in a much simpler way using a global variable.

The proposed Observable abstracts exactly this use of a .value accessor away. This point is irrespective of whatever underlying library we want to use (e.g. psygnal, solara, signal). From a user perspective, abstracting the .value accessor away is convenient. You can make your model as normal, and just add some Observable declarations to the top of e.g., your Agent, and you are done. One thing that might offer a middle ground for this is to use a context manager.

def some_function(agent):
	with autoregister():
		return agent.a + agent.b


c = Computed(some_function)

Here the autoregister context manager would set a global flag analogous to how it is done in signal. If agent.a or agent.b happens to be an observable, they would automagically register c as a dependent. [added later] It might even be possible to have the context manager stuff inside the Computed class so the user would not even see it.

Of course, to truly take advantage of Computed, quite some default stuff in Mesa should become Observable. For example, model.agents should become Observable, such that you can have a Computed that is a dependent of model.agents. The nice thing of such a design is that it resolves a lot of discussions we have had in the context of data collection about conditional groups. Such groups could be implemented quite easily, I think, using Computed.

[quaquel]

Just some additional thoughts. Making a Computed class or function on top of psygnal is doable. The challenge is more the API. Observable in my envisioned API is a descriptor. This means it is defined at the class level and parsed at the class level. Computed, however, might very well rely on stuff that is only knowable during object instantiation (i.e., in the __init__). So, it is not straightforward to define Computed as a descriptor.

One solution is to split the two:

class MyModel:
    gini = Observable(type=Computed)

    def __init__(self, seed=None):
        super().__init__(seed=seed)
        gini = Computed(calculate_gini, self.agents)

Here, we declare gini to be Observable at the class level as a normal descriptor. Next, we assign a Computed instance to mymodel.gini in __init__. Next, whenever you do mymodel.gini, it will return the value of calculate_gini. There is some behind-the-scenes magic going on to make this work leveraging both Observable.__get__ and some method on Computed (e.g., Computed.__call__. There might be other solutions possible, but this seems to me a relatively simple and coherent API.

Let me know what you think. If others like this idea, I'll spend some time adding it to #2291

[quaquel]

A working prototype of Computed and Computable is now available in #2291. Cycle detection is the key thing that still needs to be added.

[tpike3]

Sorry for being late to the party but this is awesome!!!

I know Rob Axtell was heavily looking into ways to figure out how to do datacollection on large (e.g. 20 million or more agents) as the data just becomes too much. This to me represents the most promising approach.

Also, I think if we get clever this can be critical for identifying phase transition, attached is some work I was following by Marten Scheffer, where it seems like there may be universal signal signature between nodes in a complex adaptive system that represents when the system is about to hit a bifurcation point .

Universal Resilience Patterns in Complex Networks.pdf

Early Warning Signal with Deep Learning.pdf

[EwoutH]

Thanks for sharing!

Summaries and relevance to Mesa for both papers, for your convenience:

Universal Resilience Patterns in Complex Networks:

• Develops a theoretical framework to analyze and predict resilience in complex networked systems
• Reduces high-dimensional network dynamics to an effective one-dimensional equation
• Identifies universal resilience functions that apply across different types of networks
• Shows that resilience depends on three key topological features of networks: density, heterogeneity, and symmetry
• Demonstrates how to predict critical transition points where systems lose resilience
• Provides a way to understand and quantify how network structure impacts resilience

This paper is relevant because it provides a theoretical basis for analyzing and predicting resilience in complex networked systems like those modeled in MESA. The reduction to an effective 1D equation and identification of key network properties could inform approaches to observability and signals in MESA models.

Early Warning Signals of Tipping Points:

• Develops a deep learning approach to detect early warning signals of critical transitions/tipping points in complex systems
• Trains a deep learning algorithm on simulated data from a wide range of dynamical systems approaching bifurcations
• Shows the algorithm can predict transitions in unseen empirical systems it was not explicitly trained on
• Outperforms traditional early warning indicators like variance and autocorrelation in sensitivity and specificity
• Can predict the type of bifurcation/transition that will occur, not just that a transition is approaching
• Demonstrates how to leverage knowledge of universal behaviors near bifurcations to create generalizable prediction methods

This paper is relevant because it shows how machine learning techniques can be used to detect early warning signals in complex systems, which could potentially be applied to MESA models. The ability to predict transitions and new states could be valuable for observability and analysis of MESA simulations.

Key connections to MESA discussion

• Both papers deal with predicting critical transitions in complex systems
• They provide frameworks for reducing high-dimensional dynamics to lower-dimensional descriptions
• They leverage universal properties of dynamical systems near bifurcations
• The approaches could potentially be adapted to provide early warning signals or resilience metrics for agent-based models in MESA

[Corvince]

TLDR: Its traitlets. We have been discussing traitlets the whole time

Its fascinating how having a good terminology can make such a difference. Taking away the recent discussions about "computed" properties the "Observable" class discussed here is just IPythons tratilets.

from traitlets import HasTraits, Int, observe


class Model(HasTraits):
    steps = Int(0, help="The number of steps the model has taken")
    ....

model = Model()

def func(change):
    print(change)

model.observe(func, names=["steps"])

model.step()
# prints {'name': 'steps', 'old': 0, 'new': 1, 'owner': <mesa.model.Model object at 0x000002496FE93D70>, 'type': 'change'}

It also supports the @observe wrapper, observing container types, runtime type checking, integrates niceley with solara (use_trait_observe) and some things more. I havent fully groked all the capabilities, but it looks very promising and is widely used.

[Corvince]

If you want to look at another library, you can check out param.
It has a traitlets-like API, push and pull mechanisms, parameter bounds (@EwoutH this might be especially interesting for #2268), full reactive programming and some more. But again, the biggest downside is its performance, which is comparatively bad. But still lots and lots of interesting ideas!

[rht]

Good question, because it is swamped with indirect dependencies the GitHub dependant page is a bit useless (more than 480.000 repos depend on it). So I don't know which packages use it directly, but given it has 48.000.000 monthly downloads it seems quite battle-tested. But yeah, these numbers arent really representative since its used directly probably several orders of magnitude less. Afaik solara doesn't use it much.

I looked at the dependents and combed through the ones that are sufficiently starred. Picking an example, https://github.com/search?q=repo%3Adevelopmentseed%2Flonboard%20traitlets&type=code, it seems that traitlets is used in the IPython context. It's a stretch to conclude from one sample, but I don't think anyone has repurposed traitlets for use beyond IPython widgets.

[quaquel]

I have switched from using psygnal to just writing everything from scratch for our usecase:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🟢 -76.9% [-77.1%, -76.7%]	🟢 -12.3% [-12.5%, -12.2%]
BoltzmannWealth	large	🟢 -78.4% [-79.8%, -77.6%]	🟢 -12.6% [-15.2%, -9.0%]

So yes it pays to write our own custom lightweight Observable code, while heavily relying on the available APIs and code from e.g., tratilets, psygnal, solara, signal, and param. These results are of course very much work in progress and need a lot more testing.

I hope to continue work on this later today. Add some first tests, reorganize the code a bit and try my hand at a Computable.

[rht]

That sounds too good to be true. psygnal is already optimized using Mypyc, compiled into a C extension. psygnal's the signature and type checking can be optionally disabled. What is going on here?

[quaquel]

the init time is straightforward. psygnal has several layers of indirection. A psygnal.Signal is a descriptor. Upon its first get on any instance, it creates and returns a psygnal.SignalInstance which again has its own internal overhead. This is also why psygnal has much slower init times than doing it with traitlets.

When emitting signals there is also quite some overhead, partly due to checking for recursion and potentially wrapping the message in an EmissionInfo object. To give you a rough sense of the overhead, in the latest version on #2291, I have 10 lines of code for emitting signals (and this included dereferencing weakrefs). in psygnal this is over 50 lines of code. In short, a lot of overhead that might not be needed for our specific use case.

[Corvince]

I briefly mentioned it yesterday, but I thought and read about it a bit more and decided it's worth it's own thread in this discussion.

I think param is really amazing! I don't have the time right now to talk more about it or give code examples, but if someone has time over the weekend definitely check it out!
It would bring us 95% of the things we discussed/want not only of this issue (signals/observables), but also 95% of #2268 (default values and ranges/param spec).

Yes, it has serious performance implications it seems. But we probably should investigate this on a more complete example and also think about if this still isn't worth it. We could unlock some more design patterns and we now have mesa-frames for high performance needs.

[EwoutH]

Thanks, going to look into it!