From eeda2c0ace7744d72cd9a483f9c595ecdc17714c Mon Sep 17 00:00:00 2001 From: "Pierre R. Mai" Date: Tue, 26 Mar 2024 16:55:56 +0100 Subject: [PATCH 1/3] Add FMI 3.0 native support --- doc/spec/binary_variables.adoc | 46 +++++++++++++++++++++++++++++++--- osmp.xsd | 1 + 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/doc/spec/binary_variables.adoc b/doc/spec/binary_variables.adoc index fa85c95..22c3453 100644 --- a/doc/spec/binary_variables.adoc +++ b/doc/spec/binary_variables.adoc @@ -6,16 +6,17 @@ endif::[] FMI 2.0 cite:[fmi2.0] does not directly support the efficient exchange of arbitrary binary data between FMUs. OSMP therefore introduces the concept of notional binary variables that are mapped to actual integer variables for use with FMI 2.0 cite:[fmi2.0]. -Future FMI versions will directly support binary variables compatible with this concept. + +For FMI 3.0 cite:[fmi3.0] and above these notional binary variables can be directly mapped into actual binary variables as specified below. A notional binary variable named `` is defined using the following conventions: -The name of the notional binary variable given by `` shall be a valid structured name according to FMI 2.0 cite:[fmi2.0]. +The name of the notional binary variable given by `` shall be a valid structured name according to FMI 2.0 cite:[fmi2.0] (or FMI 3.0 cite:[fmi3.0] for 3.0 FMUs). The FMU shall not contain any other variable that is named ``. This restriction ensures that there is no conflict between notional binary variables and actual variables. -For each notional binary variable, three actual FMU integer variables shall be defined: +For FMI 2.0, for each notional binary variable, three actual FMU integer variables shall be defined: `.base.lo`:: Lower, meaning the least significant, 32-bit address part of the binary data buffer to be passed into or out of the model, cast into a signed 32-bit integer without changing the bit values. @@ -71,3 +72,42 @@ This convention allows the use of FMUs in simulation engines that have no specia The simulation engine can rely on the provided buffer to remain valid from the moment it is passed out of a model until the end of the next co-simulation calculation cycle. Thus, the simulation engine does not need to copy the contents in that case, corresponding to zero-copy output for the simulation engine at the cost of double buffering for the model providing the output data. It is possible to daisy-chain FMUs with protocol buffer inputs and outputs in a normal simulation engine supporting FMI, and get valid results. + +== FMI 3.0 + +For FMI 3.0, each notional binary variable is mapped to an actual binary variable with the name `` and the causality and variability of the notional binary variable. + +The variable shall have a start value of length 0 (i.e. the empty binary), indicating that no valid binary data is available. +The variable may have a different or no start value if the combination of causality and variability precludes this, for example, for `@variability = fixed` or `@variability = tunable` and `@causality = calculatedParameter`. + +Model FMUs shall interpret empty binary values to indicate that no valid binary data is available. +Model FMUs shall handle this case safely. + +The actual binary variable shall contain an annotation of the following form in the `` child element of their `` element of the `modelDescription.xml`: + +[source,xml] +---- + +---- + +`` is the prefix as defined above. + +It is an error if there is not exactly one variable for the same name. + +The MIME type given in `@mime-type` shall be a valid MIME type specification. + +In the case of OSI-specified data, the MIME type shall have the following form to indicate that the binary content is conformant to the given OSI version and contains a message of the given type: + +[source,xml] +---- +application/x-open-simulation-interface; type=; version=x.y.z +---- + +`` shall be the name of an OSI top-level message, excluding the `osi3::` prefix. + +The version parameter of the MIME type `application/x-open-simulation-interface` will default to the version specified in the `@osi-version` attribute as part of the top-level `` annotation. +It is an error if a version number is specified neither as part of the MIME type nor using the `@osi-version` attribute. + +The guaranteed lifetime of the binary data transported through the actual variable is defined in the FMI 3.0 standard, **regardless** of any specifications in the following sections. + +Alternatively, for specific compatibility or other reasons, it is permissible, though not recommended, for an FMI 3.0 FMU to follow the FMI 2.0 approach as specified above. diff --git a/osmp.xsd b/osmp.xsd index 54e2d24..251ed72 100644 --- a/osmp.xsd +++ b/osmp.xsd @@ -23,6 +23,7 @@ + From 407e10b6abd220cc562a1e9a8280f1162e2025f1 Mon Sep 17 00:00:00 2001 From: "Pierre R. Mai" Date: Tue, 26 Mar 2024 17:08:05 +0100 Subject: [PATCH 2/3] Add to basic conventions --- doc/spec/basic_conventions.adoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/spec/basic_conventions.adoc b/doc/spec/basic_conventions.adoc index ba2ac44..dc587fb 100644 --- a/doc/spec/basic_conventions.adoc +++ b/doc/spec/basic_conventions.adoc @@ -27,3 +27,10 @@ A simulator can call the FMU `fmi2DoStep` routine at this implied rate. If the step size is not supplied, the model communication rate is determined from any input configuration data the model provides, or it must be configured manually. The model may have inputs, outputs, and parameters that are not specified by OSMP if the model can be run correctly with all of those variables left unconnected and at their default values. + +== FMI 3.0 + +Alternatively a model can be packaged as a valid FMU for co-simulation as specified in the FMI 3.0 standard cite:[fmi3.0]. +In this case, unless otherwise noted, all specifications in the FMI 3.0 cite:[fmi3.0] standard apply as-is. + +The provisions above for FMI 2.0 apply, with the provision that the annotation shall be placed into the `` element of the `modelDescription.xml`. From 87374df8a8c712807cc2294fe12a3308b90b0205 Mon Sep 17 00:00:00 2001 From: "Pierre R. Mai" Date: Thu, 4 Apr 2024 11:51:47 +0200 Subject: [PATCH 3/3] Apply suggestions from code review --- doc/spec/basic_conventions.adoc | 7 ++++++- doc/spec/binary_variables.adoc | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/spec/basic_conventions.adoc b/doc/spec/basic_conventions.adoc index dc587fb..5a89745 100644 --- a/doc/spec/basic_conventions.adoc +++ b/doc/spec/basic_conventions.adoc @@ -33,4 +33,9 @@ The model may have inputs, outputs, and parameters that are not specified by OSM Alternatively a model can be packaged as a valid FMU for co-simulation as specified in the FMI 3.0 standard cite:[fmi3.0]. In this case, unless otherwise noted, all specifications in the FMI 3.0 cite:[fmi3.0] standard apply as-is. -The provisions above for FMI 2.0 apply, with the provision that the annotation shall be placed into the `` element of the `modelDescription.xml`. +The rules above for FMI 2.0 apply, with the provision that the annotation shall be placed as an `` element into the `` element of the `modelDescription.xml`: + +[source,xml] +---- + +---- diff --git a/doc/spec/binary_variables.adoc b/doc/spec/binary_variables.adoc index 22c3453..2d48fda 100644 --- a/doc/spec/binary_variables.adoc +++ b/doc/spec/binary_variables.adoc @@ -87,7 +87,7 @@ The actual binary variable shall contain an annotation of the following form in [source,xml] ---- - + ---- `` is the prefix as defined above.