Provide guidance for layered standard authors

t-sommer commented 2 months ago

because the hyphen (-) clashes with the naming convention structured.

t-sommer commented 2 months ago

One option would be to use single quotes e.g. 'org.fmi-standard.fmi-ls-xcp.UDPPort'.

bmenne-dspace commented 2 months ago

Option 1: We say that "-" is replaced by "_", as we already did in fmi-ls-xcp and fmi-ls-bus. Option 2: Use 'org.fmi-standard'.'fmi-ls-xcp'.UDPPort Option 3: 'org.fmi-standard.fmi-ls-xcp.UDPPort' (use single quotes) Option 4: 'org.fmi-standard.fmi-ls-xcp'.UDPPort

Additionally for 3.0.2 we should comment on reserving this names on variables.

bmenne-dspace commented 2 months ago

Poll:

Option 1: Benedikt, Markus, Christian, Matthias, Masoud, Klaus Option 2: Nikolai, Klaus Option 3: Otto, Karl Option 4: Nikolai, Christian, Otto, Karl, Masoud

Christian: If there are further arguments please comment. We will talk about it in the Steering Committee next week (with respect on consequences to the release of the fmi-ls-xcp standard)

t-sommer commented 2 months ago

IMHO, the variables should be marked using an annotation or a separate XML file.

The dot notation does also not play well with variableNamingConvention="structured" as it moves the parameter to the third sub-level:

chrbertsch commented 2 months ago

IMHO, the variables should be marked using an annotation or a separate XML file.

I do nto undstand how this would help. We want to define fixesd variable names of that we want to use in a layered standard. So the FMU must have exactly the predefined names. Just marking them with an annotation or putting them in a separate XML file does mot help.

The proposals Option 1-4 provide names that avoid name-clashes. (in a bugfix relesae we cannot forbid their usage in a different way, but give a strong recommendation, but it is very unlikele. In the end it is up to the exporting tool to avoid name-clashes, if it wants to support the corresponding layered standard)

The dot notation does also not play well with variableNamingConvention="structured" as it moves the parameter to the third sub-level: Option 4 wold avoid this, all parameters of the layered standard would be grouped. on the first sub-level. However, personally I do not consider this too important.

We must decide on this issue before the release of FMI-LS-XCP . (Any solution other than the option 1 will delay the release) @ all : Please give your opinions and arguments here in this issue. (@pmai , @andreas-junghanns , ....)

We will then discuss how to proceed in next weeks steering committee meeting

t-sommer commented 2 months ago

Why would it be necessary to require a fixed name for these variables? They can be identified by the respective annotation, e.g.

<UInt16 name="UDPPort" valueReference="8" causality="parameter" variability="fixed" initial="exact" start="5555">
  <Annotations>
    <Annotation type="org.fmi-standard.fmi-ls-xcp.UDPPort"/>
  </Annotations>
</UInt16>

chrbertsch commented 2 months ago

Would the name "UDPPort" be predefined, or could you also have a different variable name?

<Float64 name="myUDP" valueReference="8" causality="parameter" variability="fixed" initial="exact" start="5555">
  <Annotations>
    <Annotation type="org.fmi-standard.fmi-ls-xcp.UDPPort"/>
  </Annotations>
</Float64>

t-sommer commented 2 months ago

The variable could have any name.

chrbertsch commented 2 months ago

Why would it be necessary to require a fixed name for these variables? They can be identified by the respective annotation, e.g.
<UInt16 name="UDPPort" valueReference="8" causality="parameter" variability="fixed" initial="exact" start="5555">
  <Annotations>
    <Annotation type="org.fmi-standard.fmi-ls-xcp.UDPPort"/>
  </Annotations>
</UInt16>

I agree with Torsten that this is the cleaner solution for layered standards.

PTaeuberDS commented 2 months ago

Why would it be necessary to require a fixed name for these variables? They can be identified by the respective annotation, e.g.
<UInt16 name="UDPPort" valueReference="8" causality="parameter" variability="fixed" initial="exact" start="5555">
  <Annotations>
    <Annotation type="org.fmi-standard.fmi-ls-xcp.UDPPort"/>
  </Annotations>
</UInt16>

This is a nice idea that would have been worth discussing a year ago when we did not have any release candidates for LS XCP and when exactly this topic was discussed and decided on (s. https://github.com/modelica/fmi-ls-xcp/issues/21). There has already been a poll about the naming of the variables and almost all the participants of the F2F Design Meeting voted for the current naming.

Using annotations has other drawbacks. For instance, it is more complex to search for the variables as the information you are looking for is part of an element in an element list under the variable. Layered standards might also be defined for FMI 2.0 (like it is the case for LS XCP) and in FMI 2.0 the annotations were considered as additional information for specific tools. Due to this the annotation requires a "Tool" element, which is also not "pretty".

Besides that most tools will probably not display annotations but variable names. Using the fmi-ls prefix in the variable name will make it clearer for the user where those variables belong. Additionally, people indeed might prefer the structured variable depiction because the variables are grouped by layered standards, which makes it clearer if the FMU contains several layered standards.

I believe both variants have their drawbacks and it is a matter of preference. Since tool vendors have already invested significant effort in implementing and pushing LS XCP, we should not further postpone the release, especially because we already have reached the RC4 milestone. Changes to the implementation (which this would be) should only be made if absolutely necessary and not based on preferences.

(cc) @adriantirea @andreas-junghanns @jan-ribbe @pmai @chrbertsch

chrbertsch commented 2 months ago

FMI Steering Committee:

Pierre: the content could be represented both in FMI 2 /3 annotations
Klaus: one of the questions was: can we do this at all with a predefined with a variable name? Can we do this at all? We did not reserve a namespace? But if the FMU supports a layered standard, it can decide to follow a layered standard and comply with specific rules
Pierre: on a strategy level this gets problematic, if we want to retrofit FMUs ... Personally I think there are practical reasons that mandated names are preferrable
Torsten: we might have problems with tools that do not support "." notation ... It is late but I consider the change a better solution.
Klaus: you mean, that layered standards never should define variables, but only define annotation
Torsten: What about combinations of FMUs? Have we thought this through?
Pierre: I think we have a problem with multiple FMUs or multiple FMU slaves
Andreas: We thought about this, we have multiple FMUs with their own XCP server. This can be done if the FMUs "play nice" and and are by default turned off. We can enable them one by one if we have only one port. They each come with their own ports.
Pierre: what about the FMU having multiple XCP servers? One would have to multiplex this .... One could expose multiple XCP slaves ....
Andreas: if we delay this, we should think about Torsten S's suggestion on the annotation.
Andreas/Pierre: We would not need complicated prototyping for this change
Pierre: I could prepare an analysis until next weeks FMI Design meeting
Matthias: Patrick will not be available next week.

chrbertsch commented 1 month ago

FMI Design Meeting:

Pierre: we could after the release of LS-XCP give a recommendation in the FMI Guide how to write a layered standard ...

chrbertsch commented 4 weeks ago

FMI Design Webmeeting: Torsten: with the current solution this is no longer relvant, as we went away from fixed variables names

modelica / fmi-guides

Provide guidance for layered standard authors #113