MaximumCommunicationStep

[masoud-najafi]

Consider a master/slave co-simulation configuration with several slaves. For the sake of simplicity assume slaves compatible with FMI-2.0. Slaves communicates only with the master at communication steps. Based on internal states and inputs at communication points, some slaves have the capability to request the mater to get called not later than Tcpi for the next communication point. In other words a slave may put a limit over the next communication step Hcpi. Based on the different requested Hcpi values, the master may choose min(Hcpi) as the next communication step.

This mechanism is useful in several situations: --Ensuring the internal stability inside the Slave.

--This may also be used by the slave for efficiently handling the predictable triggered (internal) events or even handling some internal non exposed events that create discontinuity in slave outputs. In this case it is better to inform the master to choose the next comm step at appropriate time instant.

-- Sometimes there are some important information in the slave output signal that may be ignored by the others or by the master if the communication step size is too big. Consider for example a slave with a Sine signal output. If the communication step is too big, the signal is not sampled frequently enough and aliasing may happen. Since only the slave have this information, this mechanism can be used by the slave to limit the communication step-size to allow others capture the signal correctly.

Currently there is no mechanism for this purpose. Solution 1: Master ignores this information and chooses a big communication step. If a slave fails, master does a fmi2SetState on the failed slave to roll back to the previous communication point and repeat the step with smaller comm step. But this method quit inefficient and some slave may not support the rollback.

Solution 2: Assuming that the Slave supports EarlyReturn, the master can ignore this information and let the slave do an earlyReturn at Tcpi. That will become automatically a new communication point between the slave and the master. But the problem is that other slaves may have already missed this communication point and should rollback to this point. The support of EarlyReturn and rollback is necessary for all slaves.

Solution3: Add fmi3MaximumCommunicationStep enum to the structure

typedef enum{ fmi3DoStepStatus, fmi3PendingStatus,
fmi3LastSuccessfulTime, fmi3Terminated, fmi3MaximumCommunicationStep } fmi3StatusKind;

The type of return value is Float64 with fmi2GetFloat64Status () If the return value is 0.0 or negative (default value), that means there is no limit over the communication stepsize.

[KarlWernersson]

Hi would it not be easier to state the max doStepSize in the xml? If you want to change this dynamicaly i dont see how solution 3 would be better than solution2. Solution 3 doesn't allow you to preemptive call it, but only as a check after fmiDiscard has returned so you may still have the same problem but less solutions to handle it. For preemptive call you would need some return value at the end of each doStep returns max next step, alternative a fmi3getNextMaxDoStepSize() but i would prefer return struct.

Is it sufficient with a fixed value in the xml? (default 0 = no limit)

[pmai]

If I understand the proposal correctly, then the idea would be to have something like the nextEventTime mechanism for ME for (Hybrid-)CS: The FMU returns after each successfully completed DoStep optional information about a limit to the next time, indicating beforehand that the master should not try to step past that time limit. For time-based events or other predictable events, this approach can be made to work, and makes sense, since it would allow the master to know about those time limits before stepping all of the FMUs, which would be both simpler, and more efficient than approach 2. (I've changed the maximum step size to an event time in this description, since I think that makes more sense, in terms of mirroring the ME approach).

Of course for many other sources of events, which are not predictable a (potentially long) time before-hand, this does not buy you much, i.e. you'd need the early return mechanism for those.

[masoud-najafi]

@KarlWernersson : The value MaximumCommunicationStep is usually variable and may varies as a function of the FMU inputs. So this value cannot be retrieved after DoStep. It should be retrieved after setXXX (inputs) and before calling DoStep(). fmi3getNextMaxDoStepSize() is a good (maybe better) solution, but it is a new API and everyone may not agree to add a new API. fmi2GetFloat64Status () is an already existing API and less intrusive.

@pmai : yes, this is the main idea, but it is not restricted to predictable events. FMU (CS) may not have any event at all and be purely internally continuous, as the use case 3.

[chrbertsch]

FMI regular design meeting: Masoud: As we remove the get_status function in FMI 3.0, should we introduce a new function? Klaus: we still have the functionality, it is just retrieved in another way: e.g.,

typedef fmi3Status fmi3GetDoStepDiscardedStatusTYPE(fmi3Component c,
                                                    fmi3Boolean* terminate, 
                                                    fmi3Float64* lastSuccessfulTime);

Masoud: We need a similar function like this to retrieve the maximum possible communication stepsize. The master could enquire this. Klaus: Must this be a function or could it be part of the xml? Masoud: It is dynamic. Can depend on the input. Klaus: Whenever you set an input, this value could change. We should define when this can change. Pierre: Similar to NextEventTime mecanism in ME Klaus: Could this be unified? Andreas P: If is only about events, this information would be present Masoud: could be based on physics Klaus: and on tolerance Pierre: The idea is you are not allowed to step over it Masoud: Yes. In ME we have such a mechanism Klaus, Pierre: we should go in this direction; discuss again when the proposal is there. Pierre: one should differentiate between MaxNextStepSize or NextEventTime. Could have different behaviour. Should be examined. Masoud: We should also check with the IOV Proposal.

Masoud will come up with a proposal.

[masoud-najafi]

Maximum Communication Step Size.docx

[chrbertsch]

Discussion at Regular Design Meeting: Massouds prepared the proposal together with Jean-Philippe.

Karl: How is this proposal related to the callbacks from Hybrid Co-Simulation? Massoud: This proposal is for events or other stuff that is inside the FMU, not for events that are exposed to the master. (E.g. a sine-wave inside the FMU that has to be resolved in a fine enough way) Karl: Talking about event time could be confusing. We should avoid talking about events. Massoud: Agree Allan: There is no guarantee that the FMU may be able to predict when it needs a short timestep. This might not prevent problems with FMUs that do not support rollback. But it could increase efficiency Karl, Klaus, Massoud: Agree Kaska: What if we do not have the next max Communication step size? Do we set it to infinity? Massoud: we might have access to the stop time the FMU (optional) Karl: We you could use a very large number Allan: We could use a negative number Klaus: An explicit boolean is better than encoding it in the return value Massoud: we could the MaxDouble value? Karl: would like to avoide that? Klaus: The reason: It could be related to a tolerance, or a time event? In the second time I do not understand the relation to Hybrid Co-Simulation Karl: could be for any reason e.g. an internal, not exposed time event Andreas P. Is this unrelated to next event? Massoud: Yes. Christian: Signature: fmi3Status fmi3GetNextMaxCommunicationStepSize( fmi3Component c, fmi3Float64 *NextMaxComStepSize, fmi3Bool* MaxStepSizeDefined); Kaska: The pure CS FMUs are supposed to be black boxes. Shouldn't this belong more to ME FMUs? Or in a hybrid CS FMU? Klaus: I partly agree Andreas: what would be the reason to hide this information Klaus: One might get the impression that the communication step is the next solver stepsize Christian: Couldn't the FMU detect that that the communication timestep is to large and then with this proposal it could recommend to take a shorter communication timestep Masoud: this is one use cases Kaska: there are always cases where this will not work Masoud: A predication might fail, but is less costly than to do a step Klaus: What happens if the master takes a large timestep thant NextMaxComStepSize? Masoud: this is just a recommendation. A doStep with a larger step should not fail. Klaus: wouldn't MaxRecommendedNextTimstep be better as it is only a recommendation?

Christian: how shall we go on with this? Klaus: I have not yet made up my mind. We must be careful how this relates to hybrid co-simulation. And we must be clear that communication timestep is not solverstep. Andreas P.: I agree Christian: do we need some more time? Next step could be formulate the proposal based on Klaus' comments Masoud: We use an in-house version of this feature to syncronize solverSteps with Communication timesteps. Klaus: Do not understand Masoud: the FMU predicts ... and informs the master where it would wish the next comunication timestep. But there are other use cases. Andreas P. , Christian: We should not demand that the communication timestep and internal CS solver timestep should be the same. Christian: There are different use cases: Variable timstep solver internally, different to communication timestep. Other FMUs contain a fixed timestep integtrator and the communication timestep should be preferably the same. Could be done via clocks. Klaus: The default timestep in the FMU is not clear. This is different isssue #437

Masoud: will continue to work on this

[jbernalr]

My two cents on this as well: As I understand it, fmi3GetNextMaxCommunicationStepSize is intended to ensure that the “dynamics” contained in the FMU are provided meaningfully for any takers of this information. (i.e. FMU output sampled in such a way that it exposes all the frequencies embedded in the FMU) However, from the point of view of the master/engineer, “ignoring” some of these frequencies may actually be on purpose. For instance when combining models with way different frequencies (prob bad simulation practice) because appropriate models are currently not available. i.e. (Battery ageing model with very slow dynamics connected to fast a DC/DC converter model). Usually the person connecting the FMUs knows “something” about the models and their compatibilities in terms of frequencies. Having a frequency “range” in the XML may be actually very useful to pick up the right model from a bunch of them to build a simulation. I see however a number of issues of providing this information dynamically. If these issues would be cleared out, I would find the option useful, although I agree with others (above) that rationale of this new function should avoid confusing users regarding mixing up communication time with integration time.

In my view the concept of integration time for co-simulation is in particular loose to build something on top, because CS-FMUs could be anything. (do not require integration at all). Therefore, the situation of an CS FMU rejecting a proposed communication time makes in my understanding little sense. It should always be achievable right?

The issues I am thinking about are:

• If MaxStep is really provided dynamically, this parameter may change at undetermined speed causing unknown numerical effects or even worst, changes in the internal dynamics may pass completely undetected by the master.
• What about multi-rate FMUs. Would the FMU communicate the MaxStep for the smallest of those rates?
• Adaptive behaviour CS FMUs containing more than one version of a system models that switches during simulation.
• Co-Simulation FMUs will encapsulate other things without dynamics: Neural Networks, logic operations, sorting algorithms etc., so are we making Co-Simulation even more like ME (after earlyReturn and clocks)?

[chrbertsch]

Masoud: At the next Design meeting I can make a short presentation on this

[masoud-najafi]

Following the discussion in the Renningen Design meeting, what should I do next for this ticket? Could I add the API to the header files?

[chrbertsch]

From the meeting minutes: https://github.com/modelica/fmi-design/blob/master/Meetings/2019-06-25_FMI-Design-Meeting-Renningen/MeetingMinutes.adoc:

---

Presentation Massoud

Link to presentations: https://github.com/modelica/fmi-design/blob/master/Meetings/2019-06-25_FMI-Design-Meeting-Renningen/MeetingMaterial/fmi3GetMaxCommunicationStepSizeHint.pptx

Karl, Klaus: It is similar to hybird cosimulation

Massoud: also usefuly for ME as non critical eventMode

Karl: yes, possibly but additional theory and investigation is necessary

Klaus, Piere, Masoud: We have to make very clear that this is not an event, and time events should use nextTimeEvent

Poll: Should we add such a function? In favour: 4 Against: 1 Abstain: 9

---

So to my understanding: @masoud-najafi : Please go ahaed with a concrete proposal which we then can discuss in a pull request.

[masoud-najafi]

I updated the proposal (proposal_nextmaxcommstep_rev3.docx). Please let me know what should I do next? Thanks Masoud

proposal_nextmaxcommstep_rev3.docx

[chrbertsch]

copying the text:

Maximum Communication Step Size:

This proposal introduces a new capability for FMI for Co-Simulation. With this capability, an FMU can dynamically propose to the master an upper bound on the communication step during the co-simulation. This capability is intended to ensure that the dynamical behavior of the model inside the FMU is completely captured by the master and as consequence by other slaves. This capability would allow the master to communicate with FMU at an optimal rate so that the FMU output signal bandwidth be preserved. Rationale: In co-simulation, only the FMU is aware of the dynamical behavior of the model that it contains and its signal bandwidth. Consider, for example, a simple FMU outputting a Sine wave signal. If the master chooses a large communication step with respect to the Sine wave period, the FMU output is not sampled frequently enough and there may be information loss. With this capability, the FMU can communicate the appropriate communication step to the master to get sampled sufficiently. This information which is communicated from the FMU to the master, indicates an upper bound on the time limit beyond which the master may not try to step. This upper bound can be used to setup the communication step before calling fmi3DoStep. The upper bound on the communication step size cannot be stored statically in the XML, it should be retrieved dynamically during the Co-simulation. Consider, for example, an FMU with a dynamical behavior like the Van der Pol oscillator. In such a model, in order to co-simulate fast enough and to capture the complete information in the signal, the communication step size should vary from very small to very large values during the co-simulation. Also, changing FMU input values or tunable parameters, may change the internal model dynamics that needs a new adapted communication step size. If several FMUs are present in a co-simulation and each one has different frequency bandwidth or dynamical behavior, the master should call each one at different appropriate rate. For example, in a co-simulation, it may be useless to call the FMUs with slowly varying signal at the same rate as the FMUs with fast varying signals. Most of the time the dynamical behavior is the know-how of the FMU exporter, and the import environment has no idea about the FMU to setup the co-simulation efficiently. With this capability, the know-how of the FMU exporter is embedded inside the FMU and the master can leverage this information to choose appropriate communication step size for each FMU independently. API: In this proposal, this function is introduced for FMI-3.0: fmi3Status fmi3GetNextMaxCommunicationStepSize(fmi3Component c, fmi3Float64 NextMaxComStepSize, fmi3Boolean NextMaxComStepSizeAvailable); If NextMaxComStepSizeAvailable is true, NextMaxComStepSize indicates the upper bound on the next communication step. Any communication step size smaller than NextMaxComStepSize should also be acceptable to the FMU. If clocks and events are supported by the FMU, NextMaxComStepSize may be zero, which means that there is an immediate event to handle inside the FMU and the master should push the FMU into the event mode to handle the event before calling fmi3DoStep. NextMaxComStepSize should not be negative.

If an FMU provides the fmi3GetNextMaxCommunicationStepSize function, the Co-Simulation capability flag ProvidesNextMaxCommunicationStepSize="true" should be declared in the XML.

The fmi3GetNextMaxCommunicationStepSize function can be called only in StepMode. It is especially interesting to call this function right before calling fmi3DoStep. The reason is that the value of next maximum communication step size may change after fmi3SetXXX calls. Note that fmi3SetXXX calls are used for setting inputs or changing tunable parameters in FMU.

This capability provides a recommendation on the next communication step size. The master can ignore this function or ignore the returned NextMaxComStepSize value and take a larger communication step. The FMU should accept it. The only consequence would be potential loss of information which may be, in some cases, on purpose or even desirable.

[chrbertsch]

Regular FMI Design Meeting:

Torsten S: Can this not be done with an early return? Pierre: This would come to late for scheduling other FMUs. This proposal is about sampling, not about events. Pierre: It is necessary that the FMU exports know about the difference between this feature and and events and will hand this information out. Torsten: One could use an a-periodic output clock. Christian: At least as a workaround. Torsten: For me this really a new feature that would require a new FCP. It requires a new API function. Pierre: Perhaps the communication stepsize is not the right argument, but more a frequency (not the phase) Henrik: This feature will be only useful if every FMU would support this. It could be problematic if the output dynamics depends on the input dynamics.

Pierre: Convert the word document in an FCP, but check that that we could add this feature in a future version (e.g. 3.1) Hela: It should be discussed how this feature is related or decoupled from the aperiodic clock feature.

@masoud-najafi : will create an FCP and store it at https://github.com/modelica/fmi-design/tree/master/FMI_ChangeProposals. Then this ticket shall be labeled as an FCP.

[masoud-najafi]

FCP_019_Maximum_Communication_Step_Size was created.

[chrbertsch]

FMI Design Meeting:

https://github.com/modelica/fmi-design/blob/master/FMI_ChangeProposals/FCP_019_Maximum_Communication_Step_Size/proposal_nextmaxcommstep.ADOC

Discussion: Andreas: Why do we need this? Claudio: e.g., to simulation state charts, ... Masoud: it is an improvement for efficiency Andreas: If we introduce this, it implies changes Claudio: Should be optional Casper: If you have an FMU that does not support rollback, you get advantages from this proposal Andreas: one of the big advantages of (basic) co-simulation is that is so simple Klaus: its optional Klaus: In HCS one could do this this with events, but events are somthing different Casper: There is a paper by David Bromann on this, will provide a link

Poll: Shall we include this feature in FMI 3.0 BCS? Yes: 3 No: 5 Abstain:5

--> not realize this in FMI 3.0 Andreas: This would affect not only the specification, but lots of other implications examples etc. Markus: one could realize this similarly with HCS @clagms : I could provide an example with HCS from a paper form Cosim-CPS, @APillekeit: can support

[CThuleHansen]

The feature is essentially a simple step size negotiation technique. It is mainly a performance optimisation, but gives the possibility of deterministic execution if some FMUs do not support rollback (i.e. fmi2)

This functionality has already been described in literature and implemented in both FMU exporting tools and FMU importing tools. (i.e. overture, 20-sim, openmodelica, INTO-CPS COE/Maestro, ptolemy)

The semantics and examples of such a feature is given in: https://www2.eecs.berkeley.edu/Pubs/TechRpts/2013/EECS-2013-153.html

This demonstrates a timed automata FMU that would benefit from of such a feature: https://hal.inria.fr/hal-01871531/document

The feature was presented at an FMI meeting in 2017: https://svn.fmi-standard.org/fmi/branches/public/docs/Modelica2017/08_20170515_FMI_user_meeting_Prague.pdf