Functional Mock-up Interface for Model Exchange and Co-Simulation

Three header files are provided that define the interface of an FMU. In all header files the convention is used that all C function and type definitions start with the prefix "fmi3":

This header file includes fmi3PlatformTypes.h and fmi3FunctionTypes.h. The header file version number for which the model was compiled, can be inquired in the target simulator with fmi3GetVersion (see Section 2.1.4).
[Example for a definition in this header file ^[2]:
`FMI3_Export fmi3SetTimeTYPE fmi3SetTime;`]

The goal is that both textual and binary representations of FMUs are supported and that several FMUs might be present at the same time in an executable (for example, FMU A may use an FMU B). In order for this to be possible, the names of the functions in different FMUs must be different, or function pointers must be used. To support the first variant macros are provided in fmi3Functions.h to build the actual function names by using a function prefix that depends on how the FMU is shipped. Typically, FMU functions are used as follows:

A function that is defined as fmi3GetReal is changed by the macros to a function name as follows:

[An FMU can be optionally shipped so that it basically contains only the communication to another tool (needsExecutionTool = true, see Section 4.3.1). This is particularily common for co-simulation tasks. In FMI 1.0, the function names are always prefixed with the model name and therefore a DLL/Shared Object has to be generated for every model. FMI 2.0 improves this situation since model names are no longer used as prefix in case of DLL/Shared Objects: Therefore one DLL/Shared Object can be used for all models in case of tool coupling. If an FMU is imported into a simulation environment, this is usually performed dynamically (based on the FMU name, the corresponding FMU is loaded during execution of the simulation environment) and then it does not matter whether a model name is prefixed or not.]

Since modelIdentifier is used as prefix of a C-function name it must fulfill the restrictions on C-function names (only letters, digits and/or underscores are allowed). [For example, if modelName = "A.B.C", then modelIdentifier might be "A_B_C".] Since modelIdentifier is also used as name in a file system, it must also fulfill the restrictions of the targeted operating system. Basically, this means that it should be short. For example, the Windows API only supports full path-names of a file up to 260 characters (see: http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx).

To simplify porting, no C types are used in the function interfaces, but the alias types are defined in this section. All definitions in this section are provided in the header file fmi3PlatformTypes.h. It is required to use this definition for all binary FMUs. [Only for source code FMUs, a change might be useful in some cases.]:

This is a pointer to an FMU specific data structure that contains the information needed to process the model equations or to process the co-simulation of the respective slave. This data structure is implemented by the environment that provides the FMU; in other words, the calling environment does not know its content, and the code to process it must be provided by the FMU generation environment and must be shipped with the FMU.

This is a pointer to a data structure in the simulation environment that calls the FMU. Using this pointer, data from the modelDescription.xml file [for example, mapping of valueReferences to variable names] can be transferred between the simulation environment and the logMessage function (see Section 2.1.5).

This is a pointer to a data structure in the FMU that saves the internal FMU state of the actual or a previous time instant. This allows to restart a simulation from a previous FMU state (see Section 2.1.8).

This is a handle to a (base type) variable value of the model. Handle and base type (such as fmi3Real) uniquely identify the value of a variable. Variables of the same base type that have the same handle, always have identical values, but other parts of the variable definition might be different [for example, min/max attributes].

All structured entities, such as records or arrays, are "flattened" into a set of scalar values of type fmi3Real, fmi3Integer etc. An fmi3ValueReference references one such scalar. The coding of fmi3ValueReference is a "secret" of the environment that generated the FMU. The interface to the equations only provides access to variables via this handle. Extracting concrete information about a variable is specific to the used environment that reads the Model Description File in which the value handles are defined. If a function in the following sections is called with a wrong fmi3ValueReference value [for example, setting a constant with a fmi3SetReal function call], then the function has to return with an error ( fmi3Status = fmi3Error, see Section 2.1.3).

These are the basic data types used in the interfaces of the C functions. More data types might be included in future versions of the interface. In order to keep flexibility, especially for embedded systems or for high performance computers, the exact data types or the word length of a number are not standardized. Instead, the precise definition (in other words, the header file fmi3PlatformTypes.h) is provided by the environment where the FMU shall be used. In most cases, the definition above will be used. If the target environment has different definitions and the FMU is distributed in binary format, it must be newly compiled and linked with this target header file.

If an fmi3String or an fmi3Binary variable is passed as input argument to an FMI function and the FMU needs to use the string/binary later, the FMI function must copy the string/binary before it returns and store it in the internal FMU memory, because there is no guarantee for the lifetime of the string/binary after the function has returned.

If an fmi3String or an fmi3Binary variable is passed as output argument from an FMI function and the string/binary shall be used in the target environment, the target environment must copy the whole string/binary (not only the pointer). The memory of this string/binary may be deallocated by the next call to any of the FMI interface functions (the string/binary memory might also be just a buffer, that is reused).

This section defines the status flag (an enumeration of type fmi3Status defined in file fmi3FunctionTypes.h ) that is returned by all functions to indicate the success of the function call:

Status returned by functions. The status has the following meaning

This section documents functions to inquire information about the header files used to compile its functions.

Returns the version of the fmi3Functions.h header file which was used to compile the functions of the FMU. The function returns fmi3Version which is defined in this header file. The standard header file as documented in this specification has version "3.0" (so this function usually returns "3.0").

This section documents functions that deal with instantiation, destruction and logging of FMUs.

The function returns a new instance of an FMU. If a null pointer is returned, then instantiation failed. In that case, functions→logMessage is called with detailed information about the reason. An FMU can be instantiated many times (provided capability flag canBeInstantiatedOnlyOncePerProcess = false).

This function must be called successfully before any of the following functions can be called. For co-simulation, this function call has to perform all actions of a slave which are necessary before a simulation run starts (for example, loading the model file, compilation…​).

Argument instanceName is a unique identifier for the FMU instance. It is used to name the instance, for example, in error or information messages generated by one of the fmi3XXX functions. It is not allowed to provide a null pointer and this string must be non-empty (in other words, must have at least one character that is no white space). [If only one FMU is simulated, as instanceName attribute modelName or <ModelExchange/CoSimulation modelIdentifier=".."> from the XML schema fmiModelDescription might be used.]

Argument fmuType defines the type of the FMU:

Argument fmuInstantiationToken can be used by the FMU to check that the modelDescription.xml file (see Section 2.3) is compatible with the implementation of the FMU. It is an opaque string generated by the FMU exporter that is stored in the xml file as mandatory attribute instantiationToken (see Section 2.2.1). It must be passed unchanged to the FMU, this argument must not be null.

Argument fmuResourceLocation is a URI according to the IETF RFC3986 syntax to indicate the location to the resources directory of the unzipped FMU archive. The following schemes must be understood by the FMU:

[Example: An FMU is unzipped in directory "C:\temp\MyFMU", then fmuResourceLocation = "file:///C:/temp/MyFMU/resources" or "file:/C:/temp/MyFMU/resources". Function fmi3Instantiate is then able to read all needed resources from this directory, for example maps or tables used by the FMU.]

Argument functions provides callback functions to be used from the FMU functions to utilize resources from the environment (see type fmi3CallbackFunctions below).

Argument visible = fmi3False defines that the interaction with the user should be reduced to a minimum (no application window, no plotting, no animation, etc.). In other words, the FMU is executed in batch mode. If visible = fmi3True, the FMU is executed in interactive mode, and the FMU might require to explicitly acknowledge start of simulation / instantiation / initialization (acknowledgment is non-blocking).

If loggingOn = fmi3True, debug logging is enabled.
If loggingOn = fmi3False, debug logging is disabled.

[The FMU enable/disables LogCategories which are useful for debugging according to this argument. Which LogCategories the FMU sets is unspecified.]

The struct contains pointers to functions provided by the environment to be used by the FMU. It is not allowed to change these functions between fmi3Instantiate and fmi3Terminate calls. Additionally, a pointer to the environment is provided (instanceEnvironment) that needs to be passed to all of the callback functions, in order that those functions can utilize data from the environment, such as mapping a valueReference to a string, or assigning memory to a certain FMU instance. In the unlikely case that fmi3Instance is also needed in those functions, it has to be passed via argument instanceEnvironment. Argument instanceEnvironment may be a null pointer.

The instanceEnvironment pointer is also passed to the stepFinished function in order that the environment can provide an efficient way to identify the slave that called stepFinished.

In the default fmi3FunctionTypes.h file, typedefs for the function definitions are present to simplify the usage; this is non-normative. The functions have the following meaning:

Disposes the given instance, unloads the loaded model, and frees all the allocated memory and other resources that have been allocated by the functions of the FMU interface. If a null pointer is provided for c, the function call is ignored (does not have an effect).

If loggingOn=fmi3True, debug logging is enabled, otherwise it is switched off. If loggingOn=fmi3True and nCategories > 0, then only debug messages according to the categories argument shall be printed via the logMessage function. Vector categories has nCategories elements. The allowed values of categories are defined by the modeling environment that generated the FMU. Depending on the generating modeling environment, none, some or all allowed values for categories for this FMU are defined in the modelDescription.xml file via element fmiModelDescription.LogCategories, see Section 2.2.5.

This section documents functions that deal with configuration, initialization, termination, and resetting of an FMU.

Informs the FMU to setup the experiment. This function can be called after fmi3Instantiate and before fmi3EnterInitializationMode is called. Arguments toleranceDefined and tolerance depend on the FMU type:

The arguments startTime and stopTime can be used to check whether the model is valid within the given boundaries or to allocate memory which is necessary for storing results. Argument startTime is the fixed initial value of the independent variable ^[5] value [if the independent variable is time, startTime is the starting time of initializaton]. If stopTimeDefined = fmi3True, then stopTime is the defined final value of the independent variable [if the independent variable is time, stopTime is the stop time of the simulation] and if the environment tries to compute past stopTime the FMU has to return fmi3Status = fmi3Error. If stopTimeDefined = fmi3False, then no final value of the independent variable is defined and argument stopTime is meaningless.

Informs the FMU to enter the Configuration Mode or Reconfiguration Mode.

Informs the FMU to exit the Configuration Mode or Reconfiguration Mode.

Informs the FMU to enter Initialization Mode. Before calling this function, all variables with attribute <Variable initial = "exact" or "approx"> can be set with the fmi3SetXXX functions (the Variable attributes are defined in the Model Description File, see Section 2.2.8). Setting other variables is not allowed. Furthermore, fmi3SetupExperiment must be called at least once before calling fmi3EnterInitializationMode, in order that startTime is defined.

Informs the FMU to exit Initialization Mode. For fmuType = fmi3ModelExchange, this function switches off all initialization equations, and the FMU enters Event Mode implicitly; that is, all continuous-time and active discrete-time equations are available.

Informs the FMU that the simulation run is terminated. After calling this function, the final values of all variables can be inquired with the fmi3GetXXX functions. It is not allowed to call this function after one of the functions returned with a status flag of fmi3Error or fmi3Fatal.

Is called by the environment to reset the FMU after a simulation run. The FMU goes into the same state as if fmi3Instantiate would have been called. All variables have their default values. Before starting a new run, fmi3SetupExperiment and fmi3EnterInitializationMode have to be called.

All variable values of an FMU are identified with a variable handle called "value reference". The handle is defined in the modelDescription.xml file (as attribute valueReference in element Variable). Element valueReference shall be unique for all variables.

Variables can be scalar or array variables. When getting or setting the values of array variables, the serialization of array variable values used in C-API function calls, as well as in the XML start attributes is defined as row major - i.e. dimension order from left→right for the C-API (e.g. array[dim1][dim2]…[dimN]), and document order in the XML attributes.

[Example: A 2D matrix

is serialized as follows:

]

The actual values of the variables that are defined in the modelDescription.xml file can be inquired after calling fmi3EnterInitializationMode with the following functions:

Get actual values of variables by providing their variable references. [These functions are especially used to get the actual values of output variables if a model is connected with other models. Since state derivatives are also Variables, it is possible to get the value of a state derivative. This is useful when connecting FMUs together. Furthermore, the actual value of every variable defined in the modelDescription.xml file can be determined at the actually defined time instant (see Section 2.2.8).]

It is also possible to set the values of certain variables at particular instants in time using the following functions:

Set parameters, inputs, and start values, and re-initialize caching of variables that depend on these variables (see Section 2.2.8 for the exact rules on which type of variables fmi3SetXXX can be called, as well as Section 3.2.3 in case of ModelExchange and Section 4.2.3 in case of CoSimulation).

For co-simulation FMUs, additional functions are defined in Section 4.2.1 to set and inquire derivatives of variables with respect to time in order to allow interpolation.

The FMU has an internal state consisting of all values that are needed to continue a simulation. This internal state consists especially of the values of the continuous-time states, iteration variables, parameter values, input values, delay buffers, file identifiers, and FMU internal status information. With the functions of this section, the internal FMU state can be copied and the pointer to this copy is returned to the environment. The FMU state copy can be set as actual FMU state, in order to continue the simulation from it.

[Examples for using this feature:

For variable step-size control of co-simulation master algorithms (get the FMU state for every accepted communication step; if the follow-up step is not accepted, restart co-simulation from this FMU state).

For nonlinear Kalman filters (get the FMU state just before initialization; in every sample period, set new continuous states from the Kalman filter algorithm based on measured values; integrate to the next sample instant and inquire the predicted continuous states that are used in the Kalman filter algorithm as basis to set new continuous states).

For nonlinear model predictive control (get the FMU state just before initialization; in every sample period, set new continuous states from an observer, initialize and get the FMU state after initialization. From this state, perform many simulations that are restarted after the initialization with new input signals proposed by the optimizer).]

Furthermore, the FMU state can be serialized and copied in a byte vector: [This can be, for example, used to perform an expensive steady-state initialization, copy the received FMU state in a byte vector and store this vector on file. Whenever needed, the byte vector can be loaded from file and deserialized, and the simulation can be restarted from this FMU state, in other words, from the steady-state initialization.]

fmi3GetFMUState makes a copy of the internal FMU state and returns a pointer to this copy (FMUState). If on entry *FMUState == NULL, a new allocation is required. If *FMUState != NULL, then *FMUState points to a previously returned FMUState that has not been modified since. In particular, fmi3FreeFMUState had not been called with this FMUState as an argument. [Function fmi3GetFMUState typically reuses the memory of this FMUState in this case and returns the same pointer to it, but with the actual FMUState.]

fmi3SetFMUState copies the content of the previously copied FMUState back and uses it as actual new FMU state. The FMUState copy still exists.

fmi3FreeFMUState frees all memory and other resources allocated with the fmi3GetFMUState call for this FMUState. The input argument to this function is the FMUState to be freed. If a null pointer is provided, the call is ignored. The function returns a null pointer in argument FMUState.

These functions are only supported by the FMU, if the optional capability flag canGetAndSetFMUState in <fmiModelDescription> <ModelExchange / CoSimulation> in the XML file is explicitly set to true (see Section 3.3.1 and Section 4.3.1).

fmi3SerializedFMUStateSize returns the size of the byte vector, in order that FMUState can be stored in it. With this information, the environment has to allocate an fmi3Byte vector of the required length size.

fmi3SerializeFMUState serializes the data which is referenced by pointer FMUState and copies this data in to the byte vector serializedState of length size, that must be provided by the environment.

fmi3DeSerializeFMUState deserializes the byte vector serializedState of length size, constructs a copy of the FMU state and returns FMUState, the pointer to this copy. [The simulation is restarted at this state, when calling fmi3SetFMUState with FMUState.]

These functions are only supported by the FMU, if the optional capability flags canGetAndSetFMUState and canSerializeFMUState in <fmiModelDescription><ModelExchange / CoSimulation> in the XML file are explicitly set to true (see Section 3.3.1 and Section 4.3.1).

It is optionally possible to provide evaluation of partial derivatives for an FMU. For Model Exchange, this means computing the partial derivatives at a particular time instant. For Co-Simulation, this means to compute the partial derivatives at a particular communication point. One function is provided to compute directional derivatives. This function can be used to construct the desired partial derivative matrices.

This function computes the directional derivatives of an FMU.

An FMU has different Modes and in every Mode an FMU might be described by different equations and different unknowns. The precise definitions are given in the mathematical descriptions of Model Exchange (Section 3.1) and Co-Simulation (Section 4.1). In every Mode, the general form of the FMU equations are:

where

If the capability attribute providesDirectionalDerivative is true, fmi3GetDirectionalDerivative computes a linear combination of the partial derivatives of h with respect to the selected input variables \(\color{blue}{\mathbf{v}_{known}}\):

Accordingly, it computes the directional derivative vector \(\color{blue}{\Delta \mathbf{v}_{unknown}}\) (dvUnknown) from the seed vector \(\color{blue}{\Delta \mathbf{v}_{known}}\) (dvKnown)

[The variable relationships are different in different modes. For example, during Continuous-Time Mode, a continuous-time output y does not depend on discrete-time inputs (because they are held constant between events). However, at Event Mode, y depends on discrete-time inputs.] + The function may compute the directional derivatives by numerical differentiation taking into account the sparseness of the equation system, or (preferred) by analytic derivatives.

Example:
Assume an FMU has the output equations

and this FMU is connected, so that \(\color{blue}{y_1, u_1, u_3}\) appear in an algebraic loop. Then the nonlinear solver needs a Jacobian and this Jacobian can be computed (without numerical differentiation) provided the partial derivative of \(\color{blue}{y_1}\) with respect to \(\color{blue}{u_1}\) and \(\color{blue}{u_3}\) is available. Depending on the environment where the FMUs are connected, these derivatives can be provided

(a) with one wrapper function around function fmi3GetDirectionalDerivative to compute the directional derivatives with respect to these two variables (in other words, \(\color{blue}{v_{unknown} = y_1}\), \(\color{blue}{v_{known} = \left \{ u_1, u_3 \right \}}\)), and then the environment calls this wrapper function with \(\color{blue}{\Delta v_{known} = \left \{ 1, 0 \right \}}\) to compute the partial derivative with respect to \(\color{blue}{u_1}\) and \(\color{blue}{\Delta v_{known} = \left \{ 0, 1 \right \}}\) to compute the partial derivative with respect to \(\color{blue}{u_3}\), or

(b) with two direct function calls of fmi3GetDirectionalDerivative (in other words, \(\color{blue}{v_{unknown} = y_1, v_{known} = u_1, \Delta v_{known} = 1}\); and \(\color{blue}{v_{unknown} = y_1, v_{known} = u_3, \Delta v_{known} = 1}\)).

Note that a direct implementation of this function with analytic derivatives:

(a) Provides the directional derivative for all input variables; so in the above example: \(\color{blue}{\Delta y_1 = \frac{\delta g_1}{\delta x} \cdot \Delta x + \frac{\delta g_1}{\delta u_1} \cdot \Delta u_1 + \frac{\delta g_1}{\delta u_3} \cdot \Delta u_3 + \frac{\delta g_1}{\delta u_4} \cdot \Delta u_4}\)

(b) Initializes all seed-values to zero; so in the above example: \(\color{blue}{\Delta x = \Delta u_1 = \Delta u_3 = \Delta u_4 = 0}\)

(c) Computes the directional derivative with the seed-values provided in the function arguments; so in the above example: \(\color{blue}{\Delta v_{unknown} = \Delta y_1 (\Delta x = 0, \Delta u_1 = 1, \Delta u_3 = 1, \Delta u_4 = 0)}\)]

[Note, function fmi3GetDirectionalDerivative can be utilized for the following purposes:

If a dense matrix shall be computed, the columns of the matrix can be easily constructed by successive calls of fmi3GetDirectionalDerivative. For example, constructing the system Jacobian \(\color{blue}{\mathbf{A} = \frac{\delta \mathbf{f}}{\delta \mathbf{x}}}\) as dense matrix can be performed in the following way:

If the sparsity of a matrix shall be taken into account, then the matrix can be constructed in the following way:

More details and implementational notes are available from (Akesson et.al. 2012).]

The number of event indicators can change during simulation if it depends on one or more tunable structural parameters and can be retrieved after instantiating the FMU by calling:

This function returns the number of event indicators. The dependency of the number of event indicators on structural parameters must be specified in the ModelStructure in the element NumberOfEventIndicators. This element is optional but necessary if the number of event indicators depends on structural parameters. If the NumberOfEventIndicators element is not present or its dependencies list is empty, the number of event indicators does not depend on structural parameters, i.e. it is constant.

The numberOfEventIndicators attribute of the fmiModelDescription element holds the number of event indicators if all structural parameters are unchanged, i.e. set to their start value.

The number of states can change during simulation if it depends on one or more tunable structural parameters and can be retrieved after instantiating the FMU by calling:

This function returns the number of states.

The sparseness information within arrays is not given in the xml description. The sparseness muss be retrieved during run-time using the C-API functions. Zeros in the Jacobian are not necessarily due to the structure of the model. Zero in the Jacobian might be due to the current operating point (current state, current inputs) and not due to a structural independence.

The variable dependency information in the XML description does not resolve to dependencies of individual array elements, nor does it take into account changing dependencies due to resizing of arrays via structural parameters. An FMU can indicate via the providesPerElementDependencies capability flag that it is able to provide detailed dependency information at runtime through the following C-API. Note that these functions are only defined if the providesPerElementDependencies capability flag is true.

The number of dependencies of a given variable, which may change if structural parameters are changed, can be retrieved by calling the following function:

This function returns the number of dependencies for a given variable.

The actual dependencies (of type fmi3DependencyKind) can be retrieved by calling the function fmi3GetVariableDependencies:

This function returns the dependency information for a single variable.

If this function is called before the fmi3ExitInitializationMode() call, it returns the initial dependencies. If this function is called after the fmi3ExitInitializationMode() call, it returns the run-time dependencies. The retrieved dependency information of one variable becomes invalid as soon as a structural parameter linked to the variable or to any of its depending variables are set. As a consequence, if you change structural parameters affecting B or A, the dependency of B becomes invalid. The dependency information must change only if structural parameters are changed.

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 ^[7]):

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 Section 3.3.1 and Section 4.3.1.

The XML attributes of fmiModelDescription are:

[The attribute numberOfContinuousStates available in FMI 1.0 has been removed for FMI 2.0, since this information can be deduced from the remaining data in the XML file.]

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.

[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 ^[8]. 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 fmi3SetXXX functions or else is returned by the fmi3GetXXX 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):

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):

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 for a definition:

]

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 of the elements Real, Integer, Boolean, String, Binary, or Enumeration must be present. They have the following definitions:

[The attributes of "Real" and "Integer" are collected in the attribute groups "fmi3RealAttributes" and "fmi3IntegerAttributes" in file "fmi3AttributeGroups.xsd", since these attributes are reused in the Variable element definitions below.]

These definitions are used as default values in element Variables [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:

[Attributes min and max can be set for variables of type Real, Integer or Enumeration. The question is how fmi3SetReal, fmi3SetInteger, fmi3GetReal, fmi3GetInteger 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 fmi3GetReal 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 fmi3SetReal or fmi3SetInteger 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 and Enumerations (local and output variables), then the expected behavior of the FMU is that fmi3GetInteger returns values in the defined range.

If an FMU defines min/max values for Reals, then the expected behavior of the FMU is that fmi3GetReal 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.]

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 Section 2.1.5. 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.]

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:

[Note that since element <LogCategories> is optional, an FMU does not need to expose its log categories.]

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 CoSimulation the stepSize defines the preferred communicationStepSize.

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. 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 real 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 a Dimensions element specifying the array dimensions. The Dimensions element contains a sequence of Dimension elements, each specifying the size of one dimension of the array:

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 parameter allows 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.

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 might affect dimension sizes of several variables.

The attributes of Variable are:

fmi3SetXXX can be called on any variable with variability ≠ "constant" before initialization (before calling fmi3EnterInitializationMode)

fmi3SetXXX can be called on any variable with variability ≠ "constant" during initialization (after calling fmi3EnterInitializationMode and before fmi3ExitInitializationMode is called)

fmi3SetXXX can be called on any variable for ModelExchange at an event instant (after calling fmi3EnterEventMode and before fmi3EnterContinuousTimeMode is called), and for Co-Simulation at every communication point,

fmi3SetXXX can be called on any variable for ModelExchange in Continuous-Time Mode

If initial is not present, its value is defined by the following tables based on the values of causality and variability:

with

[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 element <Variable><XXX start=YYY/> or the value provided by fmi3SetXXX, if this function was called on this variable).]

The following combinations of variability/causality settings are allowed:

Discussion of the combinations that are not allowed:

Discussion of the combinations that are allowed:

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:

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 fmi3SetXXX) and before fmi3ExitInitializationMode is called (that is before and during Initialization Mode). The FMU internally carries out event handling if necessary.]

Variables of the same base type (like fmi3Real) that have identical valueReference definitions are called "alias" variables. The main purpose of "alias" variables is to enhance efficiency. If two variables a and b are alias variables, then this is only allowed if the behavior of the FMU would be exactly the same if a and b were not treated as alias variables (that is, had different valueReferences). This requirement leads naturally to the following restrictions:

The aliasing of variables only means that the value of the variables is always identical. However, aliased variables may have different attributes, such as min/max/nominal values or description texts. [For example, if v1, v2 are two alias variables with v1=v2 and v1.max=10 and v2.max=5, then the FMU will trigger an error if either v1 or v2 becomes larger than 5.]

[The dependency definition in fmiModelDescription.ModelStructure is completely unrelated to the alias definition. In particular, the "direct dependency" definition can be a superset of the "real" direct dependency definition, even if the "alias" information shows that this is too conservative. For example, if it is stated that the output y1 depends on input u1 and the output y2 depends on input u2, and y1 is an alias to y2, then this definition is fine, although it can be deduced that in reality neither y1 nor y2 depend on any input.].

Type specific properties are defined in the required choice element, where exactly one of Real, Integer, Boolean, String, Enumeration must be present in the XML file:

The attributes are defined in Section 2.2.4 (TypeDefinitions), except:

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 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 and of the (exposed) derivatives, 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 ModelExchange FMU must expose all derivatives of its continuous-time states in element Derivatives. A Co- Simulation FMU does not need to expose these state derivatives. [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 and outputs depend on inputs, and continuous-time states at the current super dense time instant (ModelExchange) or at the current Communication Point (CoSimulation). [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:

fmi3VariableDependency is defined as:

Elements of the InitialUnknowns list:

Note that attribute dependenciesKind for element InitialUnknowns has less enumeration values as dependenciesKind in the other lists.

ModelStructure consists of the following elements (see also figures above; the symbols of the mathematical equations describing the dependency are defined in Section 3.1):

Element Unknown in Outputs, Derivatives and InitialUnknowns has the following attributes:

[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 Real 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:

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:

[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:

[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}\).]_

Defining FMU features with the dependencies list:

[Note that via the dependencies list the supported features of the FMU can be defined. Examples:

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:

The following conventions for scalar names are defined:

variableNamingConvention = "flat"

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.]

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. 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:

The precise syntax is ^[9]:

The tree of names is mapped to an ordered list of Variable.names in depth-first order. Example:

is mapped to the following list of Variable.names:

All 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:

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:

]

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.

Depending on the situation, different variables need to be computed. In order to be efficient, it is important that the interface requires only the computation of variables that are needed in the present context. For example, during the iteration of an integrator step, only the state derivatives need to be computed, provided the output of a model is not connected. It might be that at the same time instant other variables are needed. For example, if an integrator step is completed, the event indicator functions need to be computed as well. If the state derivatives have already been computed at the present time instant, then it is important for efficiency that they are not newly computed in the call to compute the event indicator functions. This means, the state derivatives shall be reused from the previous call. This feature is called "caching of variables" in the sequel.
Caching requires that the model evaluation can detect when the input arguments, like time or states, have changed. This is achieved by setting them explicitly with a function call, since every such function call signals precisely a change of the corresponding variables. For this reason, this section contains functions to set the input arguments of the equation evaluation functions. This is unproblematic for time and states, but is more involved for parameters and inputs, since the latter may have different data types.

Set a new time instant and re-initialize caching of variables that depend on time, provided the newly provided time value is different to the previously set time value (variables that depend solely on constants or parameters need not to be newly computed in the sequel, but the previously computed values can be reused).

Set a new (continuous) state vector and re-initialize caching of variables that depend on the states. Argument nx is the length of vector x and is provided for checking purposes (variables that depend solely on constants, parameters, time, and inputs do not need to be newly computed in the sequel, but the previously computed values can be reused). Note that the continuous states might also be changed in Event Mode. Note that fmi3Status = fmi3Discard is possible.

Set new values for (independent) parameters, start values and inputs and re-initialize caching of variables that depend on these variables. The details of these functions are defined in Section 2.1.7.

[The functions above have the slight drawback that values must always be copied. For example, a call to fmi3SetContinuousStates will provide the actual states in a vector, and this function has to copy the values in to the internal model data structure " c " so that subsequent evaluation calls can utilize these values. If this turns out to be an efficiency issue, a future release of FMI might provide additional functions to provide the address of a memory area where the variable values are present.]

This section contains the core functions to evaluate the model equations. Before one of these functions can be called, the appropriate functions from the previous section have to be used, to set the input arguments to the current model evaluation.

The model enters Event Mode from the Continuous-Time Mode and discrete-time equations may become active (and relations are not "frozen").

The followings arguments can be set to fmi3True to inform the FMU why Event Mode was entered. [These arguments are not mutually exclusive and may all be fmi3False if the caller cannot provide this information.]

The FMU is in Event Mode and the super dense time is incremented by this call.
If the super dense time before a call to fmi3NewDiscreteStates was \((t_R,t_I)\), then the time instant after the call is \((t_R,t_I)\).
If return argument fmi3eventInfo->newDiscreteStatesNeeded = fmi3True, the FMU should stay in Event Mode, and the FMU requires to set new inputs to the FMU (fmi3SetXXX on inputs) to compute and get the outputs (fmi3GetXXX on outputs) and to call fmi3NewDiscreteStates again. Depending on the connection with other FMUs, the environment shall

When the FMU is terminated, it is assumed that an appropriate message is printed by the logMessage function (see Section 2.1.5) to explain the reason for the termination.
If nominalsOfContinuousStatesChanged = fmi3True, then the nominal values of the states have changed due to the function call and can be inquired with fmi3GetNominalsOfContinuousStates.
If valuesOfContinuousStatesChanged = fmi3True, then at least one element of the continuous state vector has changed its value due to the function call. The new values of the states can be inquired with fmi3GetContinuousStates. If no element of the continuous state vector has changed its value, valuesOfContinuousStatesChanged must return fmi3False. [If fmi3True would be returned in this case, an infinite event loop may occur.]
If nextEventTimeDefined = fmi3True, then the simulation shall integrate at most until time = nextEventTime, and shall call fmi3EnterEventMode at this time instant. If integration is stopped before nextEventTime, for example, due to a state event, the definition of nextEventTime becomes obsolete.

The model enters Continuous-Time Mode and all discrete-time equations become inactive and all relations are "frozen".
This function has to be called when changing from Event Mode (after the global event iteration in Event Mode over all involved FMUs and other models has converged) into Continuous-Time Mode.

[This function might be used for the following purposes:

This function must be called by the environment after every completed step of the integrator provided the capability flag completedIntegratorStepNotNeeded = false. Argument noSetFMUStatePriorToCurrentPoint is fmi3True if fmi3SetFMUState will no longer be called for time instants prior to current time in this simulation run [the FMU can use this flag to flush a result buffer].
The function returns enterEventMode to signal to the environment if the FMU shall call fmi3EnterEventMode, and it returns terminateSimulation to signal if the simulation shall be terminated. If enterEventMode = fmi3False and terminateSimulation = fmi3False the FMU stays in Continuous-Time Mode without calling fmi3EnterContinuousTimeMode again. When the integrator step is completed and the states are modified by the integrator afterwards (for example, correction by a BDF method), then fmi3SetContinuousStates has to be called with the updated states before fmi3CompletedIntegratorStep is called.
When the integrator step is completed and one or more event indicators change sign (with respect to the previously completed integrator step), then the integrator or the environment has to determine the time instant of the sign change that is closest to the previous completed step up to a certain precision (usually a small multiple of the machine epsilon). This is usually performed by an iteration where time is varied and state variables needed during the iteration are determined by interpolation. Function fmi3CompletedIntegratorStep must be called after this state event location procedure and not after the successful computation of the time step by the integration algorithm. The intended purpose of the function call is to indicate to the FMU that at this stage all inputs and state variables have valid (accepted) values. After fmi3CompletedIntegratorStep is called, it is still allowed to go back in time (calling fmi3SetTime) and inquire values of variables at previous time instants with fmi3GetXXX [for example, to determine values of non-state variables at output points]. However, it is not allowed to go back in time over the previous fmi3CompletedIntegratorStep or the previous fmi3EnterEventMode call.

[This function might be used, for example, for the following purposes:

Note that this function is not used to detect time or state events, for example, by comparing event indicators of the previous with the current call of fmi3CompletedIntegratorStep. These types of events are detected in the environment, and the environment has to call fmi3EnterEventMode independently in these cases, whether the return argument enterEventMode of fmi3CompletedIntegratorStep is fmi3True or fmi3False.]

Compute state derivatives and event indicators at the current time instant and for the current states. The derivatives are returned as a vector with nx elements. A state event is triggered when the domain of an event indicator changes from \(z_j > 0\) to \(z_j \leq 0\) or vice versa. The FMU must guarantee that at an event restart \(z_j \neq 0\), for example, by shifting \(z_j\) with a small value. Furthermore, \(z_j\) should be scaled in the FMU with its nominal value (so all elements of the returned vector eventIndicators should be in the order of "one"). The event indicators are returned as a vector with ni elements.
The ordering of the elements of the derivatives vector is identical to the ordering of the state vector (for example, derivatives[2] is the derivative of x[2]). Event indicators are not necessarily related to variables on the Model Description File.
Note that fmi3Status = fmi3Discard is possible for both functions.

Return the new (continuous) state vector x. This function has to be called directly after calling function fmi3EnterContinuousTimeMode if it returns with eventInfo→valuesOfContinuousStatesChanged = fmi3True (indicating that the (continuous-time) state vector has changed).

Return the nominal values of the continuous states. This function should always be called after calling function fmi3NewDiscreteStates if it returns with eventInfo→nominalsOfContinuousStatesChanged = fmi3True, since then the nominal values of the continuous states have changed [for example, because the association of the continuous states to variables has changed due to internal dynamic state selection]. If the FMU does not have information about the nominal value of a continuous state i, a nominal value x_nominal[i] = 1.0 should be returned. Note that it is required that x_nominal[i] > 0.0. [Typically, the nominal values of the continuous states are used to compute the absolute tolerance required by the integrator. Example:
absoluteTolerance[i] = 0.01*tolerance*x_nominal[i];]

Every implementation of the FMI must support calling sequences of the functions according to the following state chart:

The objective of the start chart is to define the allowed calling sequences for functions of the FMI: Calling sequences not accepted by the state chart are not supported by the FMI. The behavior of an FMU is undefined for such a calling sequence. For example, the state chart indicates that when an FMU for Model Exchange is in state Continuous-Time Mode, a call to fmi3SetReal for a discrete input is not supported. The state chart is given here as UML 2.0 state machine. If a transition is labelled with one or more function names (for example, fmi3GetReal, fmi3GetInteger), this means that the transition is taken if any of these functions is successfully called. Note that the FMU can always determine in which state it is since every state is entered by a particular function call (such as fmi3EnterEventMode), or a particular return value (such as fmi3Fatal).

The transition conditions external event, time event, and state event are defined in Section 3.1. Each state of the state machine corresponds to a certain phase of a simulation as follows:

Note that simulation backward in time is only allowed over continuous time intervals. As soon as an event occurred (fmi3EnterEventMode was called), going back in time is forbidden, because fmi3EnterEventMode / fmi3NewDiscreteStates can only compute the next discrete state, not the previous one.

Note that during Initialization, Event, and Continuous-Time Mode input variables can be set with fmi3SetXXX and output variables can be retrieved with fmi3GetXXX interchangeably according to the model structure defined under element <ModelStructure> in the XML file. [For example, if one output y1 depends on two inputs u1, u2, then these two inputs must be set, before y1 can be retrieved. If additionally an output y2 depends on an input u3, then u3 can be set and y2 can be retrieved afterwards. As a result, artificial or "real" algebraic loops over connected FMUs in any of these three modes can be handled by using appropriate numerical algorithms.]

The allowed function calls in the respective states are summarized in the following table (functions marked in "yellow" are only available for "Model Exchange", the other functions are available both for "Model Exchange" and "Co-Simulation"):

x means: call is allowed in the corresponding state
number means: call is allowed if the indicated condition holds:
1 for a variable with variability \(\neq\) "constant" that has initial = "exact" or "approx"
2 for a variable with causality = "output", or continuous-time states or state derivatives
3 for a variable with variability \(\neq\) "constant" that has initial = "exact", or causality = "input"
4 for a variable with causality = "input", or (causality = "parameter" and variability = "tunable")
5 for a variable with causality = "input" and variability = "continuous"
7 always, but retrieved values are usable for debugging only

In the following example, the usage of the fmi3XXX functions is sketched in order to clarify the typical calling sequence of the functions in a simulation environment. Furthermore, it is assumed that one FMU is directly integrated in a simulation environment. If the FMU would be used inside another model, additional code is needed, especially initialization and event iteration has to be adapted.

In the code above, errors are not handled. Typically, fmi3XXX function calls are performed in the following way:

The switch statement could also be stored in a macro to simplify the code.

If the XML file defines an FMU for Model Exchange, element "ModelExchange" must be present. It is defined as:

The following attributes are defined (all of them are optional, with exception of modelIdentifier):

The flags have the following default values.

boolean: false
unsignedInt: 0

When generating an FMU from the hypothetical model "MyLibrary.SpringMassDamper", the XML file may have the following content:

Co-simulation exploits the modular structure of coupled problems in all stages of the simulation process beginning with the separate model setup and preprocessing for the individual subsystems in different simulation tools (which can be powerful simulators as well as simple C programs). During time integration, the simulation is again performed independently for all subsystems restricting the data exchange between subsystems to discrete communication points \(tc_i\). For simulator coupling, also the visualization and post-processing of simulation data is done individually for each subsystem in its own native simulation tool. In different contexts, the communication points \(tc_i\), the communication steps \(tc_i \rightarrow tc_{i+1}\) and the communication step sizes \(hc_i := tc_{i+1} - tc_i\) are also known as sampling points (synchronization points), macro steps and sampling rates, respectively. The term "communication point" in FMI for Co-Simulation refers to the communication between subsystems in a co-simulation environment and should not be mixed with the output points for saving simulation results to file.

FMI for Co-Simulation provides an interface standard for the solution of time dependent coupled systems consisting of subsystems that are continuous in time (model components that are described by instationary differential equations) or time-discrete (model components that are described by difference equations such as discrete controllers). In a block representation of the coupled system, the subsystems are represented by blocks with (internal) state variables \(x(t)\) that are connected to other subsystems (blocks) of the coupled problem by subsystem inputs \(u(t)\) and subsystem outputs \(y(t)\). In this framework, the physical connections between subsystems are represented by mathematical coupling conditions between the inputs \(u(t)\) and the outputs \(y(t)\) of all subsystems, Kübler and Schiehlen (2000).

For co-simulation two basic groups of functions have to be realized:

In FMI for Co-Simulation, both functions are implemented in one software component, the co-simulation master. The data exchange between the subsystems (slaves) is handled via the master only. There is no direct communication between the slaves. The master functionality can be implemented by a special software tool (a separate simulation backplane) or by one of the involved simulation tools. In its most general form, the coupled system may be simulated in nested co-simulation environments and FMI for Co-Simulation applies to each level of the hierarchy.

FMI for Co-Simulation defines interface routines for the communication between the master and all slaves (subsystems) in a co-simulation environment. The most common master algorithm stops at each communication point \(tc_i\) the simulation (time integration) of all slaves, collects the outputs \(y(tc_i)\) from all subsystems, evaluates the subsystem inputs \(u(tc_i)\), distributes these subsystem inputs to the slaves and continues the (co-)simulation with the next communication step \(tc_i \rightarrow tc_{i+1} = tc_i + hc\) with fixed communication step size \(hc\). In each slave, an appropriate solver is used to integrate one of the subsystems for a given communication step \(tc_i \rightarrow tc_{i+1}\). The most simple co-simulation algorithms approximate the (unknown) subsystem inputs \(u(t), (t > tc_i))\) by frozen data \(u(tc_i)\) for \(tc_i \leq t < tc_{i+1}\). FMI for Co-Simulation supports this classical brute force approach as well as more sophisticated master algorithms. FMI for Co-Simulation is designed to support a very general class of master algorithms but it does not define the master algorithm itself.

The ability of slaves to support more sophisticated master algorithms is characterized by a set of capability flags inside the XML description of the slave (see Section 4.3.1). Typical examples are:

FMI for Co-Simulation is restricted to slaves with the following properties:

The communication step size has to be greater than zero.

FMI for Co-Simulation allows a co-simulation flow which starts with instantiation and initialization (all slaves are prepared for computation, the communication links are established), followed by simulation (the slaves are forced to simulate a communication step), and finishes with shutdown. The details of the flow are given in the state machine of the calling sequences from master to slave (see Section 4.2.3).

This section contains a formal mathematical model of a Co-Simulation FMU. The following fundamental assumptions are made:

The slave simulators are seen by the master simulator as purely sampled-data systems. Such a sampled-data system can be:

The communication between the master and a slave takes only place at a discrete set of time instants, called communication points.

An FMI Co-Simulation model is described by the following variables:

When the transient simulation of the coupled system through co-simulation is completed, the sequence of evaluations is the following (here \(\mathbf{x} = {\lbrack \mathbf{x}_c; \mathbf{x}_d \rbrack}^T\) is the combined vector of continuous-time and discrete-time states, and \(\mathbf{y} = {\lbrack \mathbf{y}_c; \mathbf{y}_d \rbrack}^T\)) is the combined vector of continuous-time and discrete-time outputs):

where \(\mathbf{\Phi}_i\) and \(\mathbf{\Gamma}_i\) define the system behavior for the time interval \(tc_i \leq t < tc_{i+1}\), with \(tc_i = tc_0 + \sum_{k=0}^{i-1}hc_k\).

[For the part of the co-simulation slave that is based on an ODE, a differential equation is solved between communication points:

In this case, the following relationship should hold (note the use of \(\mathbf{x}_{i+1}\) here):

This relation is in practice inexact due to using finite precision on machines and stopping iterations early. The slave simulators are responsible for implementing \(\mathbf{\Phi}_i\) and \(\mathbf{\Gamma}_i\) ; for example, to handle stiff differential equations as:

]

Definition (4.1) is consistent with the definition of co-simulation by (Kübler, Schiehlen 2000).

Computing the solution of an FMI Co-Simulation model means to split the solution process in two phases and in every phase different equations and solution methods are utilized. The phases can be categorized according to the following modes:

[Note that for a Co-Simulation FMU, no super dense time description is used at communication points.]

The equations are defined in Table 2 can be evaluated in the respective Mode. The following color coding is used in the table:

Function fmi3SetXXX used in the table below, is an abbreviation for functions fmi3SetReal, fmi3SetBoolean, fmi3SetInteger and fmi3SetString respectively. Function fmi3GetXXX is an abbreviation for functions fmi3GetReal, fmi3GetBoolean, fmi3GetInteger and fmi3GetString respectively.

[Remark - Calling Sequences:

In the table above, for notational convenience in Initialization Mode one function call is defined to compute all output arguments from all inputs arguments. In reality, every scalar output argument is computed by one fmi3GetXXX function call.

In Step Mode the input arguments to \(\mathbf{f}_{doStep}\) are defined by calls to fmi3SetXXX and fmi3SetRealInputDerivatives functions. The variables computed by \(\mathbf{f}_{doStep}\) can be inquired by fmi3GetXXX function calls.]

Input and output variables and variables are transferred via the fmi3GetXXX and fmi3SetXXX functions, defined in Section 2.1.7.

In order to enable the slave to interpolate the continuous real inputs between communication steps, the derivatives of the inputs with respect to time can be provided. Also, higher derivatives can be set to allow higher order interpolation. Whether a slave is able to interpolate and therefore needs this information is provided by the capability attribute canInterpolateInputs.

Sets the n-th time derivative of real input variables. Argument vr is a vector of value references that define the variables whose derivatives shall be set. The array order contains the orders of the respective derivative (1 means the first derivative, 0 is not allowed). Argument "value" is a vector with the values of the derivatives. nValueReferences is the dimension of the vectors.
Restrictions on using the function are the same as for the fmi3SetReal function.

Inputs and their derivatives are set with respect to the beginning of a communication time step.

To allow interpolation/approximation of the real output variables between communication steps (if they are used as inputs for other slaves), the derivatives of the outputs with respect to time can be read. Whether the slave is able to provide the derivatives of outputs is given by the unsigned integer capability flag MaxOutputDerivativeOrder. It delivers the maximum order of the output derivative. If the actual order is lower (because the order of integration algorithm is low), the retrieved value is 0.

[Example: If the internal polynomial is of order 1 and the master inquires the second derivative of an output, the slave will return zero.]

The derivatives can be retrieved by:

Retrieves the n-th derivative of output values. Argument vr is a vector of nValueReferences value references that define the variables whose derivatives shall be retrieved. The array order contains the order of the respective derivative (1 means the first derivative, 0 is not allowed). Argument value is a vector with the actual values of the derivatives.
Restrictions on using the function are the same as for the fmi3GetReal function.

The returned outputs correspond to the current slave time. E.g. after a successful fmi3DoStep(…​) the returned values are related to the end of the communication time step.

This standard supports polynomial interpolation and extrapolation as well as more sophisticated signal extrapolation schemes like rational extrapolation, see the companion document "FunctionalMockupInterface-ImplementationHints.pdf".

The computation of time steps is controlled by the following function.

The computation of a time step is started.
Argument currentCommunicationPoint is the current communication point of the master (\(tc_i\)) and argument communicationStepSize is the communication step size (\(hc_i\)). The latter must be \(> 0.0\). The slave must integrate until time instant \(tc_{i+1} = tc_i + hc_i\). [The calling environment defines the communication points and fmi3DoStep must synchronize to these points by always integrating exactly to \(tc_i + hc_i\). It is up to fmi3DoStep how to achieve this.] At the first call to fmi3DoStep after fmi3ExitInitializationMode was called currentCommunicationPoint must be equal to startTime as set with fmi3SetupExperiment. [Formally, argument currentCommunicationPoint is not needed. It is present in order to handle a mismatch between the master and the FMU state of the slave: The currentCommunicationPoint and the FMU state of the slaves defined by former fmi3DoStep or fmi3SetFMUState calls have to be consistent with respect to each other. For example, if the slave does not use the update formula for the independent variable as required above, \(tc_{i+1} = tc_i + hc_i\) (using argument \(tc_i\) = currentCommunicationPoint of fmi3DoStep) but uses internally an own update formula, such as \(tc_{s,i+1} = tc_{s,i} + hc_{s,i}\) then the slave could use as time increment \(\text{hc}_{s,i} := (tc_i - tc_{s,i}) + hc_i\) (instead of \(\text{hc}_{s,i} := hc_i\) ) to avoid a mismatch between the master time \(tc_{i+1}\) and the slave internal time \(tc_{s,i+1}\) for large i.]

Argument noSetFMUStatePriorToCurrentPoint is fmi3True if fmi3SetFMUState will no longer be called for time instants prior to currentCommunicationPoint in this simulation run [the slave can use this flag to flush a result buffer].

The function returns:
fmi3OK - if the communication step was computed successfully until its end.
fmi3Discard - if the slave computed successfully only a subinterval of the communication step. The master can call the appropriate fmi3GetXXXStatus functions to get further information. If possible, the master should retry the simulation with a shorter communication step size. [Redoing a step is only possible if the FMU state has been recorded at the beginning of the current (failed) step with fmi3GetFMUState. Redoing a step is performed by calling fmi3SetFMUState and afterwards calling fmi3DoStep with the new communicationStepSize. Note that it is not possible to change currentCommunicationPoint in such a call.]
fmi3Error - the communication step could not be carried out at all. The master can try to repeat the step with other input values and/or a different communication step size in the same way as described in the fmi3Discard case above.
fmi3Fatal - if an error occurred which corrupted the FMU irreparably. [The master should stop the simulation run immediatlely.] See Section 2.1.3 for details.

It depends on the capabilities of the slave which parameter constellations and calling sequences are allowed (see Section 4.3.1)

The following state machine defines the supported calling sequences.

Each state of the state machine corresponds to a certain phase of a simulation as follows:

Configuration Mode: In this state structural parameters with variability = fixed or variability = tunable can be changed. This state is entered from state instantiated by calling fmi3EnterConfigurationMode() and left back to instantiated by calling fmi3ExitConfigurationMode(). fmi3EnterConfigurationMode() can only be called if the FMU contains at least one structural parameter.

Note that in Initialization Mode input variables can be set with fmi3SetXXX and output variables can be retrieved with fmi3GetXXX interchangeably according to the model structure defined under element <ModelStructure><InitialUnknowns> in the XML file. [For example, if one output y1 depends on two inputs u1, u2, then these two inputs must be set, before y1 can be retrieved. If additionally an output y2 depends on an input u3, then u3 can be set and y2 can be retrieved afterwards. As a result, artificial or "real" algebraic loops over connected FMUs in Initialization Mode can be handled by using appropriate numerical algorithms.]

There is the additional restriction in slaveInitialized state that it is not allowed to call fmi3GetXXX functions after fmi3SetXXX functions without an fmi3DoStep call in between.

_[The reason is to avoid different interpretations of the caching, since contrary to FMI for Model Exchange, fmi3DoStep will perform the actual calculation instead of fmi3GetXXX, and therefore, dummy algebraic loops at communication points cannot be handeled by an appropriate sequence of fmi3GetXXX and, fmi3SetXXX calls as for ModelExchange.

Examples:_

]

The allowed function calls in the respective states are summarized in the following table (functions marked in "yellow" are only available for "Co-Simulation", the other functions are available both for "Model Exchange" and "Co-Simulation"):