Directional derivatives

In addition to the Temporal analysis mode, Simcenter Amesim offers a Linear analysis mode, which enables the evaluation of a locally linearized form of the model, for example for evaluating the time constants of the model, given by the eigenfrequencies of the Jacobian matrix (refer to the Linear Analysis manual for more details). This mode relies upon the computation of the Jacobian and partial derivative matrices of the time-derivative of the continuous-time state variables or some selected observer variables with respect to some selected control variables and to the continuous-time state variables.

As of the version 2.0 of the FMI specification, it is possible for an FMU to provide these partial derivatives (see ref.3). The permitted combinations are:

• the directional derivative1 of the time-derivative of a continuous-time state variable with respect to some input variables in the direction or to some continuous-time state variables in the direction defined by:

• the directional derivative of an output variable with respect to some input variables in the direction , or to some continuous-time state variables in the direction , defined by:

For Model Exchange, the directional derivatives can be evaluated at any time during simulation. For Co-simulation, it applies to the underlying model independently of the numerical solver being used, and it can be evaluated at each co-simulation time step.

Note

Due to a specific limitation of Simcenter Amesim, the directional derivatives cannot be evaluated during the Initialization Mode of both the Model Exchange and Co-simulation state machines of calling sequence. The fmi2GetDirectionalDerivative function can only be called in the modelInitialized macro-state of Model Exchange, or in the slaveInitialized macro-state of Co-simulation. Any call of this function by the importing environment in the Initialization Mode yields an error message.

Providing directional derivatives is an optional feature of the FMI 2.0 and 3.0 specifications. In the FMU Export Assistant, it is enabled by selecting a checkbox called Provide directional derivatives when applicable. It only makes sense when one of the two following interface types are selected: FMI for Model Exchange 2.0 or FMI for Co-simulation 2.0 or 3.0. If an FMI 1.0 interface type is selected, it is simply ignored.

Figure 59: The FMU Export Assistant with the directional derivatives checkbox selected

When enabled, the corresponding providesDirectionalDerivative flag attribute is set to true in the ModelExchange or CoSimulation tags of the model description, and the FMI importing environment is able to call the fmi2GetDirectionalDerivative function of the FMI Application Programming Interface. The following table summarizes the availability of the directional derivatives with respect to the different combinations of targets and numeric solver used in Simcenter Amesim to simulate the original model:

FMI type and targets for export	Simcenter Amesim numerical solver required for simulating the model
Variable step size; Explicit system	Fixed step size; Explicit system	Variable step size; Implicit system
Model Exchange 2.0 (native binary format)	Available	Available
Co-simulation 2.0 or higher (native binary format)	Available	Available	Available
Co-simulation 2.0 or higher (real-time target)		Not available 2

Regarding the case of implicit systems that are high-index DAE, please note that the directional derivative is not unique, since it depends on the pivoting strategy chosen by the index reduction algorithm. For example, consider the following system of DAE:

where is an input variable. If the third equation is differentiated once, it gives:

Substituting equation (i) yields:

This equation has to be differentiated again:

Substituting equation (ii) yields:

A final differentiation is needed to obtain an ODE, which tells that the DAE index is 3:

The final ODE is obtained by replacing equation (iii) by equation (v) which depends on the third time-derivative of the input, for which the FMI specification does not give a way to express the dependency. Regarding the differential equation in , two forms are possible, since in equations (ii) and (iv) the leading coefficients of the left-hand side are the same (it is 1), and so the pivoting strategy can choose any of these equations to build the final reduced ODE.

The first possible ODE system is:

and the second possible ODE system is:

In the first case the directional derivative of is , whereas in the second case it evaluates to 0, since the dependency on the time-derivatives of the input variables cannot be computed within the FMI specification. The actual value provided by the FMU, or 0, depends on the order in which the submodels are added and connected on the sketch.

By enabling the debug logging messages in the FMI environment, the DAE index is reported at each call to the fmi2GetDirectionalDerivative function, if the system is a high-index DAE. The debug message reads as: “Index of nilpotency is n”, with n the index that can take values as high as five in some rare cases. This way, the potential non-uniqueness issue of the directional derivative can be known.

1

This is also known as the Fréchet derivative, i.e. a differential form in

2

This means that if the

Provide directional derivatives when applicable

and the

FMU for real-time

checkboxes are simultaneously selected, an FMU for real-time is actually generated and the directional derivatives option is ignored.