Clarify countdown clock ticks

[PTaeuberDS]

The specification is unclear about the concrete time of a countdown clock tick.
Across the spec there are described two contradictory point of views:

1. A countdown clock ticks while a model partition is being executed, i.e. the clock already has ticked when intermediate update is invoked.
2. A model partition can only signal that a countdown clock is about to tick. The actual ticking takes place after the provided interval is run out.

Here are some quotes that state the first variant:

• Section 2.2.9.4:

  The FMU may request to schedule another model partition even while currently a model partition is being executed. countdown Clocks can tick at any time during the execution of any model partition. The FMU signals their ticking by calling fmi3CallbackIntermediateUpdate with argument clocksTicked == fmi3True. The importer calls fmi3GetInterval for all countdown Clocks. If a new interval is provided, the importer initiates the scheduling of the associated model partitions with the returned interval. qualifier == fmi3IntervalChanged indicates that the corresponding Clock has to be scheduled.

• The parameter name clocksTicked of the fmi3CallbackIntermediateUpdate function implies that the countdown clock already has ticked.

Here are some quotes that state the second variant:

• Table 5. Overview of Clock types. - countdown clock:

  In Scheduled Execution the FMU has to inform the importer by calling fmi3CallbackIntermediateUpdate that the Clock is about to tick using clocksTicked == fmi3True.

• Section 2.2.9 - countdown clocks - interval description:

  The time interval from the event time at which the argument qualifier == fmi3IntervalChanged of fmi3GetInterval to the next Clock tick.

• Section 5.1.1:

  During the computation of a model partition of an input Clock the FMU may inform the importer that an output Clock ticked or a countdown Clock has to be ticked.

• Comment in the SE code example:
  // ask FMU if countdown clock is about to tick

As the ticking of a countdown clock is not clearly defined this could lead to misunderstandings. To fix this, one of the variants must be chosen. The second variant is to prefer for the following reasons:

• If the clock already had ticked before fmi3CallbackIntermediateUpdate is called by the FMU this would be a behavior of an output clock

• An input clock is defined as follows (2.2.9.2):

  In Scheduled Execution, when input Clocks tick, the importer will activate the associated model partitions (but not the input Clocks) using fmi3ActivateModelPartition. While the importer is the source of the actual Clock activations, the timing of the Clocks is defined by the FMU, either through the modelDescription.xml or calling fmi3GetInterval, or by another Clock connected to a triggered input Clock.

  Since the model partition is activated after the interval is run out, there must be a clock tick. If it already had ticked "inside the FMU" and the interval is >0 there would be no model partition activation for that clock tick, which is contradictory to the definition of input clocks.

So, I propose to use the second variant to unify the description of countdown clocks and to rename the fmi3CallbackIntermediateUpdate parameter clocksTicked to clockHandlingRequested according to other parameters like intermediateVariableSetRequested.

@andreas-junghanns @MBlesken Please review

[andreas-junghanns]

@PTaeuberDS : I think you are misunderstanding the entire mechanism. I reread the quotes you cite and those fit to what we are trying to say.

Note that the reason for being in Event Mode will in most cases be a different clock than the one raised during this Event Mode (or Step Mode, Clock Activation Mode, Continuous Time Mode).
Also: Clocks in ME and CS are different from clocks in SE. An SE, ticking clocks tell the scheduler to trigger associated model partitions. The scheduler has control over when that must happen (other partitions running, their priorities...).

Could you re-read the sections to see if that makes more sense now?
If not, let´s discuss this on the phone.

[PTaeuberDS]

@andreas-junghanns I am looking from the point of view of Scheduled Execution. The mechanism is clear to me. Maybe there are some differences for ME and CS that I do not know yet. However, this PR aims at a specific inconsistency in the definition of countdown clock ticks. The changes affect mainly SE parts of the spec.
So, please let's discuss this in a call, then I can explain my point in more detail.

[PTaeuberDS]

@andreas-junghanns I added most of our discussed points. Regarding the intermediateUpdateTime parameter in fmi3CallbackIntermediateUpdate, I talked with @MBlesken and we came to the conclusion that it should be ignored for SE (as it is already mentioned in the document).
@andreas-junghanns and everyone interested: Please review
@klausschuch If you need support to solve conflicts in #1546 let me know.

[andreas-junghanns]

I fixed another issue with the time-base of the getInterval() for the Intermediate Update Mode.

[andreas-junghanns]

Web Design Meeting: We just realized that the callbackIntermediateUpdate function is a (useless) merger of two functionalities for CS and SE and we should split that up again to simplify the callback for both interface types.
Klaus: in CS call the callbackIntermediateTimeUpdate.
Pierre: maybe keep the name this late in the process.

Andreas: I will provide a separate PR for this split.

Patrick: let´s commit this PR first.