Functional Mock-up Interface Specification

The Model Exchange interface exposes an ODE to an external solver of an importing tool. Models are described by differential, algebraic and discrete equations with time-, state- and step-events. That integration algorithm of the importing tool, usually a DAE solver, is responsible for advancing time, setting states, handling events, etc. (See Section 3.)

The intention is to provide a standardized interface for coupling of simulation models or tools in a co-simulation environment. The data exchange between FMUs is largely restricted to discrete communication points. In the time between two communication points, the subsystems inside FMUs are solved independently by internal means. Co-simulation algorithms control the data exchange and the synchronization between FMUs (see Section 4).

Note that the co-simulation algorithm itself is not part of the FMI standard.

The FMI 3.0 Co-Simulation interface adds a number of features compared to FMI 2.0 primarily to allow for more sophisticated co-simulation algorithms that aim at more efficient and robust simulations. Such additional features are raising events between communication points using synchronous and asynchronous clocks or sharing values between communication points to allow for improved interpolation of data. The co-simulation algorithm is responsible for:

[TODO: is this the definition that a clock tick is an event]

For FMI for Co-Simulation the co-simulation algorithm is shielded from how the subsystem FMU advances time internally. For example, FMUs containing ODEs and exposing either of the co-simulation interfaces require to include an ODE solver inside the FMU to internally advance time between the communication points. As another example, for FMU that represent controller code, an internal scheduling algorithm will trigger tasks at the correct time and order while advancing time to the next communication point or event. (See Section 4.)

The Scheduled Execution interface exposes individual model partitions (e.g. tasks of a control algorithm), to be called by a scheduler that acts as external scheduler. The scheduler is responsible for:

In many ways, the Scheduled Execution interface is the equivalent of the Model Exchange interface: the first externalizes a scheduling algorithm usually found in a controller algorithm and the second interface externalizes the ODE solver. (See Section 5.)

Table 1 gives an overview of the features of the different interfaces.

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:

The goal is that both source code 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 source code representation of FMUs, 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.

[These macros can be defined differently in a target specific variant of fmi3Functions.h to adjust them to the requirements of the supported compilers and platforms of the importing tool.]

An FMU C-file must include at the beginning a define of FMI3_FUNCTION_PREFIX with the same value as the value of the modelIdentifier attribute defined in <fmiModelDescription><ModelExchange>, <fmiModelDescription><CoSimulation> or <fmiModelDescription><ScheduledExecution> together with _ at the end (see Section 3.3, Section 4.3, Section 5.2.3.1).

This define must be directly followed with an #include "fmi3Functions.h" statement.

Typically, FMU functions are used as follows:

A function that is defined as fmi3GetFloat64 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 simulation tool (needsExecutionTool = true, see Section 4). This is particularly common for co-simulation tasks. In this tool coupling case one DLL/Shared Object can be used for all models due to no function prefixing.]

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. These restrictions apply to all interface types and for binary and source-code FMUs. [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.

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 model/subsystem represented by the FMU.

This is a pointer to a data structure in the importer. Using this pointer, data can be transferred between the importer and callback functions it provides (see Section 2.1.5.1).

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

This is a handle to a (base type) variable value of the model. A fmi3ValueReference uniquely identifies the value and other properties of a variable, except for the variable name and the display unit that may differ for alias variable definitions.

Structured entities, such as records, must be flattened into a set of values (scalars or arrays) of type fmi3Float64, fmi3Int32, etc. Arrays may be flattened into a set of scalars or represented directly as array values. An fmi3ValueReference references one such value (scalar or array). The coding of fmi3ValueReferences is a "secret" of the environment that generated the FMU. The interface to the equations only provides access to variable values via fmi3ValueReferences. Extracting concrete information about a variable can be done by reading the modelDescription.xml in which the fmi3ValueReferences are defined. If a function in the following sections is called with a wrong fmi3ValueReference value [for example, setting a constant with a call to fmi3SetFloat64], then the function must return with an error ( fmi3Status == fmi3Error, see Section 2.1.3).

Listing Base types shows the base types used in the interfaces of the C functions.

The data types fmi3Float32, fmi3Float64, fmi3Int8, fmi3UInt8, fmi3Int16, fmi3UInt16, fmi3Int32, fmi3UInt32, fmi3Int64, fmi3UInt64 and fmi3Boolean are called "numeric types" in the following.

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

The status has the following meaning:

This function returns fmi3Version of the fmi3Functions.h header file which was used to compile the functions of the FMU. This function call is allowed always and in all interface types.

The standard header file as documented in this specification has version "3.0", so this function returns "3.0".

All FMI interface types share a number of states in their respective state machines. This chapter describes these common modes. FMI specific state-machine modes will be described in their respective chapters.

All variables of an FMU are identified with a handle called value reference. The handle is defined in the modelDescription.xml file as attribute valueReference in variable elements. Each variable must have a unique valueReference.

A variable can be a scalar or an array. 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 to right for the C-API (e.g. array[dim1][dim2]…​[dimN]), and the document order in the XML attributes for the respective dimensions. For this serialization of array variables the sparsity pattern of the array is not taken into account. All elements of the array, including structural zeros, are serialized.

[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 used to get the values of output variables if a model is connected with other models. Since state derivatives are also variables, it is also possible to get the value of a state derivative. 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.7).]

The strings returned by fmi3GetString, as well as the binary values returned by fmi3GetBinary, must be copied in the target environment because the allocated memory for these strings might be deallocated or overwritten by the next call to any of the FMI functions.

For Model Exchange: fmi3Status == fmi3Discard is possible for fmi3GetFloat32 and fmi3GetFloat64 only, but not for fmi3Get*Int*, fmi3GetBoolean, fmi3GetString, fmi3GetBinary, because these are discrete-time variables and their values can only change at an event instant where fmi3Discard does not make sense.

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.7 for the exact rules on which type of variables fmi3Set{VariableType} can be called, as well as Section 3.2.3 in case of Model Exchange, and Section 4.2.7 for Co-Simulation and Section 5.2.1 for Scheduled Execution).

All strings passed as arguments to fmi3SetString, as well as all binary values passed as arguments to fmi3SetBinary, must be copied inside these functions, because there is no guarantee of the lifetime of strings or binary values, when these functions return.

Note, fmi3Status == fmi3Discard is possible for the fmi3Set{VariableType} functions.

The value of a variable may only be accessed with the respective fmi3Get/Set{VariableType} for its type.

The Intermediate Update Mode was introduced to Co-Simulation and Scheduled Execution to facilitate the following use cases:

A Co-Simulation FMU can provide values for its output variables at intermediate points between two consecutive communication points, and is able to accept new values for input variables at these intermediate points. This is typically required when the FMU uses a numerical solver to integrate the FMU’s internal state between communication points in fmi3DoStep. This numerical solver assumes that the inputs are continuous in the integration interval, dictated by fmi3DoStep. In FMI 2.0 Co-simulation, the intermediate inputs are provided by the use of extrapolations. The intermediate update functions allow FMUs to receive inputs, and provide outputs, directly to the co-simulation algorithm, in those intermediate time points.

Due to the way numerical solvers estimate and correct the approximation error, these intermediate output values may be tentative or may be final. It is possible for the FMU to inform the co-simulation algorithm whether the internal solver is in a tentative state, meaning that the output values computed from that state are also tentative, or if the internal solver has successfully completed the integration step, meaning that the FMU’s internal state is final, and will never be change by the normal in the current execution of fmi3DoStep. If the internal integration step has successfully completed, the co-simulation algorithm can forward intermediate outputs to other FMUs, where they can be used, for e.g., for extrapolation, interpolation, filtering or asynchronous co-simulation. [For tentative output values, the co-simulation algorithm must keep in mind that these values may change for the same time point.]

The FMU requests updated intermediate input values for continuous variables every time they are required by the internal solver. This can be either at tentative solver states or after successful integration steps.

Combinations of the above use cases are also allowed.

Access to intermediate variables enables advanced Co-Simulation with interpolation/extrapolation techniques (such as polynomial extrapolation, TLM co-simulation, anti-alias filtering, smoothing of input)
Moreover, this enables the same input approximation that was possible in FMI 2.0 with fmi2SetInputDerivatives, now evaluating the approximation polynomial and not within the FMU as in FMI 2.0.

The intermediate-update functionality can be used in FMI for Co-Simulation, if both, the FMU and the co-simulation algorithm, support it. Figure 3 summarizes the above description. It illustrates that multiple intermediate internal solver steps, distinguishing between the final ones (with black-filled circles) and tentative ones (with white-filled circles). It distinguishes the level of trust that can be placed in the tentative outputs (with dashed arrows) and in final outputs (with solid arrows).

If the co-simulation algorithm signals the support for intermediate update and an FMU has at least one variable with intermediateUpdate = true, the FMU can use the callback function fmi3CallbackIntermediateUpdate to communicate information back to the co-simulation algorithm:

When providing intermediate inputs to the FMU, it is important that the co-simulation algorithm provides the same input value for the same variable, at the same intermediateUpdateTime. In other words, it is required that the calculation of inputs to the FMU be deterministic. This is assumed by the internal solver. If an input value changes for the same intermediateUpdateTime, the internal numerical solver may deem that re-estimate a state multiple times, without ever being able to decrease the approximation error.

Because the FMU intermediate outputs may be trusted when intermediateStepFinished == fmi3True, the FMU is not allowed to call intermediateUpdate for a simulation time point prior to or equal to a previous call whose argument intermediateStepFinished == fmi3True.

If the early return is conducted successfully by the FMU it must return with earlyReturn == fmi3True from fmi3DoStep, indicating the current FMU time with lastSuccessfulTime.

The co-simulation algorithm can decide if a rollback of the FMU to reach the earlyReturnTime time is required or it may continue the simulation from lastSuccessfulTime for that FMU. Note that Event Mode is not supported in Scheduled Execution.

The following code example shows an implementation of fmi3CallbackIntermediateUpdate that uses intermediate update to record a set of variables at every internal solver step:

This section highlights the differences of the concept of time (in general the independent variable) for the three different FMI types, ME, CS and SE.

In Model Exchange, time is under the sole control of the importer and its integration algorithm. The model itself receives the current time to be used in its computation with fmi3SetTime. In fact, time is not necessarily advancing linearly as solvers might need to find zero-crossing points or the importer uses the Model Exchange FMU to find points of optimal control.

In Co-Simulation, time advances in (possibly variable) steps negotiated between the co-simulation algorithm of the importer and the FMU. The importer calls fmi3DoStep with the currentCommunicationPoint and a target communicationStepSize (required to be larger than 0.0). During this fmi3DoStep, both importer and FMU might encounter events that will reduce the communicationStepSize (potentially even down to 0.0). The FMU may use earlyReturn argument of the fmi3DoStep function to tell the import that the FMU needs to return earlier, and the importer may use the callback fmi3CallbackIntermediateUpdate to signal the FMU that the later should return earlier. This way both can determine if such a step-size reduction is required. The output argument lastSuccessfulTime of fmi3DoStep allows the FMU to signal the importer its current internal time.

In Scheduled Execution, time has a more discrete form. The scheduler of the importer activates specific tasks according to the time of the importer. The time itself is communicated to the FMU as activationTime argument of fmi3ActivateModelPartition.

Depending on the instantiated FMI type, the importer is restricted in what functions it is allowed to call in order to drive the simulation. The following chapters will focus on what mechanisms are relevant for the interface type at hand, without trying to constantly declare which functions not to use because they belong to the other interface type mechanisms.

In the following section the operations on clocks are described. Clocks are defined for the exact timing of evaluations of clocked model partitions and exact timing of event handling across FMUs. [In FMI 2.0 event detection in a system of FMUs was still done inside each of the FMUs individually with all the issues of floating point arithmetic. Clocks offer a way to delegate event triggering to the importer to ensure that events meant to trigger at the exact same time will be synchronized across FMUs.]

Two types of clocks are available, designed to address similar use cases with differences in details. The clock type "Synchronous Clocks"" complies with the limitations imposed by the synchronous clock theory, the other clock type "Communication Point Clocks" is a general purpose co-simulation clock for providing suitable communication points for the timed evaluation of model partitions. The term clock is used for both clock types.

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

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

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

It is optionally possible to provide evaluation of partial derivatives for an FMU. For Model Exchange, this means computing the partial derivatives at any time instant, whereas for Co-Simulation, this means computing the partial derivatives at a communication point.

An FMU has different states and in every state 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 state, the general form of the FMU equations are:

where

[The variable relationships are different in different states. 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.]

There are two access functions for partial derivatives:

with the Jacobian

where \(\mathbf{v}_{\mathit{known}}\) are the \(n\) knowns, and \(\mathbf{h}\) are the \(m\) functions to calculate the \(m\) unknwon variables \(\mathbf{v}_{\mathit{unknwon}}\) from the knowns.

Both functions can also be used to construct the partial derivative matrices. The functions may only be called if their availability is indicated by the attributes providesDirectionalDerivatives and providesAdjointDerivatives respectively.

Both functions have the same arguments:

[Note that array variables will be serialized, so nSeed is only equal to nKnowns in the case of directional derivatives (resp., equal to nUnknowns in the case of adjoint derivatives), if all value references of knowns (resp., unknowns) point to scalar variables. Likewise nSensitivity is only equal to nUnknowns (resp., nKnowns) if all value references of unknowns (resp., knowns) point to scalar variables.]

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 is implicitly given in the modelDescription.xml file. [All event indicator variables are listed as elements <EventIndicator> in <ModelStructure>. If the event indicator variable is an array variable and the <Dimension> element maps to a dependent variable, then this dependent variable is a dependency for the number of event indicators.] If all structural parameters are unchanged then this dependency information can be used to calculate the initial number of states just using information given in the XML file without the need to call this C-API function.

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 continuous states. The dependency of the number of states on structural parameters is implicitly given in the modelDescription.xml file. [All state derivative variables are listed as elements <Derivative> in <ModelStructure>. Each state derivative variable maps to the corresponding state variable by the derivative attribute. If the state variable is an array variable and the <Dimension> element maps to a dependent variable, then this dependent variable is a dependency for the number of states.] If all structural parameters are unchanged then this dependency information can be used to calculate the initial number of states just using information given in the XML file without the need to call this C-API function.

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 capability flag providesPerElementDependencies = 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 is illustrated in Figure 9. The figure contains all elements in the schema file. Data is defined by attributes to these elements.

On the top level, the schema consists of the elements detailed in Table 2. [If an optional element is present and defines a list (such as <UnitDefinitions>), the list must have at least one element (such as <Unit>).]

At least one element of <ModelExchange>, <CoSimulation> or <ScheduledExecution> must be present to identify the type of the FMU. If multiple elements are defined, different types of models are included in the FMU. The details of these elements are defined in Section 3, Section 4 or Section 5.

The XML attributes of <fmiModelDescription> are:

In this section, the units of the variables are 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 <fmiModelDescription><UnitDefinitions> 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 set (resp. get) with functions fmi3Set{VariableType} (resp. fmi3Get{VariableType}) has 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 format for the 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. [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 \({p_{\mathit{bar}}}\) is a pressure value in unit bar, and \({p_{\mathit{Pa}}}\) is the pressure value in <BaseUnit>, then

\({p_{\mathit{Pa}} = 10^5 p_{\mathit{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 "\({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. These 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

[For example, offset is needed for temperature units.]

[For example, if \({T_K}\) is the temperature value of Unit.name (in K) and \({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:

]

The schema definition is present in a separate file fmi3Unit.xsd.

Element <fmiModelDescription><TypeDefinitions> is defined as:

This element consists of a set of <TypeDefinition> elements according to schema fmi3TypeDefinition in file fmi3Type.xsd. Each <TypeDefinition> has attributes name and description. Attribute name must be unique with respect to all other elements of the <TypeDefinitions> list. Furthermore, name of a <TypeDefinition> 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. Figure 10, Figure 11, Figure 12, Figure 13, and Figure 14, are representative examples.

The type elements are referred to in variable elements to declare their type. [The alternative would be to define a type per variable. However, this would lead to a situation where, e.g., the definition of a Torque type would have to be repeated over and over.] The attributes and elements have the following meaning:

[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 (solvers or optimizers) 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.
During system creation and prototyping, checks on min/max should be performed. For maximum performance on production or real-time systems, these 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. 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 <Enumeration> variables (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.]

Element <fmiModelDescription><LogCategories> 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.1. 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.

Table 3 shows the standardized names for <Category>. 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 importer of the FMU.]

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

[This approach to define <LogCategories> has the following advantages:

Element <fmiModelDescription><DefaultExperiment> 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 FMUs the stepSize defines the preferred communicationStepSize.

This is the root element of the XML file icons/terminalsAndIcons.xml, and is defined as:

On the top level, the schema consists of the following elements (see Figure 15).

The element of <fmiModelDescription><ModelVariables> is the central part of the model description. It provides the static information of all exposed variables and is defined as follows.

The <ModelVariables> element consists of an ordered set of variable elements (see Figure 16). 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:

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.

[This allows importing tools to ignore structural parameters because that start value reflects the internal default setting of that structural parameter. The rationale for requiring positive start values for structural parameters is that this avoids importers having to deal with vanishing dimensions if they do not want to deal with them (or even with changing sizes at all). If we allowed 0 dimension sizes for initial values, tools that do not even care about changing dimension sizes must be prepared to handle vanishing dimensions.]

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.

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.

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:

]

The attributes of variables are:

If initial is not present, its value is defined by Table 5 based on the values of causality and variability (default underlined):

[Note: For local and output signals and initial = exact, then the variable is explicitly set in Initialization Mode. The value of the variable is either the start value stored in a variable element <XXX start=YYY/> or the value set with fmi3Set{VariableType} during Initialization Mode.]

Table 6 shows the combinations of variability/causality settings that 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.