Functional Mock-up Interface for Model&#160;Exchange and Co-Simulation

fmi3GetReal

fmi3GetInteger

fmi3GetBoolean

fmi3GetString

fmi3SetReal

fmi3SetInteger

fmi3SetBoolean

fmi3SetString

fmi3EnterContinuousTimeMode

fmi3EnterEventMode

fmi3NewDiscreteStates

fmi3CompletedIntegratorStep

fmi3SetTime

fmi3SetContinuousStates

fmi3GetEventIndicators

fmi3GetContinuousStates

fmi3GetDerivatives

fmi3GetNominalsOfContinuousStates

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, state derivatives or event indicators, 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

3.2.4. Code Example

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.

m = M_fmi3InstantiateModelExchange("m", "{8c4e810f-3da3-4a00-8276-176fa3c9f000}", NULL, fmi3False, fmi3False,
                                   NULL, cb_logMessage, cb_allocateMemory, cb_freeMemory);
// "m" is the instance name
// "M_" is the MODEL_IDENTIFIER

// set the start time
time  = tStart;

// set all variable start values (of "ScalarVariable / <type> / start") and
// set the start values at time = Tstart
// M_fmi3SetReal/Integer/Boolean/String(m, ...)

// initialize
// determine continuous and discrete states
M_fmi3SetupExperiment(m, fmi3False, 0.0, tStart, fmi3True, tEnd);
M_fmi3EnterInitializationMode(m);
M_fmi3ExitInitializationMode(m);

initialEventMode = fmi3True;
enterEventMode   = fmi3False;
timeEvent        = fmi3False;
stateEvent       = fmi3False;

// initialize previous event indicators
M_fmi3GetEventIndicators(m, previous_z, nz);

M_fmi3EnterContinuousTimeMode(m);

// retrieve initial state x and
// nominal values of x (if absolute tolerance is needed)
M_fmi3GetContinuousStates(m, x, nx);
M_fmi3GetNominalsOfContinuousStates(m, x_nominal, nx);

// retrieve solution at t=Tstart, for example, for outputs
// M_fmi3SetFloat*/Int*/UInt*/Boolean/String/Binary(m, ...)

while (!terminateSimulation) {

    tNext = time + h;

    // handle events
    if (enterEventMode || stateEvent || timeEvent) {
        fmi3Boolean nextEventTimeDefined;
        fmi3Float64 nextEventTime;

        if (!initialEventMode) {
            // TODO: pass rootsFound
            M_fmi3EnterEventMode(m, fmi3False, fmi3False, NULL, 0, timeEvent);
        }

        // event iteration
        newDiscreteStatesNeeded = fmi3True;
        valuesOfContinuousStatesChanged   = fmi3False;
        nominalsOfContinuousStatesChanged = fmi3False;

        while (newDiscreteStatesNeeded) {
            fmi3Boolean _nominalsOfContinuousStatesChanged;
            fmi3Boolean _valuesOfContinuousStatesChanged;

            // set inputs at super dense time point
            // M_fmi3SetFloat*/Int*/UInt*/Boolean/String/Binary(m, ...)

            // update discrete states
            M_fmi3NewDiscreteStates(m,
                                    &newDiscreteStatesNeeded,
                                    &terminateSimulation,
                                    &_nominalsOfContinuousStatesChanged,
                                    &_valuesOfContinuousStatesChanged,
                                    &nextEventTimeDefined,
                                    &nextEventTime);

            // getOutput at super dense time point
            // M_fmi3GetFloat*/Int*/UInt*/Boolean/String/Binary(m, ...)
            valuesOfContinuousStatesChanged |= _valuesOfContinuousStatesChanged;
            nominalsOfContinuousStatesChanged |= _nominalsOfContinuousStatesChanged;

            if (terminateSimulation) goto TERMINATE_MODEL;
        }


        // enter Continuous-Time Mode
        M_fmi3EnterContinuousTimeMode(m);

        // retrieve solution at simulation (re)start
        // M_fmi3GetFloat*/Int*/UInt*/Boolean/String/Binary(m, ...)

        if (initialEventMode || valuesOfContinuousStatesChanged) {
            // the model signals a value change of states, retrieve them
            M_fmi3GetContinuousStates(m, x, nx);
        }

        if (initialEventMode || nominalsOfContinuousStatesChanged) {
            // the meaning of states has changed; retrieve new nominal values
            M_fmi3GetNominalsOfContinuousStates(m, x_nominal, nx);
        }

        if (nextEventTimeDefined) {
            tNext = min(nextEventTime, tEnd);
        } else {
            tNext = tEnd;
        }

        initialEventMode = fmi3False;
    }

    if (time >= tEnd) {
        goto TERMINATE_MODEL;
    }

    // compute derivatives
    M_fmi3GetDerivatives(m, der_x, nx);

    // advance time
    h = min(dt, tNext - time);
    time += h;
    M_fmi3SetTime(m, time);

    // set continuous inputs at t = time
    // M_fmi3SetFloat*(m, ...)

    // set states at t = time and perform one step
    for (i = 0; i < nx; i++) {
        x[i] += h * der_x[i]; // forward Euler method
    }

    M_fmi3SetContinuousStates(m, x, nx);

    // get event indicators at t = time
    M_fmi3GetEventIndicators(m, z, nz);

    stateEvent = fmi3False;

    for (i = 0; i < nz; i++) {
        stateEvent |= sign(z[i]) != sign(previous_z[i]); // detect events
        previous_z[i] = z[i]; // remember the current value
    }

    // inform the model about an accepted step
    M_fmi3CompletedIntegratorStep(m, fmi3True, &enterEventMode, &terminateSimulation);

    // get continuous output
    // M_fmi3GetFloat*(m, ...)
}

TERMINATE_MODEL:

// terminate simulation and retrieve final values
M_fmi3Terminate(m);

// M_fmi3GetFloat*/Int*/UInt*/Boolean/String/Binary(m, ...)

// cleanup
M_fmi3FreeInstance(m);

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

status = M_fmi3GetDerivatives(m, der_x, nx);

switch (status) {
    case fmi3Discard:
        // reduce step size and try again
        break;
    case fmi3Error:
        // clean up and stop simulation
        break;
    case fmi3Fatal:
        // stop using the model
        break;
    default:
        break;
}

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

3.2.5. Clocks API

Output Clocks: For a output clock, the environment integrates until a continuous-time event occurs and calls fmi3EnterEventMode. Afterwards with function call fmi3GetClock the output clocks that became active at this event instant can be inquired by the environment.
Input Clocks: Intervall is set with the function fmi3SetIntervalDecimal or fmi3SetIntervalFraction. It is activated by the environment with the function fmi3SetClock.

3.2.6. Handling of clock events

This concerns the following API calls: fmi3SetClock, fmi3GetClock, fmi3SetIntervalDecimal, fmi3SetIntervalFraction, fmi3GetIntervalDecimal, fmi3GetIntervalFraction

A clock event is handled by the environment in the following way:

Enter event mode: The Event Mode is entered after initialization (call to function fmi3ExitInitializationMode) or during simulation with a call to the function fmi3EnterEventMode. The FMU activates output clocks.
Synchronize clock activation and intervals with the environment: The clock activation status can be inquired with the function fmi3GetClock. The environment calls the function fmi3SetClock for periodic clocks and input clocks. Moreover the current clock intervals may be inquired with the function fmi3GetIntervalDecimal or fmi3GetIntervalFraction and set with the function fmi3SetIntervalDecimal fmi3SetIntervalFraction. [In the Modelica language this is the value returned by the interval() operator. The initialization of intervals is needed for output and input sample times if a clock ticks the first time. The FMU determines the interval itself at subsequent clock ticks.]
Solve algebraic loops among discrete-time equations of multiple FMUs or repeated evaluation in model-based control applications (optional): With the fmi3Set{VariableType} functions the input variables of the clocked partition can be set. If algebraic loops are present among clocked partitions of multiple FMUs, then with the fmi3Get{VariableType} functions all variables on the corresponding clock can be inquired. The latter function call triggers the evaluation of the discrete-time equations, provided the corresponding clock is active at this time instant. If the corresponding clock is not active, the last evaluated value of the variable is returned. Clocks are automatically deactivated if the corresponding discrete-time equations have been evaluated. Before a new loop iteration is started, the environment must activate the clocks again and reset discrete states using the fmi3Set{VariableType} functions.
Leave event mode: The function fmi3NewDiscreteStates evaluates the discrete-time equations, provided the corresponding clock is active and the discrete-time equations have not already been evaluated with calls to fmi3Get{VariableType} functions. Clocks are automatically deactivated by fmi3NewDiscreteStates and by fmi3Reset. [This handling of discrete states and time events is forward compatible with FMI 2.0 for any model that could be treated with FMI 2.0 and is exported again using the new features. The environment may ignore the new functions fmi3SetClock, fmi3GetClock, fmi3SetIntervalDecimal, fmi3SetIntervalFraction, fmi3GetIntervalDecimal and fmi3GetIntervalFraction. The new functions are needed for FMUs with input sample times and to set discrete-time states in model-based control applications or if algebraic loops are present among discrete-time equations of multiple connected FMUs.]

3.3. Description Schema

This is defined in Section 2.2. Additionally, the Model Exchange-specific element <ModelExchange> is defined in the next section.

3.3.1. Model Exchange FMU (ModelExchange)

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

Attribute Description

Attribute	Description
`modelIdentifier`	Short class name according to C syntax, for example, `A_B_C`. Used as prefix for FMI functions if the functions are provided in C source code or in static libraries, but not if the functions are provided by a DLL/SharedObject. `modelIdentifier` is also used as name of the static library or DLL/SharedObject. See also Section 2.1.1.
`needsExecutionTool`	If `true`, a tool is needed to execute the model and the FMU just contains the communication to this tool. [Typically, this information is only utilized for information purposes. For example, when loading an FMU with `needsExecutionTool = true`, the environment can inform the user that a tool has to be available on the computer where the model is instantiated. The name of the tool can be taken from attribute `generationTool` in `<fmiModelDescription>`.]
`completedIntegratorStepNotNeeded`	If `true`, function `fmi3CompletedIntegratorStep` need not be called (this gives a slightly more efficient integration). If it is called, it has no effect. If `false` (the default), the function must be called after every completed integrator step, see Section 3.2.2.
`canBeInstantiatedOnlyOncePerProcess`	This flag indicates cases (especially for embedded code), where only one instance per FMU is possible (multiple instantiation is default = `false`; if multiple instances are needed and the flag `canBeInstantiatedOnlyOncePerProcess = true`, the FMUs must be instantiated in different processes).
`canNotUseMemoryManagementFunctions`	If `true`, the FMU uses its own functions for memory allocation and freeing only. The callback functions `allocateMemory` and `freeMemory` given in `fmi3InstantiateXXX` are ignored.
`canGetAndSetFMUState`	If `true`, the environment can inquire the internal FMU state and can restore it. That is, functions `fmi3GetFMUState`, `fmi3SetFMUState`, and `fmi3FreeFMUState` are supported by the FMU.
`canSerializeFMUState`	If `true`, the environment can serialize the internal FMU state, in other words, functions `fmi3SerializedFMUStateSize`, `fmi3SerializeFMUState`, `fmi3DeSerializeFMUState` are supported by the FMU. If this is the case, then flag `canGetAndSetFMUState` must be `true` as well.
`providesDirectionalDerivative`	If `true`, the directional derivative of the equations can be computed with `fmi3GetDirectionalDerivative`

modelIdentifier

Short class name according to C syntax, for example, A_B_C. Used as prefix for FMI functions if the functions are provided in C source code or in static libraries, but not if the functions are provided by a DLL/SharedObject. modelIdentifier is also used as name of the static library or DLL/SharedObject. See also Section 2.1.1.

needsExecutionTool

If true, a tool is needed to execute the model and the FMU just contains the communication to this tool. [Typically, this information is only utilized for information purposes. For example, when loading an FMU with needsExecutionTool = true, the environment can inform the user that a tool has to be available on the computer where the model is instantiated. The name of the tool can be taken from attribute generationTool in <fmiModelDescription>.]

completedIntegratorStepNotNeeded

If true, function fmi3CompletedIntegratorStep need not be called (this gives a slightly more efficient integration). If it is called, it has no effect.
If false (the default), the function must be called after every completed integrator step, see Section 3.2.2.

canBeInstantiatedOnlyOncePerProcess

This flag indicates cases (especially for embedded code), where only one instance per FMU is possible (multiple instantiation is default = false; if multiple instances are needed and the flag canBeInstantiatedOnlyOncePerProcess = true, the FMUs must be instantiated in different processes).

canNotUseMemoryManagementFunctions

If true, the FMU uses its own functions for memory allocation and freeing only. The callback functions allocateMemory and freeMemory given in fmi3InstantiateXXX are ignored.

canGetAndSetFMUState

If true, the environment can inquire the internal FMU state and can restore it. That is, functions fmi3GetFMUState, fmi3SetFMUState, and fmi3FreeFMUState are supported by the FMU.

canSerializeFMUState

If true, the environment can serialize the internal FMU state, in other words, functions fmi3SerializedFMUStateSize, fmi3SerializeFMUState, fmi3DeSerializeFMUState are supported by the FMU. If this is the case, then flag canGetAndSetFMUState must be true as well.

providesDirectionalDerivative

If true, the directional derivative of the equations can be computed with fmi3GetDirectionalDerivative

The flags have the following default values.

boolean: false
unsignedInt: 0

3.3.2. Example XML Description File

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

<?xml version="1.0" encoding="UTF-8"?>
<fmiModelDescription
  fmiVersion="3.0-alpha.3"
  modelName="MyLibrary.SpringMassDamper"
  instantiationToken="{8c4e810f-3df3-4a00-8276-176fa3c9f9e0}"
  description="Rotational Spring Mass Damper System"
  version="1.0"
  generationDateAndTime="2011-09-23T16:57:33Z"
  variableNamingConvention="structured">
  <ModelExchange modelIdentifier="MyLibrary_SpringMassDamper"/>
  <UnitDefinitions>
    <Unit name="rad">
      <BaseUnit rad="1"/>
      <DisplayUnit name="deg" factor="57.2957795130823"/>
    </Unit>
    <Unit name="rad/s">
      <BaseUnit s="-1" rad="1"/>
    </Unit>
    <Unit name="kg.m2">
      <BaseUnit kg="1" m="2"/>
    </Unit>
    <Unit name="N.m">
      <BaseUnit kg="1" m="2" s="-2"/>
    </Unit>
  </UnitDefinitions>
  <TypeDefinitions>
    <Float64 name="Modelica.SIunits.Inertia" quantity="MomentOfInertia" unit="kg.m2" min="0.0"/>
    <Float64 name="Modelica.SIunits.Torque" quantity="Torque" unit="N.m"/>
    <Float64 name="Modelica.SIunits.AngularVelocity" quantity="AngularVelocity" unit="rad/s"/>
    <Float64 name="Modelica.SIunits.Angle" quantity="Angle" unit="rad"/>
  </TypeDefinitions>
  <DefaultExperiment startTime="0.0" stopTime="3.0" tolerance="0.0001"/>
  <ModelVariables>
    <Float64 name="inertia1.J" valueReference="1073741824"
      description="Moment of load inertia" causality="parameter" variability="fixed"
      declaredType="Modelica.SIunits.Inertia" start="1"/>
    <Float64 name="torque.tau" valueReference="536870912"
      description="Accelerating torque acting at flange (= -flange.tau)" causality="input"
      declaredType="Modelica.SIunits.Torque" start="0"/>
    <Float64 name="inertia1.phi" valueReference="805306368"
      description="Absolute rotation angle of component" causality="output"
      declaredType="Modelica.SIunits.Angle"/>
    <Float64 name="inertia1.w" valueReference="805306369"
      description="Absolute angular velocity of component (= der(phi))" causality="output"
      declaredType="Modelica.SIunits.AngularVelocity"/>
    <Float64 name="x[1]" valueReference="0" initial="exact"/>
    <Float64 name="x[2]" valueReference="1" initial="exact"/>
    <Float64 name="der(x[1])" valueReference="2" derivative="0"/>
    <Float64 name="der(x[2])" valueReference="3" derivative="1"/>
  </ModelVariables>
  <ModelStructure>
    <Output valueReference="805306368"/>
    <Output valueReference="805306369"/>
    <Derivative valueReference="2"/>
    <Derivative valueReference="3"/>
    <InitialUnknown valueReference="805306368"/>
    <InitialUnknown valueReference="805306369"/>
    <InitialUnknown valueReference="2" dependencies="0 536870912"/>
    <InitialUnknown valueReference="3" dependencies="0 1"/>
  </ModelStructure>
</fmiModelDescription>

4. FMI for Basic Co-Simulation

This chapter defines the Functional Mock-up Interface (FMI) for the coupling of two or more simulation models in a co-simulation environment (FMI for Basic Co-Simulation). It is designed both for coupling with subsystem models, which have been exported by their simulator together with its solver as runnable code (Figure 3), and for coupling of simulation tools on a single machine (Figure 4) or as part of a distributed co-simulation (Figure 5).

4.1. Mathematical Description

This section contains a formal mathematical model of Co-Simulation FMUs.

_[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 consists typically of a hybrid ODE that is integrated between communication points (known as "sampled access to time continuous systems") where internal events may occur and be handled, but events are not visible from the outside of the FMU. It is assumed here that all inputs and all outputs of this hybrid ODE are floating point signals (defined with variability = continuous),

Co-Simulation FMUs can also be used for real sampled-data systems (so a sampled discrete controller; the inputs and outputs could be of type <Float{32|64}>, <[U]Int{8|16|32|64}>, <Boolean>, <String>, <Clock> or <Enumeration> with variability = discrete.) However, in FMI 3.0, Hybrid Co-Simulation (HCS) and Scheduled Co-Simulation (SCS) may likely be more suitable for this use-case.]

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:

Variable Description

Variable	Description
\(t\)	Independent variable time \(\in \mathbb{R}\). (Variable defined with `causality` = `independent`). The i-th communication point is denoted as \(t = tc_i\) The communication step size is denoted as \(hc_i = tc_{i+1} - tc_i\)
\(\mathbf{v}\)	A vector of all exposed variables (all variables defined in element `<ModelVariables>`, see Section 2.2.10). A subset of the variables is selected via a subscript. Example: \(\mathbf{v}_{initial=exact}\) are variables defined with attribute `initial` = `exact`, see Section 2.2.10. These are `independent` `parameters` and `start` values of other variables, such as initial values for `states`, state derivatives or outputs.
\(\mathbf{p}\)	Parameters that are constant during simulation. The symbol without a subscript references `independent` `parameters` (variables with `causality` = `parameter`). Dependent `parameters` (variables with `causality` = `calculatedParameter`) are denoted as \(\mathbf{p}_{calculated}\) and `tunable` `parameters` (variables with `causality` = `parameter` and `variability` = `tunable`) are denoted as \(\mathbf{p}_{tune}\).
\(\mathbf{u}(tc_i)\)	Input variables. The values of these variables are defined outside of the model. Variables of this type are defined with attribute `causality` = `input`. Whether the `input` is a discrete-time or continuous-time variable is defined via attribute `variability` = `discrete` or `continuous` (see Section 2.2.10).
\(\mathbf{y}(tc_i)\)	Output variables. The values of these variables are computed in the FMU and they are designed to be used in a model connection. So output variables might be used in the environment as input values to other FMUs or other submodels. Variables of this type are defined with attribute `causality` = `output`. Via attribute `variability` = `discrete` or `continuous` it is defined whether the `output` is a discrete-time or continuous-time variable, see Section 2.2.10.
\(\mathbf{w}(tc_i)\)	Local variables of the FMU that cannot be used for FMU connections. Variables of this type are defined with attribute `causality` = `local` (see Section 2.2.10).
\(\mathbf{x}_c(t)\)	A vector of floating point continuous-time variables representing the continuous-time `states`. For notational convenience, a continuous-time `state` is conceptually treated as a different type of variable as an `output` or a `local` variable for the mathematical description below. However, at a communication point, a continuous-time `state` is part of the `outputs` or the `local` variables \(\mathbf{w}\) of an FMU.
\(\mathbf{x}_d(t)\) \(^{\bullet}\mathbf{x}_d(t)\)	\(\mathbf{x}_d(t)\) is a vector of (internal) discrete-time variables (of any type) representing the (internal) discrete `states`. \(^{\bullet}\mathbf{x}_d(t)\) is the value of \(\mathbf{x}_d(t)\) at the previous sample time instant, so \(^{\bullet}\mathbf{x}_d(t) = \mathbf{x}_d(^{\bullet}t)\). Given the previous values of the discrete-time `states`, \(^{\bullet}\mathbf{x}_d(t)\), at the actual time instant \(t\), all other discrete-time variables, especially the discrete `states` \(\mathbf{x}_d(t)\), can be computed. Discrete `states` are not visible in the interface of an FMU and are only introduced here to clarify the mathematical description. Formally, a discrete `state` is part of the `outputs` \(\mathbf{y}\) or the `local` variables \(\mathbf{w}\) of an FMU.

$t$

Independent variable time $\in \mathbb{R}$. (Variable defined with causality = independent).
The i-th communication point is denoted as $t = tc_i$
The communication step size is denoted as $hc_i = tc_{i+1} - tc_i$

$\mathbf{v}$

A vector of all exposed variables (all variables defined in element <ModelVariables>, see Section 2.2.10). A subset of the variables is selected via a subscript. Example:
$\mathbf{v}_{initial=exact}$ are variables defined with attribute initial = exact, see Section 2.2.10. These are independent parameters and start values of other variables, such as initial values for states, state derivatives or outputs.

$\mathbf{p}$

Parameters that are constant during simulation. The symbol without a subscript references independent parameters (variables with causality = parameter). Dependent parameters (variables with causality = calculatedParameter) are denoted as $\mathbf{p}_{calculated}$ and tunable parameters (variables with causality = parameter and variability = tunable) are denoted as $\mathbf{p}_{tune}$.

$\mathbf{u}(tc_i)$

$\mathbf{y}(tc_i)$

Output variables. The values of these variables are computed in the FMU and they are designed to be used in a model connection. So output variables might be used in the environment as input values to other FMUs or other submodels. Variables of this type are defined with attribute causality = output. Via attribute variability = discrete or continuous it is defined whether the output is a discrete-time or continuous-time variable, see Section 2.2.10.

$\mathbf{w}(tc_i)$

Local variables of the FMU that cannot be used for FMU connections. Variables of this type are defined with attribute causality = local (see Section 2.2.10).

$\mathbf{x}_c(t)$

A vector of floating point continuous-time variables representing the continuous-time states. For notational convenience, a continuous-time state is conceptually treated as a different type of variable as an output or a local variable for the mathematical description below. However, at a communication point, a continuous-time state is part of the outputs or the local variables $\mathbf{w}$ of an FMU.

$\mathbf{x}_d(t)$
$^{\bullet}\mathbf{x}_d(t)$

$\mathbf{x}_d(t)$ is a vector of (internal) discrete-time variables (of any type) representing the (internal) discrete states.
$^{\bullet}\mathbf{x}_d(t)$ is the value of $\mathbf{x}_d(t)$ at the previous sample time instant, so $^{\bullet}\mathbf{x}_d(t) = \mathbf{x}_d(^{\bullet}t)$.
Given the previous values of the discrete-time states, $^{\bullet}\mathbf{x}_d(t)$, at the actual time instant $t$, all other discrete-time variables, especially the discrete states $\mathbf{x}_d(t)$, can be computed.
Discrete states are not visible in the interface of an FMU and are only introduced here to clarify the mathematical description. Formally, a discrete state is part of the outputs $\mathbf{y}$ or the local variables $\mathbf{w}$ of an FMU.

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

Sequence of Basic Co-Simulation evaluations

\[\mathrm{\text{for}}\ i = 0, \cdots, n-1 \begin{Bmatrix} \mathbf{x}_{i+1} = \Phi_i \left( \mathbf{x}_i \left\{ \mathbf{u}_i^{(j)} \right\}_{j=0,\cdots,m_{ido}}, \mathbf{p}_{tune,i}, hc_i \right) \\ \left( \left\{ \mathbf{y}^{(j)}_{i+1} \right\}_{j=0,\cdots,m_{odo}}, \mathbf{w}_{i+1}\right) = \Gamma_i \left( \mathbf{x}_i, \left\{ \mathbf{u}^{(j)}_i \right\}_{j=0,\cdots,m_{ido}}, \mathbf{p}_{tune}, hc_i \right) \end{Bmatrix}\]

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:

\[\dot{\mathbf{x}}_c = \mathbf{\varphi} \left( \mathbf{x}_c(t), \mathbf{u}_c(t), \mathbf{p}_{tune} \right)\]

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

\[\frac{\partial\mathbf{\Phi_i}}{\partial hc_i} = \boldsymbol{\varphi} \left( \mathbf{x}_{c,i+1}, \sum^{m_{ido}}_{j=0} \mathbf{u}^{(j)}_{c,i} \frac{hc^j_i}{j!}, \mathbf{p}_{tune,i} \right)\]

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:

\[\mathbf{\Phi}_i \left( \mathbf{x}_{c,i}, \left\{ \mathbf{u}_{c,i}^{(j)} \right\}_{= 0,\cdots,m_{ido}},\ \mathbf{p}_{tune,i}, tc_i \right) = \mathbf{x}_{ci} + \left( \mathbf{I} - hc_i \frac{\partial \mathbf{\varphi}}{\partial \mathbf{x}_c} \right)^{- 1} hc_i \mathbf{\phi} \left( \mathbf{x}_{c,i}, \mathbf{u}_{c,i}, \mathbf{p}_{tune,i} \right) + O(hc_i^{2}).\]

]

Definition Sequence of Basic Co-Simulation evaluations is consistent with the definition of co-simulation by [KS00].

At the communication points, the master provides generalized inputs to the slave, which can be:
- The current input variables $\mathbf{u}_i^{(0)}$ of the subsystem (in other words, the input variables of the model contained in the slave simulator, in the sense of system-level simulation), along with some of their successive derivatives $\left\{ \mathbf{u}_i^{(j)} \right\}_{j=1,\cdots,m_{ido}}$ (in case of continuous-time variables), where $m_{ido}$ stands for the model input derivative order.
- Varying parameters $\mathbf{p}_{tune,i}$, also known as tunable parameters.
The slave provides generalized outputs to the master, which are:
- The current output variables $\mathbf{y}_{i+1}^{(0)}$of the subsystem (same remark as above), along with some of their successive derivatives $\left\{ \mathbf{y}_{i+1}^{(j)} \right\}_{j=1,\cdots,m_{odo}}$(in case of continuous-time variables).
- Observation variables and calculated varying parameters $\mathbf{w}_{i+1}$, along with directional derivatives estimated at $t = tc_{i+1}$ (in case of continuous-time variables).
Initialization: The slave being a sampled-data system, its internal states (which can be either continuous-time or discrete-time) need to be initialized at $t = tc_0$. This is performed through an auxiliary function [this relationship is defined in the XML file under elements <ModelStructure><InitialUnknown>]:

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:

4.1.1. Initialization Mode

This mode is used to compute at the start time $t_0$ initial values for internal variables of the Co-Simulation slave, especially for continuous-time states, $\mathbf{x}_d(t_0)$, and for the previous discrete-time states, $^{\bullet}\mathbf{x}_d(t_0)$, by utilizing extra equations not present in the other mode [for example, equations to set all derivatives to zero, that is, to initialize in steady-state]. If the slave is connected in loops with other models, iterations over the FMU equations are possible. Algebraic equations are solved in this mode.

4.1.2. Step Mode

This mode is used to compute the values of all continuous-time and discrete-time variables at communication points by numerically solving ordinary differential, algebraic and discrete equations. If the slave is connected in loops with other models, no iterations over the FMU equations are possible.

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

grey

If a variable in an argument list is marked in grey, then this variable is not changing in this mode and just the last calculated value from the previous mode is internally used. For an input argument it is not allowed to call fmi3Set{VariableType}. For an output argument, calling fmi3Get{VariableType} on such a variable returns always the same value in this mode.

green

Functions marked in green are special functions to enter or leave a mode.

blue

Equations and functions marked in blue define the actual computations to be performed in the respective mode.

Table 2. Mathematical description of an FMU for Basic Co-Simulation.
Equations	FMI functions
Equations before Initialization Mode (Instantiated in state machine)
Set and set `start` value of `independent` variable $tc_{i=0}$	`fmi3SetupExperiment`
Set variables and that have a start value (`initial` = `exact` or `approx`)	`fmi3Set{VariableType}`
Equations during Initialization Mode (Initialization Mode in state machine)
Enter Initialization Mode at (activate initialization, discrete-time and continuous-time equations)	fmi3EnterInitializationMode
Set variables $v_{initial=exact}$ and $v_{initial=approx}$ that have a `start` value with `initial` = `exact` (`independent` `parameters` $\mathbf{p}$ and continuous-time `states` with start values $\mathbf{x}_{c,initial=exact}$ are included here)	`fmi3Set{VariableType}`
Set continuous-time and discrete-time `inputs` $\mathbf{u}_{c+d}(tc_0)$ and optionally the `derivatives` of continuous-time `inputs` $\mathbf{u}_{c}^{(j)}(tc_0)$	`fmi3Set{VariableType}` `fmi3SetInputDerivatives`
$\mathbf{v}_{InitialUnknowns} := \mathbf{f}_{init}(\mathbf{u}_c, \mathbf{u}_d, t_0, \mathbf{v}_{initial=exact})$	`fmi3Get{VariableType}` `fmi3GetDirectionalDerivative`
Exit Initialization Mode (de-activate initialization equations)	fmi3ExitInitializationMode
Equations during Step Mode (`stepComplete`, `stepInProgress` in state machine)
Set `independent` `tunable` `parameters` $\mathbf{p}_{tune}$ (and do not set other `parameters` $\mathbf{p}_{other}$)	`fmi3Set{VariableType}`
Set continuous-time and discrete-time `inputs` $\mathbf{u}_{d+c}(tc_i)$ and optionally the `derivatives` of continuous-time `inputs` $\mathbf{u}_{c}^{(j)}(tc_i)$	`fmi3Set{VariableType}` `fmi3SetInputDerivatives`
$\begin{matrix} tc_{i+1} := tc_i + hc_i \\ (\mathbf{y}_{c+d}, \mathbf{y}_c^{(j)}, \mathbf{w}_{c+d}) := \mathbf{f}_{doStep}(\mathbf{u}_{c+d}, \mathbf{u}_{c}^{(j)}, tc_i, hc_i, \mathbf{p}_{tune}, \mathbf{p}_{other})_{tc_i} \\ tc_i := tc_{i+1} \end{matrix}$ $\mathbf{f}_{doStep}$ is also a function of the internal variables $\mathbf{x}_c$, $^{\bullet}\mathbf{x}_d$	`fmi3DoStep` `fmi3Get{VariableType}` `fmi3GetOutputDerivatives` `fmi3GetDirectionalDerivative`
Data types
$t, tc, hc \in \mathbb{R}, \mathbf{p} \in \mathbb{P}^{np}, \mathbf{u}(tc) \in \mathbb{P}^{nu}, \mathbf{y}(tc) \in \mathbb{P}^{ny}, \mathbf{x}_c(t) \in \mathbb{R}^{nxc}, \mathbf{x}_d(t) \in \mathbb{P}^{nxd}, \mathbf{w}(tc) \in \mathbb{P}^{nw}$ $\mathbb{R}$: floating point variable, $\mathbb{R}$: floating point or Boolean or integer or enumeration or string variable $\mathbf{f}_{init}, \mathbf{f}_{out} \in C^0$ (=continuous functions with respect to all input arguments inside the respective mode).

[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 variable output argument is computed by one fmi3Get{VariableType} function call.

In Step Mode the input arguments to $\mathbf{f}_{doStep}$ are defined by calls to fmi3Set{VariableType} and fmi3SetInputDerivatives functions. The variables computed by $\mathbf{f}_{doStep}$ can be inquired by fmi3Get{VariableType} function calls.]

4.1.3. Early Return from Current Communication Step

In the particular context of multi-FMU architectures, significant co-simulation speed-up may be obtained if the master can avoid waiting until the end of the slowest FMU step integration. If an FMU prematurely stops its current step integration computation due to an unpredictable internal event before the normal end of the step calculation, all other concurrently running FMUs may be stopped as soon as possible in order to minimize the time needed for the Co-Simulation master to resynchronize all the FMUs at the same event time.

In this context based on parallel multi-FMU calculations, the following figure illustrates different possibilities to synchronize FMUs at the same event time.

Figure 12: Different possibilities to synchronize parallel FMUs at the same event time.

Each FMU starts integration from communication point $t_{i}$ to reach the next communication point $t_{i+1}$. Assuming an unexpected internal event is detected at $t^{'}_{i+1}< t_{i+1}$ during FMU₁ integration, the master is informed of this early return. So now the master would like to avoid other FMUs exceed the event time, since all FMUs should be resynchronized at the event time which will be the next new communication point.

In the case of FMU₁, the internal event time becomes the new $t_{i+1}$ time, i.e. this is the source of the event.
In the case of FMU₂, a complete rollback from $t_{i}$ to $t^{'}_{i+1}$ is necessary.
In the case of FMU₃, computation is immediately interrupted and only a partial rollback is necessary to reach $t^{'}_{i+1}$ time.
In the case of FMU₄, the current step integration has been interrupted at $t^{'}_{i+1}$ and no rollback is necessary.

Each ongoing FMU stops its integration either exactly at the broken time given by the master or immediately after its current intermediate step if this time is already out-of-date. Afterwards, a new step integration done on the FMU returns and signals the premature stop (early-return) to the master.

Due to the early-return mechanism, the overall execution time of the simulation is reduced.

4.2. Application Programming Interface

This section contains the interface description to access the input/output data and status information of a Co-Simulation slave from a C program.

4.2.1. Variables access in Co-Simulation interface types

Input and output variables and other variables are accessed via the fmi3Get{VariableType} and fmi3Set{VariableType} functions, defined in Section 2.1.7.

In order to enable the slave to interpolate the continuous floating point 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 the slave is able to handle the derivatives of inputs is given by the unsigned integer capability flag MaxInputDerivativeOrder. It delivers the maximum order of the input derivative.

typedef fmi3Status fmi3SetInputDerivativesTYPE(fmi3Instance instance,
                                               const fmi3ValueReference valueReferences[],
                                               size_t nValueReferences,
                                               const fmi3Int32 orders[],
                                               const fmi3Float64 values[],
                                               size_t nValues);

typedef fmi3Status fmi3GetOutputDerivativesTYPE(fmi3Instance instance,
                                                const fmi3ValueReference valueReferences[],
                                                size_t nValueReferences,
                                                const fmi3Int32 orders[],
                                                fmi3Float64 values[],
                                                size_t nValues);

Both functions have the same arguments:

Argument valueReferences[] is a vector of value references that define the variables whose derivatives shall be set or get.
Argument nValueReferences is the dimension of the arguments valueReferences[] and orders[].
Argument orders[] contains the orders of the respective derivative (1 means the first derivative, 0 is not allowed).
Argument values[] is a vector with the values of the derivatives.
Argument nValues is the size of the argument values[].

fmi3SetInputDerivatives: Sets the n-th time derivative of input variables. Restrictions on using the function are the same as for the fmi3Set{VariableType} function. Different input variables may have different interpolation order. Inputs and their derivatives are set with respect to the beginning of a communication time step.
fmi3GetOutputDerivatives: Retrieves the n-th derivative of output values. Restrictions on using the function are the same as for the fmi3Get{VariableType} function. The returned outputs correspond to the current slave time. E.g. after a successful call to fmi3DoStep the returned values are related to the end of the communication time step.

To allow interpolation/approximation of the floating point 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 output is given by the unsigned integer capability flag maxOutputDerivativeOrder. It delivers the maximum order of the output derivatives. 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.]

4.2.2. Computation in Co-Simulation interface types

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

typedef fmi3Status fmi3DoStepTYPE(fmi3Instance instance,
                                  fmi3Float64 currentCommunicationPoint,
                                  fmi3Float64 communicationStepSize,
                                  fmi3Boolean noSetFMUStatePriorToCurrentPoint,
                                  fmi3Boolean* earlyReturn);

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$). comunicationStepSize must be $> 0.0$.
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]
Argument earlyReturn signals to the Co-Simulation master if the FMU returns early from the doStep call (earlyReturn = fmi3True) or if the doStep was completed successfully (earlyReturn = fmi3False).

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

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 FMU enters the Step Discarded state, see Section 4.2.4.9 for more information.
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. See Section 2.1.3 for details. [The master should stop the simulation run immediately.]

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

4.2.3. Retrieving Status Information from the Slave in Co-Simulation Interface Types

Status information is retrieved from the slave by the following function:

typedef fmi3Status fmi3GetDoStepDiscardedStatusTYPE(fmi3Instance instance,
                                                    fmi3Boolean* terminate,
                                                    fmi3Float64* lastSuccessfulTime);

If argument terminate = true, the slave wants to terminate the simulation.
Argument lastSuccessfulTime is the time instant at which the slave stopped the fmi3DoStep call.

4.2.4. State Machine of Calling Sequence from Master to Slave in Co-Simulation Interface Types

The following state machine defines the supported calling sequences.

Figure 12. Calling sequence of Co-Simulation C functions in form of an UML 2.0 state machine.

In this Co-Simulation interface the following functions must not be called: fmi3ActivateModelPartition, fmi3NewDiscreteStates, fmi3EnterEventMode, fmi3SetClock, fmi3GetClock, fmi3SetIntervalFraction, fmi3GetIntervalFraction, fmi3SetIntervalDecimal, fmi3GetIntervalDecimal including all functions that are specific to Model Exchange.

4.2.4.1. State: Slave Setable FMU State

In all states of this super state it is allowed to call fmi3GetFMUState, fmi3SetFMUState, fmi3FreeFMUState`, fmi3SerializedFMUStateSize, fmi3SerializeFMUState, fmi3DeSerializeFMUState, fmi3Reset, fmi3GetVersion, fmi3SetDebugLogging and fmi3FreeInstance.

If any function returns with fmi3Fatal the FMU enters the terminal state.

4.2.4.2. State: Slave Under Evaluation

This super state is entered by the FMU when fmi3InstantiateXXX is called. If any function returns fmi3Error the FMU enters state Terminated.

4.2.4.3. State: Slave Initialized

This super state is entered by the FMU when fmi3ExitInitializationMode is called. If the function fmi3Terminate is called, the FMU enters state Terminated.

4.2.4.4. State: Instantiated

In this state the FMU can do one-time initializations and allocate memory. The FMU sets all variables to its start values.

Allowed Function Calls: fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3SetInputDerivatives, fmi3EnterConfigurationMode
fmi3Set{VariableType}: For variables with variability $\neq$ constant and for which initial = exact or approx. The intention is to set start and guess values for these variables.
Forbidden Function Calls: fmi3InstantiateXXX, fmi3Terminate, fmi3Get{VariableType}, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives, fmi3DoStep, fmi3DoEarlyReturn, fmi3ExitInitializationMode, fmi3GetDoStepDiscardedStatus, fmi3ExitConfigurationMode, fmi3EnterStepMode

4.2.4.5. State: Initialization Mode

This mode is used by the master to compute consistent initial conditions for overall system. Therefore iterative calls of fmi3Set{VariableType} and fmi3Get{VariableType} are allowed. In between the FMU must evaluate all relevant equations. In this way artificial or real algebraic loops over connected FMUs in Initialization Mode may be handled by using appropriate numerical algorithms.

Allowed Function Calls

fmi3ExitInitializationMode, fmi3SetInputDerivatives, fmi3GetDirectionalDerivative

fmi3Set{VariableType}

For variables with:

variability $\neq$ constant that have initial = exact, or
causality = input, or
causality = to parameter and variability = to tunable.

fmi3Get{VariableType}

For variables with causality = output or continuous-time states or state derivatives.

Forbidden Function Calls

fmi3InstantiateXXX, fmi3Terminate, fmi3DoStep, fmi3DoEarlyReturn, fmi3EnterInitializationMode, fmi3GetDoStepDiscardedStatus, fmi3EnterConfigurationMode, fmi3ExitConfigurationMode, fmi3SetupExperiment, fmi3EnterStepMode

4.2.4.6. State: Step Mode

This state is used by the master to progress simulation time.

Allowed Function Calls

fmi3SetInputDerivatives, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives, fmi3Get{VariableType}, fmi3Terminate

fmi3EnterConfigurationMode

With this function call the Reconfiguration Mode is entered. This function must not be called if the FMU contains no tunable structural parameters (i.e. with causality= structuralParameter and variability = tunable).

fmi3DoStep

Within fmi3DoStep the FMU may call fmi3CallbackIntermediateUpdate

If the function returns with fmi3OK or fmi3Warning the FMU stays in this state.
If the function returns with fmi3Discard the FMU enters state Step Discarded.

fmi3Set{VariableType}

For variables with:

causality = input, or
causality = parameter and variability = tunable

It is not allowed to call fmi3Get{VariableType} functions after fmi3Set{VariableType} 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 fmi3Get{VariableType}, and therefore, dummy algebraic loops at communication points cannot be handled by an appropriate sequence of fmi3Get{VariableType} and, fmi3Set{VariableType} calls as for Model Exchange.

Examples:

Correct calling sequence	Wrong calling sequence
fmi3Set{VariableType} on inputs fmi3DoStep fmi3Get{VariableType} on outputs fmi3Set{VariableType} on inputs fmi3DoStep fmi3Get{VariableType} on outputs	fmi3Set{VariableType} on inputs fmi3DoStep fmi3Get{VariableType} on outputs fmi3Set{VariableType} on inputs fmi3Get{VariableType} on outputs // not allowed fmi3DoStep fmi3Get{VariableType} on outputs

Correct calling sequence

Wrong calling sequence

fmi3Set{VariableType} on inputs
fmi3DoStep
fmi3Get{VariableType} on outputs
fmi3Set{VariableType} on inputs
fmi3DoStep
fmi3Get{VariableType} on outputs

fmi3Set{VariableType} on inputs
fmi3DoStep
fmi3Get{VariableType} on outputs
fmi3Set{VariableType} on inputs
fmi3Get{VariableType} on outputs // not allowed
fmi3DoStep
fmi3Get{VariableType} on outputs

]

Forbidden Function Calls: fmi3ExitConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3GetDoStepDiscardedStatus, fmi3DoEarlyReturn, fmi3EnterStepMode

4.2.4.7. State: Intermediate Update Mode

In this state the master can retrieve information from the FMU between communication points. Functions called in this state must not return fmi3Discard.

The FMU enters this state by calling fmi3CallbackIntermediateUpdate within fmi3DoStep and leaves the state towards state Step Mode if the function returns fmi3OK or fmi3Warning. If the function returns fmi3Error the FMU enters state Terminated. If the function returns fmi3Fatal the FMU enters the terminal state.

Allowed Function Calls: fmi3DoEarlyReturn
fmi3Set{VariableType}, fmi3SetInputDerivatives: If intermediateVariableSetAllowed = fmi3True, the value of intermediate variables can be set. Intermediate variables are variables that are marked with attribute intermediateAccess = true in the modelDescription.xml.
fmi3Get{VariableType}, fmi3GetOutputDerivatives: If intermediateVariableGetAllowed = fmi3True, the value of intermediate variables can be retrieved. Intermediate variables are variables that are marked with attribute intermediateAccess = true in the modelDescription.xml.
Forbidden Function Calls: The same functions which are not allowed to be called in Step Mode must not be called in this state. Additionally the following functions must not be called fmi3EnterConfigurationMode, fmi3Terminate, fmi3DoStep, fmi3GetDirectionalDerivative.

4.2.4.8. State: Reconfiguration Mode

In this state structural parameters with variability = tunable can be changed. This state is entered from state Step Mode by calling fmi3EnterConfigurationMode and left back to Step Mode by calling fmi3ExitConfigurationMode.

Allowed Function Calls: fmi3ExitConfigurationMode
fmi3Set{VariableType}: Only for variables with causality = structuralParameter and variability = tunable.
Forbidden Function Calls: fmi3EnterConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3GetDoStepDiscardedStatus, fmi3DoStep, fmi3EnterStepMode, fmi3SetInputDerivatives, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives, fmi3Get{VariableType}

4.2.4.9. State: Step Discarded

The FMU changes into this state if it is not able to compute a communication step completely by returning fmi3Discard from fmi3DoStep. This might have been caused by numerical problems or intended stop of the simulation run. The master can call fmi3GetDoStepDiscardedStatus to get further information. In case of numerical problems the master may try to achieve a correct solution for example by repeating the last step with a different communication step size. [Redoing a step is only possible if the FMU state has been recorded at the beginning of the current (discarded) 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.] The master can also continue from the lastSuccessfulTime. It does not enter into this state if the FMU returns early from a communication step caused by fmi3DoEarlyReturn.

Allowed Function Calls: fmi3Terminate, fmi3Get{VariableType}, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives, fmi3SetFMUState
fmi3GetDoStepDiscardedStatus: The master calls this functions to retrieve information about the reason for discarding the last communication step.
fmi3EnterStepMode: The fmi3EnterStepMode function pushes the FMU from Step Discarded to Step Mode. [In Step Mode, the master may change again FMU inputs and parameters, or push the FMU into other states] In this case, a new step may be started from lastSuccessfulTime which can be retrieved by the fmi3GetDoStepDiscardedStatus function in state Step Discarded.
Forbidden Function Calls: fmi3EnterConfigurationMode, fmi3ExitConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3DoStep, fmi3Set{VariableType}, fmi3DoEarlyReturn, fmi3SetInputDerivatives

4.2.4.10. State: Terminated

In this state, the solution at the final time of the simulation can be retrieved.

Allowed Function Calls: fmi3Get{VariableType}, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives
Forbidden Function Calls: fmi3EnterConfigurationMode, fmi3ExitConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3DoStep, fmi3Set{VariableType}, fmi3DoEarlyReturn, fmi3SetInputDerivatives

4.2.4.11. State: Configuration Mode

In this state structural parameters with variability = tunable can be changed.

This state is entered from state Instantiated by calling fmi3EnterConfigurationMode and left back to Instantiated by calling fmi3ExitConfigurationMode.

Allowed Function Calls: fmi3ExitConfigurationMode
fmi3Set{VariableType}: Only for variables with causality = structuralParameter and variability = tunable.
Forbidden Function Calls: fmi3EnterConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3GetDoStepDiscardedStatus, fmi3DoStep, fmi3EnterStepMode, fmi3SetInputDerivatives, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives, fmi3Get{VariableType}

"yellow" are only available for Co-Simulation, the other functions are available both for Model Exchange and Co-Simulation):

Function

FMI 3.0 for Co-Simulation

Start, End

Instantiated

Initialization Mode

StepComplete

StepInProgress

StepDiscarded

StepCanceled

Terminated

Error

fmi3GetReal

fmi3GetInteger

fmi3GetBoolean

fmi3GetString

fmi3SetReal

fmi3SetInteger

fmi3SetBoolean

fmi3SetString

fmi3SetInputDerivatives

fmi3GetOutputDerivatives

fmi3DoStep

fmi3DoEarlyReturn

fmi3GetDoStepDiscardedStatus

fmi3EnterStepMode

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 (if element <ModelStructure><Derivative> is present)
3 for a variable with variability $\neq$ constant that has initial = exact, or causality = input
6 for a variable with causality = input or (causality = parameter and variability = tunable)
7 always, but retrieved values are usable for debugging only
8 always, but if status is other than fmi3Terminated, retrieved values are usable for debugging only ]_

4.2.5. Code Example for Basic Co-Simulation

In the following example, the usage of the FMI functions is sketched in order to clarify the typical calling sequence of the functions in a simulation environment. We consider two slaves, where both have one continuous floating point input and one continuous floating point output which are connected in the following way:

Figure 13. Connection graph of the slaves.

We assume no algebraic dependency between input and output of each slave. The code demonstrates the simplest master algorithm as shown in Section 4.1:

Constant communication step size.
No repeating of communication steps.
The slaves do not support asynchronous execution of fmi3DoStep.

The error handling is implemented in a very rudimentary way.

////////////////////////////
// Initialization sub-phase

// instantiate both slaves
s1 = s1_fmi3InstantiateBasicCoSimulation("slave1", guid, NULL, fmi3False, fmi3False, fmi3False, fmi3False, fmi3False,
                        NULL, cb_logMessage, cb_allocateMemory, cb_freeMemory, NULL);
s2 = s2_fmi3InstantiateBasicCoSimulation("slave2", guid, NULL, fmi3False, fmi3False, fmi3False, fmi3False, fmi3False,
                        NULL, cb_logMessage, cb_allocateMemory, cb_freeMemory, NULL);

if (s1 == NULL || s2 == NULL)
    return EXIT_FAILURE;

// start and stop time
startTime = 0;
stopTime = 10;

// communication step size
h = 0.01;

// set all variable start values (of "ScalarVariable / <type> / start")
// s1_fmi3SetReal/Integer/Boolean/String(s1, ...);
// s2_fmi3SetReal/Integer/Boolean/String(s2, ...);

// initialize the slaves
s1_fmi3SetupExperiment(s1, fmi3False, 0.0, startTime, fmi3True, stopTime);
s2_fmi3SetupExperiment(s2, fmi3False, 0.0, startTime, fmi3True, stopTime);

s1_fmi3EnterInitializationMode(s1);
s2_fmi3EnterInitializationMode(s2);

// set the input values at time = startTime
// fmi3SetReal/Integer/Boolean/String(s1, ...);
// fmi3SetReal/Integer/Boolean/String(s2, ...);

s1_fmi3ExitInitializationMode(s1);
s2_fmi3ExitInitializationMode(s2);

////////////////////////
// Simulation sub-phase
tc = startTime; // current master time

while ((tc < stopTime) && (status == fmi3OK)) {

    // retrieve outputs
    // fmi3GetReal(s1, ..., 1, &y1);
    // fmi3GetReal(s2, ..., 1, &y2);

    // set inputs
    // fmi3SetReal(s1, ..., 1, &y2);
    // fmi3SetReal(s2, ..., 1, &y1);

    // call slave s1 and check status
    status = s1_fmi3DoStep(s1, tc, h, fmi3True, NULL);

    switch (status) {
        case fmi3Discard:
            s1_fmi3GetDoStepDiscardedStatus(s1, &discard, &lastSuccessfulTime);
            if (discard == fmi3True)
                printf("Slave s1 wants to terminate simulation.");
        case fmi3Error:
        case fmi3Fatal:
            terminateSimulation = true;
            break;
        default:
            break;
    }

    if (terminateSimulation)
        break;

    // call slave s2 and check status as above
    status = s2_fmi3DoStep(s2, tc, h, fmi3True, NULL);

    // ...

    // increment master time
    tc += h;
 }

//////////////////////////
// Shutdown sub-phase
if (status != fmi3Error && status != fmi3Fatal) {
    s1_fmi3Terminate(s1);
    s2_fmi3Terminate(s2);
}

if (status != fmi3Fatal) {
    s1_fmi3FreeInstance(s1);
    s2_fmi3FreeInstance(s2);
}

4.2.6. Early-return Requested by the Co-Simulation Master in Co-Simulation Interface Types

The Boolean capability flag canReturnEarlyAfterIntermediateUpdate in the modelDescription XML file indicates whether the FMU supports the early-return feature. The default value of this capability flag is false. Each time an internal discontinuity or an event happens inside an FMU with capability flag canReturnEarlyAfterIntermediateUpdate = true, the callback function fmi3CallbackIntermediateUpdate is invoked by the FMU. The master can only use this early return functionality if it provides the fmi3CallbackIntermediateUpdate callback function pointer in the instantiate function.

typedef fmi3Status (*fmi3CallbackIntermediateUpdate) (
                   fmi3InstanceEnvironment instanceEnvironment,
                   fmi3Float64 intermediateUpdateTime,
                   fmi3Boolean eventOccurred,
                   fmi3Boolean clocksTicked,
                   fmi3Boolean intermediateVariableSetAllowed,
                   fmi3Boolean intermediateVariableGetAllowed,
                   fmi3Boolean intermediateStepFinished,
                   fmi3Boolean canReturnEarly);

The Co-Simulation master can request the FMU to end the fmi3DoStep at a Newtonian time instant and to do an early return by calling the fmi3DoEarlyReturn function inside the callback function fmi3CallbackIntermediateUpdate. The Co-Simulation master is only allowed to call this function, if canReturnEarly = fmi3True. If the master does not call fmi3DoEarlyReturn the FMU continues the fmi3DoStep computation until the next predefined communication instant (i.e., currentCommunicationPoint + communicationStepSize) or until the next call of fmi3CallbackIntermediateUpdate.

typedef fmi3Status fmi3DoEarlyReturnTYPE(fmi3Instance instance, fmi3Float64 earlyReturnTime);

The FMU should return early from the current fmi3DoStep at the time instant defined by parameter earlyReturnTime.

If the earlyReturnTime is greater than the last signaled intermediateUpdateTime, the FMU may integrate up to the time instant earlyReturnTime.

If the early return is conducted successfully by the FMU it must set the parameter earlyReturn to fmi3True in fmi3DoStep and return fmi3OK. In that case the internal simulation time of the FMU equals the value of earlyReturnTime of the last fmi3DoEarlyReturn call.

If the requested earlyReturnTime is less than the last signaled intermediateUpdateTime or the FMU can not reach the requested earlyReturnTime for other reasons, the FMU must set the parameter earlyReturn to fmi3True in fmi3DoStep and return fmi3Discard and enter state Step Discarded.

In state Step Discarded the Co-Simulation master can retrieve the lastSuccessfulTime via calling fmi3GetDoStepDiscardedStatus. The Co-Simulation master 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 Basic Co-Simulation and Scheduled Co-Simulation.

4.3. Description Schema

This is defined in Section 2.2. Additionally, the Co-Simulation specific element Implementation is defined in the next section.

If the XML file defines an FMU for Basic Co-Simulation, element BasicCoSimulation must be present. It is defined as:

These attributes have the following meaning (all attributes are optional with exception of modelIdentifier):

Attribute Description

Attribute	Description
`modelIdentifier`	Short class name according to C syntax, for example, `A_B_C`. Used as prefix for FMI functions if the functions are provided in C source code or in static libraries, but not if the functions are provided by a DLL/SharedObject. `modelIdentifier` is also used as name of the static library or DLL/SharedObject. See also Section 2.1.1.
`needsExecutionTool`	If `true`, a tool is needed to execute the model. The FMU just contains the communication to this tool (see Figure 4). [Typically, this information is only utilized for information purposes. For example, a Co-Simulation master can inform the user that a tool has to be available on the computer where the slave is instantiated. The name of the tool can be taken from the attribute `generationTool` in `<fmiModelDescription>`.]
`canBeInstantiatedOnlyOncePerProcess`	This flag indicates cases (especially for embedded code), where only one instance per FMU is possible. (For multiple instantiation the default is `false`; if multiple instances are needed, the FMUs must be instantiated in different processes.).
`canNotUseMemoryManagementFunctions`	If `true`, the slave uses its own functions for memory allocation and freeing only. The callback functions `allocateMemory` and `freeMemory` given in `fmi3InstantiateXXX` are ignored.
`canGetAndSetFMUState`	If `true`, the environment can inquire the internal FMU state and restore it. That is, `fmi3GetFMUState`, `fmi3SetFMUState`, and `fmi3FreeFMUState` are supported by the FMU.
`canSerializeFMUState`	If `true`, the environment can serialize the internal FMU state, in other words, `fmi3SerializedFMUStateSize`, `fmi3SerializeFMUState`, `fmi3DeSerializeFMUState` are supported by the FMU. If this is the case, then flag `canGetAndSetFMUState` must be `true` as well.
`providesDirectionalDerivative`	If `true`, the directional derivative of the equations at communication points can be computed with `fmi3GetDirectionalDerivative`.
`canInterpolateInputs`	The slave is able to interpolate `continuous` `inputs`. Calling of `fmi3SetInputDerivatives` has an effect for the slave.
`maxOutputDerivativeOrder`	The slave is able to provide `derivatives` of `outputs` with maximum order. Calling of `fmi3GetOutputDerivatives` is allowed up to the order defined by `maxOutputDerivativeOrder`.
`canHandleVariableCommunicationStepSize`	The slave can handle variable communication step size. The communication step size (parameter communicationStepSize of `fmi3DoStep`) has not to be constant for each call.
`providesIntermediateVariableAccess`	The slave is able to provide access to selected variables during callback function call `intermediateUpdate`. The accessible variables are marked with attribute `intermediateAccess` = `true`.
`canReturnEarlyAfterIntermediateUpdate`	If `true`, the slave is able to return early from `fmi3DoStep` if master calls `fmi3DoEarlyReturn` during callback function call `intermediateUpdate` and `canReturnEarly = true` in `fmi3CallbackIntermediateUpdate`. [If set to `true` and `providesHybridCoSimulation` is set to `false`, the FMU supports the basic functionality of ending DoSteps before the planned next communication point time. This is controlled by the simulation master for avoiding unnecessary computations and roll backs of the FMU due to external events known by the simulation master]
`providesHybridCoSimulation`	If `true`, the slave can be set to Hybrid Co-Simulation during instantiation of FMU. If set to `true` also `canReturnEarlyAfterIntermediateUpdate` must be set to `true`.
`providesScheduledCoSimulation`	If `true`, the slave can instantiated as Scheduled Co-Simulation.
`canNotUseBasicCoSimulation`	If `false`, the slave can be set to Basic Co-Simulation during instantiation of the FMU. [The support of Basic Co-Simulation should be possible for most Co-Simulation FMUs, thus the default value is `false`.]
`fixedInternalStepSize`	The fixed internal step size of the FMU (optional). [This information can be used by the co-simulation master to synchronize the communication interval with the internal step size of the FMU. The co-simulation master should calculate the communication points by multiplying (`number_of_steps * step_size`) instead of repeatedly incrementing (`time += step_size`) to avoid the accumulation of numerical errors.]

modelIdentifier

needsExecutionTool

If true, a tool is needed to execute the model. The FMU just contains the communication to this tool (see Figure 4). [Typically, this information is only utilized for information purposes. For example, a Co-Simulation master can inform the user that a tool has to be available on the computer where the slave is instantiated. The name of the tool can be taken from the attribute generationTool in <fmiModelDescription>.]

canBeInstantiatedOnlyOncePerProcess

This flag indicates cases (especially for embedded code), where only one instance per FMU is possible. (For multiple instantiation the default is false; if multiple instances are needed, the FMUs must be instantiated in different processes.).

canNotUseMemoryManagementFunctions

If true, the slave uses its own functions for memory allocation and freeing only. The callback functions allocateMemory and freeMemory given in fmi3InstantiateXXX are ignored.

canGetAndSetFMUState

If true, the environment can inquire the internal FMU state and restore it. That is, fmi3GetFMUState, fmi3SetFMUState, and fmi3FreeFMUState are supported by the FMU.

canSerializeFMUState

If true, the environment can serialize the internal FMU state, in other words, fmi3SerializedFMUStateSize, fmi3SerializeFMUState, fmi3DeSerializeFMUState are supported by the FMU. If this is the case, then flag canGetAndSetFMUState must be true as well.

providesDirectionalDerivative

If true, the directional derivative of the equations at communication points can be computed with fmi3GetDirectionalDerivative.

canInterpolateInputs

The slave is able to interpolate continuous inputs. Calling of fmi3SetInputDerivatives has an effect for the slave.

maxOutputDerivativeOrder

The slave is able to provide derivatives of outputs with maximum order. Calling of fmi3GetOutputDerivatives is allowed up to the order defined by maxOutputDerivativeOrder.

canHandleVariableCommunicationStepSize

The slave can handle variable communication step size. The communication step size (parameter communicationStepSize of fmi3DoStep) has not to be constant for each call.

providesIntermediateVariableAccess

The slave is able to provide access to selected variables during callback function call intermediateUpdate. The accessible variables are marked with attribute intermediateAccess = true.

canReturnEarlyAfterIntermediateUpdate

If true, the slave is able to return early from fmi3DoStep if master calls fmi3DoEarlyReturn during callback function call intermediateUpdate and canReturnEarly = true in fmi3CallbackIntermediateUpdate. [If set to true and providesHybridCoSimulation is set to false, the FMU supports the basic functionality of ending DoSteps before the planned next communication point time. This is controlled by the simulation master for avoiding unnecessary computations and roll backs of the FMU due to external events known by the simulation master]

providesHybridCoSimulation

If true, the slave can be set to Hybrid Co-Simulation during instantiation of FMU. If set to true also canReturnEarlyAfterIntermediateUpdate must be set to true.

providesScheduledCoSimulation

If true, the slave can instantiated as Scheduled Co-Simulation.

canNotUseBasicCoSimulation

If false, the slave can be set to Basic Co-Simulation during instantiation of the FMU. [The support of Basic Co-Simulation should be possible for most Co-Simulation FMUs, thus the default value is false.]

fixedInternalStepSize

The fixed internal step size of the FMU (optional). [This information can be used by the co-simulation master to synchronize the communication interval with the internal step size of the FMU. The co-simulation master should calculate the communication points by multiplying (number_of_steps * step_size) instead of repeatedly incrementing (time += step_size) to avoid the accumulation of numerical errors.]

The flags have the following default values.
boolean: false
unsignedInt: 0

Note that if needsExecutionTool = true, then it is required that the original tool is available to be executed during co-simulation. If needsExecutionTool = false, the slave is completely contained inside the FMU in source code or binary format (DLL/SharedObject).

4.3.1. Example XML Description File

The example below is the same as shown in Section 3.3.2 for a Model Exchange FMU. The only difference is the replacement of the element <ModelExchange> with the element <BasicCoSimulation> (with additional attributes) and the removal of local variables, which are associated with continuous states and their derivatives. The XML file may have the following content:

<?xml version="1.0" encoding="UTF-8"?>
<fmiModelDescription
  fmiVersion="3.0-alpha.3"
  modelName="MyLibrary.SpringMassDamper"
  instantiationToken="{8c4e810f-3df3-4a00-8276-176fa3c9f9e0}"
  description="Rotational Spring Mass Damper System"
  version="1.0"
  generationDateAndTime="2011-09-23T16:57:33Z"
  variableNamingConvention="structured">
  <BasicCoSimulation
    modelIdentifier="MyLibrary_SpringMassDamper"
    canHandleVariableCommunicationStepSize="true"
    canInterpolateInputs="true"/>
  <UnitDefinitions>
    <Unit name="rad">
      <BaseUnit rad="1"/>
      <DisplayUnit name="deg" factor="57.2957795130823"/>
    </Unit>
    <Unit name="rad/s">
      <BaseUnit s="-1" rad="1"/>
    </Unit>
    <Unit name="kg.m2">
      <BaseUnit kg="1" m="2"/>
    </Unit>
    <Unit name="N.m">
      <BaseUnit kg="1" m="2" s="-2"/>
    </Unit>
  </UnitDefinitions>
  <TypeDefinitions>
    <Float64 name="Modelica.SIunits.Inertia" quantity="MomentOfInertia" unit="kg.m2" min="0.0"/>
    <Float64 name="Modelica.SIunits.Torque" quantity="Torque" unit="N.m"/>
    <Float64 name="Modelica.SIunits.AngularVelocity" quantity="AngularVelocity" unit="rad/s"/>
    <Float64 name="Modelica.SIunits.Angle" quantity="Angle" unit="rad"/>
  </TypeDefinitions>
  <DefaultExperiment startTime="0.0" stopTime="3.0" tolerance="0.0001"/>
  <ModelVariables>
    <Float64 name="inertia1.J" valueReference="1073741824"
      description="Moment of load inertia" causality="parameter" variability="fixed"
      declaredType="Modelica.SIunits.Inertia" start="1"/>
    <Float64 name="torque.tau" valueReference="536870912"
      description="Accelerating torque acting at flange (= -flange.tau)" causality="input"
      declaredType="Modelica.SIunits.Torque" start="0"/>
    <Float64 name="inertia1.phi" valueReference="805306368"
      description="Absolute rotation angle of component" causality="output"
      declaredType="Modelica.SIunits.Angle"/>
    <Float64 name="inertia1.w" valueReference="805306369"
      description="Absolute angular velocity of component (= der(phi))" causality="output"
      declaredType="Modelica.SIunits.AngularVelocity"/>
  </ModelVariables>
  <ModelStructure>
    <Output valueReference="805306368"/>
    <Output valueReference="805306369"/>
    <InitialUnknown valueReference="805306368"/>
    <InitialUnknown valueReference="805306369"/>
  </ModelStructure>
</fmiModelDescription>

4.3.2. Early Return from Current Communication Step

The simulation master collects the information about the capability of an FMU to perform an early return by analyzing the modelDescription.xml as defined in section Section 2.2 and Section 4.

4.3.2.1. Co-Simulation FMU

In order to support the early return in fmi3DoStep the capability flag canReturnEarlyAfterIntermediateUpdate in the XML should be true.

4.3.2.2. Example XML Description File

Here is an example of an XML of an FMU supporting early return.

<?xml version="1.0" encoding="utf-8"?>
<fmiModelDescription
  fmiVersion="3.0-alpha.3"
  modelName="MyLibrary.SpringMassDamper_Early_Return_example"
  instantiationToken="{8c4e810f-3df3-4a00-8276-176fa3c9f9e0}"
  description="Rotational Spring Mass Damper System"
  version="1.0"
  generationDateAndTime="2011-09-23T16:57:33Z"
  variableNamingConvention="structured">
  <BasicCoSimulation
    modelIdentifier="MyLibrary_SpringMassDamper"
    canHandleVariableCommunicationStepSize="true"
    canReturnEarlyAfterIntermediateUpdate="true"/>
  <DefaultExperiment startTime="0.0" stopTime="3.0" tolerance="0.0001"/>
  <ModelVariables>
    <Float64 name="inertia1.J" valueReference="1073741824"
      description="Moment of load inertia" causality="parameter" variability="fixed"
      declaredType="Modelica.SIunits.Inertia" start="1"/>
    <Float64 name="torque.tau" valueReference="536870912"
      description="Accelerating torque acting at flange (= -flange.tau)" causality="input"
      declaredType="Modelica.SIunits.Torque" start="0"/>
    <Float64 name="inertia1.phi" valueReference="805306368"
      description="Absolute rotation angle of component" causality="output"
      declaredType="Modelica.SIunits.Angle"/>
    <Float64 name="inertia1.w" valueReference="805306369"
      description="Absolute angular velocity of component (= der(phi))" causality="output"
      declaredType="Modelica.SIunits.AngularVelocity"/>
  </ModelVariables>
  <ModelStructure>
    <Output valueReference="805306368"/>
    <Output valueReference="805306369"/>
    <InitialUnknown valueReference="805306368"/>
    <InitialUnknown valueReference="805306369"/>
  </ModelStructure>
</fmiModelDescription>

5. FMI for Hybrid Co-Simulation

The notion of clock in FMI for Model Exchange has been extended to the FMI for Co-Simulation.

Both output clocks and input clocks are supported in Co-Simulation with clocks. In order to handle input and output clocks in Co-Simulation, a new Event Mode has been introduced.

The concept and the way input and output clocks are handled are very similar in Model Exchange and Co-Simulation. In order to handle input clocks, the Co-Simulation master schedules input clocks and adjusts the communication steps in such a way that input clock ticks become communication points. At these communication points, the FMU is pushed to the Event Mode and input clocks are handled.

Output clocks, on the other hand, are detected by the FMU. The FMU detects an output clock and informs the master by invoking a callback in which the event time and the event type is communicated to the master. Then FMU stops the current Co-Simulation step and returns back from fmi3DoStep. Then the FMU is pushed to the Event Mode and the event is handled. Note that, since output events time instants are not known in advance, at output event time instants, new communication steps are created.

5.1. Mathematical Description

5.2. Application Programming Interface

If the Boolean capability flag providesHybridCoSimulation and canReturnEarlyAfterIntermediateUpdate = true the Co-Simulation master can use the interface type Hybrid Co-Simulation.

5.2.1. Communication of event time and input/output values

The fmi3CallbackIntermediateUpdate callback described in section Section 4.2.6 is also used in order to communicate the input and output and, in particular, the event and clock time from the FMU to the Co-Simulation master. The fmi3CallbackIntermediateUpdate callback allows internal events (e.g. associated to output clock ticks) to be signaled from an FMU to the Co-Simulation master. If the interface type is Hybrid Co-Simulation, the fmi3CallbackIntermediateUpdate callback must be defined in the instantiate function. In other cases a NULL pointer can be assigned to the fmi3CallbackIntermediateUpdate callback, for instance when the interface type is Model Exchange.

The output arguments of fmi3CallbackIntermediateUpdate are used to signal output clock ticks and internal events to the master.

typedef fmi3Status (*fmi3CallbackIntermediateUpdate) (
                   fmi3InstanceEnvironment instanceEnvironment,
                   fmi3Float64 intermediateUpdateTime,
                   fmi3Boolean eventOccurred,
                   fmi3Boolean clocksTicked,
                   fmi3Boolean intermediateVariableSetAllowed,
                   fmi3Boolean intermediateVariableGetAllowed,
                   fmi3Boolean intermediateStepFinished,
                   fmi3Boolean canReturnEarly);

Argument intermediateUpdateTime is the internal simulation time of the FMU at which the callback has been called. If an event happens or a output clock ticks, intermediateUpdateTime is the time of event or output clock tick. If the FMU signals an earlyReturn = fmi3True and fmi3OK after returning from fmi3DoStep then intermediateUpdateTime is the internal simulation time of the FMU of the last fmi3CallbackIntermediateUpdate call that signaled canReturnEarly = fmi3true. intermediateUpdateTime is also the time of intermediate steps of the internal FMU solver.

The following fmi3Boolean variables define the reasons for the fmi3CallbackIntermediateUpdate call. Several variables can be set by the FMU. Default value of variables is fmi3False.

When argument eventOccurred is fmi3True, the master must call fmi3DoEarlyReturn to do an early return and handle the event via entering Event Mode. In this case, earlyReturnTime argument of fmi3DoEarlyReturn is ignored. In Event Mode the master shall call the fmi3NewDiscreteStates function for gathering related information about the event that occurred at intermediateUpdateTime.
When argument clocksTicked is fmi3True, it means that fmi3GetClock function should be called for gathering all clock related information about ticking output clocks at intermediateUpdateTime. If this flag is fmi3True the master must call fmi3DoEarlyReturn to do an early return and handle the clock event in Event Mode. In this case, earlyReturnTime argument of fmi3DoEarlyReturn is ignored.
When argument intermediateVariableSetAllowed is fmi3True, the FMU signals that intermediate output values can be collected by the Co-Simulation master.
When argument intermediateVariableGetAllowed is fmi3True, the FMU signals that intermediate input values can be set by the Co-Simulation master.
When argument intermediateStepFinished is fmi3True, the FMU signals that the internal solver step for this time instant is complete.
When argument canReturnEarly is fmi3True the master can request the FMU to return early at the current intermediateUpdateTime time instant via calling fmi3DoEarlyReturn within the callback function fmi3CallbackIntermediateUpdate. If canReturnEarly is fmi3False the FMU will not do the early return, regardless of the master request.

Note that only the first discontinuity event at a Newtonian time instant shall be signaled that way. But in Event Mode, there may be an event iteration at a Newtonian time instant and have super-dense time instants.

Based on the information provided by fmi3CallbackIntermediateUpdate, additional information about the discontinuity at that time instant can be obtained by calling fmi3NewDiscreteStates and fmi3GetClock.

The FMU must not call the callback function fmi3CallbackIntermediateUpdate with an intermediateUpdateTime that is smaller than the intermediateUpdateTime given in a previous call of fmi3CallbackIntermediateUpdate with intermediateStepFinished = fmi3True.

5.2.2. Handling a Successful Early-Return by the Co-Simulation Master in Hybrid Co-Simulation

If the FMU is successful in conducting an early return, the return value of the earlyReturn argument in fmi3DoStep is fmi3True, otherwise fmi3False. If the FMU returns from fmi3DoStep with the earlyReturn = fmi3True the Co-Simulation master has to call fmi3EnterEventMode for that FMU.

typedef fmi3Status fmi3EnterEventModeTYPE(fmi3Instance instance,
                                          fmi3Boolean inputEvent,
                                          fmi3Boolean stepEvent,
                                          const fmi3Int32 rootsFound[],
                                          size_t nEventIndicators,
                                          fmi3Boolean timeEvent);

The Co-Simulation master can also call fmi3EnterEventMode at communication instants to handle input events, as will be discussed in following sections.

If an FMU provides the early-return capability that includes the handling of events in Event Mode, the FMU signals this via canReturnEarlyAfterIntermediateUpdate and providesHybridCoSimulation = true in the modelDescription.xml. The master should indicate to the FMU that this early-return feature is also supported by the master. The Co-Simulation master signals to the FMU that it supports and has recognized the early return Co-Simulation capabilities of the FMU by calling the Co-Simulation interface type instantiate function fmi3InstantiateHybridCoSimulation.

The FMU stops computation at the first encountered internal event (if any) and the event time is provided through intermediateUpdateTime. If fmi3DoStep returns with earlyReturn = fmi3True and an event has happened, i.e. eventOccurred = fmi3True, then an event handling has to be done by the Co-Simulation master. In order to start event handling the Co-Simulation master has to call fmi3EnterEventMode for that FMU to push the FMU into Event Mode. In this mode the Co-Simulation master is supposed to catch all events through the fmi3NewDiscreteStates function.

If the early-return request of the Co-Simulation master is ignored by the FMU, then fmi3DoStep returns with earlyReturn = fmi3False. The master can start a resynchronization of FMUs at an event time, if the currentCommunicationPoint has passed the event time, the master can roll-back the FMU and repeat the step with a suitable communicationStepSize (if the FMU supports the roll-back).

In Event Mode and only after fmi3DoStep returned with earlyReturn = fmi3True the function fmi3NewDiscreteStates may be called. Only the following output arguments may be considered:

When newDiscreteStatesNeeded = true, the master should stay in Event Mode and another call to fmi3NewDiscreteStates is required.
When nextEventTimeDefined = fmi3True, an event time is available and the value is given by nextEventTime. This is the case when the model can report in advance the accurate time of the next predictable time event.
When terminateSimulation = fmi3True, the model requested to stop integration and the Co-Simulation master should call fmi3Terminate.

In Event Mode it is allowed to call fmi3Get{VariableType} after fmi3NewDiscreteStates has been called and it is allowed to call fmi3Set{VariableType} before calling fmi3NewDiscreteStates. The FMU leaves Event Mode when the master calls fmi3EnterStepMode.

It is not allowed to call fmi3EnterEventMode or fmi3EnterStepMode for an FMU with interface type Basic Co-Simulation and Scheduled Co-Simulation.

5.2.3. Co-Simulation with Clock Support in Hybrid Co-Simulation

In this section, signaling and retrieving clock ticks as well as the interface for supporting clocks in FMI for Co-Simulation will be discussed. If an FMU for Co-Simulation declares clocks and clocked variables in the modelDescription.xml file, it supports clocks. The Co-Simulation master should indicate the FMU that the master has recognized the clock capabilities of the FMU and supports the clock handling by calling the Hybrid Co-Simulation interface instantiation function fmi3InstantiateHybridCoSimulation. Note, even if no clock is defined by an FMU in modelDescription.xml, the master can instantiate a Hybrid Co-Simulation FMU to be able to use early return with event handling in Event Mode.

If an FMU provides clocks, but the Co-Simulation master does not support or does not want to support early-return or clocks, by setting the interface to Hybrid Co-Simulation, the activation of model partitions inside of the FMU has to be handled internally within fmi3DoStep.

[Remark: Wrapping towards other Co-Simulation interfaces can influence the simulation results. Depending on the model especially wrapping towards Hybrid Co-Simulation may result in divergent simulation results. Especially aperiodic input clocks can not always be sufficiently emulated in modes that do not directly support clocks. Therefore it is recommended that the FMU provides logging information to the user about the influence of the current mode on simulation results, if non-optimal modes are used by the simulation environment.]

typedef fmi3Status fmi3EnterStepModeTYPE(fmi3Instance instance);

5.2.3.1. Transfer of Input / Output Values and Parameters in Hybrid Co-Simulation

If the Co-Simulation master supports clocks, all input clocks of the model should be handled and input clock events should be scheduled by the master. If an output clock ticks, the FMU calls fmi3CallbackIntermediateUpdate with clocksTicked = fmi3True. Then the master must call fmi3DoEarlyReturn to do an early return from fmi3DoStep and push the FMU into Event Mode by calling fmi3EnterEventMode. Once the FMU is in Event Mode, the activation status of output clocks are retrieved by fmi3GetClock function. Then fmi3SetClock (and fmi3SetIntervalDecimal or fmi3SetIntervalFraction if necessary) should be invoked to enable the ticked input clocks. Each clock, that ticks outside of the FMU (i.e. input clock), is activated for an FMU based on its clockReference and an associated fmi3SetClock in Event Mode. fmi3SetClock can activate multiple clocks with each call. An event iteration is possible. Once all clock events are handled for this time instant, the FMU should be pushed into Step Mode by calling fmi3EnterStepMode. In Step Mode, the Co-Simulation master can call fmi3DoStep for the time interval from the current event time instant until the next input event instant. Note that fmi3DoStep may not reach the next input event instant because an early return may occur.

The simulation master sets and gets clock variable values similar to the FMI for Model Exchange, as defined in Section 2.1.9.

5.2.3.2. Computation in Hybrid Co-Simulation

Similar to FMI for Model Exchange, in order to activate input clocks of an FMU, it is required to push the FMU into Event Mode by calling fmi3EnterEventMode. If fmi3DoStep returns with earlyReturn = fmi3True and eventOccurred = fmi3True or clocksTicked = fmi3True, the FMU must be pushed into the Event Mode by calling fmi3EnterEventMode.

In order to retrieve the status of output clocks, fmi3GetClock and fmi3GetIntervalDecimal or fmi3GetIntervalFraction need to be called in the Event Mode. If the fmi3DoStep return value is fmi3OK and earlyReturn = fmi3False, the calling of fmi3GetClock, fmi3GetIntervalDecimal, fmi3GetIntervalFraction, fmi3NewDiscreteStates is only meaningful after fmi3SetClock in the case of super-dense time iterations are desired.

Similar to the Model Exchange case, the allowed call order is fmi3GetClock, fmi3GetIntervalDecimal, fmi3GetIntervalFraction, fmi3Get{VariableType}, fmi3Set{VariableType}. Function calls of this call order can be omitted.

The handling of return values of function calls is identical to Basic Co-Simulation.

If terminateSimulation becomes fmi3True after calling fmi3NewDiscreteStates then the co-simulation should be terminated by calling fmi3Terminate. Once handling of the clock events finished, the master calls fmi3EnterStepMode for that FMU to push it into Step Mode. Note that it is not allowed to call fmi3EnterEventMode or fmi3EnterStepMode in Basic and Scheduled Co-Simulation.

[Usually the Co-Simulation master should be able to derive (but is not forced to do so) the correct communication point times for input clocks in advance and thus it should be able to set the proper communicationStepSize for fmi3DoStep. This might not be possible if an aperiodic input clock of an FMU depends on the ticking of an aperiodic output clock of another FMU or other aperiodic tick sources.]

5.2.4. State Machine of Calling Sequence from Master to Slave in Hybrid Co-Simulation

The following state machine defines the supported calling sequences.

Figure 14. Calling sequence of Hybrid Co-Simulation interface.

In this Co-Simulation interface the following functions must not be called: fmi3ActivateModelPartition including all functions that are specific to Model Exchange.

Unlike the state machine in section Section 4.2.4 the entry state after Initialization Mode is the Event Mode in order to allow the FMU to handle the very first discrete event. Each state of the state machine corresponds to a certain phase of a simulation as follows:

5.2.4.1. State: Slave Setable FMU State

This super state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.1.

5.2.4.2. State: Slave Under Evaluation

This super state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.2.

5.2.4.3. State: Slave Initialized

This super state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.3.

5.2.4.4. State: Instantiated

This super state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.4.

5.2.4.5. State: Configuration Mode

This state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.11.

5.2.4.6. State: Initialization Mode

This state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.5.

5.2.4.7. State: Event Mode

The master and the FMU enter this state when the master calls fmi3ExitInitializationMode in state Initialization Mode or fmi3ExitConfigurationMode in state Reconfiguration Mode or fmi3EnterEventMode in state Step Mode. In order to handle discrete events and clock ticks, the FMU is pushed into the Event Mode by calling fmi3EnterEventMode

Allowed Function Calls
fmi3Terminate: Upon return of fmi3NewDiscreteStates, if terminateSimulation = fmi3True, the master should finish the Co-Simulation by calling fmi3Terminate on all FMU instances.
fmi3EnterConfigurationMode: With this function call the Reconfiguration Mode is entered. This function must not be called if the FMU contains no tunable structural parameters (i.e. with causality = structuralParameter and variability = tunable).
fmi3NewDiscreteStates: In order to handle discrete events fmi3NewDiscreteStates is called. When the output argument newDiscreteStatesNeeded = fmi3True, the FMU should stay in Event Mode and another call to fmi3NewDiscreteStates is required.
fmi3EnterStepMode: Once all events are handled and newDiscreteStatesNeeded = fmi3False, the FMU should be pushed to Step Mode by calling fmi3EnterStepMode, unless it requests to terminate the Co-Simulation by setting terminateSimulation to fmi3True. In this case, a new step can be started from the current communication point time.
fmi3GetClock: The status of clocks can be inquired by this function.
fmi3SetClock: For input clocks, fmi3SetClock is called after entering Event Mode to set the activation status of clocks. For both input and trigerred clocks, this function can be called several times, only if recomputations of clock state are needed during Event Mode.
fmi3GetIntervalDecimal & fmi3GetIntervalFraction: For both output clocks and input clocks it is allowed to call these functions during Event Mode.
fmi3SetIntervalDecimal & fmi3SetIntervalFraction: It is not allowed to call these functions for output, aperiodic and strictly periodic clocks. For input periodic clocks, these functions are called after the first clock activaion.

5.2.4.8. State: Step Mode

This state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.6.

5.2.4.9. State: Intermediate Update Mode

This state in Hybrid Co-Simulation differ from Basic Co-Simulation described in section Section 4.2.4.6 as following:

Allowed Function Calls
fmi3DoEarlyReturn: If canReturnEarly = fmi3True, the Co-Simulation master can request the FMU to end the fmi3DoStep and to do an early return by calling this function.
Forbidden Function Calls: All API functions not listed in the allowed function list, including fmi3GetClock and fmi3SetClock are forbidden in this mode.

5.2.4.10. State: Reconfiguration Mode

This state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.8.

5.2.4.11. State: Step Discarded

This state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.9.

5.2.4.12. State: Terminated

This state in Hybrid Co-Simulation does not differ from Basic Co-Simulation described in section Section 4.2.4.10.

"yellow" are only available for Co-Simulation, the other functions are available both for Model Exchange and Co-Simulation):

Function

FMI 3.0 for Co-Simulation

start, end

Instantiated

Configuration Mode

Initialization Mode

Event Mode

Reconfiguration Mode

Step Mode

stepComplete

stepInProgress

Step Discarded

Intermediate Update Mode

stepCanceled

Terminated

error

fmi3GetReal

fmi3GetInteger

fmi3GetBoolean

fmi3GetString

fmi3SetReal

fmi3SetInteger

fmi3SetBoolean

fmi3SetString

fmi3SetInputDerivatives

fmi3EnterStepMode

fmi3GetOutputDerivatives

fmi3DoStep

fmi3ActivateModelPartition

fmi3DoEarlyReturn

fmi3GetDoStepDiscardedStatus

]

5.2.5. Code Example for Hybrid Co-Simulation

In the following example, the usage of the FMI functions is sketched in order to clarify the typical calling sequence of the functions in a simulation environment. We consider …

The error handling is implemented in a very rudimentary way.

  //////////////////////////
  // Initialization sub-phase

  fmi3EventInfo s_eventInfo;

  // Set callback functions
  callbacks.logMessage          = cb_logMessage;
  callbacks.allocateMemory      = cb_allocateMemory;
  callbacks.freeMemory          = cb_freeMemory;
  // Signal that early return is supported by master
  callbacks.intermediateUpdate  = cb_intermediateUpdate;
  callbacks.lockPreemption      = NULL; // Preemption not active
  callbacks.unlockPreemption    = NULL; // Preemption not active


  // Instantiate slave
  // Create pointer to information for identifying the FMU in callbacks
  callbacks.instanceEnvironment = NULL;

  //set Co-Simulation mode
  fmi3CoSimulationConfiguration coSimulationConfiguration;
  coSimulationConfiguration.intermediateVariableGetRequired         = fmi3False;
  coSimulationConfiguration.intermediateInternalVariableGetRequired = fmi3False;
  coSimulationConfiguration.intermediateVariableSetRequired         = fmi3False;
  coSimulationConfiguration.coSimulationMode                        = fmi3ModeHybridCoSimulation;


  // Instantiate slave
  s = fmi3Instantiate("Slave", fmi3CoSimulation, s_GUID, NULL, &callbacks, fmi3False, fmi3True, &coSimulationConfiguration); // [TODO]: resourceLocation --> NULL?

  if (s == NULL) return EXIT_FAILURE; // error



  // Configuration Mode
  //fmi3EnterConfigurationMode(s);
  //fmi3ExitConfigurationMode(s);


  // Setup Experiment
  // Start and stop time
  startTime = 0;
  stopTime  = 10;
  // Communication constant step size
  h = 0.01;

  // Set all variable start values (of "ScalarVariable / <type> / start")
  //fmi3SetReal / Integer / Boolean / String(s, ...); // [TODO]: To be set.
  //fmi3SetClock(s, ...); // [TODO]: To be set.

  fmi3SetupExperiment(s, fmi3False, 0.0, startTime, fmi3True, stopTime);



  // Initialization Mode
  fmi3EnterInitializationMode(s);

  // Set the input values at time = startTime
  //fmi3SetReal / Integer / Boolean / String(s, ...); // [TODO]: To be set.
  //fmi3SetClock(s, ...); // [TODO]: To be set.

  fmi3ExitInitializationMode(s);



  //////////////////////////
  // Simulation sub-phase
  tc = startTime; // Starting master time
  tStop = stopTime; // Stopping master time
  step = h; // Starting non-zero step size
  inferredClocksTickedS = fmi3False; // [TODO]: To be set.

  mode = eventMode; // [TODO]: @Masoud recheck: continuousTimeMode --> eventMode

  while (tc < tStop) {
    if (0 /* Inferred clock is active at current time tc */) { // [TODO]: To be set.
      /*Set possible active inferred clocks to true or to false*/
      if(mode == stepMode) { // [TODO]: @Masoud recheck: continuousTimeMode --> stepMode
        status = fmi3EnterEventMode(s);
        if ((status == fmi3Fatal) || (status == fmi3Error)) break;
        mode = eventMode;
      };
      //fmi3SetClock(s, ...); // [TODO]: To be set.
      //fmi3SetIntervalDecimal(s, ...); /*Only needed if interval changes*/ // [TODO]: To be set.
      //fmi3SetIntervalFraction(s, ...); /*Only needed if interval changes*/ // [TODO]: To be set.
    };



    if (mode == eventMode) {
      status = fmi3NewDiscreteStates(s, &s_eventInfo);
      if ((status == fmi3Fatal) || (status == fmi3Error)) break;
    }



    if(mode == stepMode) { // [TODO]: @Masoud recheck: continuousTimeMode --> stepMode
      // Step Mode (default mode)
      tend = tc+step;
      t = tend*2;
      earlyReturn = fmi3False;
      status = fmi3DoStep(s, tc, step, fmi3False, &earlyReturn); // [TODO]: noSetFMUStatePriorToCurrentPoint == fmi3False?

      switch (status) {
        case fmi3Discard:
          fmi3GetDoStepDiscardedStatus(s, &discard, &lastSuccessfulTime);
          if (discard == fmi3True) printf("Slave s wants to terminate simulation.");
        case fmi3Error:
        case fmi3Fatal:
          terminateSimulation = fmi3True;
          break;
        default:
          break;
      }

      if (terminateSimulation) break;



      if(earlyReturn) {
        t = s_intermediateUpdateInfo.intermediateUpdateTime;
        /*rollback FMUs to earliest event time*/
        fmi3EnterEventMode(s);
        if ((status == fmi3Fatal) || (status == fmi3Error)) break;
        mode = eventMode;
        tc = t;
      }
      else{
        tc = tend;
      };
    };



    if(s_intermediateUpdateInfo.clocksTicked) {
      //fmi3GetClock(s, ...); // [TODO]: To be set.
      //fmi3GetIntervalDecimal(s, /*Intervals*/,...); // [TODO]: To be set.
      //fmi3GetIntervalFraction(s, /*Intervals*/,...); // [TODO]: To be set.
    };



    if((mode == eventMode) && (s_eventInfo.newDiscreteStatesNeeded == fmi3False) && (1 /*no clocks from GetClock() are active*/)) { // [TODO]: To be set.
      status = fmi3EnterStepMode(s); // [TODO]: @Masoud recheck: EnterContinuousTimeMode --> fmi3EnterStepMode
      if ((status == fmi3Fatal) || (status == fmi3Error)) break;
      mode = stepMode;
      //step = min(/*Intervals*/, s_eventInfo.nextEventTime); // [TODO]: To be set.
    };


    // Get outputs
    //fmi3GetReal/Integer/Boolean/String(s, ...); // [TODO]: To be set.
    // Set inputs
    //fmi3SetReal/Integer/Boolean/String(s, ...); // [TODO]: To be set.

  }


  //////////////////////////
  // Shutdown sub-phase
  if ((status != fmi3Error) && (status != fmi3Fatal)) {
    fmi3Terminate(s);
  }

  if (status != fmi3Fatal) {
    fmi3FreeInstance(s);
  }

5.3. Description Schema

The Co-Simulation master collects the information about the number and properties of clocks supported by the FMU by analyzing the modelDescription.xml, see [clock-type-definition].

The definition of clocks is optional.

Each input clock that ticks outside of the FMU, is activated for an FMU based on their valueReference. Output clocks inside of an FMU signal their activation based on their valueReference`.

[If dependencies (fmi3Unknown) are defined in the <ModelStructure> section of the modelDescription.xml, it is recommended to define such dependencies only within a model partition of a model (i.e. between variables that are assigned to the same clock).]

If dependencies are defined for variables across model partitions, such variables can not be assigned to a clock via clockReference.

For FMI for Co-Simulation, variables that are assigned to a model partition of the model based on clockReference are not necessarily clocked. Such variables can be continuous-time or discrete-time variables if the clock is of clockType = communicationPoint.

5.3.1. Capability Flags

If the XML file defines an FMU for Hybrid Co-Simulation, element CoSimulation must be present as described in section Section 4.

In order to provide a Hybrid Co-Simulation, the attribute providesHybridCoSimulation has set to be set to true.

5.3.2. Example XML Description File

The example below is the same one as shown in Section 4.3.1 for a Co-Simulation FMU. The only differences are, that providesHybridCoSimulation is set to true and clocks are defined in the modelDescription.xml. [TODO]: Recheck later The XML file may have the following content:

//include::examples/co_simulation_clocked_cosimulation.xml[]

6. FMI for Scheduled Co-Simulation

6.1. Mathematical Description

The Scheduled Co-Simulation interface has a different timing concept compared to the other two Co-Simulation interfaces. This is required to cover clock ticks for aperiodic input clocks which may tick at time instances that are not predictable in advance for the simulation master. Typically, hardware I/O or virtual ECU software events belong to this category.

A Co-Simulation master’s call for computing a model partition will compute the results of the model partition defined by an input clock for the current clock tick time $t_i$.

The result values will be computed for the current clock tick time (activation time) $t_i$ from the assigned input clock (which is known to the Co-Simulation master). Refer to the clock time progress definition (Section 2.1.8.1) for periodic clocks.

If required, the FMU can internally derive the clock interval $\Delta T_i$ based on the last clock tick time $t_{i-1}$ i.e. last activation time for this model partition.

A model partition can only be activated once per activation time point $t_i$.

Model partitions that are associated to output clocks will accordingly provide the result values of the model partition’s variables for the current output clock tick time $t_i$ of the active output clock. The activation of such a output clock is not directly controlled by the Co-Simulation master but internally by the FMU.

6.2. Application Programming Interface

This section contains the interface description for supporting the Scheduled Co-Simulation interface from a C program.

The direct scheduling of model partitions based on clock ticks requires an additional handling mode for FMUs. The FMU signals its support for direct model partition scheduling in the modelDescription.xml via the flag providesScheduledCoSimulation = true. The Co-Simulation master signals to the FMU that it supports and has recognized the clock and model partition scheduling capabilities of the FMU by instantiating it as Scheduled Co-Simulation.

If the flag providesScheduledCoSimulation = false, it is not allowed to use the Scheduled Co-Simulation interface.

If no input clocks are defined by the FMU it is not allowed to set providesScheduledCoSimulation to true in the modelDescription.xml.

Error, reset or terminate information is a global state of the FMU. If e.g. an function returns fmi3Discard or fmi3Error this is also assumed for all active or preempted model partitions. In case of fmi3Discard or fmi3Error no repetition of the step is possible, the only possible way to go forward is to enter the Terminated state and to end or to reset the simulation or - if supported - to set the FMU back to a former state.

6.2.1. Transfer of Input / Output Values and Parameters in Scheduled Co-Simulation

The simulation master sets and gets variable values as defined in section Section 2.1.7.

Before scheduling a model partition it is allowed to set all variables assigned to that model partition via its associated clock (including all global variables that are not associated to a clock) via fmi3Set{VariableType}. After the computation of a model partition (call of fmi3ActivateModelPartition with the clockReference of the clock that is associated to the model partition) all variables that are assigned to this model partition (including all global variables that are not associated to a clock) can be retrieved via fmi3Get{VariableType}. Set/get operations have to be atomic for a single variable.

[The value of global variables can be influenced by more than one model partition if multiple model partitions are active at the same time.]

The computational effort has to be predictable, thus all computationally expensive operations needed to calculate a model partition have to be contained within the fmi3ActivateModelPartition function. The simulation master can assume that fmi3Get{VariableType} and fmi3Set{VariableType} operations are not computationally expensive. In Scheduled Co-Simulation the handling of fmi3CallbackIntermediateUpdate callbacks is the same as in section Section 5. The only difference is that an early return has no meaning in this mode and no additional event handling based on fmi3NewDiscreteStates is conducted. All internal events that shall be handled by the Co-Simulation master are signaled via fmi3CallbackIntermediateUpdate. [In this mode it is recommended to restrict such updates by the FMU to output clock ticks for reducing the computational load in real-time simulations.]

6.2.2. Computation in Scheduled Co-Simulation

If this mode is set, the master has to directly control the time of computation of model partitions associated to input clocks. The activation states of output clocks are transported via fmi3CallbackIntermediateUpdate and fmi3GetClock.

Each fmi3ActivateModelPartition call is now associated to the computation of a (publicly disclosed, externally controlled) model partition of the model and therefore to a single defined input clock.

typedef fmi3Status fmi3ActivateModelPartitionTYPE(fmi3Instance instance,
                                                  fmi3ValueReference clockReference,
                                                  fmi3Float64 activationTime);

The fmi3ActivateModelPartition function has the following parameters:

fmi3Instance instance: same meaning as for other fmi3* functions
fmi3ValueReference clockReference: valueReference of an input clock defined in the modelDescription.xml which shall be activated
fmi3Float64 activationTime: simulation (i.e. virtual) time of the clock tick

Scheduling of fmi3ActivateModelPartition calls for each FMU is done by the simulation master. Calls are based on ticks of periodic or aperiodic input clocks. These input clock ticks can be based on clock ticks from FMU external sources (e.g. output clocks of other FMUs) or other external clocks/events/interrupts assigned via the simulation master configuration (such external events can be based on a potentially unpredictable process or can be just simulation time based events e.g. the planned communication point). The fmi3ActivateModelPartition function is not called for output clocks of an FMU.

The value for the fmi3ActivateModelPartition parameter activationTime is the clock tick time $t_i$ from the assigned input clock (which is known to the Co-Simulation master).

Refer to Section 6.1 and Section 2.1.8.1.

This is a different timing concept compared to fmi3DoStep calls. A fmi3ActivateModelPartition call will compute the results of the model partition defined by clockReference (i.e. valueReference of the variable that defines a clock) for the current clock tick $t_i$.

The value for the fmi3ActivateModelPartition parameter activationTime is the clock tick time $t_i$ from the assigned input clock (which is known to the Co-Simulation master). Refer to the clock time progress definition (Section 2.1.8.1) for periodic clocks.

If required, the FMU can internally derive the clock interval $\Delta T_i$ based on the last clock tick time $t_{i-1}$ i.e. last activationTime for this clockReference (based on last fmi3ActivateModelPartition call).

It is not allowed to call fmi3ActivateModelPartition for a clockReference (i.e. valueReference of clock variable) more than once for the same activationTime $t_i$.

6.2.3. State Machine for Scheduled Co-Simulation

This section summarizes the available states and the allowed function calls in the respective states. All states must not be entered or exited concurrently for model partitions of an FMU but only for the whole FMU instance.

Figure 10: Calling sequence of Scheduled Co-Simulation.

In Scheduled Co-Simulation the following functions must not be called: fmi3DoStep, fmi3NewDiscreteStates, fmi3SetClock, fmi3SetIntervalDecimal, fmi3SetIntervalFraction, fmi3DoEarlyReturn, fmi3EnterEventMode, fmi3EnterStepMode including all functions that are specific to the Model Exchange interface.

The states Configuration Mode, Instantiated, Initialization Mode, and Terminated are handled in the same way as in Co-Simulation, with the exception that the generally not allowed functions of Scheduled Co-Simulation must not be called.

6.2.3.1. State: Slave Settable FMU State

In all states of this super state it is allowed to call fmi3GetFMUState, fmi3SetFMUState, fmi3FreeFMUState, fmi3SerializedFMUStateSize, fmi3SerializeFMUState, fmi3DeSerializeFMUState, fmi3Reset, fmi3GetVersion, fmi3SetDebugLogging and fmi3FreeInstance.

If any function returns with fmi3Fatal the FMU enters the terminal state.

6.2.3.2. State: Slave Under Evaluation

This super state is entered by the FMU when fmi3InstantiateXXX is called. If any function returns fmi3Error or fmi3Discard the FMU enters state Terminated.

6.2.3.3. State: Slave Initialized

This super state is entered by the FMU when fmi3ExitInitializatoinMode is called. If the function fmi3Terminate is called, the FMU enters state Terminated from all states of this super state. The FMU enters state Terminated only after all other tasks related to the computation of model partitions of this FMU have ended. After fmi3Terminate has been called no new tasks can be started (e.g. related to output clock ticks) and all other function calls for this FMU must return fmi3Error until the state Terminated is reached.

6.2.3.4. State: Clock Activation Mode

The FMU enters this state when the master calls fmi3ExitInitializationMode in state Initialization Mode or fmi3ExitConfigurationMode in state Reconfiguration Mode. In this state the master can create multiple concurrent tasks related to an FMU and in each task the master can activate one or multiple input clocks of an FMU based on the defined clock properties via a fmi3ActivateModelPartition call for each clock.

Allowed Function Calls
fmi3ActivateModelPartition: If the function returns with fmi3OK or fmi3Warning the FMU stays in this state. In case of fmi3Fatal the master can prematurely end all tasks related to the computation of model partitions of this FMU. In case of fmi3Discard or fmi3Error the master must wait until all other tasks related to the computation of model partitions of this FMU have ended, but no new tasks can be started (e.g. related to output clock tick) and all other function calls for this FMU must also return fmi3Discard or fmi3Error until the state Terminated is reached.

It is recommended to call fmi3Set{VariableType} and fmi3Get{VariableType} in the same task as fmi3ActivateModelPartition for setting and retrieving variable values associated to a clock activation.
fmi3Set{VariableType}, fmi3SetInputDerivatives: Is called before the start of the computation of a model partition (i.e. before call of fmi3ActivateModelPartition) and only for global variables and variables associated to the input clock assigned to the model partition.

The restrictions related to variable causality and variability defined for Step Mode in Basic Co-Simulation apply.

If the function returns with fmi3OK or fmi3Warning the FMU stays in this state. In case the function returns fmi3Fatal the master can prematurely end all tasks related to the computation of model partitions of this FMU. In case the function returns fmi3Discard or fmi3Error the master must wait until all other tasks related to the computation of the model partitions of this FMU have ended, but new tasks must not be started (e.g. related to output clock ticks) and all other function calls for this FMU must also return fmi3Discard or fmi3Error until the state Terminated is reached.
fmi3Get{VariableType}, fmi3GetOutputDerivatives, fmi3GetDirectionalDerivative`: Is called after the end of the computation of a model partition (i.e. after return of fmi3ActivateModelPartition) and only for global variables and variables associated to the input clock assigned to the model partition.

The restrictions related to variable causality and variability defined for Step Mode in Basic Co-Simulation apply.

If the function returns with fmi3OK or fmi3Warning the FMU stays in this state. In case the function returns fmi3Fatal the master can prematurely end all tasks related to the computation of model partitions of this FMU. In case the function returns fmi3Discard or fmi3Error the master must wait until all other tasks related to the computation of model partitions of this FMU have ended, but new tasks must not be started (e.g. related to output clock ticks) and all other function calls for this FMU have to also return fmi3Discard or fmi3Error until the state Terminated is reached.

It is not allowed to call fmi3Get{VariableType} functions after fmi3Set{VariableType} functions without an fmi3ActivateModelPartition call in between.

Example:

Correct calling sequence for a model partition of an FMU

Wrong calling sequence

fmi3Set{VariableType} on inputs
fmi3ActivateModelPartition
fmi3Get{VariableType} on outputs
fmi3Set{VariableType} on inputs
fmi3ActivateModelPartition
fmi3Get{VariableType} on outputs

fmi3Set{VariableType} on inputs
fmi3ActivateModelPartition
fmi3Get{VariableType} on outputs
fmi3Set{VariableType} on inputs
fmi3Get{VariableType} on outputs // not allowed
fmi3ActivateModelPartition
fmi3Get{VariableType} on outputs

]

fmi3CallbackIntermediateUpdate: Only in this state the FMU is allowed to call the callback fmi3CallbackIntermediateUpdate. The callback may be called from concurrent tasks within fmi3ActivateModelPartition. The function must not return fmi3Discard.
fmi3EnterConfigurationMode: This function must not be called if the FMU contains no structural parameters or other tasks related to the computation of model partitions of this FMU are currently active or preempted. Thus this function can not be called concurrently for model partitions of an FMU but only for the whole FMU instance.

If the function returns with fmi3OK or fmi3Warning the FMU goes into state Reconfiguration Mode.
fmi3Terminate, fmi3Reset, fmi3FreeInstance: These functions can not be called concurrently for model partitions of an FMU but only for the whole FMU instance. If these functions are called while a model partition of an FMU is currently active or preempted, the FMU changes its state after the computation of all model partitions of this FMU has ended.
fmi3GetFMUState, fmi3SetFMUState, fmi3FreeFMUState,fmi3SerializedFMUStateSize, fmi3SerializeFMUState, fmi3DeSerializeFMUState: Can be called if no other task related to the computation of model partitions of this FMU is currently active or preempted and the prerequisites defined for these functions in Basic Co-Simulation are fulfilled. Thus these functions can not be called concurrently for model partitions of an FMU but only for the whole FMU instance.
Forbidden Function Calls: Additionally to the generally forbidden functions in Scheduled Co-Simulation as listed above, the following functions must not be called in this state: fmi3ExitConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3GetDoStepDiscardedStatus.

6.2.3.5. State: Intermediate Update Mode

In this state the master can retrieve information from the FMU between communication points. Functions called in this state must not return fmi3Discard.

The FMU enters this state by calling fmi3CallbackIntermediateUpdate within fmi3ActivateModelPartition and leaves the state towards state Clock Activation Mode if the function returns fmi3OK or fmi3Warning. If the function returns fmi3Error the FMU enters state Terminated. If the function returns fmi3Fatal the FMU enters the terminal state.

Forbidden Function Calls: The same functions which are not allowed to be called in Clock Activation Mode must not be called in this state. Additionally the following functions must not be called fmi3ActivateModelPartition, fmi3EnterConfigurationMode, fmi3Terminate.
Allowed Function Calls: For a output clock only the first call of fmi3GetClock for a specific activation of this clock signals fmi3True. The FMU sets the reported activation state immediately back to fmi3False for the following fmi3GetClock calls for that clock (in the same or other model partitions of the FMU) until this output clock is internally activated again. The master can call fmi3Set{VariableType} and fmi3Get{VariableType} during the callback for variables associated to a output clock that is active during this callback. Also intermediate variable access is allowed as defined in Section 4.2.4.7

[Based on the FMI standard it cannot be determined which part of the code of an FMU has called the callback function fmi3CallbackIntermediateUpdate. This is especially the case for Scheduled Co-Simulation where multiple model partitions can be active at the same time. This causes no issues since all function call prerequisites are connected to the activation state of clocks, modelDescription.xml information and additionally available information from fmi3CallbackIntermediateUpdate]

6.2.3.6. State: Reconfiguration Mode

In this state structural parameters with variability = tunable can be changed. This state is entered from state Clock Activation Mode by calling fmi3EnterConfigurationMode and left back to Clock Activation Mode by calling fmi3ExitConfigurationMode.

Allowed Function Calls

fmi3ExitConfigurationMode
fmi3Set{VariableType}: Only for variables with causality = structuralParameter and variability = tunable.

Forbidden Function Calls

Additionally to the generally forbidden functions in Scheduled Co-Simulation listed above the following functions must not be called in this state: fmi3EnterConfigurationMode, fmi3InstantiateXXX, fmi3SetupExperiment, fmi3EnterInitializationMode, fmi3ExitInitializationMode, fmi3GetDoStepDiscardedStatus, fmi3ActivateModelPartition,fmi3SetInputDerivatives, fmi3GetDirectionalDerivative, fmi3GetOutputDerivatives, fmi3Get{VariableType}, fmi3DoEarlyReturn

Function

FMI 3.0 for Scheduled Co-Simulation

Start, End

Instantiated

Initialization Mode

Configuration Mode

Clock Activation Mode

Reconfiguration Mode

Intermediate Update Mode

Terminated

Error

Fatal

fmi3GetReal

fmi3GetInteger

fmi3GetBoolean

fmi3GetString

fmi3SetInteger

fmi3SetReal

fmi3SetBoolean

fmi3SetString