4_3_basic_co-simulation_schema.adoc

Description Schema

This is defined in [fmi-description-schema]. Additionally, the Co-Simulation specific element Implementation is defined in the next section.

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

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

Attribute Name	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 [header-files-and-naming-of-functions].
needsExecutionTool	If true, a tool is needed to execute the model. The FMU just contains the communication to this tool (see [figure-co-simulation-with-tool-coupling]). [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 attribute generationTool of 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 [fmi3Instantiate] 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 fmi3HybridCoSimulation 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 fmi3CoSimulation 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.]

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

Example XML Description File

The example below is the same as shown in [xml-example-model-exchange] for a Model Exchange FMU. The only difference is the replacement of the element ModelExchange with the element CoSimulation (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:

link:examples/co_simulation.xml[role=include]

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 [fmi-description-schema] and [fmi-for-basic-co-simulation].

Co-Simulation FMU (CoSimulation)

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

Example XML Description File

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

link:examples/co_simulation_early_return.xml[role=include]