Call on time integration in Mesa (Tuesday 27 aug 14:30 CEST)

[EwoutH]

We are planning a call Tuesday 27 aug 14:30 CEST (12:30 PM GMT) to discuss how the concept of time should be integrated in Mesa. The call will take place from our General channel on Matrix, as usual.

Proposed agenda

• Who is our target audience?
  • Experience levels
  • Only ABM or also SD / DES / hybrid?
• How would each of these audience(s) best experience time management?
• Are there specific use cases we want to enable for one or more of these specific audiences?
• What specific constraints do we have (technical, engineering capacity, etc.)?
• What would a conceptual approach to time in line with these be?
  • Automatically increasing Step counter by default #2227
  • The time variable in mesa.Model #2228
  • Standardized order of events in a step and defining the first step #2229
• How do we integrate with the DEVS simulator
  • DEVS/simulator: Use Model time #2248

Write-up of current state of affairs

Thanks @quaquel for the write-up!

PR #2223 to automatically increase time and step count in the model touched on many conceptual subjects on time. After more discussion, 5 discussions where split of.

Where consensus is already reached

1. MESA should be easy to use out of the box and offer convenient ways of expanding to more advanced use cases. The current approach where the user just calls model.step seems perfect out of the box.
2. It would be good to have easy support in MESA for tracking the number of steps/time. There are different design directions here. These range from some convenience method/function/annotation that the user can opt into, to automagically tracking it as the original PR proposed.
3. There needs to be agreed convention for the order of things: incrementing step/time, executing the model step, and collecting data.

Where consensus still needs to be reached

1. Is there a use case for allowing the user control over the time/step increment, and, if we agree on the need to support this use case, how to offer this control?
2. Should MESA by default track both step and time. Currently both attributes exist on the model class. But do we want to continue this in MESA 3?
3. What is the order of things. In particular, when to increment step and when to increment time. What are existing conventions for this in other modeling tools and libraries?
4. How to implement point 2. Let it be handled automagically, or force the user to control it explicitly.

Conclusion of the call

• There is no agreement between the long term usefulness of a continuous time variable built-in. Potential use cases are the simulator, having a datetime and human-interpreble time. For now we keep it as is: model._time is (by default) a copy of model._steps, as a way to move the discussion forward
• We adopt the count-do-collect order. That's a different schedulers, who first do and then increase the step counter.
• AgentSet operations are generally preferred above schedulers, but we'll keep them around for another
• Implementation: We're wrapping the step

Maintainers, feel free to edit/update this post directly.

[rht]

The current approach where the user just calls model.step seems perfect out of the box.

Not yet fully resolved, #2227 (comment). There is an "explicit is better than implicit" argument in this context. Note that NetLogo opted to use an explicit tick call.

[EwoutH]

From a historical perspective, we’ve always had schedulers that increased the scheduler.steps counter automatically. Maybe that’s where this is originating from.

[quaquel]

The more we’re discussing it the more I’m leaning to just letting users do it themselves. It’s not as clean as I would like, but sometimes explicit is better than implicit.

My take away is actually the opposit. We need to figure out a good default and a way of making it easy to extend. @EwoutH bolder analogy made elsewhere applied here. I actually think it might be possible to use annotations (as suggested by @Corvince below), if the user does not annotate their model.step, MESA automagically adds a default annotation that does increment step, execute user's step method, and call datacollect.collect. Then we also capture this order explicitly. If users want more control, their is a set of annotations, possibly with keyword arguments,to further control and refine how mesa behaves.

[EwoutH]

I’m not strictly against it, but I find annotations quite a difficult concept for starting modelers.

Edit: We can users just link this video.

[Corvince]

Oh I like the suggestion by @quaquel to have opt-out/modify annotations! That's beginner friendly, but highly customizable.

[EwoutH]

Jan and I discussed this a little further, and I can get behind the step-wrapping-decorator-with-keyword-arguments. It's basically the same kind of wrapping I did in #2223, but then with a decorator with keyword arguments instead of keyword arguments in the subclassed step.

[quaquel]

As input to the conversation, it might be useful to take a look at chapter 3 from Zieg'ers Theory of Modeling and Simulation. Note that this chapter informed the design of the current experimental ABMSimulator and DEVSSimulator.

[rht]

This is the algorithm as shown in the chapter 3 of the book. There is no explicit increment of t, but I'd assume t starts with Ti, then the while check happens, then y(t) and q(t+1) are calculated, t is incremented, then the next while check happens, and so on. This is equivalent to the forward algorithms, but also could be adapted to be backward (q(t+1) = delta(q(t), x(t+1))), as the book later discusses about forward and backward Euler.

But this would mean that:

1. q(0) is the initial state
2. initial output trajectory, y(0), is calculated from q(0) and x(0)
3. the next state, q(1) is calculated from Ti, not Ti+1 (Ti is the initial time)
4. There is no notion of steps as in Mesa, but rather a more general t, that once again, I think is incremented last

In Mesa syntax, (my interpretation of) Zeigler's convention would be

# Model.__init__
state_0 = prepare()
steps = 0

# Step 0, the first model step
y_0 = datacollector.collect()
state_1 = agentset.step()  # uses state_0 inside
steps += 1

# Step 1
y_1 = datacollector.collect()
state_2 = agentset.step()  # uses state_1 inside
steps += 1

The differences with the current Mesa:

1. datacollector is called first
2. datacollector is called only inside the model step, but never in Model.__init__()

[rht]

The current Mesa would be

# Step 0, i.e. defined in __init__, there is not a single step() call
steps = 0
state_0 = prepare()
y_0 = datacollector.collect()

# Step 1, i.e. the first model step
steps += 1
state_1 = agentset.step()  # uses state_0 inside
y_1 = datacollector.collect()

[quaquel]

It is indeed annoying that the example does not tell you where $t$ is incremented.

But what if, while in the step method, a user wants to collect data? What is the "time index" assigned to this data point? In my view, the moment you are inside the state update (i.e. model.step in MESA), you are no longer in $t_0$. So, I don't see any other option then to first increment $t$ before executing the state updates associated with this new $t$. This, of course, assumes that $t$ is just the "time index".

[rht]

I consider the $y(t)$ (the output) to encompass what the data collector does. The problem with Zeigler's scheme is that at a given step, there are y(t) and q(t+1) that correspond to a different time. Mesa's current scheme is more consistent with the step, state, output/data collection all in sync.

[EwoutH]

Sometimes it's worth asking the question: "Is this the best use of time to improve mesa?"

Two totally unrelated points:

• Making and updating examples let's you find out what's actually working and what's not
• Go talk to students and modellers, what Mesa part did you find most difficult to understand or what did you spend most time on to get working?

But I guess academics is also about debate, so whatever

[EwoutH]

I started a discussion on how the DEVS simulator could integrate in this picture:

• DEVS/simulator: Use Model time #2248

[Corvince]

Since unfortunately I wont be able to make it to the call, here is my opinion on the matter.

First of all I want to repeat that I now think we should not conflate the steps counter and time too much. This is somewhat already present in that we have currently have both steps and time, but also in the discussion "steps" is sometimes regarded as a time variable. And while I think this is a valid approach for most models, I think we should just conceptually define it simply as what it is - the number of times "model.step" is called. And we define this as a significant change in model state - hence we trigger visualization updates in response to this event and we collect the number of steps whenever the datacollector collects data.
From this definition it also follows that disabling it or changing the step size doesn't really make any sense. If you really really don't want to use it - just don't call model.steps, but move your model logic to another function. There is no need to use a model.step, just a convention. And we can expand that convention to also count the number of times it has been called.

But of course it also makes sense for some models to have a more fine granular handling of time - and I am very excited for which features you will discuss could be added to a possible time or clock function. But I would see this as a completely additional module and I don't think we need to hard code something into our model base class. Just let users add it by declaring model.time = AwesomeMesaClock()

Lastly I want to add my opinion on when to call model.step. I had the impression that almost everyone suggested doing it at the beginning, before user actions. I agree with this opinion. It's less clear cut for time, but this is a separate issue.

[EwoutH]

Without judgement, here’s an example of someone wanting to increase the step counter by some other amount:

• Mesa implementation of Ising Model mesa-examples#138

[EwoutH]

@vitorfrois you’re very welcome to join the call by the way!

[quaquel]

I looked at the code. In my view, this hijacks _steps to count the number of agent activations. It would be cleaner to just at a seperate agent_activations attribute and increment that after each single agent activation.

[EwoutH]

Conclusions from the meeting

• There is no agreement between the long term usefulness of a continuous time variable built-in. Potential use cases are the simulator, having a datetime and human-interpreble time. For now we keep it as is: model._time is (by default) a copy of model._steps, as a way to move the discussion forward
• We adopt the count-do-collect order. That's a different from some of the existing schedulers (e.g., staged activation), who first do and then increase the step counter.
• AgentSet operations are generally preferred above schedulers, but we'll keep them around for another
• Implementation: We're wrapping the step