1 Getting Started - MapleSim Help

1 Getting Started

1.1 FMI Code Generation Steps

This chapter describes how to use the FMI template 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 template consists of the following steps to generate C code:

 1 Subsystem selection
 2 Inputs/Outputs and parameter management
 3 FMI code generation options
 4 Generate FMI C code
 5 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, enter ?FMIConnector at a prompt in a Maple worksheet.

1.2 Opening an FMI Template

To open the FMU Generation template

 1 Click Templates ( ) in the main toolbar and select the FMU Generation template.
 2 In the Attachment field, provide a worksheet name and click Create Attachment. Your MapleSim model opens in a Maple worksheet in the Subsystem Selection window.
 3 From the drop down list select a subsystem.  The subsystem and its contents appear in the MapleSim embedded component window.

1.3 Using the C FMU Generation Template

The MapleSim FMI Connector provides an FMU Generation template in the form of a Maple worksheet for manipulating and exporting MapleSim subsystems as FMU archive files. This template contains pre-built embedded components that allow you to export FMU archive files from a MapleSim subsystem.

With this template, 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 use any Maple commands to perform task analysis, 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 the FMI Connector Examples palette in MapleSim.

 Step 1: Subsystem Selection This part of the template identifies the subsystem modeling components that you want to export as a block component.  Since FMI only supports data signals, properties on acausal connectors such as mechanical flanges and electrical pins, must be converted to signals using the appropriate ports. 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. Note:  For connectors you must use signal components since acausal connectors can not be converted to a signal. 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 Parameter Management The Inputs/Outputs and Parameter Management interface lets 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: FMI C Code Generation Options) are anything other than FMI 2.0 and Co-Simulation. To use fully qualified parameter names for the generated FMU, check the corresponding checkbox; otherwise, short parameter names will be used by default.

Step 3: FMI C Code Generation Options

The FMI Component Options settings specify the advanced options for the code generation process.

 FMI version and environment Select the FMI version and environment for your code. You can choose between FMI 1.0, FMI 2.0 RC1, and FMI 2.0 for the version, and between Model Exchange and Co-Simulation for the environment.
 Embedded Solver for Co-Simulation If you are exporting to the Co-Simulation environment, specify the fixed-step solver and maximum stepsize.
 Optimization Options Set the level of code optimization to specify whether equations are left in their implicit form or converted to an ordinary differential equation (ODE) system during the code generation process.  This option specifies the degree of simplification applied to the model equations during the code generation process and eliminates redundant variables and equations in the system. Select one of the following options: None (0): no optimization is performed; the default equations will be used in the generated code. Partial (1, 2): removes redundant equations from the system. Full (3): performs index reduction to reduce the system to an ODE system or a differential algebraic equation (DAE) system of index 1, and removes redundant equations.
 Constraint Handling Options The Constraint Handling Options specifies 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. Set the Maximum number of projection iterations to specify the maximum number of times that a projection is permitted to iterate to obtain a more accurate solution. Set the Error tolerance to specify the desirable error tolerance to achieve after the projection. Select Apply projection during event iterations to interpolate iterations to obtain a more accurate solution. Constraint projection is performed using the constraint projection routine in the External Model Interface as described on The MathWorks web site to control the drift in the result of the DAE system.
 Event Handling Options 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 Maximum number of event iterations to specify the maximum number of times that a projection is permitted to iterate to obtain a more accurate solution. Set the Width of event hysteresis band to specify the desirable error tolerance to achieve after the projection. Event projection is performed using the event projection routine in the External Model Interface as described on The MathWorks web site 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.
 Baumgarte Constraint Stabilization 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: Apply the Baumgarte constraint stabilization. Alpha: Set the derivative gain for Baumgarte constraint stabilization. Beta: Set the proportional gain for Baumgarte constraint stabilization.
 Optional Information In the generated FMU archive file, model information (e.g. 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 2015). License: Intellectual property licensing (for example, Proprietary, Public Domain, or BSD License).
 Step 4: Generate FMI C Code Generating the C code creates temporary files for viewing purposes. Select Remove temporary fmiTMPXXXXXXdirectory to remove temporary files after code generation. Specify the locations for the Target Directory and Visual C++ Directory. Note:  The Visual C++ Directory is not required for Linux and Macintosh® platforms. For Windows platforms, the Visual C++ Directory is usually located at: C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC (64-bit) or C:\Program Files\Microsoft Visual Studio 10.0\VC (32-bit). If necessary, navigate to the correct Visual C++ Directory for your platform using the Browse button. Provide a name for the generated FMU Archive. If required, set the binary target to 32-bit or 64-bit. Select Remove Source Files from the FMU Archive: to remove source files after code generation. To generate an FMU archive click Generate FMU Archive. 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 5: View Generated FMI C Code After the C code is generated, the FMI C Code and MsimModel.c components can be viewed.

1.4 Viewing Examples

Within MapleSim there are many examples for you to view.

To view an example:

 1 In the Libraries tab on the left side of the MapleSim window, expand the FMI Connector Examples palette, and click the entry for the model that you want to view.

Note: Some models include additional documents, such as templates that display model equations or define custom components.

 2 In the Project tab, expand the Attachments palette and then expand Documents.  You can open any of these documents by right-clicking (Control-clicking, for Macintosh) its entry in the list and clicking View.  After you add a template to a model, it will be available from this list.

1.5 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:

 1 From the FMI Connector Examples palette, open the RLC Parallel Circuit example.
 2 Click Templates ( ) in the main toolbar.
 3 From the list, select the FMU Generation template.
 4 In the Attachment field, enter RLC Circuit as the worksheet name.
 5 Click Create Attachment. Your MapleSim model opens in Maple, using the selected template.
 6 Browse to the RLC subsystem by selecting the subsystem name from the drop-down menu in the toolbar above the model diagram. This menu displays all of the subsystems and components in your MapleSim model.
 7 Click Load Selected Subsystem.  All of the template 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.
 8 In the FMI Code C Generation Options section, set the Optimization Options to Full (3). This option specifies the degree of simplification applied to the model equations during the code generation process, and eliminates redundant variables and equations in the system.
 9 In the Generate FMI C Code section of the template, specify the target, the Visual C++ directories and FMU archive name.
 10 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.