Contents Previous Next Index
5 Analyzing and Manipulating a Model
In this chapter:
Overview
Retrieving Equations and Properties from a Model
Analyzing Linear Systems
Optimizing Parameters
Generating and Exporting C Code from a Model
Generating a Custom Component from External C Code/Library Definition
Working with Maple Embedded Components
5.1 Overview
MapleSim is fully integrated with the Maple environment.
You can use Maple-based Apps within the MapleSim interface.
You can attach Templates to a model, which open in the Maple interface.
You can attach Maple worksheets to a MapleSim model, allowing you full access to commands, embedded components, plotting tools, and many other technical features to analyze and manipulate the dynamic behavior of a MapleSim model or subsystem.
You can use the MapleSim application programming interface (API) in a Maple worksheet to manipulate, simulate, and analyze an existing MapleSim model programmatically.
MapleSim Apps
To start working with your MapleSim model in Maple, you can use the apps available in the Apps Manager. Apps are pre-built tools for model building and analysis tasks: you first create a MapleSim model and open it in one of the available apps to perform an analysis task. Apps open in the Apps Manager tab of the Analysis window in MapleSim. To access the Apps Manager, in the main toolbar, click Show Apps Manager ( ). The Analysis window opens with Apps tab selected. For example, you can use apps to perform parameter sweeps, Monte Carlo simulations, or code generation.
The following tables list the MapleSim Apps and Templates available in the Apps Manager.
App Name
Task
Component Creation
1-D Motion Generation
Create motion profiles for 1-D motion that adhere to defined velocity, acceleration, and jerk constraints.
Custom Port
Create a custom port for a custom component. For more information, see Creating Custom Modeling Components.
DCV Builder
Create a custom hydraulic directional control valve.
External C/Library Block
Define and generate a MapleSim custom component from external C Code/DLL.
Kinematic Cam Generation
Model the kinematic behavior of cams and followers.
Linearization
Linearize a MapleSim continuous subsystem. Perform linear analysis on the linear system object, such as generating Bode plots and Root Locus plots.
Model Analysis
Equation Extraction
Retrieve equations from linear or nonlinear models. For more information, see Tutorial 7: Using the Equation Extraction App.
Initialization Diagnostics
Resolve inconsistent initial conditions and errors detected during the simulation, as well as give insight into the original configuration of the system.
Modal Analysis
Visualize the vibration modes of a multibody model.
Monte Carlo Simulation
Define a random distribution for a parameter and run a simulation using the distribution.
Multibody Analysis
Retrieve multibody equations in a form that is suitable for manipulation and analysis.
Optimization
Analyze and edit the parameters of a model and view possible simulation results in a graph. For more information, see Optimizing Parameters.
Parameter Sweep
Execute a parameter sweep.
Utility
Code Generation
Translate your model into C code. For more information, see Generating and Exporting C Code from a Model.
Data Generation
Define and generate a data set to be used in MapleSim, for example, a data set for an interpolation table component. For more information, see Creating a Data Set for an Interpolation Table Component.
Excel Connectivity
Import MapleSim parameter sets from an Excel spreadsheet, or export MapleSim parameter sets to an Excel spreadsheet.
Random Data
Define and generate a set of random data points to be used in MapleSim, for example, a data set for an interpolation table component.
Heat Transfer (The MapleSim Heat Transfer Library is available as a separate add-on.)
Board and Parts Generation
Generate a component of a board with parts.
Temperature Distribution
Plot a 3-D visualization of the temperature distribution of a Heat Transfer shape component, mapping temperatures to colors.
Note: After using a MapleSim template, save the .mw file and then save the .msim file to which the .mw file is attached.
Working with Apps
If you close and reopen an app, the Apps Manager remembers the previous state of the app.
The Apps Manager displays three options:
Refresh ( ): Return the app to the default settings.
Export ( ): Save the current settings for the app. The settings are saved as a data file.
Import ( ): Retrieve saved settings for an app.
Working with Templates and Scripting Worksheets
Templates are Maple worksheets that you attach to a model. Templates can be used to retrieve and work with equations for a subsystem or build custom components.
To open a Template, from the main toolbar, click Load a Maple Worksheet ( ). Select from the available templates. The templates open in Maple.
Template Name
Custom Component
Create a custom modeling component based on a mathematical model. For more information, see Creating Custom Modeling Components.
Worksheet
Create a worksheet by opening a MapleSim model in an embedded component.
You can also open a black worksheet from the Load a Maple Worksheet ( ) dialog.
If you have already attached a template or worksheet to a model, it appears in the list in the Load a Maple Worksheet dialog under Attached Worksheets. You can select it and click OK to load that worksheet.
Working with MapleSim Equations and Properties in a Maple Worksheet
When viewing and working with MapleSim equations or properties in a Maple template, corresponding parameters, variables, connectors, subscripts and superscripts are mapped and represented differently.
Mapping MapleSim Programmatic Names to Maple
The programmatic names of certain parameters, variables, and connectors displayed in the Maple worksheet differ from the names displayed for the corresponding elements in the MapleSim interface. For example, if an Inertia component is included in a model, the parameter for the initial value of the angular velocity appears as w0 in the MapleSim interface and w_start in a Maple worksheet. For more information about the mappings of parameter, variable, and connector names, see the MapleSim Component Library in the MapleSim help system.
Representing MapleSim Subscripts and Superscripts in Maple
Subscripts and superscripts in the MapleSim interface are represented differently in a Maple worksheet. Subscripts in the MapleSim interface appear with an underscore character in a Maple worksheet. For example, a connector called flangea in the MapleSim interface appears as flange_a in a Maple worksheet. Also, superscripts are formatted as regular characters in a Maple worksheet. For example, a variable called a2 in the MapleSim interface would be displayed as a2 in a Maple worksheet.
Using Subsystems
The basic structure for exporting models is the subsystem. An app or template allows you to select a complete subsystem for which you want to analyze and manipulate. By converting your model or part of your model into a subsystem, you can more easily identify the set of modeling components that you want to explore, define the set of inputs and outputs for the subsystem, or identify the components that you want to export as a block component. For best practices on creating subsystems in MapleSim, see Best Practices: Laying Out and Creating Subsystems.
For an example of a basic structure for exporting models, from the Help menu, select Examples > User's Guide Examples > Chapter 5, and then select the Preparing a Model for Export example.
Note: When generating code for a subsystem, any included ports must be real input or real output ports. When generating code for the top-level system, the system is considered to have no inputs, but all probed values are treated as outputs.
Tip: If you want to use your complete model, group all of the components at the top level of your model into a single subsystem.
5.2 Retrieving Equations and Properties from a Model
You can use the Equation Extraction App to retrieve, define, and analyze equations and properties such as parameters and variables in your model. Additional features within this app are useful in generating reusable equations when there is more than one subsystem.
For a complete tutorial on how to use the Equation Extraction App, see Tutorial 7: Using the Equation Extraction App.
To retrieve equations and properties:
In MapleSim, open the model for which you want to retrieve equations or properties.
In the main toolbar, click Show Apps Manager ( ). The Analysis window opens with Apps tab selected.
From the Apps palette, under Model Analysis, double-click Equation Extraction to open this app.
Use the navigation tools under Subsystem Selection to select the subsystem for which you want to view equations. If you want to retrieve equations from the complete system, click Main.
Click Load Selected Subsystem. The model equations are extracted and the system parameters and variables are loaded. Under View Equations, click Extract Equations. The system equations are shown and are automatically stored in the variable DAEs.
5.3 Analyzing Linear Systems
You can use the Linearization app to retrieve, view, and analyze the equations of a linear system, test system input and output values, and view possible simulation results in a Bode, Nyquist, or root locus plot.
Note: Linear analysis cannot be performed on the entire system. To perform linear analysis using the tools in the Analysis and Simulation section of the template, you must select a subsystem.
To analyze a linear system model from MapleSim:
In MapleSim, open the linear system model that you want to analyze.
From the Apps palette, under Component Creation, double-click Linearization to open this app.
Using the navigation tools above the model diagram, select the subsystem for which you want to view equations.
Click Load Selected Subsystem.
(Optional) Make changes in the configuration section.
Click Linearize. The linear system object is created and the equations for the system are displayed.
(Optional) Create bode, nyquist, root locus, or response plots. See the following section, Linear System Analysis, for details.
Under the Create Model section, you can create a custom component from the linear system. After it is created, the component can be found under the Local Components tab ( ). You can then add this component to your model.
Linear System Analysis
You can use the tools in the Analysis section to analyze your linear system and to view the effects of different inputs on the outputs of your system.
For analysis, you can use the following tools:
Bode plot
Nyquist plot
Root locus plot
Response plot
In the Response section you can choose an input signal to apply to the system and then simulate to see the effects on the output.
5.4 Optimizing Parameters
You can use the Optimization App to test the model parameters, view simulation plots, and assign parameters to a Maple procedure to perform parameter sweeps and other advanced optimization tasks.
You can also use commands from the Global Optimization Toolbox to perform parameter optimization tasks. This product is not included with MapleSim. For more information, visit the Maplesoft Global Optimization Toolbox website at http://www.maplesoft.com/products/toolboxes/globaloptimization/.
To optimize parameters
From the Apps palette, under Model Analysis, double-click Optimization to open this app.
Click Load System. The model simulation settings are imported.
In the Parameters section, use the combo box list to select a parameter you want to optimize and click Add. Do the same to select other parameters and you'll see the list box appear with the parameters you selected.
Note: When a parameter is selected, its current (nominal) value is shown in Nom.
Set the range over which the parameter may vary using the Min and Max fields.
Using the same process described above, set the Min and Max fields for the other parameters you want to optimize.
9. When you have defined all of the parameters, under Objective Function you can specify details of how to construct your objective function, and specify whether to Minimize Objective or Maximize Objective. The objective function is defined as a Maple procedure.
For more information about Maple procedures, see Procedures in the Maple help system.
10. Now you can perform the parameter optimization. If you have the Maple Global Optimization toolbox, you can use it for this step. Click Run Parameter Optimization to perform the parameter optimization. The Results section displays the parameter values that optimize the objective function.
To test different values for the parameters, move the sliders and then click Run Simulation. Click Restore Optimum Values to restore the values computed in step 10.
11. To use the parameter values of the sliders in the linked model, click Update Parameters in Model.
5.5 Generating and Exporting C Code from a Model
If you want to use or test your model in an application that supports the C programming language, you can use the Code Generation App to translate your model or a subsystem in your model into C code. Access to the basic C code, and the ability to compile and run it, is available in Maple. Extensions of this code are available for a variety of software tools as additional Connector toolboxes.
For a general high-level overview of the MapleSim code export process, refer to Generating Code for Export.
With the Code Generation 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 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: C code generation handles all systems modeled in MapleSim, including hybrid systems with defined signal input (RealInput) and signal output (RealOutput) ports.
Whenever you export code or generate equations you often only see a subset of the parameters for that model. The following parameters cannot be exported:
Multibody parameters cannot be directly exported. Only user-generated parameters that the multibody parameters are assigned using Properties tab ( ) are able to be exported.
Dependent parameters cannot be exported. If the parameter A is a function of b (A=b, A=sin(b), A=1+3/b, etc.), then A will not be able to be exported. It will be directly substituted for in the equations as a function of b. You will be able to export b.
Parameters that change the number of equations cannot be exported.
Parameters for discrete values cannot be exported.
The process of generating C code from a MapleSim model consists of the following steps:
Preparing the MapleSim model
Opening the Code Generation app
Loading the subsystem
Customizing, defining, and assigning parameter values to specific ports
Selecting the code generation options
Generating and saving the C code
Preparing the Model for Export in MapleSim
The basic structure for exporting models is the subsystem where you define the input and output signals from the generated code. By creating a subsystem you also improve the visual layout of a system in the Model Workspace. The following figure shows a subsystem with a defined input (blue arrow) and a defined output (white arrow). When generating code for a subsystem, all ports must be defined as real input or real output ports.
When generating code for the top-level system, there are no inputs, but all probed values are considered as outputs, as shown in the following figure.
Tip: If you want to generate code for your complete model, group all of the components at the top level of your model into a single subsystem.
In addition to inputs and outputs, generated code can have user-modifiable parameters defined for it. By default, not all parameters are selected to be modifiable in the exported code. In general, the fewer the parameters left modifiable, the less time it will take to generate and run the exported code. By default, only parameters defined in the exported subsystem are selected to be modifiable in the generated code. In the above example, generating code for the RLC subsystem, only the parameters R, L and C will default to being modifiable in the exported code.
Note: Since not all parameters are modifiable in the generated code, parameters that change the structure of the equations, by adding or removing variables from the system, are automatically removed from the list of parameters that can be exported. This is true even if the parameters are defined in the exported subsystem.
Initialization
All discrete events initialize to the same values as the corresponding MapleSim model. For example, if a clutch is initialized as 'locked' in the MapleSim model, then the generated code assumes that the clutch starts in the 'locked' configuration. The same is true for continuous variables and their derivatives.
Since exported code obtains its initial conditions from an initialized MapleSim model, that code can only be exported for subsystems that are part of a model that can be simulated.
Note: If you are unable to run or initialize your model in MapleSim, you will not be able to export code for that model or any of its subsystems.
Opening the Code Generation App
To perform code generation, first open the Code Generation app.
From the Apps palette, under Utility, double-click Code Generation to open this app.
Loading the Subsystem
The Subsystem Selection part of the app identifies the subsystems that you want to generate and export code for. After selecting a subsystem, click Load Selected Subsystem. All defined input and output ports are loaded.
Customizing, Defining, and Assigning Parameter Values to Specific Ports
The Configuration 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.
Tip: If you close and reopen this app, the Apps Manager remembers the previous state of the app.
The refresh, export, and import buttons can be used to maintain or restore settings if you close the app and then reopen it:
Export ( ): Save the current settings for the app.
Inputs: Contains the model input variables.
Outputs: Contains the model output variables.
Export All/Export None: Allows you to either select or remove all of the parameters for export.
Add an additional output port for subsystem state variables: Select this option to add an additional port for the selected subsystem state variable.
Parameters: Contains the model parameters.
Filter: Filter for specific parameters.
View All/Exports: Toggle the view.
Export: Select which parameters you want to export in the symbolic form.
Value: Displays the value for the system parameter.
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.
Note: If the parameters are not marked for export they will be numerically substituted.
Selecting the Code Export Options
The Code Export Options settings specify the advanced options for the code generation process.
Solver Options
In this section you can specify the type of solver.
Note: There is an option to Match Current Fixed-step Simulation Settings. If selected, the app settings will match the model's current simulation settings, which covers Solver, Baumgarte Constraint Stabilization, Constraint Handling, and Event Handling.
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.
Apply Baumgarte constraint stabilization: select this option to apply Baumgarte constraint stabilization to your model.
Export Baumgarte parameters: select this option to have constants for alpha and beta included in the generated C code. This allows you change the values of alpha and beta in the source code. You can then recompile your code and run it to see the effect on your model.
alpha: enter a value for the derivative gain that is appropriate to your model.
beta: enter a value for the proportional gain that is appropriate to your model.
Constraint Handling Options
The Constraint Handling Options specify whether the constraints are satisfied in a DAE system by using constraint projection in the generated 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 Max 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™ website to control the drift in the result of the DAE system.
Event Handling Options
The Event Handling Options section specifies whether the events are satisfied in a DAE system by using event projection in the generated 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.
Generating and Saving the C code
To generate C code
In MapleSim, open the model for which you want to generate code.
In the Model Workspace, make sure that the components for which you want to generate code are grouped in a subsystem.
In the main toolbar, click Show Apps Manager ( ).
From the drop down list, select the subsystem for which you want to generate code. The subsystem and its contents appears in the Subsystem Selection window.
Click the Load Selected Subsystem located directly below the model diagram. The subsystem, along with all input and output variables, are now loaded into the Code Generation app.
Configure the inputs, outputs, and parameters.
Under Code Export Options, select the solver. By default, the Euler solver is selected.
Under Export, browse to select the directory where you want to save the code and specify the name of the file. The file is automatically given a “c” prefix and a “c” extension.
Click Generate C Code. The C code is saved to your specified location. After the C code is generated, the code can be viewed in the View Code area at the bottom of the app.
5.6 Generating a Custom Component from External C Code/Library Definition
MapleSim can call external code directly within your model. By using the External C Code/Library Definition app, you can create a custom component to call external C Code and DLL functions directly into your model or subsystem. You can access the basic C code, and then compile and run the code in Maple. Extensions of this code are available for a variety of software tools as additional Connector toolboxes.
With this app, you can define the external inputs and outputs, specify the function name and arguments, generate the source code, and choose the format of the resulting 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.
Changes to the parameters, inputs and outputs are remembered when you re-load your system using the External C Code/Library Definition app.
The process of creating an external code custom component for a MapleSim model consists of the following steps:
Specify the custom component name
Specify the location of the external C/library
Define the external C/Library code options
Specify the directory of the generated Modelica code
Generate and save the external code custom component
Opening the External C Code/Library Definition App
From the Apps palette, under Component Creation, select the External C/Library Block to open this app.
Specifying the C/Library Code Location and Options
Use the External C Code/Library Definition app to define the library code location, and/or validate and assign the code to a model. You can specify a header file, use an existing C or shared library file, or create a new C file using the text area.
Specifying a Header file (optional)
If required, select Header File and provide the location of the existing header file.
Using an Existing C or Library File
Provide the location of the existing C or Library file.
Providing External Code into a Text Area and then Saving to File or Attachment
Enter the content directly into the app, then save to either a file or attachment before generating the component. Tutorial 6: Using the External C Code/DLL Custom Component App walks you through this step.
If you save to an attachment, the attachment is saved in the Attached Files tab ( ) under Other.
Click Validate C to verify the validity of the provided C code.
Defining the C/Library Code Location and Options
In the Configuration section,you can define the external C/Library function name, specify the external C/Library prototype, choose the parameter name, data type, whether it is an array, and whether it is an output of the Modelica block (by checking passed by reference).
Use the up/down arrows to rearrange the parameters. The order must match that of the C function. If necessary click Delete Parameter to remove a parameter.
For a complete tutorial on how to create an external code custom component and its use, see Tutorial 6: Using the External C Code/DLL Custom Component App.
Component Generation
To generate the custom component:
Enter the Block Name for the custom component under Component Generation.
Click Generate Component. In MapleSim, the custom component appears in the Local Components tab ( ), located in the Components palette, on the left side of the MapleSim window. The modelica code for the component can be viewed in the Modelica Code Editor.
5.7 Working with the MapleSim API and Maple Commands
In addition to working with apps and templates to interact with and analyze a model, you can use the MapleSim application programming interface (API) in a Maple worksheet. The first step is to use the LinkModel command to link to a MapleSim model. The LinkModel command returns a 'connection module' that allows access to a MapleSim model. For more information about the MapleSim API, refer to the MapleSim help page and the examples section in the LinkModel help page.
Within Maple, you can also the full power of Maple to work with your model, use commands from any Maple packages, including MapleSim and DynamicSystems, to work with your model programmatically.
5.8 Working with Maple Embedded Components
Embedded Components are simple graphical interface elements that you embed into a Maple worksheet or document to view, edit, create actions, display information, and analyze the properties of MapleSim models. You can also associate model properties with other Maple embedded components, including sliders and plots to create custom analysis tools.
For example, you can view and change parameter values using commands in the DocumentTools package. Model or subsystem equations can be retrieved using commands from the MapleSim package and you can manipulate your model as a DynamicSystems object to analyze the model or subsystem behavior using any input functions. Embedded Components are inserted using the Components palette.
Tip: The pre-built analysis tools available in templates are Maple embedded components, which allow you to interact with Maple code through graphical interactive components. The code associated with each embedded component uses commands from Maple packages, including MapleSim and DynamicSystems.
To view the code associated with an embedded component, right-click (Control-click for Macintosh) any of the tools in the Maple worksheet, select Component Properties, and click Edit. For more information about embedded components, see the EmbeddedComponents topic in the Maple help system.
For more information about advanced analysis tasks, first open the Sliding Table example from the Help > Examples > User's Guide Examples > Chapter 5 menu, and then open the AdvancedAnalysis.mw worksheet attachment (from MapleSim, under the Attached Files tab ( ), expand the Documents entry).
Download Help Document
