Introduction

The CDP FMI2Cosimulation operator enables importing of simulation models compliant with the FMI 2.0 Co-Simulation standard into your CDP applications.

The Functional Mock-up Interface (FMI) is a tool-independent standard for the exchange of simulation models. It defines a standardized interface for the integration of simulation models into computer simulations, facilitating the development of complex cyber-physical systems.

This standard defines a container, known as a Functional Mock-up Unit (FMU), for exchanging dynamic simulation models. An FMU is basically a ZIP file containing XML files, binaries, and C code, facilitating portability and tool independence. It is supported by 200+ tools and maintained as a Modelica Association Project.

By using FMUs, simulation models can then be shared and reused across different platforms, enabling collaborative development and system-level simulation without requiring specific tool dependencies. FMI aims to improve interoperability, reduce integration effort, and enhance model reusability, leading to a more streamlined, scalable, and cost-effective development process for multi-domain and complex engineering systems.

BouncingBall python example from https://fmi-standard.org/ and the same FMU in CDP Studio Analyze mode

The FMI2Cosimulation operator can load and execute FMUs (Functional Mock-up Units) that follow the FMI 2.0 Co-Simulation standard.

Quick links:

• FMIVariable
• FMI2Cosimulation Configuration Options
• FMI2Cosimulation Operator Example

Supported Platforms

The imported FMU files include pre-compiled binaries for various platforms but according to the FMI 2.0 standard, only x86 architecture is supported. As CDP only provides 64-bit toolkits for x86, the following platforms are compatible with the FMI2Cosimulation operator:

• Windows 64-bit
• Linux 64-bit

Usage

To use the FMI2Cosimulation operator, it is recommended to first run the FMU Discoverer tool which scans the FMU file and automatically generates the necessary configuration.

Configuring With FMU Discoverer

Running the FMU Discoverer

1. Create a system.
2. Click on the options menu next to the resource search and select Discover FMU Resources... from the context menu.
3. Click to browse the FMU. Either provide the path to a .fmu file or the already unzipped FMU directory.
4. Select the types of variables to discover (hover to see the tooltips for more information). Usually, the default options are sufficient but the others can be useful for debugging.
5. Press OK to start the discovery.
6. Optionally, have a look at the General Messages pane for the discoverer output. Any errors will be displayed there.
7. If successful, the discovered configuration will be available in the Resource tree.

Adding the Discovered FMU to the System

1. From the Resource tree, add the discovered FMU .
2. Optionally, adjust the FMUPath property which after discovery will be the absolute path to the FMU on your local PC.
   • For smaller FMUs or remote deployments, it is recommended to click the browse button when editing the FMUPath and use the CDP Studio file dialog to select the FMU file and enable the "Copy the file to application folder" option. This ensures the FMU is copied to the project and automatically deployed with the system to the target device.
   • For larger FMUs (which can be several GB) or local deployments, it is advisable to manually unzip the FMU and provide the path to the unzipped directory. This approach helps avoid long deployment times, multiple copies consuming disk space, and slow startup times (as the application would otherwise need to unzip the FMU at startup).
3. Optionally, for readability, rename any of the discovered variables and remove any unnecessary ones. Keep only variables which are needed for syncing data between the FMU and the CDP application or are useful for monitoring the FMU's internal state.
4. Optionally, adjust the AutoStart and Debug properties as needed.
5. If AutoStart is false, send the Start message to begin the simulation.

Tips

• In a regular CDP application, the FMI2Cosimulation operator is executed with the parent component's fs (frequency). If necessary add the operator into a dummy container CDPComponent to set the desired frequency.

  Note: For FMUs with heavy computational loads, it is advisable to set the SchedulingGroup property of the parent component to something other than "Default" (each scheduling group runs in its own thread). See Priority levels and scheduling groups for more information.

• If the FMI2Cosimulation operator is added to a Simulator Application within a DynamicSimComponent then the simulation time step along with simulation start, stop and reset will be managed by the SimulatorManager component.

  Note: The AutoStart property is ignored when using SimulatorManager, as the simulation start is managed by the manager.

• Disable the OverrideFMUStartValue property of an FMIVariable to prevent the Value property from overriding the FMU's default start value.
• During runtime, stop the simulation (with the Stop message) to edit output variables and fixed parameters. During simulation, only inputs and tunable parameters can be modified.
• The Debug property can be used to set the debug level of the FMU, allowing for more detailed logging if needed.

Manual Configuration

While the FMU Discoverer tool can automatically generate the configuration for an FMU, one can also manually configure the FMU by following these steps:

1. From the Resource tree, add a CDPSim.FMI2Cosimulation operator to your component.
2. Configure the operator with the path to your FMU file via the FMUPath property. Either provide the path to the FMU file or the already unzipped FMU directory.
3. From the Resource tree, add one or more FMIVariables into the FMI2Cosimulation operator to define the variables to be exchanged between the FMU and the CDP application.
4. Set up the variables by specifying FMUMapping (the full, unique name of the variable in the FMU) and check the Input property if the variable is an input.

   Note: If the FMUMapping property of an FMIVariable is empty, the variable Name will be used to map to the FMU variable. However, using the FMUMapping property is recommended to avoid conflicts with reserved characters in CDP names (e.g., dots and slashes are not allowed).

5. Either set the Value (the initial value) or uncheck OverrideFMUStartValue (whether the Value overrides the FMU's default start value).

The rest of the configuration is the same as for the discovered FMU.

Configuration

Properties

The following properties are available for configuration:

Messages

The following messages can be sent to control the simulation:

FMIVariable

Each FMIVariable element represents a variable to be exchanged with the FMU.

Properties

In addition to the above properties, the FMIVariable element shows the following read-only settings. These are retrieved from the FMU for information purposes and cannot be modified:

Error Handling

If the FMI2Cosimulation operator fails to load an FMU or encounters an error during simulation, it reports configuration faults:

• The FMUState property may show "Uninstantiated".
• The FMUStatus property may indicate "Error" or "Fatal".
• The ConfigurationFaults alarm of the parent component is set. Check the CDP Studio Alarms pane for more information about the error.
• All errors are printed to the CDP Studio Application Output pane. Set the Debug property to 2 to also get info and verbose level printouts.

Example - Bouncing Ball FMU

This example demonstrates how to configure an FMI2Cosimulation operator to run the standard reference "Bouncing Ball" FMU. The FMU simulates a ball bouncing on the ground, with the height and velocity of the ball as output variables.

You can download the FMI 2.0 reference FMU files, including the BouncingBall, from the Modelica GitHub page.

Setup

1. Add a container CDPComponent to your system.
2. Configure the container component fs as needed. This will determine the simulation time step.
3. Add an FMI2Cosimulation operator named "BouncingBall" to your component.
4. Set the AutoStart property to false to manually control the simulation start.
5. Set the FMUPath property to the location of your FMU file, e.g., "BouncingBall-v2.0.fmu".
6. Add some FMIVariables to the operator:
   • Height: An output variable representing the height of the ball.
     • Set Input to false.
     • Set FMUMapping to "h".
     • Set Value to the initial height, e.g., 100.
   • Velocity: An output variable representing the velocity of the ball.
     • Set Input to false.
     • Set FMUMapping to "v".
   • CoefficientOfRestitution: A parameter controlling the bounciness of the ball.
     • Set Input to true.
     • Set FMUMapping to "e".
     • Set Value to 0.9.

Running the Simulation and Verifying Results

1. Right-click on the Height and Velocity variables and select Add to Plot.
2. Run the system.
3. Start the simulation by sending the Start message to the operator.
4. Observe the outputs (Height and Velocity) as the simulation progresses.
5. Check Analyze mode to view the Height and Velocity variables in the plot.

Simulation Control

• During simulation, you can modify tunable parameters (e.g., CoefficientOfRestitution) even while the simulation is running.
• Outputs are read-only during simulation but become read-write when the simulation is stopped.
• During the simulation, outputs (Height and Velocity) are updated according to the FMU's logic.
• To stop the simulation, send the Stop message.
• To reset the FMU, send the Reset message. This restores all variables (except parameters) to their initial values.

Handling Variable Limits

The FMU may define minimum and maximum values for variables:

• Attempting to set a value below the minimum will result in the variable being set to the minimum.
• Attempting to set a value above the maximum will result in the variable being set to the maximum.
• For example, CoefficientOfRestitution has a minimum of 0.5 and a maximum of 1:
  • Setting it to 0.4 will result in it being set to 0.5.
  • Setting it to 1.1 will result in it being set to 1.

See Also

• FMI Standard Documentation
• SimulatorManager Documentation
• DynamicSimComponent Class