5 Analyzing and Manipulating a Model - MapleSim Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : MapleSim : User's Guide : MapleSimUserGuide/Chapter05

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 and Templates

To start working with your MapleSim model in Maple, you can use the apps and templates available in the Add Apps or Templates tab ( ). 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 Analysis window in MapleSim.  For example, you can use apps to perform parameter sweeps, Monte Carlo simulations, or code generation.

Templates are Maple worksheets that you attach to a model.  Templates open in Maple.  Templates can be used to retrieve and work with equations for a subsystem or build custom components.

The following tables list the MapleSim Apps and Templates available in the Add Apps or Templates tab ( ).

Table 5.1: MapleSim Apps

App Name

Task

Component Creation

1-D Motion Generation

Create motion profiles for 1-D motion that adhere to defined velocity and acceleration constraints.

Custom Port

Create a custom port for a custom component.  For more information, see Creating Custom Modeling Components.

External C/Library Block

Define and generate a MapleSim custom component from external C Code/DLL.

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

Temperature Distribution

Plot a 3-D visualization of the temperature distribution of a Heat Transfer shape component, mapping temperatures to colors.  (The MapleSim Heat Transfer Library is available as a separate add-on.)

Table 5.2: MapleSim Templates

Template Name

Task

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.

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

1. 

In MapleSim, open the model for which you want to retrieve equations or properties.

2. 

Click the Add Apps or Templates tab ( ).

3. 

From the Apps palette, select Equation Extraction.

4. 

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.

5. 

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:

1. 

In MapleSim, open the linear system model that you want to analyze.

2. 

Click the Add Apps or Templates tab ( ).

3. 

From the Apps palette, select Linearization.  The App opens in the Analysis window.

4. 

Using the navigation tools above the model diagram, select the subsystem for which you want to view equations.

5. 

Click Load Selected Subsystem.

6. 

(Optional) Make changes in the configuration section.

7. 

Click Linearize. The linear system object is created and the equations for the system are displayed.

8. 

(Optional) Create bode, nyquist, root locus, or response plots.

9. 

After you have analyzed and configured your system, you can create a custom component based on the system and attach it to your MapleSim 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.

 

Create Component

After you have analyzed and configured your system, you can create a custom component based on the system and attach it to your MapleSim model.

To create a custom component from your system:

1. 

In the Create Model section, Enter a name in the Component Name text box.

2. 

Enter a description for your component in the Description text box.

3. 

Click Create.

Your custom component can be found in the Components palette of the Local Components tab ( ) of your MapleSim model.

5.4 Optimizing Parameters

You can use the Parameter 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

1. 

In MapleSim, open the linear system model that you want to analyze.

2. 

Click the Add Apps or Templates tab ( ).

3. 

From the Apps palette, double-click Optimization.  The App opens in the Analysis window.

4. 

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.

5. 

Click Load System.  The model simulation settings are imported.

6. 

In the Parameter Values section, click the first choose... list and selecting the parameter you want to optimize.  Do the same to select other parameters.

Note: When a parameter is selected, its current (nominal) value is shown in Nom.

7. 

Set the range over which the parameter may vary using the min and max fields.

8. 

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 MapleSim 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.

1. 

Click the Add Apps or Templates tab ( ).

2. 

From the Apps palette, select Code Generation.  The C Code Generation app opens in the Analysis window.

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:

• 

Refresh ( ): Return the app to the default settings.

• 

Export ( ): Save the current settings for the app.  

• 

Import ( ): Retrieve saved settings for an app.

 

 

 

Inputs:  Contains the model input variables.

 

Change Row:  Select the equations with the specified row.

 

 

Outputs:  Contains the model output variables.

Export:  Select which variables you want to leave in the symbolic form.

Change Row:  Select the equations with the specified row.

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.

Export All/Export None:  Allows you to either select or remove all of the parameters for export.

 

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 Generation 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.

 

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.

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.

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

1. 

In MapleSim, open the model for which you want to generate code.

2. 

In the Model Workspace, make sure that the components for which you want to generate code are grouped in a subsystem.

3. 

Click the Add Apps or Templates tab ( ).

4. 

From the Apps palette, double-click Code Generation. The app opens in the Apps Manager tab of the Analysis window.

5. 

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.

6. 

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.

7. 

Configure the inputs, outputs, and parameters.

8. 

Under Code Export Options, select the solver. By default, the Euler solver is selected.

9. 

Choose where you want to save the code and the name of the file. The file is automatically given a “c” prefix and a “c” extension.

10. 

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

Click Add Apps or Templates ( ) and select the External C/Library Block app. The External C/Library Block app opens in the Analysis window.

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:

1. 

Enter the Block Name for the custom component under Component Generation.

2. 

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 andDynamicSystems, 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).

 

Contents     Previous     Next     Index