Improve explanation of variable naming for fmi3GetIntervalFraction, fmi3SetIntervalFraction, fmi3GetShiftFraction and fmi3SetShiftFraction

[Tc-Fast]

• The functions fmi3GetIntervalFraction, fmi3SetIntervalFraction, fmi3GetShiftFraction and fmi3SetShiftFraction use arguments named "counter" and "resolution". This is incomprehensible. The variable names should be "intervalNumerators", "intervalDenominators", "shiftNumerators" and "shiftDenominators", because these names are commonly used in the context of fractions.
• The variable "counter" is not a "counter". I guess this name is the result of a translation from german to english ("Zähler" -> "Counter"), but in the context of fraction it should translate to "numerator".
• The documentation states about the "counter" variable: "Note: This variable may increment by values other than 1." This is wrong, since the "counter" is not a "counter". It is never incremented or decremented.
• The variable "resolution" is misleading as well. A fraction does not have a "resolution".
• Some subscripts in the mathematical notation use numbers in italic font. In mathematical notation numbers should always use a "normal" font.

In order to maintain backwards compatibility the naming in the xsd files can not be changed. I suggest to leave the names in the xsd therefor as is and add a comment for clarification.

[pmai]

• The functions fmi3GetIntervalFraction, fmi3SetIntervalFraction, fmi3GetShiftFraction and fmi3SetShiftFraction use arguments named "counter" and "resolution". This is incomprehensible. The variable names should be "intervalNumerators", "intervalDenominators", "shiftNumerators" and "shiftDenominators", because these names are commonly used in the context of fractions.

This seems to me to be the underlying mis-understanding: That these accessors are about fractions, which would rather suggest that the Fraction part of their names should be struck. The non-fraction versions of these accessors are also dealing in fractions, as floating-point numbers are just as much fractions as the others are. The fact that these accessors carry "Decimal" in their name is lamentable - given that these are exactly not decimal but binary fractions - but like the rest of the naming not something up for change this late in the game.

• The variable "counter" is not a "counter". I guess this name is the result of a translation from german to english ("Zähler" -> "Counter"), but in the context of fraction it should translate to "numerator".

Disregarding the fact that numerator is just the latin word for counter in any case (no need to take german into account here), this is not about fractions, it is about the way that such clocks are usually implemented: You have a counter that counts up, the resolution of which then determines how this is mapped to the time unit, how it fits into the overall schedule, and how and when wrap-around is handled. This is usually tied to an overall scheduling mechanism, but that is beyond the things that FMI standardizes (which makes explaining the concepts slightly more problematic).

• The documentation states about the "counter" variable: "Note: This variable may increment by values other than 1." This is wrong, since the "counter" is not a "counter". It is never incremented or decremented.

This is talking about the internal implementation, where exactly this counter does count up. Which again suggests that the whole fraction business is misleading you into thinking this should be about fractions (the mathematical concept), not clocks and scheduling. So we should rather downplay this whole fractional wording, rather than more fully embracing it.

• The variable "resolution" is misleading as well. A fraction does not have a "resolution".

But a schedule or clock does. Just because a concept can be expressed via mathematical constructs does not make them the same (or as Korzybski would have it: The map is not the territory).

In order to maintain backwards compatibility the naming in the xsd files can not be changed. I suggest to leave the names in the xsd therefor as is and add a comment for clarification.

I suggest to not change any of the naming, but rather explain more clearly the concepts in a way that does not mislead people into thinking about fractions the whole time.

[chrbertsch]

FMI Design Meeting: Pierre: the clocks have counters and resolutions. The wording stems from how you would implement clocks. It is perhaps misleading that we talk about fractions ... We might want to look into the Modelica spec. Nikolai: I will look into this and start a new PR.

[Tc-Fast]

... it is about the way that such clocks are usually implemented

This may be right. Clocks in Modelica are implemented this way: https://specification.modelica.org/maint/3.6/synchronous-language-elements.html#modelica:clock-rational. However the FMI standard is not an Modelica extension nor is it an extension for any other implementation. It is a general purpose simulation interface and therefore should not assume the implementation.

... You have a counter that counts up

Maybe I do not have a counter. How do you know?

[pmai]

... it is about the way that such clocks are usually implemented

This may be right. Clocks in Modelica are implemented this way: https://specification.modelica.org/maint/3.6/synchronous-language-elements.html#modelica:clock-rational. However the FMI standard is not an Modelica extension nor is it an extension for any other implementation. It is a general purpose simulation interface and therefore should not assume the implementation.

Except of course that the Modelica specification is not an implementation, but a specification. Whether internally Modelica implementations use counters or not is immaterial to the way clocks are specified for Modelica. The way clocks are specified in Modelica just recognizes the fact that they are used - first and foremost - to model actual sampled control systems, and those are usually implemented in this fashion, hence the carry over of naming.

Now even though FMI is a separate standard, and rightly so, it is an MA standard, hence having harmonized naming for similar concepts across standards is not a bad thing.

... You have a counter that counts up

Maybe I do not have a counter. How do you know?

I don't care? This is a discussion about why things are named the way they are, and that derives from the history of synchronous languages and other modeling approaches used to model actual sampled control systems, and those systems are usually implemented in this way, hence this informed some of the naming choices. Once we are at the specification level you can of course implement clocks any way you want, as long as it respects the mandated semantics. But that does not change the reasons things are named the way they are.

Could different names have been used? Certainly. Would just talking about fractions have been better? Not at all.

[Tc-Fast]

Then let's keep it as is