All static information related to an FMU is stored in the text file modelDescription.xml in XML format.
Especially, the FMU variables and their attributes such as name, unit, default initial value, etc. are stored in this file.
It is not allowed to change the modelDescription.xml file.
[Reason: The modelDescription.xml file has to be consistent with the binary or source code implementations.
Specifically, changes to the start values are not allowed.]
The structure of this XML file is defined with the schema file fmi3ModelDescription.xsd.
This schema file utilizes several helper schema files.
In this section these schema files are discussed.
The normative definition are the above mentioned schema files.
Below, optional elements are marked with a dashed box.
The required data types (like: xs:normalizedString) are defined in XML Schema Part 2: Datatypes Second Edition.
The types used in the FMI schema files are:
XML |
Description (http://www.w3.org/TR/xmlschema-2/) |
Mapping to C |
|
IEEE 754 double-precision 64-bit floating point type [An IEEE 754 double-precision floating point value can have up to 17 significant digits in its decimal representation. In order to not loose precision, either an appropriate minimal printer algorithm should be used, or alternatively a number of this type should be stored in XML files with at least 17 significant digits.] |
|
|
IEEE 754 single-precision 32-bit floating point type [An IEEE 754 single-precision floating point value can have up to 9 significant digits in its decimal representation. In order to not loose precision, either an appropriate minimal printer algorithm should be used, or alternatively a number of this type should be stored in XML files with at least 9 significant digits.] |
|
|
Integer number with maximum value 127 and minimum value -128 (8 bit signed integer) |
|
|
Integer number with maximum value 255 and minimum value 0 (8 bit unsigned integer) |
|
|
Integer number with maximum value 32767 and minimum value -32768 (16 bit signed integer) |
|
|
Integer number with maximum value 65535 and minimum value 0 (16 bit unsigned integer) |
|
|
Integer number with maximum value 2147483647 and minimum value -2147483648 (32 bit signed integer) |
|
|
Integer number with maximum value 4294967295 and minimum value 0 (32 bit unsigned integer) |
|
|
Integer number with maximum value 9223372036854775807 and minimum value -9223372036854775808 (64 bit signed integer) |
|
|
Integer number with maximum value 18446744073709551615 and minimum value 0 (64 bit unsigned integer) |
|
|
Boolean number. Legal literals: |
|
|
Any number of characters |
|
|
String without carriage return, line feed, and tab characters |
|
|
Arbitrary hex-encoded binary data |
|
|
Date, time and time zone (for details see the link above).
Example: |
tool specific |
The first line of an XML file, such as modelDescription.xml, must contain the encoding scheme of the XML file.
It is required that the encoding scheme is always UTF-8:
link:examples/co_simulation.xml[role=include]The FMI schema files (fmi3*.xsd) are also stored in UTF-8.
[Note that the definition of an encoding scheme is a prerequisite in order for the XML file to contain letters outside of the 7 bit ANSI ASCII character set, such as German umlauts, or Asian characters.
Furthermore, note the FMI calling interface requires that strings are encoded in UTF-8.
Since the XML files are also required to be encoded in UTF-8, string variables need not to be transformed when reading from the XML files in to C string variables.].
The special values NaN, +INF, -INF for variables values are not allowed in the FMI XML files.
[Note that child information items, such as elements in a sequence are ordered lists according to document order, whereas attribute information items are unordered sets (see http://www.w3.org/TR/XML-infoset/#infoitem.element).
The FMI schema is based on ordered lists in a sequence and therefore parsing must preserve this order.
For example, the information stored in <ModelVariables><Derivative> is only correct if this property is fulfilled.]
This is the root-level schema file and contains the following definition (the figure below contains all elements in the schema file. Data is defined by attributes to these elements):
On the top level, the schema consists of the following elements (see figure above).
[Note that elements <ModelVariables> and <ModelStructure> are mandatory, whereas <UnitDefinitions>, <TypeDefinitions>, <LogCategories>, <DefaultExperiment>, and <VendorAnnotation> are optional.
If an optional element is present and defines a list (such as <UnitDefinitions>), the list must have at least one element (such as <Unit>).]
| Element-Name | Description |
|---|---|
|
If present, the FMU is based on FMI for Model Exchange [(in other words, the FMU includes the model or the communication to a tool that provides the model, and the environment provides the simulation engine)]. |
|
If present, the FMU is based on FMI for Co-Simulation [(in other words, the FMU includes the model and the simulation engine, or a communication to a tool that provides the model and the simulation engine, and the environment provides the master algorithm to run coupled FMU Co-Simulation slaves together)]. |
|
A global list of unit and display unit definitions [for example, to convert display units into the units used in the model equations].
These definitions are used in the XML element |
|
A global list of type definitions that are utilized in |
|
A global list of log categories that can be set to define the log information that is supported from the FMU. |
|
Providing default settings for the integrator, such as stop time and relative tolerance. |
|
Additional data that a vendor might want to store and that other vendors might ignore. |
|
The central FMU data structure defining all variables of the FMU that are visible/accessible via the FMU functions. |
|
Defines the structure of the model.
Especially, the ordered lists of |
At least one element of ModelExchange or CoSimulation must be present to identify the type of the FMU.
If both elements are defined, different types of models are included in the FMU.
The details of these elements are defined in [ModelExchange] and [fmi-for-basic-co-simulation].
The XML attributes of fmiModelDescription are:
| Attribute-Name | Description |
|---|---|
|
Version of FMI for Model Exchange or FMI for Co-Simulation that was used to generate the XML file.
The value for this version is [During development prototype FMU implementations can indicate compliance with a certain development version based on the tags available at https://github.com/modelica/fmi-standard/tags.
For example the value for the FMI 3.0 Alpha 2 release is |
|
The name of the model as used in the modeling environment that generated the XML file, such as |
|
The instantiationToken is a string that can be used by the FMU to check that the XML file is compatible with the implementation of the FMU.
For this purpose the importing tool must pass the instantiationToken from the |
|
Optional string with a brief description of the model. |
|
Optional string with the name and organization of the model author. |
|
Optional version of the model [for example |
|
Optional information on the intellectual property copyright for this FMU [for example |
|
Optional information on the intellectual property licensing
for this FMU [for example |
|
Optional name of the tool that generated the XML file. |
|
Optional date and time when the XML file was generated.
The format is a subset of |
|
Defines whether the variable names in - - |
The BuildConfiguration provides the necessary information to compile and link the contained sources of the model into a dynamic library or as part of an executable.
| Attribute | Description |
|---|---|
modelIdentifier |
The |
platform |
Platform tuple of the platform the build configuration is intended for (e.g. |
description |
Description of the build configuration |
The �SourceFileSet element groups source files that can be compiled with the same compiler and compiler options. Every build configuration must contain at least one SourceFileSet.
| Attribute | Description |
|---|---|
language |
Language of the source files (e.g. |
compiler |
The compiler to compile the sources (e.g. |
compilerOptions |
The compiler flags that have to be used when compiling the sources (e.g. |
The PreprocessorDefinition element defines a preprocessor definition that needs to be passed to the compiler when compiling the source files in the SourceFileSet.
| Attribute | Description |
|---|---|
|
Name of the preprocessor definition |
|
Value of the preprocessor definition |
|
Determines wether the definition is optional (default is |
|
Description of the preprocessor definition |
The Option element defines a possible value for the PreprocessorDefinition. If a PreprocessorDefinition contains Option elements, its default value must be contained in the options.
| Attribute | Description |
|---|---|
|
Value of the preprocessor definition option |
|
Description of the preprocessor definition option |
The IncludeDirectory element defines the include directories that need to be passed to the compiler when compiling the source files in the SourceFileSet.
| Attribute | Description |
|---|---|
|
Path of the include directory relative to the |
The Library element defines a static library required to link the model binary.
| Attribute | Description |
|---|---|
|
Name of the library |
|
Version specifier of the library as defined in PEP 440.
The characters |
|
Boolean attribute that determines wether the library is contained in the |
|
Description of the library definition option |
[In this section, the units of the variables are (optionally) defined. Unit support is important for technical systems since otherwise it is very easy for errors to occur. Unit handling is a difficult topic, and there seems to be no method available that is really satisfactory for all applications, such as unit check, unit conversion, unit propagation or dimensional analysis. In FMI, a pragmatic approach is used that takes into account that every software system supporting units has potentially its own specific technique to describe and utilize units. The approach used here is slightly different than FMI 1.0 to reduce the need for standardized string representations.]
Element UnitDefinitions of fmiModelDescription is defined as:
It consists of zero or more Unit definitions.
[If no units are defined, element <UnitDefinitions> must not be present.
If 1 or more units are defined, this element must be present.]
A Unit is defined by its name attribute such as N.m or N*m or Nm, which must be unique with respect to all other defined elements of the UnitDefinitions list.
If a variable is associated with a Unit, then the value of the variable has to be provided with the fmi3Set{VariableType} functions or else is returned by the fmi3Get{VariableType} functions with respect to this Unit.
[The purpose of the name is to uniquely identify a unit and, for example, use it to display the unit in menus or in plots.
Since there is no standard to represent units in strings, and there are different ways how this is performed in different tools, no specific string representation of the unit is required.]
Optionally, a value given in unit Unit can be converted to a value with respect to unit BaseUnit utilizing the conversion factor and offset attributes:
Besides factor and offset, the BaseUnit definition consists of the exponents of the 7 SI base units kg, m, s, A, K, mol, cd, and of the exponent of the SI derived unit rad.
[Depending on the analysis/operation carried out, the SI derived unit rad is or is not utilized, see discussion below.
The additional rad base unit helps to handle the often occurring quantities in technical systems that depend on an angle.]
A value with respect to Unit (abbreviated as Unit_value) is converted with respect to BaseUnit (abbreviated as BaseUnit_value) by the equation:
BaseUnit_value = factor * Unit_value + offset
[For example, if \(\color{blue}{p_{bar}}\) is a pressure value in unit bar, and \(\color{blue}{p_{Pa}}\) is the pressure value in BaseUnit, then
\(\color{blue}{p_{Pa} = 10^5 p_{bar}}\)
and therefore, factor = 1.0e5 and offset = 0.0.
In the following table several unit examples are given (Note that if in column exponents the definition "\(\color{blue}{kgm^2 / s^2}\)" is present, then the attributes of BaseUnit are: kg=1, m=2, s=-2):
Quantity |
Unit.name |
Unit.BaseUnit |
||
exponents |
factor |
offset |
||
Torque |
|
\(\color{blue}{kg \cdot m^2 / s^2}\) |
|
|
Energy |
|
\(\color{blue}{kg \cdot m^2 / s^2}\) |
|
|
Pressure |
|
\(\color{blue}{\frac{kg}{m \cdot s^2}}\) |
|
|
Angle |
|
|
|
|
Angular velocity |
|
|
|
|
Angular velocity |
|
|
|
|
Frequency |
|
|
|
|
Temperature |
|
|
|
|
Per cent by length |
|
|
|
|
Parts per million |
|
|
|
|
Length |
|
|
|
|
Length |
|
|
|
|
Note that Hz is typically used as Unit.name for a frequency quantity, but it can also be used as DisplayUnit for an angular velocity quantity (since revolution/s).]
The BaseUnit definitions can be utilized for different purposes (the following application examples are optional and a tool may also completely ignore the Unit definitions):
- Signal connection check
-
When two signals v1 and v2 are connected together, and on at least one of the signals no
BaseUnitelement is defined, then the connection equation "v2 = v1" holds (if v1 is anoutputof an FMU and v2 is aninputof another FMU, withfmi3Get{VariableType}the value of v1 is inquired and used as value for v2 by callingfmi3Set{VariableType}).When two signals v1 and v2 are connected together, and for both of them
BaseUnitelements are defined, then they must have identical exponents of theirBaseUnit. Iffactorandoffsetare also identical, again the connection equationv2 = v1holds. Iffactorandoffsetare not identical, the tool may either trigger an error or, if supported, perform a conversion; in other words, use the connection equation (in this case therelativeQuantityof theTypeDefinition, see below, has to be taken into account in order to determine whetheroffsetshall or shall not be utilized):factor(v1) * v1 + offset(v1) = factor(v2) * v2 + offset(v2)As a result, wrong connections can be detected (for example, connecting a force with an angle signal would trigger an error) and conversions between, say, US and SI units can be either automatically performed or, if not supported, an error is triggered as well.
[Note that this approach is not satisfactory for variables belonging to different quantities that have, however, the same
BaseUnit, such as quantitiesEnergyandTorque, orAngularVelocityandFrequency. To handle such cases, quantity definitions have to be taken into account (seeTypeDefinitions) and quantity names need to be standardized.]This approach allows a general treatment of units, without being forced to standardize the grammar and allowed values for units (for example, in FMI 1.0, a unit could be defined as
N.min one FMU and asN*min another FMU, and a tool would have to reject a connection, since the units are not identical. In FMI 2.0, the connection would be accepted, provided both elements have the sameBaseUnitdefinition). - Dimensional analysis of equations
-
In order to check the validity of equations in a modeling language, the defined units can be used for dimensional analysis, by using the
BaseUnitdefinition of the respective unit. For this purpose, theBaseUnitradhas to be treated as1. Example:\[\begin{align*} J \cdot \alpha = \tau \rightarrow [kg.m^2]*[rad/s^2] = [kg.m^2/s^2] & \quad \text{// o.k. ("rad" is treated as "1")} \\ J \cdot \alpha = f \rightarrow [kg.m^2]*[rad/s^2] = [kg.m/s^2] & \quad \text{// error, since dimensions do not agree} \end{align*}\] - Unit propagation
-
If unit definitions are missing for signals, they might be deduced from the equations where the signals are used. If no unit computation is needed,
radis propagated. If a unit computation is needed and one of the involved units hasradas aBaseUnit, then unit propagation is not possible. Examples:-
a = b + c, and
Unitof c is provided, but notUnitof a and b:
The Unit definition ofc(in other words,Unit.name,BaseUnit,DisplayUnit) is also used foraandb. For example, if BaseUnit(c) =rad/s, then BaseUnit(a) = BaseUnit(b) =rad/s. -
a = b*c, and
Unitof a and of c is provided, but notUnitof b:
Ifradis either part of theBaseUnitofaand/or ofc, then theBaseUnitofbcannot be deduced (otherwise it can be deduced). Example: IfBaseUnit(a) = kg.m/s2andBaseUnit(c) = m/s2, then theBaseUnit(b) can be deduced to be `kg. In such a caseUnit.nameof b cannot be deduced from theUnit.nameofaandc, and a tool would typically construct theUnit.nameofbfrom the deducedBaseUnit.
-
]
Additionally to the unit definition, optionally a set of display units can be defined that can be utilized for input / output of a value:
A DisplayUnit is defined by name, factor and offset.
The attribute name must be unique with respect to all other names of the DisplayUnit definitions of the same Unit [(different Unit elements may have the same DisplayUnit names)].
A value with respect to Unit (abbreviated as Unit_value) is converted with respect to DisplayUnit (abbreviated as DisplayUnit_value) by the equation:
DisplayUnit_value = factor * Unit_value + offset
[offset is, for example, needed for temperature units.]
[For example, if \(\color{blue}{T_K}\) is the temperature value of Unit.name (in K) and \(\color{blue}{T_F}\) is the temperature value of DisplayUnit (in °F), then
and therefore, factor = 1.8 (=9/5) and offset = -459.67 (= 32 - 273.15*9/5).
Both the DisplayUnit.name definitions as well as the Unit.name definitions are used in the variable elements.
Example of a definition:
link:examples/unit_definition.xml[role=include]]
The schema definition is present in a separate file fmi3Unit.xsd.
Element TypeDefinitions of fmiModelDescription is defined as:
This element consists of a set of SimpleType definitions according to schema fmi3SimpleType in file fmi3Type.xsd.
One SimpleType has a type name and description as attributes.
Attribute name must be unique with respect to all other elements of the TypeDefinitions list.
Furthermore, name of a SimpleType must be different to all name attributes of variables [if the same names would be used, then this would nearly always give problems when importing the FMU in an environment such as Modelica, where a type name cannot be used as instance name].
Additionally, one variable type element must be present.
Each variable type has its own attributes which can be consulted in the schema.
The following are representative examples:
These definitions are used as default values in variable elements [in order that, say, the definition of a Torque type does not have to be repeated over and over again].
The attributes and elements have the following meaning:
| Name | Description |
|---|---|
|
Physical quantity of the variable. [For example, |
|
Unit of the variable defined with |
Default display unit. The conversion to the |
|
|
Indicates the type of data passed as a binary.
Defaults to |
|
If this attribute is |
|
Minimum value of variable (variable value \(\geq\) |
|
Maximum value of variable (variable value \(\leq\) |
|
Nominal value of variable.
If not defined and no other information about the nominal value is available, then nominal = 1 is assumed. |
|
If |
Item |
Items of an enumeration has a sequence of |
[Attributes min and max can be set for variables of numeric type or Enumeration.
The question is how fmi3Set{VariableType}, fmi3Get{VariableType} shall utilize this definition.
There are several conflicting requirements:
Avoiding forbidden regions (for example, if u is an input and "sqrt(u)" is computed in the FMU, min = 0 on u shall guarantee that only values of u in the allowed regions are provided).
Numerical algorithms (ODE-solver, optimizers. nonlinear solvers) do not guarantee constraints.
If a variable is outside of the bounds, the solver tries to bring it back into the bounds.
As a consequence, calling fmi3Get{VariableType} during an iteration of such a solver might return values that are not in the defined min/max region.
After the iteration is finalized, it is only guaranteed that a value is within its bounds up to a certain numerical precision.
In debug mode checks on min/max should be performed.
For maximum performance on a real-time system the checks might not be performed.
The approach in FMI is therefore that min/max definitions are an information from the FMU to the environment defining the region in which the FMU is designed to operate.
The environment is free to utilize this information (typically, in debug mode of the environment the min/max is checked in the cases as stated above).
In any case, it is expected that the FMU handles variables appropriately where the region definition is critical.
For example, dividing by an input (so the input should not be in a small range of zero) or taking the square root of an input (so the input should not be negative) may either result in fmi3Error, or the FMU is able to handle this situation in other ways.
If the FMU is generated so that min/max shall be checked whenever meaningful (for example, for debug purposes), then the following strategy should be used:
If fmi3Set{VariableType} is called violating the min/max attribute settings of the corresponding variable, the following actions are performed:
If an FMU defines min/max values for integer types and Enumerations (local and output variables), then the expected behavior of the FMU is that fmi3Get{VariableType} functions return values in the defined range.
If an FMU defines min/max values for numeric types, then the expected behavior of the FMU is that fmi3Get{VariableType} returns values at the solution (accepted steps of the integrators) in the defined range with a certain uncertainty related to the tolerances of the numerical algorithms.]
Clocks are integrated in the element ModelVariables of fmiModelDescription as a variable element with the base type fmi3Clock.
The variable sub type fmi3Clock provides additional attributes for defining clocks.
| Attribute-Name | Description |
|---|---|
|
The type of |
|
The [For periodic
|
|
Clocks can be periodic or non-periodic. If a
|
|
If a periodic
|
|
The interval of
The initial tick of periodic
More information about clock intervals: [additional-clock-properties]. The attributes
|
Element LogCategories of fmiModelDescription is defined as:
LogCategories defines an unordered set of category strings that can be utilized to define the log output via function [logMessage], see [creation-destruction-and-logging].
A tool is free to use any normalizedString for a category value.
The name attribute of Category must be unique with respect to all other elements of the LogCategories list.
There are the following standardized names for Category and these names should be used if a tool supports the corresponding log category.
If a tool supports one of these log categories and wants to expose it, then an element Category with this name should be added to LogCategories [To be clear, only the Category names listed under LogCategories in the XML file are known to the environment in which the FMU is called.]
| Category name | Description |
|---|---|
|
Log all events (during initialization and simulation). |
|
Log the solution of linear systems of equations if the solution is singular (and the tool picked one solution of the infinitely many solutions). |
|
Log the solution of nonlinear systems of equations. |
|
Log the dynamic selection of |
|
Log messages when returning |
|
Log messages when returning |
|
Log messages when returning |
|
Log messages when returning |
|
Log all messages. |
The optional attribute description shall contain a description of the respective log category.
[Typically, this string can be shown by a tool if more details for a log category shall be presented.]
[This approach to define LogCategories has the following advantages:
-
A simulation environment can present the possible log categories in a menu and the user can select the desired one (in the FMI 1.0 approach, there was no easy way for a user to figure out from a given FMU what log categories could be provided).
Note that since elementLogCategoriesis optional, an FMU does not need to expose its log categories. -
The log output is drastically reduced, because via [fmi3SetDebugLogging] exactly the categories are set that shall be logged and therefore the FMU only has to print the messages with the corresponding categories to the [logMessage] function. In FMI 1.0, it was necessary to provide all log output of the FMU to the [logMessage] and then a filter in the [logMessage] could select what to show to the end-user. The approach introduced in FMI 2.0 is therefore much more efficient.]
Element DefaultExperiment of fmiModelDescription is defined as:
DefaultExperiment consists of the optional default start time, stop time, relative tolerance, and step size for the first simulation run.
A tool may ignore this information.
However, it is convenient for a user that startTime, stopTime, tolerance and stepSize have already a meaningful default value for the model at hand.
Furthermore, for Co-Simulation the stepSize defines the preferred communicationStepSize.
Terminals are fully optional and can be ignored by any importing tool.
Definition Terminal: 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
-
a sequence of references to variables with connection meta data
Predefined rules for variable matching in a connection are given below. Predefined variable kinds are used to describe how the member variables have to be handled. Domain specific connection rules, terminals and their member variables can be provided by other standards.
[Co-Simulation errors are not addressed by the terminals. The co-simulation algorithm has to be chosen and implemented by the importing tool. Features that might be required for specific co-simulation algorithms had to be implemented by the FMU exporting tool.
Algebraic loops in systems of connected Model Exchange FMUs are not addressed or resolved by the terminals.
It is not required that the causality of the terminal member variables in connected terminals match.
The SSP standard refers to a connectorKind.
This connectorKind is not related to the terminalKind or variableKind described in the following sections.]
Element Terminals of fmiModelDescription is defined as:
All instances of Terminal have the type fmi3Terminal and are listed in the Terminals sequence.
The normalized string attribute name of the Terminal element is the instance name of the terminal. The terminal name must be unique on each level.
The normalized string attribute matchingRule describes the rules for variable matching in a connection.
There are three predefined matching rules: plug, bus, and sequence.
Other standards may define new matching rules.
[It is recommended that vendor specific rules start with _vendorName or _toolName to avoid namespace clashes.]
There is a sequence of terminal member variables, terminal stream member variables, and nested terminals in the Terminal element.
The member variables are the exchanged variables.
The type of the nested terminals is fmi3Terminal, and they can be used to implement structured terminals.
The normalized string terminalKind is an optional attribute. Other standards may define terminal kinds.
It is intended that the terminalKind is used to define domain specific member variable sequences, member names and order, or high level restrictions for connections.
[Other terminal kinds should refer to the predefined matchingRules.
Vendor specific terminal kinds should start with _vendorName or _toolName to avoid namespace clashes.
Examples for terminalKind: StandardXXX_Mechanical_Translational, Modelica.Mechanics.Translational.Interfaces.Flange_a, vendorNameA_customTypeA, _vendorNameB_customLibrary_customTypeB.
The structured naming convention of the ModelVariables is independent from the terminal names and member variable names.
A tool may choose to connect terminals with a different or unknown terminalKind, if the matchingRule matches.]
The TerminalMemberVariable is defined as:
The normalized string variableKind is used to provide general information about the variable.
This information defines how the connection of this variable has to be implemented (e.g. Kirchhoff’s current law or common signal flow).
The normalized string memberName is the representation in tools which apply name-based matching in connections.
The member name has to be unique in a terminal.
The normalized string variableName is used to identify the terminal member variable in the list of ModelVariables.
[The name attribute of the model variable is equal to the variableName of the TerminalMemberVariable.
An importing tool may use the variableName attribute to identify a specific alias to get additional information, such as minimum, maximum, and nominal values.]
One variable can be part of several terminals.
[Tools which apply sequence based matching should also provide unique member names, so that all importing tools which use name based matching use the same member names.
The suggested variable naming scheme for the structured naming convention is <ModelVariable name> = <terminalName>.<memberName>.
Not all ModelVariables which have the prefix "<terminalName>." are a member variable, and there may exist member variables which don’t have this prefix.
Example 1 (suggested scheme): <ModelVariable name> is portA.U, <terminalName> is portA, <memberName> is U.
Example 2 (suggested scheme): <ModelVariable name> is hierarchConn.innerConn.U, <outer terminal name> is hierarchConn, <inner terminal name> is innerConn, <memberName> is U.
Example 3 (no prefix): <ModelVariable name> is u, <terminalName> is portA, <memberName> is u.
Example 4 (prefix but not a member): <ModelVariable name> is portA.u, there is a terminal with <terminalName> portA, but this variable is not a terminal member.
The suggested variable naming scheme for the non-structured naming convention is: <ModelVariable name> = <memberName>
Matching is not restricted by variability, causality or variable type.
Example: A fixed variable may be connected to a tunable variable, a variable of type fmi3Float64 may be connected to a variable of type fmi3Int32.
However, it is recommended that the variable types and variabilities are equal.
The matchingRule refers to the TerminalMemberVariables on the same level only. Nested terminals can have different matchingRules.
There is no special handling of derivatives.
If a derivative is a terminal member variable then it is considered as normal member variable.
However, if a derivative of a terminal member variable is not terminal member, then this derivative information may be used by an importing tool.]
The predefined variable kinds are:
| variableKind | Description |
|---|---|
|
The values in connected terminals are intended to be equal.
Restricted to |
|
Variables which fulfill Kirchhoff’s current law.
Restricted to |
[The signal variableKind can be applied for different use cases.
The first use case is a signal flow from an output of one FMU to an input of another FMU. The output value has to be forwarded to the input.
The signal flow can cause algebraic loops.
If variables in connected terminals have the causality output, then an importing tool may iterate an undefined input of an FMU to ensure that the connected output values are equal.
Another use case is the parameter propagation.
If a variable in both connected terminals has the causality parameter, then an importing tool could ask the user for the value of one of those parameters only, and propagate this value to the other FMU.
If only one of the variables has causality parameter, and the other is a constant output or calculatedParameter, then the importing tool could also propagate the parameter value without presenting a parameter to the user.
One example of use would be the name of a substance flowing through a pipe.
If the fluid flows from one pipe FMU to another, the substance should be the same.
This substance name could be propagated over several FMUs.
Finally the variableKind signal can be applied to implement compatibility checks.
If for example the variability of the variables in connected terminals are constant, then the importing tool can implement an equality assertion.
This is also possible with calculated parameters.
One example of use would be the cross sectional flow area in pipes which is calculated from geometry parameters.
A change in the cross sectional flow area is relevant for the momentum equation, and therefore the connection has to be deemed incompatible if these variables are present and unequal.]
[Flow variables have a direction and must fulfill a zero sum constraint i.e. the sum of all flow variables connected together must be zero (Kirchhoff’s current law).
In addition because different tools might have different direction definitions both, inflow and outflow variableKinds are available.
For variables with inflow a positive value means that the flow is inwards, and for outflow a positive value means that the flow is outwards.
For the sake of simplicity in the following \(\dot{m}_i\) denotes an inflowing quantity:
\(0 = \sum{\dot{m}_i}\)
The TerminalStreamMemberVariable is defined as:
This element is used for variables which fulfill the balance equation for transported quantities.
It is restricted to input and output, parameter and calculatedParameter.
The Stream concept is described in the appendix D.3 of the Modelica specification.
Only one terminal member variable with the variableKind inflow or outflow per terminal is allowed, if a TerminalStreamMemberVariable is present.
[More sophisticated structures can be implemented using hierarchical terminals.]
The attribute inStreamVariableName and outStreamVariableName are used to identify the ModelVariables.
If the referenced model variables are arrays, then the size of the inStreamVariableName and outStreamVariableName has to be equal.
A terminal may have more than one TerminalStreamMemberVariable.
The inStreamMemberName and outStreamMemberName describe the terminal member name for matching purposes, similar to the memberName attribute in the TerminalMemberVariable.
[An example of use for an array of stream variables is a gas mixture flow.
The gas composition could be implemented as a mass fraction vector.
The outStreamVariableName refers to \(portA.q_\textit{outStream}\textit{[]}\) and the inStreamVariableName refers to \(portA.q_\textit{inStream}\textit{[]}\) .
The inStreamMemberName and outStreamMemberName are " \(q_\textit{inStream}\textit{[]}\) " and " \(q_\textit{outStream}\textit{[]}\) ".
Balance equation for transported quantities:
\(0 = \sum{q_i\dot{m}_i}\)
\(0 = \sum{\dot{m}_i}\cdot \left\{\begin{array}{ll} q_{\textit{$i$, outStream}} &\textit{if $\dot{m}$ is outflowing through terminal $i$}\\ q_{\textit{$i$, inStream}} &\textit{if $\dot{m}$ is inflowing through terminal $i$} \end{array}\right.\)
The \(q_\textit{$i$, outStream}\) is the convective quantity in case the matter flows out of the FMU.
\(q_\textit{$i$, inStream}\) is the convective quantity in case the matter flows into the FMU. Both variables are present in the terminal.
The outStream variable has the causality output or calculatedParameter because this information has to be provided by each FMU.
The inStream variable has the causality input or parameter.
To display the actual value in an importing tool, this actual value has to be selected depending on the sign of the terminal member variable with variableKind inflow or outflow.
However, calculating the actual value is not necessary.
If only two terminals with a variable are connected and their causality matches, then the values of the outStream variables can be forwarded to the corresponding inStream values.
In Modelica the inStream variable is not directly visible, the value can only be accessed using "inStream()", therefore an additional ModelVariable has to be added during the export. It is suggested that Modelica tools exporting an FMU derive the member name for the inStream variable according to the scheme "<outStream name>_inStream". E.g. if the outStream name is "h_outflow" then the inStream name should be "h_outflow_inStream".]
The graphical representation of the FMU and terminals are needed in order to more easily comprehend the meaning of connected FMUs and to help an importing tool to display the terminals and the FMU icon in the way the exporter intended.
The graphical representation is fully optional.
The graphical representation of terminals is separate from the terminal definitions in the Terminals element.
There are three optional elements in the GraphicalRepresentation:
-
The
CoordinateSystemdefines the extent of the whole icon (graphical items may exceed that rectangle). -
The
Icondefines an image source for the FMU. -
The
Terminalsequence contains the graphical representation of the visible terminals.
The CoordinateSystem element and its defined extent is used as reference for other graphical items. It also provides a scaling factor to millimeter.
The coordinate system is defined by the coordinates of two points, the lower left (x1, y1) corner and the upper right (x2, y2) corner, where the coordinates of the first point shall be less than the coordinates of the second point [a first quadrant coordinate system].
The x-axis directed to the right, the y-axis is directed upwards.
[The exporting tool should define how the coordinate system unit relates to mm display or print out size. However, an importing tool might choose to use the factor from the default coordinate system extent to the actual coordinate system extent to calculate a scaling factor, to match the default icon size in the importing tool.
The area defined by the coordinate system suggested to be used as "clickable icon size" in other tools.
A Terminal might be placed outside of this area, so the visible bounding box has to be determined by the importing tool.]
The coordinate system default is x1=-100, y1=-100, x2=100, y2=100. This extent is used if the CoordinateSystem element is missing.
The default suggestedScalingFactorTo_mm is 0.1.
So the default coordinate system display size should be 20 mm width and 20 mm height.
The FMU icon and all graphical representations provide the position and extent with the attributes x1, y1, x2, y2.
The values of these attributes directly relate to this coordinate system and are not normalized.
Flipping of the FMU icon or a terminal can be realized by setting its attributes x2 < x1 or y2 < y1 without changing the coordinate system.
In the Icon element the FMU icon without terminals is defined, its extent and position.
The iconSource_PNG attribute is mandatory to simplify the import in other tools, so a PNG file has to be provided in any case.
Optionally an SVG file can be provided.
This enables high quality rendering and printing in importing tools.
The point (x1, y1) maps to the left lower corner of the PNG image or SVG viewport.
The point (x2, y2) maps to the right upper corner of the PNG image or SVG viewport.
For fmi3Terminals (terminals which are listed in the Terminals element) the name of the terminal in the GraphicalRepresentation is equal to the name of the terminal in the Terminals element (e.g. port_a).
[If the graphical representation is used for an input or output (e.g. a fmi3Float64 input u), then a Terminal has to be added to the Terminals element which has one TerminalMemberVariable.
The name of the Terminal and the name of the TerminalMemberVariable should be equal to the name of the input / output.]
The iconSource_PNG is mandatory for a terminal, optionally an SVG file can be provided.
The default connection stroke size and color can be provided, to define the intended connection line layout in the importing tool. The stroke size is given relative to the coordinate system extent.
The stroke color is given in RGB values from 0 to 255. E.g.: 255 255 0.
The VendorAnnotations element can be used by vendors to store additional information for the graphical representation.
[It is suggested that Modelica tools store the Modelica annotation of the connector under the tool name Modelica3Annotation in the attribute annotation of an element connector.
The attribute name of the connector element is equal to the name attribute of the referenced fmi3Terminal.]
The clickable icon size is defined by the CoordinateSystem element. The FMU icon itself may exceed this extent (or bounding box). The bounding box of the terminals is given by the extent in the terminals element. Their location is neither limited to the extent of the icon nor the extent of the coordinate system. [An importing tool has to determine the outer bounding box enclosing all graphical items.]
Transparent SVG or PNG files are allowed and wanted. The order of the elements in the XML file defines the order of painting. The first element in the GraphicalRepresentation is painted first and therefore behind the others, the last element is painted on top of the others and because of that in front of them. [So the FMU icon should be placed first in the XML file, terminal below.]
Element VendorAnnotations of fmiModelDescription is defined as:
VendorAnnotations consist of an ordered set of annotations that are identified by the name of the tool that can interpret the any element.
The any element can be an arbitrary XML data structure defined by the tool.
The attribute name must be unique with respect to all other elements of the VendorAnnotation list.
The ModelVariables element of fmiModelDescription is the central part of the model description.
It provides the static information of all exposed variables and is defined as:
The ModelVariables element consists of an ordered set of variable elements (see figure above).
Variable elements can uniformly represent variables of primitive (atomic) types, like single floating point or integer variables, or as well as arrays of an arbitrary (but fixed) number of dimensions. The schema definition is present in a separate file fmi3Variable.xsd.
Variable elements representing array variables must contain at least one Dimension element.
Each Dimension element specifies the size of one dimension of the array:
-
If the
startattribute of theDimensionelement is present, it defines a constant unsigned 64-bit integer size for this dimension. Thevariabilityof the dimension size isconstantin this case. -
If the
valueReferenceattribute of theDimensionelement is present, it defines the size of this dimension to be the value of the variable with the value reference given by thevalueReferenceattribute. The referenced variable must be a variable of typeUInt64, and must either be a constant (i.e. withvariability=constant) or astructural parameter(i.e. withcausality=structuralParameter). Thevariabilityof the dimension size is in this case thevariabilityof the referenced variable.
These two options are mutually exclusive, i.e. for each Dimension element either a start attribute or an valueReference attribute can be supplied, but not both.
However different dimension sizes can be specified using different mechanisms and can have differing variability attributes.
All initial dimension sizes (i.e. prior to any configuration or reconfiguration) must be positive integers (i.e. not zero), so that no dimension is initially vanished.
Changes to dimension sizes are constrained by the min/max attributes of the referenced structural parameters, which can be any non-negative integer, including zero.
Specifying a minimum size of zero on a structural parameterallows any related dimension sizes to be changed to zero in Configuration Mode or Reconfiguration Mode, thus causing the respective array size to go to zero, which leaves the respective array variable without any active elements.
The actual dimension sizes of arrays are also constrained by the FMU platform, due to memory and addressing constraints:
Since the API functions to access variables and their values are constrained to size_t individual elements, platforms with addresses of less than 64-bit width will not be able to access elements beyond their addressing limits, neither will they be able to allocate enough memory or address space to represent such arrays.
For these reasons implementations must take platform-specific constraints into account when changing dimension sizes, and must be prepared to handle the inability of the FMU to adjust to the desired sizes during Configuration Mode or Reconfiguration Mode.
Changing any dimension of a variable in Configuration Mode or Reconfiguration Mode invalidates the variable’s current value (including its start value).
It should be noted that changing a structural parameter might affect dimension sizes of several variables.
It is not possible to use a variable of type Clock in arrays, since array elements do not have individual valueReference and the access to clocks requires a unique valueReference information.
A variable can have any number of <Alias> elements that define a variable alias.
Each variable alias has a required attribute name whose value must be unique among all variables and variable aliases and an optional attribute description.
Variable aliases of floating point variables may additionally have a displayUnit that follows the same rules as for variables.
Example:
link:examples/alias_example.xml[role=include]The attributes of variables are:
| Attribute-Name | Description |
|---|---|
|
The full, unique name of the variable. Every variable is uniquely identified within an FMU instance by this name. |
|
A handle of the variable to efficiently identify the variable value in the model interface and for references within the |
|
An optional description string describing the meaning of the variable. |
|
Enumeration that defines the causality of the variable. Allowed values of this enumeration:
[ Example: <Variable name="spD" valueReference="126" causality="structuralParameter" variability="fixed">
<Integer start="3"/>
</Variable>]
The default of [ |
|
Enumeration that defines the time dependency of the variable, in other words, it defines the time instants when a variable can change its value.
[The purpose of this attribute is to define when a result value needs to be inquired and to be stored.
For example,
The default is [Note that the information about continuous |
|
Enumeration that defines how the variable is initialized.
It is not allowed to provide a value for
If [The environment decides when to use the If If |
|
Only for Model Exchange (if only Co-Simulation FMU, this attribute must not be present.
If both Model Exchange and Co-Simulation FMU, this attribute is ignored for Co-Simulation): |
|
The optional attribute Clock ( Communication Point Clock ( If The attribute |
|
If present, this variable is a discrete-time [state] |
|
If this boolean attribute is |
fmi3Set{VariableType} can be called on any variable with variability \(\neq\) constant before initialization (before calling [fmi3EnterInitializationMode])
-
if
initial=exactorapprox[in order to set the correspondingstartvalue.] [Note that this prevents any changes to the input before [fmi3EnterInitializationMode] is called.]
fmi3Set{VariableType} can be called on any variable with variability \(\neq\) constant during initialization (after calling [fmi3EnterInitializationMode] and before [fmi3ExitInitializationMode] is called)
fmi3Set{VariableType} can be called on any variable for Model Exchange at an event instant (after calling [fmi3EnterEventMode] and before [fmi3EnterContinuousTimeMode] is called), and for Co-Simulation at every communication point,
fmi3Set{VariableType} can be called on any variable for Model Exchange in Continuous-Time Mode
-
if
causality=inputandvariability=continuous
[in order to provide new values forinputsduring continuous integration]
If initial is not present, its value is defined by the following tables based on the values of causality and variability:
structual |
|||||||||||
data |
(A) or -- |
-- |
-- |
-- |
(A) |
(A) |
-- |
-- |
-- |
||
(A) |
(A) |
(B) |
-- |
-- |
(B) |
-- |
-- |
-- |
|||
(A) |
(A) |
(B) |
-- |
-- |
(B) |
-- |
-- |
-- |
|||
signals |
-- |
-- |
-- |
(D) |
(C) |
(C) |
-- |
-- |
-- |
||
-- |
-- |
-- |
(D) |
(C) |
(C) |
(E) |
-- |
-- |
|||
-- |
-- |
-- |
-- |
-- |
-- |
-- |
(F) |
(G) |
|||
with
default |
possible values |
|
(A) |
exact |
exact |
(B) |
calculated |
approx, |
(C) |
||
(D) |
--- |
--- |
(E) |
--- |
--- |
(F) |
exact |
exact |
(G) |
calculated |
calculated |
[Note: (1) If causality = independent, it is neither allowed to define a value for initial nor a value for start.
(2) If causality = input, it is not allowed to define a value for initial and a value for start must be defined.
(3) If (C) and initial = exact, then the variable is explicitly defined by its start value in Initialization Mode (so directly after calling [fmi3ExitInitializationMode], the value of the variable is either the start value stored in a variable element <XXX start=YYY/> or the value provided by fmi3Set{VariableType}, if this function was called on this variable).]
The following combinations of variability/causality settings are allowed:
structural |
|||||||||||
data |
-- |
-- (a) |
-- (a) |
-- (a) |
(7) |
(10) |
-- (c) |
-- |
-- |
||
(16) |
(1) |
(3) |
-- (d) |
-- (e) |
(11) |
-- (c) |
-- |
-- |
|||
(17) |
(2) |
(4) |
-- (d) |
-- (e) |
(12) |
-- (c) |
-- |
-- |
|||
signals |
-- (b) |
-- (b) |
-- (b) |
(5) |
(8) |
(13) |
--(c) |
-- |
-- |
||
-- (b) |
-- (b) |
-- (b) |
(6) |
(9) |
(14) |
(15) |
-- |
-- |
|||
clocks |
-- |
-- |
-- |
-- |
-- |
-- |
-- |
18 |
18 |
||
[Discussion of the combinations that are not allowed:
Explanation why this combination is not allowed |
|
(a) |
The combinations |
(b) |
The combinations |
(c) |
For an |
(d) |
A |
(e) |
A |
Discussion of the combinations that are allowed:
| Setting | Example | |
|---|---|---|
(1) |
||
(2) |
|
|
(3) |
Non- |
|
(4) |
|
|
(5) |
||
(6) |
|
|
(7) |
Variable where the value never changes and that can be used in another model. |
|
(8) |
|
|
(9) |
|
|
(10) |
Variable where the value never changes. Cannot be used in another model. |
|
(11) |
Local variable that depends on |
|
(12) |
Local variable that depends on |
|
(13) |
|
|
(14) |
|
|
(15) |
All variables are a function of the continuous-time variable marked as |
|
(16) |
|
|
(17) |
|
|
(18) |
Variable that defines a |
How to treat tunable variables:
A parameter p is a variable that does not change its value during simulation, in other words, dp/dt = 0.
If the parameter p is changing, then Dirac impulses are introduced since dp/dt of a discontinuous constant variable p is a Dirac impulse.
Even if this Dirac impulse would be modeled correctly by the modeling environment, it would introduce unwanted vibrations.
Furthermore, in many cases the model equations are derived under the assumption of a constant value (like mass or capacity), and the model equations would be different if p would be time varying.
FMI for Model Exchange:
Therefore, "tuning a (structural) parameter" during simulation does not mean to "change the parameter online" during simulation.
Instead, this is a short hand notation for:
-
Stop the simulation at an event instant (usually, a step event, in other words, after a successful integration step).
-
Change the values of the
tunable(structural)parameters. Fortunablestructural parameters, the Reconfiguration Mode must be entered before and left afterwards. -
Compute all
parameters(and sizes of variables,states,derivatives, event indicators, …) that depend on thetunable(structural)parameters. -
Newly start the simulation using as initial values the current values of all
previousvariables and the new values of theparameters.
Basically this means that a new simulation run is started from the previous FMU state with changed parameter values.
With this interpretation, changing parameters online is "clean", as long as these changes appear at an event instant.
FMI for Co-Simulation:
Changing of tunable parameters is allowed before an [fmi3DoStep] call (so, whenever an input can be set with fmi3Set{VariableType}) and before [fmi3ExitInitializationMode] is called (that is before and during Initialization Mode).
The FMU internally carries out event handling if necessary.]
Type specific properties are defined in the required choice element, where exactly one of the numeric types or an Enumeration must be present in the XML file. The following are representative examples:
The attributes are defined in Definition of Types (TypeDefinitions) (TypeDefinitions), except:
| Attribute-Name | Description |
|---|---|
|
If present, name of type defined with |
|
Initial or guess value of variable.
This value is also stored in the C functions.
[Therefore, calling The interpretation of [The standard approach is to set the If Variables with
|
|
If present, this variable is the derivative of variable with value reference The [state] |
|
Only for Model Exchange (if only Co-Simulation FMU, this attribute must not be present.
If both Model Exchange and Co-Simulation FMU, this attribute is ignored for Co-Simulation): |
|
The optional attributes |
With element Annotations additional, tool specific data can be defined:
With Tool.name the name of the tool is defined that can interpret the any element.
The any element can be an arbitrary XML data structure defined by the tool.
[Typically, additional data is defined here how to build up the menu for the variable, including the graphical layout and enabling/disabling an input field based on the values of other parameters.]
The attribute name must be unique with respect to all other elements of the Annotations list.
The structure of the model is defined in element ModelStructure within fmiModelDescription.
This structure is with respect to the underlying model equations, independently how these model equations are solved.
[For example, when exporting a model both in Model Exchange and Co-Simulation format; then the model structure is identical in both cases.
The Co-Simulation FMU has either an integrator included that solves the model equations, or the discretization formula of the integrator and the model equations are solved together ("inline integration").
In both cases the model has the same continuous-time states.
In the second case the internal implementation is a discrete-time system, but from the outside this is still a continuous-time model that is solved with an integration method.]
The required part defines an ordering of the outputs, the (exposed) derivatives, the event indicators and defines the unknowns that are available during Initialization [Therefore, when linearizing an FMU, every tool will use the same ordering for the outputs, states, and derivatives for the linearized model.
The ordering of the inputs should be performed in this case according to the ordering in ModelVariables.]
A Model Exchange FMU must expose all derivatives of its continuous-time states in elements <ModelStructure><Derivative> and must expose all event indicators in elements EventIndicator.
A Co- Simulation FMU does not need to expose these state derivatives and event indicators.
[If a Co-Simulation FMU exposes its state derivatives, they are usually not utilized for the co-simulation, but, for example, to linearize the FMU at a communication point.]
The optional part defines in which way derivatives, outputs and unitial unknowns depend on inputs, and continuous-time states at the current super-dense time instant (Model Exchange) or at the current communication point (Co-Simulation).
[The listed dependencies declare the dependencies between whole (multi-dimensional-)variables and not individual elements of the variables.]
[A simulation environment can utilize this information to improve the efficiency, for example, when connecting FMUs together, or when computing the partial derivative of the derivatives with respect to the states in the simulation engine.]
ModelStructure has the following definition:
Note that attribute dependenciesKind for element InitialUnknown has less enumeration values as dependenciesKind in the other lists, see below.
ModelStructure consists of the following elements (see also figures above; the symbols of the mathematical equations describing the dependency are defined in [math-model-exchange]):
| Element-Name | Description |
|---|---|
|
Ordered list of all outputs, in other words, a list of value references where every corresponding variable must have |
|
Ordered list of all state derivatives, in other words, a list of value references where every corresponding variable must be a state derivative.
[Note that only The corresponding continuous-time |
|
Ordered list of all exposed unknowns in Initialization Mode. This list consists of all variables with
The resulting list is not allowed to have duplicates (for example, if a [state] is also an \(\color{blue}{\mathbf{v}_{initialUnknowns} := \mathbf{f}_{init}(\mathbf{u}_c, \mathbf{u}_d, t_0, \mathbf{v}_{initial=exact})}\) Since, [Example: Assume an FMU is defined in the following way: \(\color{blue}{(\mathbf{y}_{c+d}, \dot{\mathbf{x}}_c) := \mathbf{f}_{init}(\mathbf{x}_c, \mathbf{u}_{c+d}, t_0, \mathbf{p})}\) \(\color{blue}{(\mathbf{y}_{c+d}, \dot{\mathbf{x}}_c) := \mathbf{f}_{sim}(\mathbf{x}_c, \mathbf{u}_{c+d}, t_i, \mathbf{p})}\) Therefore, the initial state \(\color{blue}{\mathbf{x}_c(t_0)}\) has |
|
Elements <Output>, <Derivative> and <InitialUnknown> have the following attributes:
| Attribute-Name | Description |
|---|---|
|
The value reference of the unknown \(\color{blue}{v_{\text{unknown}}}\). |
|
Optional attribute defining the dependencies of the unknown \(\color{blue}{v_{\text{unknown}}}\) (directly or indirectly via auxiliary variables) with respect to \(\color{blue}{\mathbf{v}_{\text{known}}}\).
If not present, it must be assumed that the unknown depends on all knowns.
If present as empty list, the unknown depends on none of the knowns.
Otherwise the unknown depends on the knowns defined by the given value references. - inputs (variables with - continuous-time states -
- inputs (variables with - variables with - For Co-Simulation, |
|
If
Only for floating point type unknowns \(\color{blue}{v_{\text{unknown}}}\):
Only for floating point type unknowns \(\color{blue}{v_{\text{unknown}}}\) in Event and Continuous-Time Mode (Model Exchange) and at communication points (Co-Simulation), and not for
|
[Example 1:
An FMU is defined by the following equations:
where \(\color{blue}{u_{1}}\) is a continuous-time input (variability = continuous), \(\color{blue}{u_{2}}\) is any type of input, \(\color{blue}{u_{3}}\) is a floating point discrete-time input (variability = "discrete"`), and \(\color{blue}{p}\) is a fixed parameter (variability = fixed).
The initialization is defined by:
and therefore, the initialization equations are:
This equation system can be defined as:
link:examples/model_structure_example1.xml[role=include]Example 2:
where \(\color{blue}{u}\) is a continuous-time input with valueReference = 1 and \(\color{blue}{y}\) is a continuous-time output with valueReference = 2.
The definition of the model structure is then:
link:examples/model_structure_example2.xml[role=include][Note that \(\color{blue}{y = d \cdot u}\) where \(\color{blue}{d}\) changes only during Event Mode ( \(\color{blue}{d = 2 \cdot u}\) or \(\color{blue}{3 \cdot u\ }\) depending on relation \(\color{blue}{u > 0}\) that changes only at Event Mode).
Therefore dependenciesKind = discrete.]
Example 3:
where \(\color{blue}{u}\) is a continuous-time input with valueReference = 1 and \(\color{blue}{y}\) is a continuous-time output with valueReference = 2.
The definition of the model structure is then:
link:examples/model_structure_example3.xml[role=include][Note that \(\color{blue}{y = c}\) where \(\color{blue}{c}\) changes only during Event Mode ( \(\color{blue}{c = 2}\) or \(\color{blue}{3\ }\) depending on relation \(\color{blue}{u > 0}\) that changes only at Event Mode).
Therefore dependenciesKind = dependent because it is not a linear relationship on \(\color{blue}{u}\). ]
Example 4:
where u is continuous-time input value reference 1, y is a continuous-time output with value reference 2 and dxdt is a continuous-time derivative with value reference 4.
The definition of the model structure is then:
link:examples/model_structure_example4.xml[role=include]Defining FMU features with the dependencies list:
[Note that via the dependencies list the supported features of the FMU can be defined.
Examples:
-
If a state derivative
der_xis a function of aparameterp (so of astartvalue of a variable withcausality=parameterandvariability=fixed), and the FMU does not support an iteration overpduring Initialization Mode (for example, to iterate over p such that the state derivativeder_xis zero), then thedependencieslist ofder_xshould not includep. If an FMU is imported in an environment and such an iteration is set up, then the tool can figure out that the resulting algebraic system of equations is structurally singular and therefore can reject such a definition. -
For standard Co-Simulation FMUs, it is common that no algebraic loops over the
input/outputvariables nor over start-values is supported. In such a case, alldependencieslists foroutputvariables under theInitialUnknownelement should be defined as empty lists defining that the setting ofinputsand/or ofstartvalues does not influence theoutputs. As a result, it is not possible to formulate algebraic loops of connected FMUs during Initialization Mode.]
With attribute variableNamingConvention of element fmiModelDescription, the convention is defined how the variable names have been constructed.
If this information is known, the environment may be able to represent the names in a better way (for example, as a tree and not as a linear list).
In the following definitions, the EBNF is used:
= production rule
[ ] optional
{ } repeat zero or more times
| or
The names must be unique, non-empty strings.
[It is recommended that the names are visually clearly different from each other; but it is not required.]
The following conventions for scalar names are defined:
variableNamingConvention = flat
name = Unicode-char { Unicode-char } // identical to xs:normalizedString
Unicode-char = any Unicode character without carriage return (#xD),
line feed (#xA) nor tab (#x9)
variableNamingConvention = structured`
Structured names are hierarchical using "." as a separator between hierarchies.
A name consists of "_", letters and digits or may consist of any characters enclosed in single apostrophes.
A name may identify an array element on every hierarchical level using "[…]" to identify the respective array index.
If an array is a leaf node of the variable hierarchy then the array can also be represented as a single variable of type array.
A derivative of a variable is defined with der(name) for the first time derivative and der(name,N) for the N-th derivative.
Examples:
vehicle.engine.speed resistor12.u v_min robot.axis.'motor #234' der(pipe[3,4].T[14],2) // second time derivative of pipe[3,4].T[14]
The precise syntax is:
name = identifier | "der(" identifier ["," unsignedInteger ] ")"
identifier = B-name [ arrayIndices ] {"." B-name [ arrayIndices ] }
B-name = nondigit { digit | nondigit } | Q-name
nondigit = "pass:[_]" | letters "a" to "z" | letters "A" to "Z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
Q-name = "'" ( Q-char | escape ) { Q-char | escape } "'"
Q-char = nondigit | digit | "!" | "#" | "$" | "%" | "&" | "(" | ")" |
"*" | "+" | "," | "-" | "." | "/" | ":" |
";" | "<" | ">" | "=" | "?" | "@" | "[" |
"]" | "^" | "{" | "}" | "|" | "~" | " "
escape = "\'" | "\"" | "\?" | "\\" | "\a" | "\b" |
"\f" | "\n" | "\r" | "\t" | "\v"
arrayIndices = "[" unsignedInteger {"," unsignedInteger} "]"
unsignedInteger = digit { digit }
[This definition is identical to the syntax of an identifier in Modelica version 3.2.]
The tree of names is mapped to an ordered list of variable names in depth-first order. Example:
vehicle
transmission
ratio
outputSpeed
engine
inputSpeed
temperature
is mapped to the following list of variable names:
vehicle.transmission.ratio vehicle.transmission.outputSpeed vehicle.engine.inputSpeed vehicle.engine.temperature
All flattened array elements are given in a consecutive sequence of variables. Elements of multi-dimensional arrays are ordered according to "row major" order that is elements of the last index are given in sequence.
[For example, the vector centerOfMass in body arm1 is mapped to the following variables:
robot.arm1.centerOfMass[1] robot.arm1.centerOfMass[2] robot.arm1.centerOfMass[3]
For example, a table T[4,3,2] (first dimension 4 entries, second dimension 3 entries, third dimension 2 entries) is mapped to the following variables:
T[1,1,1] T[1,1,2] T[1,2,1] T[1,2,2] T[1,3,1] T[1,3,2] T[2,1,1] T[2,1,2] T[2,3,1] ...
]
It might be that not all elements of an array are present. If they are present, they are given in consecutive order in the XML file.