Review of 3.2 (ME API)

[chrbertsch]

https://fmi-standard.org/docs/3.0-dev/#_application_programming_interface: If the super-dense time before a call to

• [x] explain argument x; describe or reference internal order of the argument x of fmi3SetContinuousStatesTYPE, also referring to array serialization

• [x] In explanation of fmi3NewDiscreteStatesTYPE: Correct sentence " fmi3NewDiscreteStates was (tR,tI), then the time instant after the call is (tR,tI)." to "... after the call is (tR,tI+1)."

• [x] I do not understand the non-normative text below the definition of fmi3EnterContinuousTimeModeTYPE:

[This function might be used for the following purposes: If the FMU stores results internally on file, then the results after the initialization and/or the event has been processed can be stored. If the FMU contains dynamically changing states, then a new state selection might be performed with this function.]

• [x] Describe the order of the the continues states returned from typedef fmi3Status fmi3GetContinuousStatesTYPE ...

• ~~in the text a function fmi3EnterContinuousTimeModeTYPE(fmi3Instance instance); is defined, but in the state machine for ME, the function fmi3EnterStepModeis displayed (which belongs to CS, right?): ~~

• [x] Text below ME State machine:

For example, the state chart indicates that when an FMU for Model Exchange is in state Continuous-Time Mode, a call to fmi3Set{VariableType} for a discrete input is not supported.

This was true for FMI2.0, but in FMI 3.0 this cannot be seen from the state machine. Replace this text with a new one telling that the State machine displayes allowed transitions (and call of transition functions), but the allowed calls to functions in each state are defined in the text below.

• [x] Generally missing in 3.2.3.x: Detailed list of allowed and forbidden function calls. -> singled out as #1151

- 3.2.3.6: missing point at the end.

• [x] 3.2.5. Clocks API: "For a outputClock, the environment" --> "For an ..."

[clagms]

Comment " [The functions above have the slight drawback that values must always be copied. ..." : is this the right place for this comment? As this is a general issue for all FMU types: Should be removed or moved to Chaper 2

@chrbertsch , by "this" in "this is a general issue" you mean the copying of values, right? If so, I agree that the comment should be made general to all FMI functions but I disagree that it should be removed, because function SetContinuousStates is specific to ME, and this comment should actually not be non-normative text.

I suggest that a similar comment be made about:

• setting array variables, near All strings passed as arguments to `fmi3SetString`, as well as all binary values passed as arguments to `fmi3SetBinary`, must be copied inside these functions, because there is no guarantee of the lifetime of strings or binary values, when these functions return.; and
• getting array variables, near The strings returned by `fmi3GetString`, as well as the binary values returned by `fmi3GetBinary`, must be copied in the target environment because the allocated memory for these strings might be deallocated or overwritten by the next call to any of the FMI functions.

[hubertus65]

@chrbertsch : this was moved to a spearate ticket https://github.com/modelica/fmi-standard/issues/1059 as it adresses a completely new point.

(Maybe I am a bit out of the loop here. The FMI-ME statechart does not seem to be complete for me for the -admittedly quite complex case - of structural parameters that add or remove states, at least if "initialization" is interpreted in the sense of initializing an ODE/DAE. If a structural parameter is changed in event mode and changes the number of states, there has to be a new initialization state to initialize "new" states, or what the values of the reduced number of states should be. A second remark: It will not be possible to create such FMUs from Modelica tools since Modelica as of today does not support a changing number of states in a model based on an event. My assumption is that this is for controller design, where the number of states in the controller changes dynamically? I also wonder whether it might not be wise to forbid a changing number of states in ME FMUs: it opens a can of worms in terms of hard open questions. How are the start values of "new" states defined and made visible? If the number of states is reduced, do the values of the remaining states remain the same as before the event? How are they mapped? I can imagine that control design tools might want to support this, but I don't see physical modeling tools support this any time soon. I have not seen customer demand for this feature either. )

[andreas-junghanns]

@hubertus65 This was discussed and we decided this is not an issue FMI has to solve. If the FMU can handle changing number of states, it offers states depending on structural parameters, else it does not. If the importer cannot handle such an offer for changing structural parameters changing the number of states, well, it should not change that structural parameter away from its initial value.

We wanted to make sure we do not restrict artificially which can be restricted by the tools very easily to allow future, smarter implementations to potentially use these possibilities.

[hubertus65]

Ok, I can definitely live with that. To me, it still feels like an incomplete proposal, since the "how" of the initialization (and possibly removal) of states is not specified. If nobody can explain how to do that in a standards-conform way, I find it a bit doubtful to leave it in.

[andreas-junghanns]

@chrbertsch : Can we both run through the remaining points to create a PR together? Please let me know when you are available.