Proposal: adding some form of event sourcing to MESA

[quaquel]

Why?

Imagine you want to keep a log of all agents added and removed from the model and track all the changes to their positions. Doing this at the moment requires modifying your model in several places and modifying/overriding some of the source of MESA itself. Imagine you want to track one specific agent through the model and log its state changes. Again, there is currently no easy way to do this without heavily adapting your model code. Or imagine a loose coupling between the simulation model and whatever animation platform you want to use; again, this is currently not easy to implement. The observer software design pattern, or the more generic architectural design idea of event sourcing, exists to solve this type of problem.

I have three key questions:

1. is adding some kind of basic event sourcing a good idea?
2. What to do with attribute changes?
3. Have I missed anything important?

How might it be done?

At its core, adding some form of event sourcing following the observer pattern requires at least two things: an event producer that is responsible for firing events and a way of subscribing and unsubscribing to specific events.

In MESA, at a minimum, it seems sensible that Agent and Model are (i.e., inheritance) or have (i.e., composition) an EventProducer.

As events, I currently see the following key events

• agent added; fired whenever an agent is added to the model
• agent removed; fired whenever an agent is removed from the model
• state change; fired whenever an attribute on an agent or model is changed
• time increment; fired whenever the clock is advanced to the next time instant (this depends in part on how #1942) is resolved.

State change requires a bit more discussion. I see three possible options.

1. It is up to the user to explicitly fire STATE_CHANGE events when they want to. This is the simplest solution and should always be possible. However, it would be convenient if the user does not have to remember this if a given state of an agent can be changed in multiple places of the code. Or if the state is set from outside the agent (e.g., pos), in which case the state of the agent is changed, but the change is done by the space. Who is responsible for firing the STATE_CHANGE event?
2. Users can declare explicitly that specific attributes are Observable (i.e., they fire STATE_CHANGE events). This is explicit, but the only way I see that this can be done is through descriptors, and given the discussion in #1933, there seems to be resistance to using descriptors.
3. Any attribute change results in an STATE_CHANGE event being fired. This can be supported but will likely require the use of metaclasses. Moreover, in agents with more complex inner logic, many attributes might be changed, resulting in massive overhead if all of these changes result in the firing of STATE_CHANGE events. The upside is that it just always works and thus does not require any change to a model.

A first draft API

So, what might the API look like? Let's start with the example of logging all events in the simulation. Look at the code below. Here, we have a single class that encapsulates all the logging, and this can work without having to touch any of the underlying model implementation.

class EventLogger:
    def __init__(self, model):
        model.subscribe(Event.AGENT_ADDED, self.agent_added_handler)
        model.subscribe(Event.AGENT_REMOVED, self.agent_removed_handler)
        model.subscribe(Event.TIME_INCREMENT, self.time_increment_handler)

    def agent_added_handler(self, model, instance):
        instance.subscribe(Event.STATE_CHANGE, self.state_change_handler)
        self.write_to_log(f"Agent {instance.unique_id} created")

    def agent_removed_handler(self, model, instance):
        self.write_to_log(f"Agent {instance.unique_id} removed")

    def state_change_handler(self, instance, state):
        self.write_to_log(f"Agent {instance.unique_id} {state} changed to {getattr(instance, state)}")
	
	def time_increment_handler(self, instance):
		self.write_to_log(f"time was incremented to {getattr(instance, "time")}")

	def write_to_log(message):
		...

Next, let's consider the tracing of a single agent. Again, this can very easily be achieved, assuming we identify the agent by ID:

class AgentTracer:
    def __init__(self, model, agent_id):
        model.subscribe(Event.AGENT_ADDED, self.agent_added_handler)
        model.subscribe(Event.AGENT_REMOVED, self.agent_removed_handler)
        model.subscribe(Event.TIME_INCREMENT, self.time_increment_handler)
        self.agent_id = agent_id
        self.model = model

    def agent_added_handler(self, model, agent):
    	if agent == self.agent_id:
        	instance.subscribe(Event.STATE_CHANGE, self.state_change_handler)
        	model.unsubscribe(Event.AGENT_ADDED, self.agent_added_handler)
        	self.write_to_log(f"Agent {agent.unique_id} created")

    def agent_removed_handler(self, model, agent):
        self.write_to_log(f"Agent {agent.unique_id} removed")

    def state_change_handler(self, agent, state):
        self.write_to_log(f"Agent {agent.unique_id} {state} changed to {getattr(agent, state)}")
	
	def time_increment_handler(self, model):
		self.write_to_log(f"time was incremented to {getattr(model, "time")}")

	def write_to_log(message):
		...		

Or let's consider a situation where I want to track the lifetime of agents in some evolutionary model and tie this to the discussion in (#1944)[#1944]. Again, we can easily support this by subscribing to AGENT_REMOVED events and extracting whatever statistics we want from each agent. Again, we can add a statistics observer without changing anything fundamental in the underlying model.

# building on #1944
class AgentLifeTimeCollector(Collector):
	def __init__(self, model):
		model.subscribe(event.AGENT_REMOVED, self.agent_removed_handler)
		self.data = {}
		self.collected = []
		self.model = model

	def agent_removed_handler(self, instance)
		self.data[instance.unique_id] = dict(livetime=instance.lifetime, simtime=model.time)

We can now use this collector (depending evidently on #1944), for example like this to get the dynamic evolution of our average lifetime over time:

lifetimecollector = AgentLifeTimeCollector()

# running the model

# during the analysis
avg_lifetime = lifetimecollector.to_dataframe().groupby(simtime).average()

possible implementation

Below, I give a sketch of the core classes that would be required. The Event enum is for convenience. The user knows what default events are defined within MESA. The API is open to users defining their own events of they choose to do so because events are just strings in this proposed implementation. EventProducer is the core class. It is what you subscribe to and which is responsible for firing events. Again, It is left to the user to decide which information is part of the event. Note that fire_event calls the event_handler with itself as the first argument.

class Event(StrEnum):
    STATE_CHANGE = auto()
    AGENT_ADDED = auto()
    AGENT_REMOVED = auto()
    TIME_INCREMENT = auto()


class EventProducer:
    
    def __init__(self):
        self.subscribers = defaultdict(list)
    
    def subscribe(self, event: str, event_handler: callable):
        self.subscribers[event].append(event_handler)
        
    def unsubscribe(self, event: str, event_handler: callable):
    	# or try except pass, which is slightly faster
        with contextlib.suppress(ValueError):
            self.subscribers[event].remove(event_handler)

    def fire_event(self, event: str, *args, **kwargs):
        # copy is needed here because the handling of the event
        # might result in the receiver unsubscribing itself, causing a change
        # in the dict while iterating over it.
        for entry in self.subscribers[event].copy():
            entry(self, *args, **kwargs)


class Observable:
	# observable is a descriptor that can be used on 
	# objects to declare specific attributes as observable (i.e., they fire events)

    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}"
    
    def __set__(self, instance, value):
        setattr(instance, self.private_name, value)
        instance.fire_event(Event.STATE_CHANGE, self.public_name)
        

Model, Agent, and possibly Space should have an EventProducer or should be EventProducers. I am largely indifferent between these two options. If they have an event producer, all classes need to implement subscribe and unsubscribe and pass it to their event producer:

def subscribe(self, event, event_handler:callable):
	self.event_producer.subscribe(event, event_handler)

Moreover, Model._agents or the Agent itself should be modified to fire AGENT_ADDED and AGENT_REMOVED events. In my view, agents are added to or removed from the model, so the cleaner implementation is to handle this at the Model class (rather than the current implementation in Agent: self.model._agents[type(self)][self] = None). Likewise, TIME_INCREMENT should be fired by whatever handles time in the simulation (see discussion in #1942).

The one thing that is tricky is STATE_CHANGE events. In my view, it should be up to the user of MESA to decide which attributes in their agents and model should be observable and thus fire these events (i.e., my second option above). Moreover, I don't want to force the user to add fire_event calls whenever they are changing the relevant state. So, therefore I suggest the Observable descriptor. It is used like this:

class MoneyAgent(Agent):
    """ An agent with fixed initial wealth."""
    wealth = Observable()

    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        self.wealth = 1

By declaring wealth to be Observable in the class definition, now whenever a value is assigned to wealth (i.e., self.wealth = 1), Observable__set__ is called. This handles the firing of the event and assigning the new value to _private_attribute.

small update: As pointed out by @Corvince in #1933 (comment), it is possible to automatically add descriptors to classes from the outside, which offers additional possibilities.

[rht]

Adding a note on @quaquel's take on the existing library eventsourcing: #1930 (comment).

[EwoutH]

@Corvince what's your take on this?

[EwoutH]

Thanks for this extensive proposal. On a high-level, I like the direction. Few questions:

1. Can events be logged conditional? So logging every Nth agent created, logging wealth if it gets above 10, that kind of stuff. If so, how would it look?
2. Can we think of something that we don't have to define each attribute two times? Because we're really increasing boiler plate.

class MoneyAgent(Agent):
    """ An agent with fixed initial wealth."""
    wealth = Observable()

    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        self.wealth = wealth

3. We're now writing strings to the log. Can we use another format that's more machine searchable/scalable?

While I think this is useful in some cases, I haven't seen the killer application yet. Is there one?

[quaquel]

1. The basic idea is to put in place a generic structure on which a whole range of things can be built in a way that is easier and less intrusive in any model than currently is possible. So, I haven't thought about the killer application but rather trying to show a range of possible ways in which this proposed structure can be used.
2. Your questions are more about examples of how users might use it. But still, some quick responses. If you want to filter, go ahead. It is easy to do by counting events within a user-defined class. Likewise, it becomes trivial with event sourcing if you want to write to a database or in a more machine-readable format. Again, it is not the purpose of event sourcing to solve this particular problem but rather to make it easy to do this if your use case demands it without having to change anything in the underlying model. Eventsourcing thus allows for a very clean separation of concerns.
3. Descriptors are not defining attributes two times. This is a really fundamental misconception of what is happening here. The first statement declares the attribute to be Observable. The second statement assigns an actual value to the observable attribute. So far, I haven't been able to develop any other solution that gives the user full control over declaring which attributes are observable and which are not. Note also that as pointed out by @Corvince in Add system state tracking #1933 (comment), it is possible to assign descriptors to classes from the outside automatically. Doing something like that, however, first requires agreeing on using descriptors for Observables in the first place.

another way to come at it is for each example I gave, ask yourself how you would solve it currently in MESA. So, how would you log all state changes? How would you trace all state changes of a single Agent? How would you track the lifetime of each agent when it is removed from the simulation? Next, compare your answer to what becomes possible through my proposal.

[EwoutH]

For me the main point now is: Is there a net benefit / do the benefits outweigh the costs.

Current benefits:

• Precise control over when an event fires
• Ability to precisely collect data

Current costs:

• Increase in code base size
• Increase in things people new to Mesa/programming have to learn
• Performance?

So a possible way to move forward I think would be:

• Open a draft PR. With an implementation, we can better see the costs
• Develop sample cases. With use cases, we can see the benefits.

This will be a risky development. Doing the things above takes time and effort, and at this point I don't know if we in the end decide to mainline it or not. So if we want to push this, we have to accept the risk that it might end rejected.

[quaquel]

Fair enough. I want to prioritize a few other things first (e.g., new grid, the RNG singleton issue) and write up my vision for enabling discrete event and hybrid ABM-Discrete Event first.

[Corvince]

@Corvince what's your take on this?

I haven't commented on this idea yet, because I think @quaquel wrote a very nice proposal and I didn't want to sound too negative immedieately. So I will try to lay down my words carefully. I think the idea or wish to use some form of event sourcing is sound and understandable for some use cases. I am just not sure if this needs to be included in mesa itself. This proposal suggests that we should somewhat write our own Observable library, with all the advantages, but also pitfalls. In my mind the nice thing about mesa is that it gives you the full range of possibilities Python has to offer. That means if someone has a need for an observable pattern they should be free to use it. There are multiple observable libraries out there and I see no reason not to use them. If you want to fire an event when agents are created just do it explicitly when you create an agent. As a model developer you have full control over such things.

My main worry is that if we provide such functionality we have to tell users when to use it and when not and we create situations where there is more than one obvious way of how to do things. Therefore if we include event sourcing I think we would also need to make it the default. But then the whole of mesa would look completely different. I think its a very interesting and also promising idea to base an ABM library purely on reactive event-based triggers. But I don't think we should transform mesa into that.

There are also some caveats with observables. One thing that might be solveable is the need to unsubscribe from event listeners, which otherwise can cause memory issues. This is a common point of errors in reactive libraries. Another thing is

How would you trace all state changes of a single Agent?

This one is tricky, because with descriptors that is still hard to do. Take this example:

agent.wealth = 12 # <= This one triggers an event
agent.neighbors.append(other_agent) # <= This one doesn't 

The second one uses a mutable data structure, so the descriptor isn't fired, because the reference stays the same. So you would need to use immutable state updates like

agent.neighbors = [*agent.neighbors, other_agent]

So its not true that this wouldn't require rewrites to the model logic in some cases, which are easy to miss if you are not familiar with this topic.

[quaquel]

Thanks for this thoughtful reply.

1. I am not sure that it is possible to fire events from all relevant parts of the model without changing stuff within the source of MESA itself. In particular if you start thinking about position changes and how this interacts with the current Grid classes.
2. If some form of event sourcing were added to MESA, it is indeed important to be very clear about which events exists, when they are fired, and how to subscribe to them. In effect, this would become part of the public API of MESA.
3. I am not advocating to fully rewrite MESA in a react style way. I am merely suggesting adding a set of well defined events that a user can use for their own convenience, and a way for users to expand upon this.
4. Memory problems are solvable through weakrefs. I did not include it in my possible implementation example for simplicity but it is indeed a key concern in many other libraries.
5. Your point on lists (and dicts) etc. is well taken. I have to think about that.

[quaquel]

I spend some time looking into observable collections (point 5). The best solution seems to make a distinction between Observables (numbers, strings?, tuples), and ObservableCollections (list, set, dict). Unfortunately, I have not found a cleaner way of doing this. However, I also think that for most situations, numbers are the most commonly used state you want to track. Moreover, the entire descriptor thing is just a shorthand for not having to fire a state change event every time you change the relevant attribute.

[quaquel]

In the possible implementation, I use an Enum to list all events. Thinking about this more over the last few weeks, I think it might be better to declare events on the class level. So, it is clear what events it can fire for each class. Declaring this at the class is the proper way to do it because these events are part of the public API of the class.

No idea how to implement this cleanly yet.