Final review of FMI2.0.1 RC

[chrbertsch]

Please inspect the PDF documents of the RC (see below) and comment in case of errors or possible improvements - ASAP but before Oct 1st. In case we do not find blockers, we plan to vote on the release in the FMI steering committee on Oct 2nd.

//Updated files due to misssing pages FunctionalMockupInterface_v2.0.1_RC1.pdf FunctionalMockupInterface_v2.0.1_RC1_with_changemarks.pdf

// Update 2019-09-25 10:43CEST FunctionalMockupInterface_v2.0.1_RC2.pdf FunctionalMockupInterface_v2.0.1_RC2_with_changemarks.pdf FunctionalMockupInterface_v2.0.1-Diff_RC1_RC2.pdf

// Update 2019-09-27 21:22CEST : RC3 added FunctionalMockupInterface_v2.0.1_RC3.pdf FunctionalMockupInterface_v2.0.1_RC3_with_changemarks.pdf FunctionalMockupInterface_v2.0.1-Diff_RC2_RC3.pdf

// Update 2019-10-01 18:41CEST : RC4 added FunctionalMockupInterface_v2.0.1_RC4.pdf FunctionalMockupInterface_v2.0.1_RC4_with_changemarks.pdf FunctionalMockupInterface_v2.0.1-Diff_RC3_RC4.pdf

// Update 2019-10-02 12:24 CEST : RC5 added FunctionalMockupInterface_v2.0.1_RC5.pdf FunctionalMockupInterface_v2.0.1_RC5_with_changemarks.pdf FunctionalMockupInterface_v2.0.1-Diff_RC4_RC5.pdf

// Update 2019-10-06 15:20 CEST: RC6 added (figure numbers fixed) FunctionalMockupInterface_v2.0.1_RC6.pdf FunctionalMockupInterface_v2.0.1_RC6_with_changemarks.pdf FunctionalMockupInterface_v2.0.1-Diff_RC5_RC6.pdf

Please comment on the latest documents

[chrbertsch]

Ah, just saw we have to use the "Create bookmarks using .... headings" with this option it is there. Will be included in RC4.

[nickbattle]

@chrbertsch I don't see contents with either RC1, 2 or 3.

chrbertsch: fixed in principle, see below

[chrbertsch]

@chrbertsch I don't see contents with either RC1, 2 or 3.

@nickbattle What about this: test_bookmarks.pdf

chrbertsch: fixed in principle, see below

[clagms]

@chrbertsch I don't see contents with either RC1, 2 or 3.

@nickbattle What about this: test_bookmarks.pdf

It's a bit strange on SumatraPDF: Same thing in Acrobat Reader.

[nickbattle]

Yes, I'm seeing the same thing as @clagms: a burst of section "1." empty entries, followed by a plausible contents for the remainder. And "Figure 13" for some reason. This is Okular on Linux.

[chrbertsch]

It's a bit strange on SumatraPDF:

no, get it also with Adobe acrobat

I get the same with Adobe PDF export. So this must be part information contained in the word document.

Could someone with better Word 2016 knowledge than I have please give a hint?

[nickbattle]

The "1s" are all on page 7. This is where the table of contents is located in Word, so I suspect that is causing it. The rogue "Figure 13" and the individuals listed at the end are also being picked up as a "heading". My guess is that these entries (and perhaps the contents too?) have a "Heading" style? It might be possible to change this to something that isn't a heading style?

[clagms]

Thank you for these hints @nickbattle ! When exporting the pdf on my machine (word for office 365) I get something that looks a little bit better:

Now trying to figure out which styles are being picked up by word to export the bookmarks.

[nickbattle]

@clagms It's probably anything that inherits from "heading" - just a guess though. What style are those names in the appendix?

[hyumo]

• Inconsistent XML word format in Example 4 Page 65
• Figure number errors starting from Figure 332, then 443, 554, 665, 776, 887, ...
• In Figure 3 t and E are overlapping
• Inconsistent syntax highlighting in pseudo code example 3.2.4

chrbertsch: fixed, see below

[clagms]

@clagms It's probably anything that inherits from "heading" - just a guess though. What style are those names in the appendix?

@nickbattle that's exactly what it is :)

Below are some of the elements I had to change the style to "normal" in order to get rid of these spurious headers (note the page numbers). Maybe you can right-click in the Heading 1 style and select all instances: Or you can open the navigation pane and go straight to those elements.

Here's the doc and generated pdf, after these issues have been corrected. You can see the changes I made in the docx. FunctionalMockupInterface.docx FunctionalMockupInterface.pdf

I guess the spurious "1."'s are caused by the same problem.

[nickbattle]

@clagms Confirmed that your modified PDF has a correct table of contents, as viewed in Okular. So that's probably the fix you need, @chrbertsch.

I could fix individual problems, but then when I fix the others, the already fixed ones re-apper. Do not understand what word does here. Current workaround : deletel the "1.".s manually

[filip-stenstrom]

Page reference: RC3

• or else is returned by the fmi2GetXXX functions // what does "else" refer to? p34 chrbertsch: Fixed, see below
• where 𝑢 continuous-time input // --> where 𝑢 is a continuous-time input, p65 chrbertsch: fixed in RC4

[clagms]

In the mathematical model of a co-sim FMU: please clarify that $m_{ido}$ stands for the model input derivative order.

chrbertsch: fixed, see below

[clagms]

Is Feedthrough Supported?

Please clarify the FMI 2.x Co-simulation support for feed-through.

First we need a definition of feedthrough.

Given an Co-simulation FMU instance $c$ , the input $u_c$ feeds-through to output $y_c$ when there exist two different values $v_1, v_2$ and FMU state $s_c$, such that $$get_c(set_c(s_c, u_c, v_1), y_c) \neq get_c(set_c(s_c, u_c, v_2), y_c)$$ where:

• the FMU state $s_c$ represents the whole FMU state (just like the one used in the FMI get/set state functions)
• $set_c(s_c, u_c, v_1)$ returns an FMU state, that is used in the call to $get_c$,
• $set_c(s_c, u_c, v_2)$ returns an FMU state, that is used in the call to $get_c$.

Here are some properties of the feed-through:

• When $u_c$ feeds through to $y_c$, we say that there is an algebraic dependency (or algebraic relationship) between $u_c$ and $y_c$. Also, if all other variables are fixed, it means that there is a function $g(u_c)$ such that $y_c = g(u_c)$.
• Usually, when $dy_c/du_c \neq 0$ then we can also conclude that there is feedthrough from $u_c$ to $y_c$.

Note that this definition of feed-through is well accepted, and it means the exact same thing as "algebraic dependency".

Also note that any ODE that has an output equation of the form: $$\dot{x} = F(x, u)$$ $$y = G(x, u)$$

has feed-through.

This definition is therefore consistent with [Kubler2000], that RC3 claims to be consistent with.

Now let's look at the RC3 text regarding feedthrough.

Right at the beginning, it says:

Support many and nested FMUs: A simulator may run many FMUs in a single simulation run and/or multiple instances of one FMU. The inputs and outputs of these FMUs can be connected with direct feedthrough. Moreover, an FMU may contain nested FMUs.

Setting aside the fact that "direct feedthrough" is redundant with "feedthrough", this induces the reader into thinking that FMI CS supports feedthrough. I would argue that supporting feedthrough is a necessary feature to export Modelica models, in

Expressivity: The FMI provides the necessary features that Modelica®, Simulink® and SIMPACK® models1 can be transformed to an FMU.

Then, in the definition of the causality attribute, the words algebraic relationship are used:

"output": The variable value can be used by another model or slave. The algebraic relationship to the inputs is defined via the dependencies attribute of <fmiModelDescription><ModelStructure><Outputs><Unknown>.

Leading the reader to believe that any dependency declared in the ModelStructure, is a feedthrough dependency, and therefore satisfies the definition I put above.

In fact, in the definition of the ModelStructure, it says:

Attribute dependencies defines the dependencies of the outputs from the knowns at the current super dense time instant in Event and in Continuous-Time Mode (ModelExchange) and at the current Communication Point (CoSimulation).

Again, the reader might think that this means there is an algebraic (an instant) dependency between knowns and unknowns.

Thankfully, in the mathematical definition of the FMU for co-simulation, we observe:

Which tells the reader that there is no feedthrough in that model (i.e., the output $y{i+1}$ does not depend algebraically on the input $u{i+1}$).

However, the text immediately after says

Definition (4.1) is consistent with the definition of co-simulation by (Kübler, Schiehlen 2000)

which is not true. Equation (4.1) clearly forbids feedthrough, and [Kubler2000] has the equation:

(apologies for the scribbles).

This equation clearly shows the feed-through.

Moreover, later in the standard, there is a remark:

There is the additional restriction in \emph{slaveInitialized} state that it is not allowed to call fmi2GetXXX functions after fmi2SetXXX functions without an fmi2DoStep call in between

Which makes it clear that feedthrough is not supported, which is also claimed in https://github.com/modelica/fmi-standard/issues/117#issuecomment-430378201.

If indeed the intent is not to support feedthrough in the FMI co-simulation, then I suggest that the parts I've highlighted above be rewritten to avoid giving this idea.

Moreover, note that the mathematical definition of FMU co-simulation forbids the use of a Gauss-Seidel master algorithm. This is because a Gauss Seidel algorithm will produce an input $u_{i+1}$ to one of the FMUs that is at the timestamp $i+1 = t+H$, violating the assumptions in Equation (4.1). This also means that solving algebraic loops on the output variables is something that requires rollback (whereas, with feedthrough, rollback would not be needed).

To summarize the changes:

• The claim that The FMI provides the necessary features that Modelica® should maybe be restricted to FMI Model Exchange, as I would argue that having feedthrough is an essential feature of Modelica. Even the simplest coupled mechanical models (such as a mass-spring-damper) need feedthrough to be more accurately co-simulated.
• Avoid using the expressions "algebraic relationship", "algebraic dependency", etc. when referring to the actual FMU inputs/outputs. We need to make the distinction between the inputs/outputs of the model inside the FMU, and the inputs/outputs of the FMU. The model may have feedthrough, but the FMU does not have it, so one might as well forget that the model has feedthrough as well.
• Clarify the use of the Model Structure dependencies. Without feed-through, are these only used to know which directional derivatives to ask for? Btw, having a non-zero directional derivative also hints at an algebraic dependency, but maybe we need to make it clear that this is the model dependency, and not the FMU dependency.

I hope this helps! :)

PS - This issue has been discussed with, and approved by @CThuleHansen .

Refs:

[Kubler2000] - Kübler, R., and W. Schiehlen. 2000. “Two Methods of Simulator Coupling.” Mathematical and Computer Modelling of Dynamical Systems 6 (2): 93–113. https://doi.org/10.1076/1387-3954(200006)6:2;1-M;FT093.

Gomes, Cláudio, Casper Thule, Levi Lucio, Hans Vangheluwe, and Peter Gorm Larsen. 2019. “Generation of Co-Simulation Algorithms Subject to Simulator Contracts.” In 3rd Workshop on Formal Co-Simulation of Cyber-Physical Systems, to be published. Oslo, Norway.

chrbertsch: See below

[clagms]

Input Approximation Ambiguity

Please clarify the FMI 2.x Co-simulation on what FMUs should assume about the timestamp of their inputs.

Interpolations and Extrapolations are two different function approximation schemes.

The flag canInterpolate inputs may confuse the reader into thinking that an FMU mathematical model requires inputs $u_{i+1}$ before the execution of the doStep function.

This is not the case:

What I think this flag means is that the FMU can approximate the input function over the interval $t$ to $t+H$. In that case, maybe a name "canApproximateInputs" would be more adequate.

Also, a strict interpretation of the mathematical model means that the Gauss Seidel master algorithm is not a valid FMI Cosim algorithm, because such algorithm will compute $u_{i+1}$ at time $t$, before starting the execution of $ɸ_i$.

Also, which inputs are being approximated by the FMU? All continuous inputs? Or just some?

This is because, as stated in Section 4.1.2., an FMU can be a combination of a hybrid ODE and a sampled data system. In that case, it is not necessarily the case that all continuous inputs are being approximated by the FMU.

I would argue that whether an input can be approximated or not is information on each variable (I haven't thought through the exact conditions on that variable), and not information about the FMU.

Thank you very much for all the work on reviewing these issues! :)

PS - This issue has been discussed with, and approved by @CThuleHansen .

chrbertsch: see below

[beutlich]

• page 124: could use the new repository of FMITest, i.e. change the link to https://github.com/modelica/FMIModelicaTest chrbertsch: fixed in RC4
• page 126: change "w.r.t to" to "w.r.t." chrbertsch: fixed in RC4

[clagms]

In the description of "unbounded", it says

during time integration, the variable gets a value much larger than its nominal value nominal.

But the meaning of "much larger" is not specified anywhere else. How does one know that an FMU implements this attribute correctly?

see below

[nickbattle]

or else is returned by the fmi2GetXXX functions // what does "else" refer to? p34

The wording is a bit awkward, but I read it to mean that either a value is set (with fmi2SetXXX) or "else" retrieved (with fmi2GetXXX) relative to the unit specified. I think it would mean the same if the "else" was removed.

chrbertsch: fixed, see below

[chrbertsch]

or else is returned by the fmi2GetXXX functions // what does "else" refer to? p34

The wording is a bit awkward, but I read it to mean that either a value is set (with fmi2SetXXX) or "else" retrieved (with fmi2GetXXX) relative to the unit specified. I think it would mean the same if the "else" was removed.

I undstand this sentence in a way that both setting and getting the varibal is w.r.t to the unit. So I would replace the "or else" by "and"

If a variable is associated with a Unit, then the value of the variable has to be provided with the fmi2SetXXX functions and is returned by the fmi2GetXXX functions with respect to this Unit.

Please comment, if you agree or disagree with this understanding and proposal.

[chrbertsch]

In the description of "unbounded", it says

during time integration, the variable gets a value much larger than its nominal value nominal.

But the meaning of "much larger" is not specified anywhere else. How does one know that an FMU implements this attribute correctly? @clagms : Even though this is not clearly defined, we cannot fix this in a bugfix release 2.0.1 by clearly defining it, as this could invalidate existing 2.0 implementations. If you consider this topic important, please open a new ticket for FMI 3.0.

[filip-stenstrom]

or else is returned by the fmi2GetXXX functions // what does "else" refer to? p34

The wording is a bit awkward, but I read it to mean that either a value is set (with fmi2SetXXX) or "else" retrieved (with fmi2GetXXX) relative to the unit specified. I think it would mean the same if the "else" was removed.

I undstand this sentence in a way that both setting and getting the varibal is w.r.t to the unit. So I would replace the "or else" by "and"

If a variable is associated with a Unit, then the value of the variable has to be provided with the fmi2SetXXX functions and is returned by the fmi2GetXXX functions with respect to this Unit.

Please comment, if you agree or disagree with this understanding and proposal.

This makes sense to me

[antvl]

Regarding clarifications of the mathematical model for Co-simulation:

• $m_{ido}$ stands for the the model input derivative order. This should be added to page 105, at the end of the following paragraph:

The current input variables ... (in case of continuous-time variables), where $m_{ido}$ stands for the the model input derivative order.

As already stated in this paragraph extrapolation only applies to continuous-time input variables. Is is clear enough?

• The mathematical model does not prevent implementing a Gauss-Seidel co-simulation schema. Within this schema, the approximation of input variables is considered as interpolation. With Jacobi schema, the approximation is done using extrapolation. As FMI only describes the interface between a master environment and a slave component, the mathematical model does not describe the whole co-simulation schema applied to a set of coonected FMUs, but it does not prevent applying either Jacobi or Gauss-Seidel algorithms. Unfortunately, it is not possible in FMI 2.0.1 version, that is a maintenance version, to change the wording from "canInterpolateInputs" to "canApproximateInputs".

• Regarding direct feedthrough, one must distinguish between the FMU for Co-simulation and the model inside the FMU (that is described by an ODE). The inside model can have direct feedthroughs between input and output, and this can be queried using the directional derivatives (since this applied to the underlying model, not the FMU component). In contrast, co-simulation, is a numerical approximation that is applied to the model, and as such, it has been decided that in FMI 2.0, direct feedthrough is not allowed at co-simulation level. This is expressed by the current mathematical model, and it is actually a restriction with respect to the schema described by Kübler & Schiehlen.

chrbertsch: adding sentence The current input variables ... (in case of continuous-time variables), where $m{ido}$ stands for the the model input derivative order. in RC4_

[clagms]

Thank you for the thorough reply, and for paying attention to this topic @antvl !

As already stated in this paragraph extrapolation only applies to continuous-time input variables. Is is clear enough?

Unfortunately, it is still not enough, as one can have continuous time variable that are being approximated, while others are not. Or does the standard constraint the implementation of the FMU to either implement approximation in all continuous time variables, or on none? If so, please maybe make this clearer to tool providers.

Within this schema, the approximation of input variables is considered as interpolation.

Maybe I did not explain this properly. Consider an FMU A, that implements an input interpolation scheme. When FMU A is at time $t$, and a setReal is called in that FMU A, the FMU A will assume that it is receiving an input that was computed by another FMU B that is already at time $t+H$. This assumption has to be made because there is no way of knowing the timestamp of an input when a call is made to setReal. We may argue that the timestamp of a value corresponds to the timestamp of the internal state of the FMU that computed it (although one has to be careful with this definition, and more details are given in the paper cited below). If that is correct (I cannot think of any other way of defining the timestamp of a value, but I'm all ears for alternatives!), then the Co-simulation model should depict a "+1" on the $u$ var, as shown in blue: This shows that the gauss seidel is not allowed by the math description of the standard.

Now I try to show why, even if it is allowed, there is an ambiguity in the standard.

When a doStep is called, FMU A will compute an interpolation (think of a linear interpolation, for instance).

Now imagine the exact same FMUs A and B being used in a Jacobi co-simulation. That same FMU A is still making the assumption that the value it gets is from a "future" timestamp, and will consequently perform an interpolation on it. However, when a Jacobi cosim is used, any approximation on the inputs needs to be an extrapolation. Without explicit timestamps on the inputs, the implementation of a interpolation is different than the implementation of an extrapolation. The following figure is an attempt at depicting the difference on the inputs that FMU A will give to its internal numerical solver, when used correct (top) and incorrectly (bottom):

I also attach the paper where me and the co-authors have hopefully explain this matter a little bit better 😋 cosimcpspaper.pdf

chrbertsch: see below

[antvl]

• The FMI for Co-simulation standard does not require that providing derivatives for all continuous-time input variables is mandatory. It is up to the master environment to provide these derivatives through appropriate calls to the fmi2SetRealInputDerivatives function. The FMU has to deal with that, input variables can have different extrapolation or interpolation orders (as shown on page 108).

We could add the following sentence:

Differents input variables may have different interpolation order.

• As I said before, the mathematical model does not try to describe all possible co-simulation schemas. It is about the internal representation of co-simulation in the FMU, not about how connected FMUs are evaluated in a particular co-simulation algorithm. Formulas for extrapolation or interpolation are not part of the 2.0 specification document, as it was the case in the FMI for Co-simulation 1.0. This is to let freedom to the FMU implementer. However, extrapolation or interpolation can be correctly implemented by providing the appropriate values for successive derivatives, as shown on page 47, appendix D, of the FMI for Co-simulation 1.0.1 document.

chrbertsch: inclduded clarification sentence Differents input variables may have different interpolation order. For additional topics please add a new issue

[CThuleHansen]

See https://github.com/modelica/fmi-standard/issues/440#issuecomment-536975569 related to set inputs in instantiated mode

chrbertsch: see comment there

[chrbertsch]

* Inconsistent XML word format in Example 4 Page 65

Corrected to @hyumo please check. If you have findings please propose the correct formatting

* Figure number errors starting from Figure 332, then 443, 554, 665, 776, 887, ...

Figure 332 --> changed to Figure 3, 443 --> 4, 554 --> 5, 665 --> 6 and all other occurences that I found

* In Figure 3 `t` and `E` are overlapping

Will be fixed in RC4

* Inconsistent syntax highlighting in pseudo code example 3.2.4

fixed in RC4, only "// comments" see. e.g.

[chrbertsch]

If a variable is associated with a Unit, then the value of the variable has to be provided with the fmi2SetXXX functions and is returned by the fmi2GetXXX functions with respect to this Unit. ... This makes sense to me

Will change to "and" in RC4

[GallLeo]

Would be nice to put the new "Modelica Association" and "FMI" logos on the title page? https://github.com/modelica/BackOffice/tree/master/Task006_CI/Designer/Logo/Print (Project leaders do have access to this repo; I'll store the new logos in the general MA repo, as soon as we have it set up)

[chrbertsch]

@GallLeo included in RC5

[chrbertsch]

Changes RC4--> RC5:

Add new MA and FMI Logo. Add missing #392 to word document

Known issue in RC5: figure numbers

[beutlich]

@chrbertsch Can you please edit the issue topic since Oct. 1st is in past.

[chrbertsch]

RC5 was accepted on Oct 2nd by the FMI steering committee (with the addition that formatting changes may be done before the release process within MA will be initiated).

The currently last known formatting issues is the figure numbering. The root cause has been identified by an incorrect change in numbering already detected in comment https://github.com/modelica/fmi-standard/issues/623#issuecomment-534034916 (@andreas-junghanns , you were right and I corrected my comment there) in combination with a bug of word regarding figure numbering in combination with tracked changes (https://superuser.com/questions/717022/ms-word-figure-numbers-are-wrong) This will be fixed in RC6

[chrbertsch]

Figure numbers fixed in RC6, see above