Review the current draft

[chrbertsch]

From: https://github.com/modelica/fmi-design/tree/master/Meetings/2024/2024-07-16-FMI-Design-Webmeeting

[Tc-Fast]

Here is my first review:

• The term "stimuli" does not fit the context. I would prefer something like "excitation" or "input signal" etc.
• I get, that LS-REF provides a standardized way of including reference simulations in order to validate the importers simulation results. But what is the point of including other "related" files? It seems like an over engineered way of documenting the model. The FMI3 standard already has a directory for documentations.
• What is the point of the "role" attribute? in the manifest file? What are the roles used for?

I think some parts of the documentation need to be rewritten, since they are unclear. Especially the use case of "other related files" is unclear to me.

[chrbertsch]

• The term "stimuli" does not fit the context. I would prefer something like "excitation" or "input signal" etc.

For me "stimuli" are undestandable, the term is often used in the context of simulation

• I get, that LS-REF provides a standardized way of including reference simulations in order to validate the importers simulation results. But what is the point of including other "related" files? It seems like an over engineered way of documenting the model. The FMI3 standard already has a directory for documentations.

The scope of this layered standard is "related files", and goes beyond reference simulations. I think this is clear from the text except for the first sentence. Thus I propose to move the more general description up to the beginning, see #9

• What is the point of the "role" attribute? in the manifest file? What are the roles used for?

As the scope of this LS is more general, the "related files" can have different "roles". Do you have a suggestion to describe this better?

[Tc-Fast]

For me "stimuli" are understandable, the term is often used in the context of simulation

Google proves, this is (globally) not the case.

The scope of this layered standard is "related files", and goes beyond reference simulations.

This Layered standard is called "LS-Ref". How does including "related files" match the standards name? How are they refs? What is even the point of including them here and not in the documentation section of the FMU?

As the scope of this LS is more general, the "related files" can have different "roles". Do you have a suggestion to describe this better?

Same as above. Why is all of this necessary?

[chrbertsch]

What is even the point of including them here and not in the documentation section of the FMU?

The documentation folder is intended for (human readable) documentation.
The /extra folder and its subfolders are reserved for files described by layered standards. Take the example of parameter files: If we put them in a defined location in defined format, importing tools supporting this layered standard can automatically process them, e.g. make them selectable by the end user.

This Layered standard is called "LS-Ref". How does including "related files" match the standards name? How are they refs?

"LS-REF" is just a name and not a description of the layered standard. The description makes the role of related files clear, and #9 fixes that this was not clear in the first sentence.
We could consider splitting the current proposal in two layered standards, e.g. LS-REF and LS-REL for the related files, but as the LS-REF will need related files anyway (such as parameter files), I like it better to have them combined.
So we can discuss whether we find a name better than LS-REF ...

[Tc-Fast]

If we put them in a defined location in defined format, importing tools supporting this layered standard can automatically process them, e.g. make them selectable by the end user.

This makes e.g. a parameter set (denoted by the role "parameter") available for selection when importing the FMU. That's clear to me. But what about the other roles? I don't get the meaning and the use case for most of them.

We could consider splitting the current proposal in two layered standards, e.g. LS-REF and LS-REL for the related files.

I am not suggesting to split the standard or rename it yet. In my opinion the documentation needs clarification on the use case of "related files" and the meaning of the "roles".

[pmai]

This issue, if it is still considered germaine, will be moved to a future MA-COORD repo on the experiments part. If there are still issues with the core part of fmi-ls-ref that should be considered, please re-raise as new issues against the current draft (including currently pending PRs).