MotionSolve Models as a Functional Mockup Unit (FMU)

Learn about how you can leverage Functional Mockup Units (FMUs) to couple your MBS model with external solvers or processes to perform co-simulation or couple systems.

An FMU can be thought of as a stand-alone modeling unit that implements the Functional Mockup Interface or FMI. Converting your 3D MotionSolve model into an FMU enables you to represent your MBS system in a 1-D block environment simulator like Altair/Twin Activate®.

Figure 1. A MotionSolve model inside a 1D block simulation environment


A common usage scenario for FMUs is to import them into a 1-D simulator (example, Figure 1) and connect them with other systems like controls, hydraulics, thermal etc. to enable co-simulation analyses. More information on the FMI can be found at www.fmi-standard.org/.

FMUs can be one of two types:
Model Exchange
Briefly, such an FMU contains within it a set of equations that must be solved by the calling program.
Co-simulation
Such an FMU solves its model equations independent of the calling program and only communicates certain signals to and from the calling program.
Figure 2. Coupling a co-simulation FMU with other systems in a 1-D environment


The FMI implemented by MotionSolve is for the co-simulation flavor only and conforms to 2.0 versions of the standard. Further, the co-simulation FMU generated by MotionSolve is a “tool-coupling” FMU which means that the FMU contains all the information to “couple” MotionSolve with the calling program, but the MotionSolve solver resides and runs independently of the calling program to generate simulation results.
Figure 3. A MotionSolve FMU which is based on “tool-coupling” in a 1-D environment


The “tool-coupling” FMU needs to know where the MotionSolve solver is when a co-simulation is requested.

MotionSolve currently offers several native co-simulation interfaces for coupling your MBS model to systems like:
  • Controls (Simulink, Twin Activate)
  • Hydraulics (Simulink, Twin Activate, DSHPlus)
  • Thermal (Simulink, Twin Activate)
  • Fluids (AcuSolve)
In view of the above, what advantage does the FMI co-simulation approach offer?
Generality
Since the FMI is a standard that is increasingly being adopted in the CAE industry, the distinct advantage of the FMI is generality. Any solver that implements the FMI can be coupled with several other solvers, systems or processes, which makes creation and management of a co-simulation pipeline easier.
Portability
The FMU is self-descriptive and all the libraries and resources required to run the co-simulation FMU are contained within the FMU itself. Thus, this FMU can easily be re-used between models, assemblies, systems and even machines running the same platform.

Creating an FMU from a MotionSolve Model

You can easily create an FMU from any MotionSolve model from within MotionView. The process for setting up your model for co-simulation remains the same as for other interfaces.
  • The MotionView (MBS) model should contain at least a Solver Array of type Plant Output. This solver array should refer to at least one solver variable that act as a channel of output from the FMU. The solver variable channel output from FMU becomes input to other components in the external system.

    In order for the MBS model to receive input/s from the external system, a Solver Array of type Plant Input is necessary, though not mandatory to generate an FMU. This solver array also refers to one or more solver variables.

Export a Model as FMU
  1. From the menu bar at the top, go to File > Export > Functional Mock-up Unit to display the FMU Editor dialog.
  2. Review the Inputs and Outputs channels from their respective tabs.
  3. From the Parameters tab, select model attributes to declare parameters for the FMU.
    Note: Parameters help in varying the FMU system configuration for the simulation. This enables FMU to be designable through a finite set of parameters.
  4. Select a file to export to in Select FMU file.
  5. Click Export.
The generated FMU contains the following:
  1. A description of the FMU, contained within “modelDescription.xml”.
  2. The MotionSolve specific FMU libraries within the “bin” folder.
  3. The MotionSolve model file in MDL format. If your model contains additional property files or user subroutine files, then these are packaged too.
    Note: User subroutine or property files found within the HW installation are not packaged, to manage the size of the FMU and avoid issues with software versions.

Connecting and co-simulating the MotionSolve FMU with other systems

This MotionSolve FMU can be used with any software that supports import of co-simulation FMUs. Altair’s 1-D simulation environment, sT/Twin Activate is an example of such a software. In order for the co-simulation to work with the other simulation environments, the following requirements must be satisfied.
  1. Version 2017.1 or later is needed.
  2. A Altair product license is required.

    The license file ALTAIR_LIC.dat can be either saved into altair_install/security (the default location on Windows for altair_install for v2017 is C:/Program Files/2017) or set an environment variable ALTAIR_LICENSE_PATH that points to the license file where it is saved. This environment variable can also be used to draw license from a server. Refer to Connecting to the Altair License Manager for more details.

    Set the following environment variables based on the version and Operating System:
    Version Windows Linux
    2017/2018 ALTAIR_FMU_ROOT=altair_install

    NUSOL_DLL_DIR= altair_install/hwsolvers/motionsolve/bin/win64

    		 Not available
    2019 ALTAIR_FMU_ROOT=altair_install Not available
    2020 and later ALTAIR_FMU_ROOT=altair_install ALTAIR_FMU_ROOT=altair_install/altair

    LD_LIBRARY_PATH= altair_install/altair/hwsolvers/motionsolve/bin/linux64: altair_install/altair/hwsolvers/common/bin/linux64: $LD_LIBRARY_PATH

    (MotionSolve solver and licensing location is being appended to the LD_LIBRARY_PATH environment variable)
    altair_install (examples for v2023): C:/Program Files/Altair/2023 in Windows or /homes/applications/2023 on Linux

For the rest of this topic, we will use Twin Activate as our 1-D simulator to demonstrate the workflow:

Within Twin Activate, you can load in the MotionSolve FMU using the FMU Import block available in the CoSimulation palette through the Palette Browser.
Figure 4.


Once dropped into the main window, double click on the block:
  1. Browse to the .fmu file that was exported.
  2. Set the value of the input ports.

    Twin Activate by default sets a dependency vector based on the number of outputs.

  3. Provide an output file location for the .mrf file (MotionSolve Result File) as a string.
Figure 5.


Note: Entity data members that are selected as parameters using the Parameters tab in the FMU Editor during export in MotionView will be listed under the Parameters section. These parameters can be varied for a simulation. During the solution, MotionView will modify the model as per the new values of the parameter and export a MotionSolve XML corresponding to the modified model.
In addition, you can go to the Advanced tab and specify a directory where the FMU can be unpackaged. By default, Twin Activate uses the temp directory to unpack in case it is not specified. Note that the MotionSolve Output file location is relative to the unpacking directory, if a relative path is provided.
Figure 6.


You can connect the inputs and outputs from the MotionSolve FMU to the rest of your control system depending on the number of inputs and outputs specified in the MotionSolve model.
Figure 7.


MotionSolve simulation settings are controlled within the MotionSolve model, however, the simulation end time may be modified automatically depending on the simulation end time of the calling program.

Click on the Run the simulation (Play) button on the ribbon at the top:
Figure 8.


When a co-simulation is started, MotionSolve is invoked by the co-simulation FMU. Currently, it is assumed that a MotionSolve installation is available on the machine where the FMU is being used. Once invoked, MotionSolve talks to the calling program and communicates with it.

As with other co-simulation interfaces within MotionSolve, the quality of results is controlled by choosing an acceptable trade-off between accuracy and performance. So, simulation results obtained using a time step that is an order of magnitude smaller may be more accurate, but they will be achieved at a higher cost of performance.

A unique ability of abstracting your MBS model as an FMU is being able to connect several MotionSolve models between one another.

This allows you to connect systems that are captured in different MotionSolve models together. Since there are no restrictions on how the signals from the MotionSolve FMU are connected, you can even run multiple, stand-alone MotionSolve FMUs to compare design, for example.

See MV-7011: Co-Simulation with Twin Activate via Function Mockup Interface (FMI) for additional information.