Merge pull request #1887 from modelica/main

Merge main into v3.0.x

.github/workflows/build-spec.yml

@@ -15,7 +15,7 @@ on:
 jobs:
 
   build-code-snippets:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
     steps:
 
     - uses: actions/checkout@v3

docs/1___overview.adoc

@@ -55,6 +55,11 @@ Parallel to the new standard features, the FMI Design Community has improved the
 
 * integrating within the FMI Standard only validated C-code, XML and XSD snippets to reduce redundancy and ensure correctness.
 
+
+==== Changes in FMI 3.0.1 [[fmi-301]]
+
+Clarifications and fixes in FMI 3.0.1 are listed in the https://github.com/modelica/fmi-standard/releases[Release notes on Github.]
+
 === Overview
 
 The Functional Mock-up Interface (FMI) defines a ZIP archive and an application programming interface (API) to exchange dynamic models using a combination of XML files, binaries and C code: the Functional Mock-up Unit (FMU).

docs/2_2_common_mechanisms.adoc

@@ -289,7 +289,7 @@ The attribute <<causality>> defines the direction of the information flow with r
 Variables, except Clocks, may be scalar or multi-dimensional arrays.
 Clocks must always be scalar.
 
-===== Serialization of Array Variables [[serialization-of_variables]]
+===== Serialization of Array Variables [[serialization-of-variables]]
 
 Array variables in C-API and <<modelDescription.xml>> (i.e. <<start>> attribute) are serialized as row major.
 The order of dimensions is defined as follows:
@@ -332,6 +332,7 @@ _]_
 
 For this serialization of array variables the sparsity pattern of the array is not taken into account.
 All elements of the array, including structural zeros, are serialized.
+If an API function takes multiple value references, the serialized variables are concatenated.
 
 ===== Getting and Setting Variable Values [[get-and-set-variable-values]]
 
@@ -354,7 +355,7 @@ include::../headers/fmi3FunctionTypes.h[tags=GetClock]
 
 * `valueReferences` is a vector of `nValueReferences` handles that reference the variables that shall be inquired.
 
-* `values` is a vector with the actual values of these variables.
+* `values` is a vector consisting of the <<serialization-of-variables,serialized>> values of these variables.
 
 * `valueSizes` is a vector with the actual sizes of the values for binary variables.
 
@@ -376,7 +377,7 @@ include::../headers/fmi3FunctionTypes.h[tags=SetClock]
 
 * `valueReferences` is a vector of `nValueReferences` handles that reference the variables that shall be set.
 
-* `values` is a vector with the actual values of these variables.
+* `values` is a vector consisting of the <<serialization-of-variables,serialized>> values of these variables.
 
 * `valueSizes` is a vector with the actual sizes of the values of binary variables.
 
@@ -999,7 +1000,7 @@ This function returns the dependency information for a single variable.
 * `elementIndicesOfDependent` must point to a buffer of `size_t` values of size `nDependencies` allocated by the calling environment.
 It is filled in by this function with the element index of the dependent variable that dependency information is provided for.
 The element indices start with 1. Using the element index 0 means all elements of the variable.
-(Note: If an array has more than one dimension the indices are serialized in the same order as defined for values in <<serialization-of_variables>>.)
+(Note: If an array has more than one dimension the indices are serialized in the same order as defined for values in <<serialization-of-variables>>.)
 
 * `independents` must point to a buffer of <<fmi3ValueReference>> values of size `nDependencies` allocated by the calling environment.
 It is filled in by this function with the value reference of the <<independent>> variable that this dependency entry is dependent upon.
@@ -1008,7 +1009,7 @@ It is filled in by this function with the value reference of the <<independent>>
 It is filled in by this function with the element index of the <<independent>> variable that this dependency entry is dependent upon.
 The element indices start with 1.
 Using the element index 0 means all elements of the variable.
-(Note: If an array has more than one dimension the indices are serialized in the same order as defined for values in <<serialization-of_variables>>.)
+(Note: If an array has more than one dimension the indices are serialized in the same order as defined for values in <<serialization-of-variables>>.)
 
 * `dependencyKinds` must point to a buffer of <<dependenciesKind>> values of size `nDependencies` allocated by the calling environment.
 It is filled in by this function with the enumeration value describing the dependency of this dependency entry.
@@ -1166,9 +1167,9 @@ Both functions have the same arguments:
 * `nUnknowns` contains the length of argument `unknowns`.
 * `knowns` contains value references of the knowns.
 * `nKnowns` contains the length of argument `knowns`.
-* `seed` contains the components of the seed vector.
+* `seed` contains the <<serialization-of-variables,serialized>> components of the seed vector.  
 * `nSeed` contains the length of `seed`.
-* `sensitivity` contains the components of the sensitivity vector.
+* `sensitivity` contains the <<serialization-of-variables,serialized>> components of the sensitivity vector.
 * `nSensitivity` contains the length of `sensitivity`.
 
 _[Note that array variables will be serialized, so `nSeed` is only equal to `nKnowns` in the case of directional derivatives (resp., equal to `nUnknowns` in the case of adjoint derivatives) if all value references of `knowns` (resp., `unknowns`) point to scalar variables._

docs/2_3_common_states.adoc

@@ -98,7 +98,6 @@ Only in this case, <<fmi3DoStep>> may return with <<earlyReturn,`earlyReturn = f
 This set may be empty (<<nRequiredIntermediateVariables>> = 0) when the simulation algorithm does not intend to use intermediate update.
 Only the variables in <<requiredIntermediateVariables>> may be accessed by the simulation algorithm using <<get-and-set-variable-values,`fmi3Set{VariableType}`>> and <<get-and-set-variable-values,`fmi3Get{VariableType}`>> during <<IntermediateUpdateMode>>.
 All variables referenced in this set must be marked with the attribute <<intermediateUpdate,`intermediateUpdate = "true"`>> in <<modelDescription.xml>>.
-For Co-Simulation, these intermediate variables must be continuous-time variables.
 
 * [[nRequiredIntermediateVariables,`nRequiredIntermediateVariables`]] `nRequiredIntermediateVariables` gives the number of entries in <<requiredIntermediateVariables>>.
 If <<nRequiredIntermediateVariables>> is zero <<requiredIntermediateVariables>> is not defined.

docs/2_4_common_schema.adoc

@@ -252,7 +252,7 @@ _If more space is required, the folder <<license-information,`licenses`>> should
 |Optional date and time when the XML file was generated.
 The format is a subset of `dateTime` and should be: `YYYY-MM-DDThh:mm:ssZ` (with one `T` between date and time; `Z` characterizes the Zulu time zone, in other words, Greenwich meantime) _[for example `2009-12-08T14:33:22Z`, according to ISO 8601]_.
 
-|[[variableNamingConvention,`Convention`]]<<variableNamingConvention>>
+|[[variableNamingConvention,`variableNamingConvention`]]`variableNamingConvention`
 |Defines whether the variable names in <<ModelVariables>> and in `<TypeDefinitions>` follow the `flat` or `structured` convention as defined in <<namingSection>>.
 
 |====
@@ -1026,11 +1026,12 @@ _Therefore, such an <<input>> should not appear in an algebraic loop.]_
 |
 [[intermediateUpdate,`intermediateUpdate`]]
 If this boolean attribute is `true`, the variable can be accessed in <<IntermediateUpdateMode>>.
-Variables with <<causality>> = <<parameter>> must not be marked with <<intermediateUpdate,`intermediateUpdate = true`>>.
+Only continuous-time variables can have <<intermediateUpdate,`intermediateUpdate = true`>>.
+The default value of this attribute is `false`.
 
-This attribute is ignored in Model Exchange and Scheduled Execution.
 Variables of type <<Clock>> must not have the <<intermediateUpdate>> attribute.
-The default value of this attribute is `false`.
+
+This attribute is ignored in Model Exchange and Scheduled Execution.
 
 |`previous`
 a|
@@ -1361,7 +1362,7 @@ _It is not allowed to change the start values in the <<modelDescription.xml>> fi
 _This could lead to unpredictable behavior of the FMU in different importers, as it is not mandatory to call <<get-and-set-variable-values,`fmi3Set{VariableType}`>> to set <<start>> values during initialization.]_
 
 The <<start>> attribute is either a single value or a list of values.
-The serialization of a multi-dimensional array variable is described in <<serialization-of_variables>>.
+The serialization of a multi-dimensional array variable is described in <<serialization-of-variables>>.
 If only a single value is given for a multi-dimensional array, all values of the multi-dimensional array are equal to this value.
 
 For variables of type `<String>` and `<Binary>`, the start values are not given as a list in the `start` attribute but as a sequence of `<Start>` elements with a `value` attribute.
@@ -1743,9 +1744,9 @@ The following <<dependenciesKind>> is only allowed for floating point latexmath:
 
 ==== Terminals and Icons [[fmiTerminalsAndIcons]]
 
-Terminals define semantic groups of variables to ease connecting compatible signals on the system level.
+Terminals define semantic groups of variables.
 This definition adds an additional layer to the interface description of the FMUs.
-It does not change the <<causality>> of the variables (i.e. inputs and outputs), but enables the definition of physical and bus-like  connectors that require special handling on the system level by the importer (e.g. flow variables and bus frames).
+It does not change the <<causality>> of the variables (e.g. inputs will remain inputs, outputs will remain outputs, and parameters will remain parameters) but enables the definition of physical and bus-like connectors and variable groups that require special handling on the system level by the importer (e.g. flow variables and bus frames).
 Icons define a graphical representation of an FMU and its terminals.
 
 Both features are optional and may be defined in the separate XML file `terminalsAndIcons/terminalsAndIcons.xml`. +
@@ -1773,7 +1774,7 @@ If used in previous FMI versions, this attribute points to the FMI version defin
 |If present, contains information for importers of FMUs to draw graphical representations of the FMU in a system view.
 
 |`<Terminals>`
-|If present, this allows combining variables (e.g. inputs, outputs and parameters) into logical groups to ease connections on a system level and add semantic information required for system-level connections.
+|If present, this allows combining variables (e.g. inputs, outputs and parameters) into logical groups, e.g.,  to ease connections on a system level and add semantic information required for system-level connections.
 |====
 
 ===== Definition of a Graphical Representation [[graphicalRepresentation]]
@@ -1861,12 +1862,12 @@ Terminals are fully optional and can be ignored by any importer.
 A terminal is:
 
 * a structured interface for connections to other models,
-* intended to be used for signal flow between models, parameter propagation, and compatibility checks of the model configuration, and
-* a sequence of references to variables with connection meta data.
+* intended to be used for signal flow between models, parameter grouping and propagation, and compatibility checks of the model configuration, and
+* a sequence of references to variables with connection and other meta data.
 
 Predefined rules for variable matching in a connection are given in <<table-predefined-matching-rules>>.
 Predefined variable kinds are used to describe how the terminal member variables have to be handled.
-Domain specific connection rules, terminals and their member variables can be provided by other standards.
+Domain specific connection rules, terminals and their member variables can be provided by other standards, including layered standards.
 
 _[Algebraic loops in systems of connected FMUs are not addressed or resolved by the terminals._
 _The FMU standard does not require that the <<causality>> of the terminal member variables in connected terminals match._
@@ -1959,6 +1960,7 @@ The normalized string `variableKind` is used to provide general information abou
 This information defines how the connection of this variable has to be implemented (e.g. Kirchhoff's current law or common signal flow).
 
 The predefined `variableKind` are:
+
 .Predefined kinds of variables.
 [[table-variable-kinds]]
 [cols="1,3",options="header"]
@@ -2212,6 +2214,8 @@ image::images/schema/SourceFileSet.png[width=60%]
 |The compiler flags that have to be used when compiling the sources (e.g. `-fno-rtti`, `/Od`)
 |====
 
+_[Please refer to the https://modelica.github.io/fmi-guides/main/fmi-guide/[FMI Implementer's Guide] for lists of commonly agreed upon language and compiler names.]_
+
 ===== SourceFile [[SourceFile,`<SourceFile>`]]
 
 .`SourceFileSet` element.

docs/2_5_fmu_distribution.adoc

@@ -4,15 +4,16 @@ An FMU consists of several files, that are stored in a ZIP file with a pre-defin
 The implementation of the FMI C-API may be distributed in source code and/or in binary format.
 The FMU must be distributed with at least one implementation, in other words, either sources or one of the binaries for a particular machine.
 It is also possible to provide the sources and binaries for different target machines together in one ZIP file.
-The FMU must implement all common API functions according to <<general-mechanisms>> and the functions for at least one of the interface types.
-Especially it is required that all functions that are part of the specified interface type are present, even if they are only needed for optional capabilities that the FMU does not support.
-The behavior of those functions is unspecified, so while calling environments can rely on the functions being present, they cannot rely on any particular behavior for functions only needed for capabilities the FMU does not support.
+The FMU must implement all API functions declared in `fmi3Functions.h`, even if they are only needed for interface types or optional capabilities that the FMU does not support.
+The behavior of those functions is unspecified, so while calling environments can rely on the functions being present, they cannot rely on any particular behavior for functions only needed for capabilities or interface types the FMU does not support.
+_[The recommended implementation for such stub functions is to return `fmi3Error` after logging the error reason, as specified in <<status-returned-by-functions>>.
+Calling environments should not rely on the presence of functions that are not required and avoid calling them.]_
 Additional functions may be present in the FMU, as for example required by the OS ABI, for layered standards, or future FMI versions.
 All symbols starting with the prefix `fmi3` are reserved for use in future minor releases of FMI 3.0.
 The extension of the ZIP file must be `.fmu` _[, for example, `HybridVehicle.fmu`]_.
-The compression method for all files stored in the ZIP archive must be either 8 (`deflate`), or 0 (`store`).
-Only files stored using compression method 8 (`deflate`) may be stored with general purpose bit 3 set.
-The field `version needed to extract` of the archive must not be higher than 2.0, and encryption must not be employed.
+The compression method for all files stored in the ZIP archive must be either `8` (deflate) or `0` (store).
+Only files stored using compression method `8` (deflate) may be stored with general purpose bit `3` set.
+The field `version needed to extract` of the archive must not be higher than `2.0` and encryption must not be employed.
 The archive must not be a split or spanned ZIP archive.
 Links must not be used inside the ZIP archive.
  _[These restrictions ensure broad compatibility of the archive with common ZIP processing tools and libraries.)]_

docs/3_2_model_exchange_api.adoc

@@ -93,7 +93,7 @@ Set new continuous state values.
 +
 * Argument `continuousStates` contains the new values for each <<state,continuous state>>.
 The order of the `continuousStates` vector must be the same as the ordered list of elements <<ContinuousStateDerivative>> in <<ModelStructure>>.
-Array variables are serialized as defined in <<serialization-of_variables>>.
+Array variables are serialized as defined in <<serialization-of-variables>>.
 This order is also used in the arguments of the following functions: <<fmi3GetNominalsOfContinuousStates>>, <<fmi3GetContinuousStates>>, and <<fmi3GetContinuousStateDerivatives>>.
 +
 * Argument `nContinuousStates` is the size of the `continuousStates` vector.

docs/4_1_co-simulation_math.adoc

@@ -40,8 +40,8 @@ If multiple derivatives of a variable shall be retrieved, list the value referen
 * `orders` contains the orders of the respective <<derivative>> (1 means the first <<derivative>>, 2 means the second <<derivative>>, ..., 0 is not allowed).
 If multiple derivatives of a variable shall be retrieved, its value reference must occur multiple times in `valueReferences` aligned with the corresponding `orders` array.
 
-* `values` is a vector with the values of the <<derivative,`derivatives`>>.
-The order of the `values` elements is derived from a twofold serialization: the outer level corresponds to the combination of a value reference (e.g., `valueReferences[k]`) and order (e.g., `orders[k]`), and the inner level to the serialization of variables as defined in <<serialization-of_variables>>.
+* `values` is a vector consisting of the <<serialization-of-variables,serialized>> values of these <<derivative,`derivatives`>:
+The order of the `values` elements is derived from a twofold serialization: the outer level corresponds to the combination of a value reference (e.g., `valueReferences[k]`) and order (e.g., `orders[k]`), and the inner level to the serialization of variables as defined in <<serialization-of-variables>>.
 The inner level does not exist for scalar variables.
 
 * `nValues` is the size of the argument `values`.

docs/7___appendix.adoc

@@ -280,7 +280,7 @@ Since Sept. 2012 until Nov. 2015, this work is partially carried out within the
 == Contributors
 
 The Modelica Association Project FMI was headed by Andreas Junghanns (Synopsys) and Torsten Blochwitz (ESI Group).
-The FMI 3.0 standard text is based on FMI 2.0 and FMI 1.0 and we wish to acknowledge their contributors.
+The FMI 3.0.x standard text is based on FMI 2.0 and FMI 1.0 and we wish to acknowledge their contributors as listed on https://github.com/modelica/fmi-standard/graphs/contributors[Github].
 
 Special thanks to