Contents Previous Next Index
1 Getting Started
1.1 FMI Code Generation Steps
This chapter describes how to use the FMI app and in the Example: RLC Circuit Model section of this chapter, a step by step procedural example shows you how to create an FMU archive file. The FMU Generation app consists of the following steps to generate C code:
Subsystem selection
Inputs/Outputs and parameter management
FMI code generation options
Generate FMI C code
View generated FMI C code
The FMI Connector package
The FMI Connector package is a collection of procedures for manually generating and compiling FMI code from MapleSim models. For information about the FMI Connector package, in Maple, refer to the FMIConnector help page.
1.2 Opening the FMU Generation App
To open the FMU Generation app:
From the main toolbar in MapleSim, click Show Apps Manager ( ).
Double-click the FMU Generation entry in the Apps palette. The FMU Component Code Generation app opens.
In the Subsystem Selection section, select a subsystem from the drop down list.
1.3 Using the FMU Generation App
The MapleSim FMI Connector provides an FMU Generation app for manipulating and exporting MapleSim subsystems as FMU archive files.
With this app, you can define inputs and outputs for the system, set the level of code optimization, generate the source code, and choose the format of the resulting FMU component and library code. You can assign model equations to a variable, group inputs and outputs, and define additional input and output ports for variables.
Note: FMU component generation now handles all systems modeled in MapleSim, including hybrid systems with defined signal input (RealInput) and signal output (RealOutput) ports.
Example models are available in MapleSim. To access these, from the Help menu, select Examples > FMI Connector Examples.
Step 1: Subsystem Selection
This part of the app identifies the subsystem modeling components that you want to export as a block component.
To connect a subsystem to modeling components outside of its boundary, you add subsystem ports to your model. A subsystem port is an extension of a component port in your subsystem. The resulting signals can then be directed as inputs and outputs for the FMU archive files. By creating a subsystem you improve the visual layout of a system in the model workspace and also prepare the model for export. The example in Chapter 2 shows you how to group all of the components into a subsystem.
You can select which subsystems from your model you want to export to an FMU archive file. After selecting a subsystem, click Load Selected Subsystem. All defined input and output ports are loaded.
Step 2: Inputs, Outputs, and Parameters
The Inputs, Outputs, and Parameters sections let you customize, define, and assign parameter values to specific ports. Subsystem components to which you assign the parameter inherit a parameter value defined at the subsystem level.
After the subsystem is loaded you can group individual input and output variable elements into a vector array, and add additional input and output ports for customized parameter values. Input ports can include variable derivatives, and output ports can include subsystem state variables. You can specify prefixes for both input and output port variables. The prefix for the input (output) port variables will be applied to all the variables in the input ports (outputs) table.
Note: If the parameters are not marked for export they will be numerically substituted. Parameters marked as tunable will also be marked for export by default. However, tunable parameters will be ignored if FMI Version and Environment (see Step 3: Export Options) are anything other than Co-Simulation. To use fully qualified parameter names for the generated FMU, check the corresponding check box; otherwise, short parameter names will be used by default.
Step 3: Export Options
Select Export Options to specify the advanced options for the code generation process. Default settings are provided for both Model Exchange and Co-Simulation export options.
FMI Version and Environment
Select the FMI version and environment for your code. You can choose between FMI 2.0 and FMI 3.0 for the version. For FMI 2.0 you can also choose between Model Exchange and Co-Simulation for the FMU type , the FMI 3.0 export includes interfaces for both.
Select Include MapleSim Insight data to include the necessary data for the FMU to be run with MapleSim Insight (available as a separate product).
Select View advanced FMU settings to see Contraint Handling, Event Handling, Code Generation, and Solver options.
To match the MapleSim model's current simulation settings, click the Match Simulation Settings button. (Note that you can revert to the default settings for Model Exchange and Co-Simulation using the refresh button at the top of the app window.)
Co-Simulation Solver Settings
For the Co-Simulation interface, the Co-Simulation Solver can be set to Euler, RK2, RK3, RK4, Implicit Euler, CK45, or Rosenbrock. The communication step size can also be specified.
Advanced FMU Settings
Select View advanced FMU Settings to make further modifications.
You can specify Solver Options for the chosen solver.
Jacobian: In the case of the Implicit Euler solver, specify either numeric or symbolic formulation for the system Jacobian.
The Constraint Handling Options specify whether the constraints are satisfied in a DAE system by using constraint projection in the generated FMU archive file. Use this option to improve the accuracy of a DAE system that has constraints. If the constraint is not satisfied, the system result may deviate from the actual solution and could lead to an increase in error at an exponential rate.
The Baumgarte constraint stabilization method stabilizes the position constraint equations, by combining the position, velocity, and acceleration constraints into a single expression. By integrating the linear equation in terms of the acceleration, the Baumgarte parameters, alpha and beta, act to stabilize the constraints at the position level.
Baumgarte stabilization: Apply the Baumgarte constraint stabilization.
Alpha: Set the derivative gain for Baumgarte constraint stabilization.
Beta: Set the proportional gain for Baumgarte constraint stabilization.
Set the Projection iterations to specify the maximum number of times that a projection is permitted to iterate to obtain a more accurate solution.
Set the Projection tolerance to specify the desirable error tolerance to achieve after the projection.
The Event Handling Options specifies whether the events are satisfied in a DAE system by using event projection in the generated FMU archive file. Use this option to improve the accuracy of a DAE system with events. If the constraint is not satisfied, the system result may deviate from the actual solution and could lead to an increase in error at an exponential rate.
Set the Event iterations to specify the maximum number of times that a projection is permitted to iterate to obtain a more accurate solution.
Set the Initial hysteresis to specify the desirable error tolerance to achieve after the projection.
Select Event projection to perform event projection using the event projection routine in the External Model Interface as described on The MathWorks website to control the drift in the result of the DAE system.
Note: Currently, if the model has events, they are handled using the event handling functions in the generated MsimModel.c file, and not the FMI provided Event Handling routines.
The Code Generation Options control details of the generated code and run-time errors.
Add directional derivatives: Select the check box to generate directional derivatives code. Note: This option is expensive; use only when required.
Optimize for fixed-step solver: Specifies if the generated code should be optimized for use with fixed-step solvers.
Allow input deriv. ports: Specifies if ports can be added for derivatives of inputs, if needed. Otherwise, numerical derivatives are computed.
Detailed run-time errors: Report run-time errors in detail.
Add extended variables: Choose between minimal and extended variable tracking during the simulation.
Step 4: Info Options
In the generated FMU archive file, model information (for example, variable names, units and initial values) are stored in a text file in XML format. Additional information about the model, such as the model author, description, and version, can also be included in this file.
Author: Name and organization of the model author (for example, J. Smith, Maplesoft http://www.maplesoft.com).
Description: Brief description of the model (for example, Model of a lithium-ion battery).
Version: Model version or FMU version.
Copyright: Intellectual property copyright (for example, (C) Maplesoft 2024).
License: Intellectual property licensing (for example, Proprietary, Public Domain, or BSD License).
Step 5: Export
Generating the C code creates temporary files for viewing purposes.
Specify the location for the Target Directory.
Provide a name for the generated FMU archive in FMU Archive Name.
Specify the FMU Distribution Type to DLL/Shared Object or Source Code Only.
Select Remove Source Files from the FMU Archive to remove source files after code generation.
Select Remove temporary `fmiTMPXXXXXX`directory to remove temporary files after code generation.
Specify whether to overwrite an exisiting FMU archive, if present.
To generate an FMU archive click Generate FMU Archive. The FMU is generated.
Note: If your model contains an external library, you must add the directory that contains the external library to your search path. See Adding External Libraries to Your Search Path for instructions on how to do this.
Step 6: View Code
After the C code is generated, the FMI C Code and MsimModel.c components can be viewed.
1.4 Note on Ports for Derivatives
When the derivative of an input is required in the FMU, the FMU Generation app adds additional ports to the FMU that allow the user to directly define these. This avoids the numerical differentiation of these values, which can be unstable at the start of a simulation.
If ports for derivatives are created, their names will be of the form VariableName__der (first derivative) or VariableName__der__der (second derivative).
1.5 Viewing Examples
Within MapleSim there are many examples for you to view.
To view an example:
From the Help menu, select the Examples > FMI Connector Examples menu, and then click the entry for the model that you want to view.
Some models include additional documents, such as Maple worksheets. For example, the Double Wishbone example has an attached Maple worksheet, DefiningHardPoints.mw. To view an attached Maple worksheet:
From the main toolbar in MapleSim, click the Load a Maple Worksheet icon ( )
Select the document from the list of attached worksheets, and click OK. The worksheet opens in Maple.
Alternatively, all attachments to a MapleSim model can be found under the Attached Files tab ( ). You can right-click (Control-click, for Mac) on an attachment and select View to open it in Maple (for Maple worksheets) or in the appropriate program.
1.6 Example: RLC Circuit Model
In this example, you will generate an FMU archive file using an RLC circuit model created in MapleSim.
To generate an FMU archive file:
From the Help menu, select Examples > FMI Connector Examples, and then select the RLC Parallel Circuit example.
From the main toolbar, click Show Apps Manager ( ).
Select the RLC subsystem from the drop-down list in the Subsystem Selection section. This menu displays all of the subsystems and components in your MapleSim model.
Click Load Selected Subsystem. All of the app fields are populated with information specific to the subsystem displayed in the model diagram. You can now specify which subsystem parameters will be kept as configurable parameters in the generated block.
In the Export section of the app, specify the target directory and the FMU archive name.
Click Generate FMU Archive. The .fmu zip file is created and saved in the target directory.
Note: Generating a block may require a few minutes.
Download Help Document
