Interaction between nested timelines and nested models

[LourensVeen]

We now have nested models, where a model can be used as an implementation of a component, and nested timelines with conduit filters, which allow communicating between callers and callees. These features interact however, and it's not yet clear how that needs to work. So that needs to be worked out and implemented.

[LourensVeen]

Okay, so after a bunch of thinking and puzzling and somehow losing my notes to mate-desktop/mate-terminal#228, and thinking and puzzling again, here's how I think this should work, with a few undecided things.

Timeline annotations

Timeline annotations are associated with ports, and ports can be on components and on implementations, these being programs or models. Timeline annotations on implementation ports describe the behaviour of that implementation, putting constraints on when it will send or receive on which port.

For programs, the program needs to be written in such a way as to adhere to those constraints (for each timeline, send on all O_I ports then receive on all S ports or vice versa), or libmuscle will raise an error. For models, O_I and S ports with the same timeline annotation need to be connected to ports on components in the model with the same timeline.

Components can also have timeline annotations on their ports, and those should match those of the implementation used for that component. It would be possible to allow different names as long as there's a one-on-one mapping, but I don't really see the point as we're already requiring matching port names. So let's just require them to be the same and reduce potential for confusion.

Timeline annotations on a component's O_I and S ports must consist of a yMMSL Identifier, which will be appended to the component's name (a Reference) as <component>.<timeline> and then appended to the component's parent timeline with a colon separator, producing <parent timeline>:<component>.<timeline>. If no timeline annotation is present, then the ports are on timeline <parent timeline>:<component>.

Timelines within models

Components are connected to each other and to model ports using conduits. Those are used to determine the parent timeline of each component, from that the timelines on all the component ports, which can then be checked for consistency taking into account any filters.

This works for dispatch and call-and-release couplings, but for interacting components we end up trying to connect seemingly unrelated timelines. This can still work in practice if the components are configured to run in lock-step, or if one of them uses the timestamps on the messages to adapt its timeline to that of its peer, as time bridges do. In that case we need a way to let MUSCLE3 know that the seemingly unrelated timelines are actually equivalent.

Given a model with interacting components a and b, their O_I and S ports will be on timelines a and b respectively, relative to the model's root timeline. Those are not the same, so a conduit from a.out to b.in or vice versa is invalid, unless we declare the two timelines to be the same somehow.

Timeline cross-references

One way to do this is a timeline annotation :b on a.out, putting as port on bs timeline and making the two ports have the same timeline. Or we could put :a on b.in, or even :common_timeline on both. The leading colon would indicate that this annotation isn't relative to the component, but to the model the component is in, allowing us to reference other components and their timelines.

If either component adapts its timeline to the other, then this kind of annotation makes sense, because it describes just that, and the version with a "neutral" timeline that isn't associated with either could represent a symmetrical situation where two interacting components are configured with identical time stepping by the user.

On the other hand, this way of doing it makes timeline equivalence a property of a port that happens to be on that timeline, which isn't quite right. It's the timelines that are or aren't equivalent, not the ports. We could put :a on b.in and :b on a.in and have two valid conduits between a and b, on the same timeline in practice but a different one in theory.

This option also requires either annotating all ports on all the equivalent timelines, or extending a single annotation to all ports on the same timeline automatically and accepting that if the port it's on gets removed you need to remember to add it back on another port. That's messy.

And finally, unless we allow multiple annotations, putting :b on a.out in the component means that we can't put a normal annotation on the component port to check against the corresponding port on the implementation, while there's no reason that one should preclude the other here.

Timeline equivalence sets

Another approach could be to leave the components be and add an attribute equivalent_timelines to Model:

models:
  tokamak:
    components:
      plasma:
        ports:
          o_i: plasma_out
      plasma_diagnostics:
        ports:
          timeline plasma:
            s: data_plasma_in
          timeline diagnostics:
            s: clock_in
            o_i: data_plasma_out
    equivalent_timelines:
      plasma: plasma_diagnostics.plasma
    conduits:
      plasma.plasma_out: plasma_diagnostics.data_plasma_in

By explicitly declaring the timelines to be equivalent, we'll inform the checker that these timelines all have the same time points, and we don't need to repeat ourselves on every port. If more than two timelines need to be declared equivalent, then maybe a list-based syntax is better:

    equivalent_timelines:
      -
        - plasma
        - plasma_diagnostics.plasma
      -
        - diagnostics
        - diagnostics_control.diagnostics

I like that this is explicit, and that it makes the equivalence a property of the model. That's really where it belongs, because this is about a relationship between the components, not about properties of the components themselves. On the other hand, the symmetry doesn't feel exactly right for time bridges and other adaptive components, where there is in fact an asymmetry. For a time bridge, the time line is defined by the component it connects to, rather than by a shared definition.

Perhaps the dictionary-based syntax could help with that though:

    equivalent_timelines:
      c1:      # component with two bridges that adapt to it
        - bridge1.sender
        - bridge2.sender
      common:  # multiple lock-step components, "common" an arbitrary name for this timeline
        - c1
        - c2
        - c3

edit: I'm leaning towards matching_timelines now instead of equivalent_timelines, but I'm not entirely sure yet it's actually better.

Conduit labels

If the problem is that we're going to get an error for certain conduits that connect ports on different timelines together, even if we know that this is okay, then another option would be to add a note to the conduit that says to skip the check:

    conduits:
      plasma.plasma_out: plasma_diagnostics.data_plasma_in common_timeline

If there are multiple conduits between those timelines then we'll have to add the note on all of them, and this may make the conduit annotation a bit complicated if filters are also involved. It is however similar to disabling a linter check with a comment at the end of the line, which people may be familiar with. It's likely easier to just override the error than having to learn about timelines and how to declare them equivalent. Easier and more dangerous...

Decision

I'm not completely decided yet, but I think equivalent_timelines may be preferable. Opinions welcome!

Next up: how do we flatten a model in the light of the above options, and make sure that the flattened model still has correct annotations and passes (or doesn't pass!) the checks in the same way.

[LourensVeen]

Flattening models with timeline annotations

Simple timeline annotations describing the behaviour of an implementation or component are relative to that component. They put the port they're associated with on a timeline relative to that component, and that's not affected by flattening. The component will simply be renamed, and the timelines of its ports change along with that automatically.

The three solutions above for supporting interaction between components do require work while flattening.

How flattening works now

To flatten a hierarchical model, we start with the root model and an empty prefix, then

1. copy all program-implemented components into the flat model, prefixing them with the current prefix
2. queue all model-implemented components for later processing
3. copy all conduits that lead from a program-implemented component to another program-implemented component, prefixing their endpoints with the prefix of this model
4. add any other conduits (connected to a model-implemented component or a model port) to the plate
5. for each model port, find all conduits attached to it on either side, glue each pair together, and add it to flat model if complete (from program to program) or put it back on the plate if not
6. get the next model-implemented component from the queue and go back to 1.

Timeline cross-references

These cross-references are on a component port, and if the component is implemented by a submodel then that port will disappear while flattening. The conduit gets connected to everything in the submodel that the model port was connected to, and it seems that the annotation would have to be transferred to those ports.

There's a problem there, because there may already be an annotation there. A local description could be overwritten, but what if there's already a cross-reference to another timeline within the submodel? The submodel could have components a and b with O_I port a.out connected to S port b.in and annotation :b to make that possible, but with another conduit from a.out to a model port. If that port then gets an annotation :c in the outer model to let it interact with that component in the outer model, then we'd need two at the same time.

Another issue is that that c component in the outer model may itself be implemented by a submodel, in which case we may need to update the annotation in the current submodel when processing that other submodel later. That is not currently necessary, we just process everything once, and it would make the hammer quite a bit more complicated.

Timeline equivalence sets

Timeline equivalence sets are defined within a (sub-)model, and may reference any timeline on any component of that model, as well as nominal ones that do not correspond to a model. If a timeline on a component is referenced with a model for its implementation, then we are also declaring equivalence with everything within that submodel that is declared equivalent to that timeline there. So those equivalences need to be merged when flattening.

So, to flatten an equivalence set in the current model-implemented component, we first need to prefix all the timelines in the set with the current component's prefix. Then we need to check each item in the set against all other sets that we've processed so far to see if it's in there as well, in which case that other set can be merged into the current one. Then finally we add the current set to the set of processed sets. After the whole hierarchical model has been processed, that set of sets becomes the set of equivalence sets of the flat model.

Conduit labels

For the conduit labels, it seems that we just need to check when gluing two conduits together whether at least one of them has an override label, and if so apply it to the resulting combined conduit.

Decision

The cross-references are starting look like a bad idea the longer I look at them. This was my initial stab at the problem, and I put some time into them, but they just don't work well. Conceptually it's not right to model what is a relation between two component's timelines as a property of one of those components, it collides with the relative annotations we want to be able to put everywhere, and it's difficult to implement, probably because the concept is wrong. So I'm leaning towards not doing that.

Of the remaining options, equivalence sets add a different mechanism that does model the relation as a relation, it's got a clean way of representing more than two components on the same timeline, with the dictionary-based syntax we can still declare one timeline the leading one and the rest following so we can naturally describe time bridges, and it's not that difficult to implement either.

Conduit labels that disable the timeline checker aren't really a solution, they just declare the problem out of scope and allow the user to disable the check. That's definitely easy to implement, but it's not very satisfying because the point of the timelines was to avoid having to disable the checker, and instead being able to describe things cleanly. Adding more stuff onto the conduits besides the filters may also not be the best for usability. On the other hand, it's simple conceptually, we don't have much time to implement this, and it surely is little work.

I'd like to work out a few concrete examples of how the equivalence sets would work, I'm fairly confident they're correct but it always helps to verify. So that's next.

[LourensVeen]

From some more thinking and discussion, it seems that there's another issue.

In a model, we can have multiple nested timelines, and we can connect O_I and S ports on the model at different levels. For example, if we have a macro-micro inside the model, then we can have two O_I model ports, one connected to the macro model and one to the micro model. We could add annotations macro and micro on the ports, and that would communicate that the ports are on different timelines, but not that those timelines are nested, or that micro is two levels deep. That is relevant information however, because it determines how many filters a user may have to add to make things work.

So it seems that we need to either forbid O_I and S model ports to be connected to anything other than length-1 timelines relative to the model root, so that F_INIT/O_F and O_I/S of an implementation are always exactly one level apart, or we need a way to specify the length on the outside of the closed box that is an implementation.

One way to do that would be to annotate the model ports in the example above as macro and macro:micro. That would clearly show the relationship between them, and the depth. The checker could then use that to check the filters, and in fact I think this already works for conduits between components and model ports.

For components and their implementations, Configuration._check_consistent_ports checks that ports and timelines are identical between components and their implementations, which I think is also what we want.

So it looks like the only thing that needs to get done is to make sure that when we implement the <component>.<timeline> style component port timelines, we prefix each item in the timeline. In the above example, if we had a component c1, then its ports would have final timelines c1.macro and c1.macro:c1.micro. Of course those would then disappear on flattening as c1 is removed. And a test would be good if we don't already have one.

[LourensVeen]

Decisions

• We agree that timeline equivalence sets are better than timeline cross-references, so we'll go with the equivalence sets. Conduit labels don't really solve the problem.
• matching_timelines is the best name for it, because as @IrisvdWerf pointed out, these are different timelines (produced by different components) that produce the same time points.

To do

• Add timeline equivalence sets to ymmsl (ymmsl #68)
• Update the timeline checker to take them into account (ymmsl #68)
• Flatten timeline equivalence sets in the hammer, using . and prefixing each part of the timeline
• Add some more tests
  • macro-micro in a box with all ports between them exported and external direct connections
• Check if we still need absolute timelines, or can simplify Timeline (ymmsl #68)
• Fix bug in Timeline._yatiml_attributes when using both the main component timeline and subtimelines, which I think should be allowed