Changing parameter values in the modeldescription.xml file

[modelica-trac-importer]

Reported by cbertsch on 15 Oct 2016 11:06 UTC
I would like to clarify, whether it is allowed to change paramter values in the modeldescription.xml file and what the consequences of this are. I know of tools, that do this, and it is unclear to me, what the importing tools shall do with such a modified FMU.

Changing parameters in the modeldescription.xml file could lead to making the GUID invalid (as the 2.0 FMI standard states:
Argument fmuGUID is used to check that the modelDescription.xml file (see section 2.3) is
compatible with the C code of the FMU. It is a vendor specific globally unique identifier of the
XML file (for example it is a “fingerprint” of the relevant information stored in the XML file). It
is stored in the XML file as attribute “guid” (see section 2.2.1) and has to be passed to the
fmi2Instantiate function via argument fmuGUID. It must be identical to the one stored
inside the fmi2Instantiate function. Otherwise the C code and the XML file of the FMU
are not consistent to each other. This argument cannot be null.

Additionally, the parameter values are also stored within the C-Code and/or DLL and I think that it is not specified, that these internal values have to be overwritten with the values from the XML when importing the FMI. Is this correct? I think that some importing tools will do this and other not. Thus a clarificatoin is suggested for FMI 2.0.1

---

Migrated-From: https://trac.fmi-standard.org/ticket/387

[modelica-trac-importer]

Comment by ottot on 19 Oct 2016 12:51 UTC
In the table on page 53 it's quite clear that you only have to call fmi2SetXXX if you want a different value then the one stored in the xml file. This kind of implies that you cannot change the xml file and expect that to have any effect, as you say maybe it should be stated more clearly that your not supposed to change the xml file.

Initial or guess value of variable. This value is also stored in the C functions
 [Therefore, calling fmi2SetXXX to set start values is only necessary, if a 
different value as stored in the xml file is desired.]

[modelica-trac-importer]

Comment by cbertsch on 20 Oct 2016 18:51 UTC
I agree. However, do we consider an FMU with manipulated parameter values in the modeldescription.xml as "corrupt"? (I would do so, as they could produce completely different results)
Can the compliance checker detect this? I think it should!
Should importing tools reject such FMUs or which parameter values should they take?

[modelica-trac-importer]

Comment by apillekeit on 26 Oct 2016 13:40 UTC
Dear all,

the rules for creating and also the meaning of the GUID are a bit vague in the FMI specification. So far I would agree with the other comments. But I disagree with the conclusion of illegalizing changes to the ModelDescription.xml.

From a tool’s perspective regarding start/guess values:
Referring to the sentence on page 53:_ “only necessary”_ doesn’t mean “only allowed”! So it is currentlyperfectly fine to read and set the start values from the ModelDescription.xml for an importing tool. As an importing toolI would do so in any case for consistency/safety reasons since you cannot be sure that the values in the Modeldescription.xml – which are the values you show to the user in your tool! - are the same values as specified in the c-code. There is no other way to be sure except for setting the values yourself.

The current GUID of the ModelDescription.xml is no proper means for checking the correctness. And providing a kind of hash value based on the GUID in future versions for the ModelDescription.xml is not a good option. Firstly it is unnecessarily complicated (not mentioning that the GUID is actually part of the ModelDescription.xml you like to create a hash value for) as well as a source of importing errors and secondly please see next point.

From a user’s perspective:
In my view is the separation of model description and model code a big advantage of FMI and we should not artificially limit the potentials of that approach. Not only related to “start” values but related to many values of the ModelDescription.xml file. There is a good reason why there are tools in the market that support the editing of the ModelDescription.xml file. The reason is user demand!

If a model integrator in a company gets an FMU s/he usually has no access to the original model – may it be because it comes from a different department or from a 3rd-party supplier. The process of getting a new version of that FMU is in most cases very cumbersome and expensive and time consuming! Many typical everyday integration problems can be solved straightforwardly by editing the ModelDescription.xml. the FMU can transport the changes to the various importing tools s/he wants to use the FMU with. That is a great feature of the standardized separation of model code and model description!

In all the projects that used FMUs I worked in, the possibility to do such changes to the Modeldescription.xml really saved a lot of time and even solved compatibility issues between tools.

So I am strongly in favor of exploiting this advantage of FMI instead of eliminating it. If someone changes the original ModelDescription.xml it is in his/her responsibility to check the results.

Thus I vote for changing the sentence on page 53 in brackets to [Calling fmi2SetXXX to set start values during initialization is nevertheless recommended for all available start values in the xml file, since these values may have been altered due to user intervention.]

Best regards
Andreas

[modelica-trac-importer]

Modified by apillekeit on 8 Jun 2017 11:40 UTC

[modelica-trac-importer]

Comment by cbertsch on 11 Jun 2018 10:45 UTC
(FCP Alignment Meeting)
It is recommended to use SSP for changed parameter sets and not to demand from importing tools to use the values of the XML.

[KarlWernersson]

Closing this for FMI 2.0.1
It is clear that this is not allowed and the implication if you do it is also clear (the start values are not correct and you cannot assume that the importer will set them). No clarification is needed and changing the definition is not an option for 2.0.1.

Please reopen for 3.0 if it is relevant there.

[chrbertsch]

As a lot of tools and users have done this forbidden action of modifying the modeldescription.xml file, I still think that one should add an explicit warning to FMI 2.0.1 not to do so. (Perhaps with a NOTE: as a further non-normative explanation.
This would also be a good point for an (non-normative) Implementers Guide in form of a Wiki.

[chrbertsch]

As I have seen many people running in problems modifying start values in the FMU leading to unpredictable behaviour in different importing tools, I still recommend to include non-normative warning in FMI 2.0.1

I would change on p53 of FMI 2.0
[Therefore, calling fmi2SetXXX to set start values is only necessary, if a different value as stored in the xml file is desired.]
to
[Therefore, calling fmi2SetXXX to set start values is only necessary, if a different value as stored in the xml file is desired.
WARNING: One should not change the start value in the modeldescription.xml file of an FMU, as this would break the consistency with the hard-coded start values in the C-Code. This could lead to unpredictable behaviour of the FMU in different importing tools, as it is not mandatory to call fmi2SetXXX to set start values during initialization. Instead it is recommended to use the SSP Standard to handle modified parameters of FMUs or different parameter sets.]

[andreas-junghanns]

Your warning text explains this in a round-about way. The reason is that the modelDescription.xml is a way of documenting the C-code, not of influencing it. If we can make clear that, changing start values would be clearly useless. Can we find a good place where this should go?

[APillekeit]

I marked my suggested changes in bold. I see this as a recommendation, since nothing has been stated about this before in the documentation.
[Therefore, calling fmi2SetXXX to set start values is only necessary, if a different value as stored in the xml file is desired.
WARNING: It is not recommended to change the start values in the modelDescription.xml file of an FMU, as this would break the consistency with the hard-coded start values in the C-Code. This could lead to unpredictable behaviour of the FMU in different importing tools, as it is not mandatory to call fmi2SetXXX to set start values during initialization. Instead it is recommended to use the SSP Standard to handle modified parameters of FMUs or different parameter sets.]

[t-sommer]

Instead it is recommended to use the SSP Standard to handle modified parameters of FMUs or different parameter sets.

Should we really add advertisement for the SSP Standard in a maintenance release? There might be other equally good (or bad) means of managing parameters.

[chrbertsch]

Should we really add advertisement for the SSP Standard in a maintenance release? There might be other equally good (or bad) means of managing parameters.

As this is non-normative text, I do not consider this problematic.

I included the version proposed by @APillekeit in @KarlWernersson PR #579 so that it can be discussed there.

[vtoltrianee]

hi,

Comment by apillekeit on 26 Oct 2016 13:40 UTC
Dear all,

the rules for creating and also the meaning of the GUID are a bit vague in the FMI specification. So far I would agree with the other comments. But I disagree with the conclusion of illegalizing changes to the ModelDescription.xml.

From a tool’s perspective regarding start/guess values:
Referring to the sentence on page 53:_ “only necessary”_ doesn’t mean “only allowed”! So it is currentlyperfectly fine to read and set the start values from the ModelDescription.xml for an importing tool. As an importing toolI would do so in any case for consistency/safety reasons since you cannot be sure that the values in the Modeldescription.xml – which are the values you show to the user in your tool! - are the same values as specified in the c-code. There is no other way to be sure except for setting the values yourself.

The current GUID of the ModelDescription.xml is no proper means for checking the correctness. And providing a kind of hash value based on the GUID in future versions for the ModelDescription.xml is not a good option. Firstly it is unnecessarily complicated (not mentioning that the GUID is actually part of the ModelDescription.xml you like to create a hash value for) as well as a source of importing errors and secondly please see next point.

From a user’s perspective:
In my view is the separation of model description and model code a big advantage of FMI and we should not artificially limit the potentials of that approach. Not only related to “start” values but related to many values of the ModelDescription.xml file. There is a good reason why there are tools in the market that support the editing of the ModelDescription.xml file. The reason is user demand!

If a model integrator in a company gets an FMU s/he usually has no access to the original model – may it be because it comes from a different department or from a 3rd-party supplier. The process of getting a new version of that FMU is in most cases very cumbersome and expensive and time consuming! Many typical everyday integration problems can be solved straightforwardly by editing the ModelDescription.xml. the FMU can transport the changes to the various importing tools s/he wants to use the FMU with. That is a great feature of the standardized separation of model code and model description!

In all the projects that used FMUs I worked in, the possibility to do such changes to the Modeldescription.xml really saved a lot of time and even solved compatibility issues between tools.

So I am strongly in favor of exploiting this advantage of FMI instead of eliminating it. If someone changes the original ModelDescription.xml it is in his/her responsibility to check the results.

Thus I vote for changing the sentence on page 53 in brackets to [Calling fmi2SetXXX to set start values during initialization is nevertheless recommended for all available start values in the xml file, since these values may have been altered due to user intervention.]

Best regards
Andreas

Hi Andreas,
I tried to change the parameters in modelDescription.xml file, i'm new to fmi/fmusdk , i have some questions to ask you
as you mentioned in a line

In all the projects that used FMUs I worked in, the possibility to do such changes to the Modeldescription.xml really saved a lot of time and even solved compatibility issues between tools

what is the use of modelDescription.xml file?
what happens if we change the .xml file ? is it possible?
if possible what are the things we have to do?
if we change the .xml file what are the issues will occur?

i hope that you will reply soon......

thanks,
sharadha

[friedrichatgc]

I would simply say that it is NOT allowed to make changes in the modelDescription.xml file! The file is generated by the FMU creator and must map to the binary code. Violating this rule causes undefined behaviour!

[pmai]

As @friedrichatgc says, from the point of view of FMI, the modelDescription.xml is the description of the model for the importer to understand and handle the FMU properly. It is not for user-editing, parameter changes, etc. This should be handled in the way that the importing tool specifies.

For cross-platform purposes the SSP standard provides standardized ways of changing FMU parameters and transporting those changes between platforms.

While there are tools out there that enable "editing" of FMUs (we do sell such a tool, there are others), they have to support other ways than just editing of the modelDescription.xml to effect changes to FMU start values / parameters. Just changing their value in modelDescription.xml is not enough.

And I think that is as it should be, because the FMU as a whole should not be changed just to change parametrization.

[chrbertsch]

I would simply say that it is NOT allowed to make changes in the modelDescription.xml file! The file is generated by the FMU creator and must map to the binary code. Violating this rule causes undefined behaviour!

Do have to state this more pronouncedly in FMI 3.0?

Currently we have only "WARNING: It is not recommended to change the start values in the modelDescription.xml file of an FMU, as this would break the consistency with the hard-coded start values in the C-Code. This could lead to unpredictable behavior of the FMU in different importing tools, as it is not mandatory to call fmi3Set{VariableType} to set start values during initialization. Instead it is recommended to use the SSP Standard (https://ssp-standard.org/) to handle modified parameters of FMUs or different parameter sets."
in at the definiation of start attributes https://fmi-standard.org/docs/3.0-dev/#ModelStructure

We could state in https://fmi-standard.org/docs/3.0-dev/#fmu-distribution :
"It is NOT allowed to make changes in the modelDescription.xml file"

Anyway we cannot prevent people from doing forbidden things, but then they have to bear the consequences.

[andreas-junghanns]

I agree with Christian´s suggestion.

[nickbattle]

This is consistent with the formal modelling. We regard the modelDescription.xml as defining the static semantics of the FMU; the behaviour of the API calls is the dynamic semantics. The expectation is that the static semantics of the FMU does not change, while the dynamic behaviour, of course, is affected by the API call sequence (as well as the static configuration).