MapleSim User's Guide

Copyright © Maplesoft, a division of Waterloo Maple Inc.
2024

MapleSim User's Guide
Copyright
Maplesoft, MapleSim, and Maple are all trademarks of Waterloo Maple Inc.
© Maplesoft, a division of Waterloo Maple Inc. 2008-2024. All rights reserved.
No part of this book may be reproduced, stored in a retrieval system, or transcribed, in any form or by any means— electronic, mechanical, photocopying, recording, or otherwise. Information in this document is subject to change
without notice and does not represent a commitment on the part of the vendor. The software described in thisdocument is furnished under a license agreement and may be used or copied only in accordance with the agreement.
It is against the law to copy the software on any medium except as specifically allowed in the agreement.
Linux is a registered trademark of Linus Torvalds.
Mac and Macintosh are trademarks of Apple Inc., registered in the U.S. and other countries.
Microsoft, Excel, and Windows are registered trademarks of Microsoft Corporation.
Modelica is a registered trademark of the Modelica Association.
All other trademarks are the property of their respective owners.
This document was produced using Maple and DocBook.

Contents
Introduction ................................................................................................ xiii
1 Getting Started with MapleSim ........................................................................ 1
1.1 Physical Modeling in MapleSim ................................................................ 1
Topological or “Acausal” System Representation .......................................... 1
Mathematical Model Formulation and Simplification ..................................... 1
Advanced Differential Algebraic Equation Solvers ........................................ 1
Acausal and Causal Modeling ................................................................... 2
1.2 The MapleSim Window ........................................................................... 6
1.3 Basic Tutorial: Modeling an RLC Circuit and DC Motor ................................ 8
Building an RLC Circuit Model ................................................................. 8Specifying Component Properties ............................................................. 11
Adding a Probe ..................................................................................... 12
Simulating the RLC Circuit Model ........................................................... 13
Building a Simple DC Motor Model ......................................................... 14
Simulating the DC Motor Model .............................................................. 16
2 Building a Model ......................................................................................... 19
2.1 The MapleSim Component Library .......................................................... 19
Viewing Help Topics for Components ....................................................... 20
Updating Models Created in a Previous Release of MapleSim ........................ 20
2.2 Browsing a Model ................................................................................. 20
Model Tree .......................................................................................... 21
Model Navigation Controls ..................................................................... 23
2.3 Defining How Components Interact in a System ......................................... 24
2.4 Specifying Component Properties ............................................................ 25
Specifying Parameter Units ..................................................................... 26
Specifying Initial Conditions ................................................................... 27
2.5 Creating and Managing Subsystems ......................................................... 28
Example: Creating a Subsystem ............................................................... 29
Viewing the Contents of a Subsystem ........................................................ 30
Adding Multiple Copies of a Subsystem to a Model ..................................... 31
Editing Subsystem Definitions and Shared Subsystems ................................ 34
Working with Standalone Subsystems ....................................................... 39
2.6 Global and Subsystem Parameters ............................................................ 43
Global Parameters ................................................................................. 43
Subsystem Parameters ............................................................................ 45
Using Parameter Blocks for Subsystem Parameters ...................................... 46
Saving Parameter Sets ............................................................................ 52
Using Advanced Parameter and Variable Settings ........................................ 53
2.7 Attaching Files to a Model ...................................................................... 59
2.8 Creating and Managing Custom Libraries .................................................. 60
Example: Creating a Custom Library from an Existing Model ........................ 60iii

iv • Contents

2.9 Annotating a Model ............................................................................... 62
Example: Adding Text Annotation to a Model ............................................ 63
2.10 Entering Text in 2-D Math Notation ........................................................ 64
2.11 Creating a Data Set for an Interpolation Table Component ........................... 65
Example: Creating a Data Set in Maple ..................................................... 65
2.12 Best Practices: Building a Model ............................................................ 66
Best Practices: Laying Out and Creating Subsystems ................................... 66
Best Practices: Building Electrical Models ................................................. 67
Best Practices: Building 1-D Translational Models ...................................... 69
Best Practices: Building Multibody Models ................................................ 70
Best Practices: Building Hydraulic Models ................................................. 71
Best Practices: Enforcing Initial Conditions ................................................ 72
3 Creating Custom Modeling Components .......................................................... 73
3.1 Understanding Custom Components ......................................................... 73
Creating a Simple Custom Component ...................................................... 74
Typical Uses ........................................................................................ 75
Using The Custom Component Template ................................................... 76
3.2 Creating Custom Components with Signal-Flow Behavior ............................ 76
Creating a Simple Signal-Flow Custom Component ..................................... 76
Using Differential Equations in Custom Components ................................... 82
3.3 Creating Custom Components with Physical Connections ............................. 82
Deriving the System Equations for a Resistor ............................................. 83
3.4 Working with Custom Components in MapleSim ........................................ 84
Save a Custom Component as Part of the Current Model .............................. 84
Add a Custom Component to a Custom Library .......................................... 84
Edit a Custom Component ...................................................................... 85
3.5 Example: Creating a Nonlinear Spring-Damper Custom Component ............... 85
Opening the Custom Component Template ................................................. 86
Defining the Component Name and Equations ............................................ 86
Defining Component Ports ...................................................................... 87
Checking Dimensions ............................................................................ 89
Generating the Custom Component .......................................................... 90
4 Simulating and Visualizing a Model ................................................................ 91
4.1 How MapleSim Simulates a Model ........................................................... 91
Modelica Description ............................................................................. 91
Model Description ................................................................................. 91
System Equations .................................................................................. 91
Simplified Equations ............................................................................. 92
Integration and Event Handling ................................................................ 92
Simulation Results ................................................................................ 92
4.2 Simulating a Model ............................................................................... 93
Simulation and Advanced Simulation Settings ............................................ 94
Editing Probe Values .............................................................................. 99

Contents • v

Storing Parameter Sets to Compare Simulation Results ............................... 100
4.3 Simulation Progress Messages ............................................................... 100
4.4 Managing Simulation Results and Snapshots ............................................ 101
Storing Results .................................................................................... 101
Saving and Using Snapshots .................................................................. 102
4.5 Customizing Plot Window Configurations ................................................ 103
Example: Plotting Multiple Quantities in Individual Graphs ......................... 104
Example: Plotting One Quantity versus Another ........................................ 106
4.6 Visualizing a Multibody Model .............................................................. 109
3-D Visualization and Multibody Settings ................................................ 109
The 3-D Workspace ............................................................................. 111
Viewing and Browsing 3-D Models ........................................................ 112
Adding Shapes to a 3-D Model .............................................................. 114
Building a Model in the 3-D Workspace ................................................... 117
Example: Building and Animating a Double Pendulum Model in the 3-D Workspace ................................................................................................. 121
4.7 Best Practices: Simulating and Visualizing a Model ................................... 129
Use an External C Compiler to Run Simulations with Longer Durations ......... 129
Compare Results Generated by Sections of Your Model .............................. 129
5 Analyzing and Manipulating a Model ............................................................ 131
5.1 Overview ........................................................................................... 131
MapleSim Apps .................................................................................. 131
Working with Apps .............................................................................. 133
Working with Templates and Scripting Worksheets .................................... 133
Using Subsystems ............................................................................... 134
5.2 Retrieving Equations and Properties from a Model .................................... 135
5.3 Analyzing Linear Systems ..................................................................... 135
Linear System Analysis ........................................................................ 136
5.4 Optimizing Parameters ......................................................................... 136
5.5 Generating and Exporting C Code from a Model ....................................... 138
Preparing the Model for Export in MapleSim ............................................ 139
Opening the Code Generation App .......................................................... 140
Loading the Subsystem ......................................................................... 140
Customizing, Defining, and Assigning Parameter Values to Specific Ports ...... 141
Selecting the Code Export Options .......................................................... 142
Generating and Saving the C code .......................................................... 145
5.6 Generating a Custom Component from External C Code/Library Definition .... 146
Opening the External C Code/Library Definition App ................................. 147
Specifying the C/Library Code Location and Options ................................. 147
Defining the C/Library Code Location and Options .................................... 148
Component Generation ......................................................................... 148
5.7 Working with the MapleSim API and Maple Commands ............................. 149
5.8 Working with Maple Embedded Components ........................................... 149

vi • Contents

6 MapleSim Tutorials .................................................................................... 151
6.1 Tutorial 1: Modeling a DC Motor with a Gearbox ...................................... 151
Adding a Gearbox to a DC Motor Model .................................................. 151
Simulating the DC Motor with the Gearbox Model .................................... 153
Grouping the DC Motor Components into a Subsystem .............................. 154
Assigning Global Parameters to a Model .................................................. 155
Rerunning the Simulation with Different Parameter Values .......................... 157
Changing Input and Output Values .......................................................... 158
6.2 Tutorial 2: Modeling a Cable Tension Controller ....................................... 160
Building a Cable Tension Controller Model .............................................. 160
Specifying Component Properties ........................................................... 162
Rerunning the Simulation with Different Parameter Values .......................... 163
Simulating the Cable Tension Controller .................................................. 164
6.3 Tutorial 3: Modeling a Nonlinear Damper ................................................ 166
Generating a Spring Damper Custom Component ...................................... 166
Providing Damping Coefficient Values .................................................... 166
Building the Nonlinear Damper Model .................................................... 167
Assigning a Parameter to a Subsystem ..................................................... 171
Simulating the Nonlinear Damper with Linear Spring Model ....................... 173
6.4 Tutorial 4: Modeling a Planar Slider-Crank Mechanism .............................. 175
Creating a Planar Link Subsystem .......................................................... 175
Defining and Assigning Parameters ......................................................... 178
Creating the Crank and Connecting Rod Elements ..................................... 179
Adding the Fixed Frame, Sliding Mass, and Joint Elements ........................ 180
Specifying Initial Conditions ................................................................. 181
Simulating the Planar Slider-Crank Mechanism ......................................... 181
6.5 Tutorial 5: Using the Custom Component Template ................................... 183
Example: Modeling a Temperature Dependent Resistor ............................... 183
Example: Compliant Contact and Piecewise Functions ............................... 188
Example: Custom Ports ........................................................................ 193
Advanced Uses for Custom Components .................................................. 198
6.6 Tutorial 6: Using the External C Code/DLL Custom Component App ............ 203
6.7 Tutorial 7: Using the Equation Extraction App .......................................... 208
App Description .................................................................................. 209
Generating the Equations ...................................................................... 211
6.8 Tutorial 8: Modeling Hydraulic Systems .................................................. 213
Computational Issues ........................................................................... 214
Basic Hydraulic Library Components ...................................................... 214
Basic Hydraulic Equations .................................................................... 216
Analysis of Simple Hydraulic Networks ................................................... 218
Overview of Controlling Hydraulic Flow Path .......................................... 221
Mechanical and Hydraulic Systems ......................................................... 222
Overview of Compressibility of Hydraulic Liquids .................................... 230

Contents • vii

Overview of Fluid Inertia Models ........................................................... 231
Overview of Water Hammer Models ....................................................... 233
Overview of Hydraulic Custom Components ............................................ 241
7 Reference: MapleSim Keyboard Shortcuts ...................................................... 245
Glossary .................................................................................................... 251
Index ........................................................................................................ 253

viii • Contents

List of Figures
Figure 1.1: Causal Model Block Diagram ............................................................. 2
Figure 1.2: Acausal Model Block Diagram ........................................................... 3
Figure 1.3: Simple Through and Across Variable Model .......................................... 3
Figure 1.4: Simple Through and Across Variable Electrical Model ............................ 3
Figure 1.5: RLC Circuit .................................................................................... 4
Figure 1.6: RLC MapleSim Circuit ..................................................................... 5
Figure 1.7: MapleSim Window ........................................................................... 6
Figure 1.8: Voltage Response Plot ..................................................................... 14
Figure 1.9: EMF and Inertia connections ............................................................ 15
Figure 1.10: Plots of DC Motor Torque and Speed ................................................ 17
Figure 2.1: Components view in the Model Tree .................................................. 21
Figure 2.2: Component selection using the Model Tree .......................................... 22
Figure 2.3: Exploring a subsystem ..................................................................... 23
Figure 2.4: Model Navigational Controls ............................................................ 23
Figure 2.5: Specifying Units using the Conversion Block ....................................... 26
Figure 2.6: Initial Conditions ............................................................................ 27
Figure 2.7: Subsystem Group ........................................................................... 28
Figure 2.8: Creating a Subsystem ...................................................................... 29
Figure 2.9: Creating Multiple Subsystems ........................................................... 32
Figure 2.10: Subsystem Definition .................................................................... 33
Figure 2.11: Adding Multiple Subsystems to a Model ........................................... 34
Figure 2.12: DC Motor Subsystem .................................................................... 36
Figure 2.13: Copy Subsystem Dialog ................................................................. 42
Figure 2.14: Attachments ................................................................................. 59
Figure 2.15: Verifying Force Arrows .................................................................. 70
Figure 2.16: Center of Mass Placement Best Practice ............................................ 70
Figure 2.17: Hydraulic Model ........................................................................... 71
Figure 3.1: The Add Apps or Templates tab ........................................................ 74
Figure 3.2: Equations Defining a Custom Component ........................................... 77
Figure 3.3: Port Mappings ............................................................................... 78
Figure 3.4: Variable to Port Mapping ................................................................. 78
Figure 3.5: Generated Custom Component .......................................................... 79
Figure 3.6: Completed Custom Component Model ............................................... 80
Figure 3.7: Double Mass-Spring-Damper Equations ............................................. 82
Figure 3.8: Port Mapping for Double Mass-Spring-Damper .................................... 82
Figure 3.9: Resistor Port Mapping ..................................................................... 84
Figure 3.10: Nonlinear Spring-Damper Custom Component ................................... 85
Figure 4.1: Simulation Process ......................................................................... 93
Figure 4.2: Simulation Results Progress Messages .............................................. 101
Figure 4.3: Snapshots in the Advanced Simulation Settings .................................. 102
Figure 4.4: The Stored Results Palette and Snapshots .......................................... 103ix

x • List of Figures

Figure 4.5: Simulation Graphs ........................................................................ 104
Figure 4.6: Custom Plot Window ..................................................................... 106
Figure 4.7: Plot One Quantity Versus Another .................................................... 108
Figure 4.8: 3-D Workspace ............................................................................. 111
Figure 4.9: 3-D View Controls ........................................................................ 112
Figure 4.10: Perspective View Double Pendulum ................................................ 113
Figure 4.11: Orthographic View Double Pendulum ............................................. 113
Figure 4.12: Implicit Geometry Double Pendulum .............................................. 114
Figure 4.13: Attached Shapes ......................................................................... 115
Figure 6.1: Cable Tension Controller ................................................................ 165
Figure 6.2: Nonlinear Damper Model ............................................................... 169
Figure 6.3: Planar Slider-Crank Mechanism ...................................................... 175
Figure 6.4: Temperature Dependent Resistor ...................................................... 187
Figure 6.5: Falling Ball .................................................................................. 188
Figure 6.6: Bouncing Ball Dynamics ................................................................ 189
Figure 6.7: Bouncing Ball .............................................................................. 191
Figure 6.8: Bouncing Ball Result ..................................................................... 193
Figure 6.9: Custom Ports ............................................................................... 195
Figure 6.10: Using a Custom Port .................................................................... 196
Figure 6.11: Centrifugal Pump Head Flow Rate Curve ......................................... 199
Figure 6.12: Centrifugal Pump Custom Component ............................................ 200
Figure 6.13: External C Code Definition for Windows ......................................... 204
Figure 6.14: External C Code Definition for Unix ............................................... 204
Figure 6.15: Flow Through a Pipe ................................................................... 219
Figure 6.16: Controlling Flow Path .................................................................. 222
Figure 6.17: Fixed Flow Rate Source ............................................................... 223
Figure 6.18: Translational Motion with Fixed Pressure Source .............................. 225
Figure 6.19: Fixed Pressure Source Results ....................................................... 227
Figure 6.20: Translational Fixed Flange Hydraulic component .............................. 227
Figure 6.21: Rotational Fixed Flange Hydraulic component .................................. 228
Figure 6.22: Pascal's Principle Example ............................................................ 230
Figure 6.23: Hydraulic Liquids Compressibility ................................................. 230
Figure 6.24: System without Fluid Inertia .......................................................... 232
Figure 6.25: System with Fluid Inertia .............................................................. 232
Figure 6.26: System with and without Fluid Inertia ............................................. 233
Figure 6.27: Water Hammer ........................................................................... 234
Figure 6.28: Discretized Pipeline Segment ........................................................ 235
Figure 6.29: Water Hammer Pressure Flow Rate ................................................. 238
Figure 6.30: Pressure Surge with an Accumulator ............................................... 241
Figure 6.31: Head Flow Rate .......................................................................... 242
Figure 6.32: Centrifugal Pump Custom Component Equations .............................. 242
Figure 6.33: Gravity Head Custom Component Equations .................................... 243

List of Tables
Table 1.1: Through and Across Variable Domain Types ........................................... 4
Table 1.2: MapleSim Window Components .......................................................... 6
Table 2.1: MapleSim Component Library ........................................................... 19
Table 2.2: Model Navigation Controls ................................................................ 24
Table 2.3: Domain-Specific Connection Line Colors ............................................. 25
Table 2.4: 2-D Math Notation Key Combinations ................................................. 64
Table 3.1: Port Map ........................................................................................ 79
Table 3.2: Signal Flow Components ................................................................... 80
Table 3.3: Characteristics of Through and Across Variables .................................... 83
Table 3.4: Through and Across Variable Mathematical Relationship ........................ 83
Table 3.5: Resistor Variables and Parameters ....................................................... 83
Table 4.1: Simulation Settings .......................................................................... 95
Table 4.2: Advanced Simulation Settings ............................................................ 97
Table 4.3: Multibody Parameter Values ............................................................. 110
Table 4.4: 3-D Visualization Parameter Values ................................................... 110
Table 4.5: 3-D Workspace Controls .................................................................. 112
Table 5.1: MapleSim Apps ............................................................................. 131
Table 5.2: MapleSim Templates ...................................................................... 133
Table 6.1: Temperature Dependent Resistor Components ..................................... 186
Table 6.2: Bouncing Ball Multibody Components ............................................... 192
Table 6.3: Centrifugal Pump Data .................................................................... 199
Table 6.4: Circular Pipe Parameters ................................................................. 199
Table 6.5: Centrifugal Pump Components ......................................................... 200
Table 6.6: External C Code DLL Custom Components and Required Settings .......... 206
Table 6.7: Basic Hydraulic Library Components ................................................. 215
Table 6.8: Bernoulli and Darcy Equation Notation .............................................. 217
Table 6.9: Circular Pipe Parameters ................................................................. 218
Table 6.10: Hydraulic Components .................................................................. 219
Table 6.11: Spool Valve ................................................................................. 222
Table 6.12: Translational Motion with Fixed Flow Rate Sources ............................ 224
Table 6.13: Translational Motion with a Fixed Pressure Source ............................. 226
Table 6.14: Actuating Multibody Components ................................................... 228
Table 6.15: Hydraulic Liquids Compressibility Components ................................. 230
Table 6.16: Confined Hydraulic System Components .......................................... 231
Table 6.17: Fluid Inertia ................................................................................. 231
Table 6.18: Fluid Properties Values .................................................................. 235
Table 6.19: Water Hammer Parameters ............................................................. 236
Table 6.20: Accumulator Parameters Custom Component .................................... 240
Table 7.1: Operations on a File ........................................................................ 245
Table 7.2: Building a Model in the Block Diagram View ...................................... 245
Table 7.3: Adding Annotations to a Model ........................................................ 245

xi

xii • List of Tables

Table 7.4: Browsing a Model in the Block Diagram View .................................... 246
Table 7.5: Browsing a Model in the 3-D View .................................................... 247
Table 7.6: Simulating a Model ........................................................................ 248
Table 7.7: Navigating the Console Pane ............................................................ 249
Table 7.8: Modifying the Plot Window Layout ................................................... 249
Table 7.9: Editing a Modelica Custom Component .............................................. 249
Table 7.10: Miscellaneous .............................................................................. 250

Introduction
MapleSim Overview
MapleSimTM is a modeling environment for creating and simulating complex multidomain
physical systems. It allows you to build component diagrams that represent physical systems
in a graphical form. Using both symbolic and numeric approaches, MapleSim automaticallygenerates model equations from a component diagram and runs high-fidelity simulations.
Build Complex Multidomain Models
You can use MapleSim to build models that integrate components from various engineering
fields into a complete system. MapleSim features a library of hundreds of modeling components, including electrical, hydraulics, mechanical, and thermal devices; sensors andsources; and signal blocks. You can also create custom components to suit your modelingand simulation needs.
Advanced Symbolic and Numeric Capabilities
MapleSim uses the advanced symbolic and numeric capabilities of MapleTM to generate
the mathematical models that simulate the behavior of a physical system. You can, therefore,
apply simplification techniques to equations to create concise and numerically efficientmodels.
Pre-built Analysis Tools and Templates
MapleSim provides various pre-built apps and templates in the form of Maple worksheetsfor viewing model equations and performing advanced analysis tasks, such as parameter
optimization. To analyze your model and present your simulation results in an interactive
format, you can use Maple features such as embedded components, plotting tools, anddocument creation tools. You can also translate your models into C code and work withthem in other applications and tools, including applications that allow you to perform realtime simulation.
Interactive 3-D Visualization Tools
The MapleSim 3-D visualization environment allows you to build and animate 3-D graphical representations of your multibody mechanical system models. You can use this environment to validate the 3-D configuration of your model and visually analyze the behaviorof your system under different conditions and at different simulation start times.

Related Products
MapleSim 2024.1 requires Maple 2024.1.

xiii

xiv • Introduction

MaplesoftTM also offers a suite of toolboxes, add-ons, and other applications that extend
the capabilities of Maple and MapleSim for engineering design projects. For a complete
list of products, visit http://www.maplesoft.com/products.

Related Resources
Resource

Description
System requirements and installation instructions for MapleSim.
The MapleSim Product Installation and Licensing Guide is
MapleSim ProductInstallation and Licensing available in the Install.html file located in the folder where you
installed MapleSim, or on the websiteGuide
https://www.maplesoft.com/documentation_center
Provides the following information:• MapleSim User's Guide: conceptual information about
MapleSim, an overview of MapleSim features, and tutorials
to help you get started.
MapleSim Help System• Using MapleSim: help topics for model building, simulation,
and analysis tasks.
• MapleSim Component Library: descriptions of the modelingcomponents available in MapleSim.

MapleSim Examples
MapleSim User's Guide
Examples

MapleSim Online
Resources

MapleSim Model Gallery

Model examples from various engineering domains. From theHelp menu, select Examples to access these examples.
Model and Tutorial examples used in the User's Guide. To accessthese examples, from the Help menu, select Examples > User's
Guide Examples. The examples are listed by chapter, in the orderthat they appear in the User's Guide.
Training webinars, product demonstrations, videos, sample
applications, and more.
For more information, visit
http://www.maplesoft.com/products/maplesim.
A collection of sample models, custom components, and analysis
templates that you can download and use in your MapleSim
projects.
For more information, visit
http://www.maplesoft.com/products/maplesim/modelgallery/.

For additional resources, visit http://www.maplesoft.com/site_resources.

Getting Help
To request customer support or technical support, visit http://www.maplesoft.com/support.

Introduction • xv

Customer Feedback
Maplesoft welcomes your feedback. For comments related to the MapleSim product documentation, contact doc@maplesoft.com.

xvi • Introduction

1 Getting Started with MapleSim
In this chapter:• Physical Modeling in MapleSim (page 1)• The MapleSim Window (page 6)• Basic Tutorial: Modeling an RLC Circuit and DC Motor (page 8)

1.1 Physical Modeling in MapleSim
Physical modeling, or physics-based modeling, incorporates mathematics and physical laws
to describe the behavior of an engineering component or a system of interconnected components. Since most engineering systems have associated dynamics, the behavior is typicallydefined with ordinary differential equations (ODEs).
To help you develop models quickly and easily, MapleSim provides the following features:

Topological or “Acausal” System Representation
The signal-flow approach used by traditional modeling tools requires system inputs andoutputs to be defined explicitly. In contrast, MapleSim allows you to use a topologicalrepresentation to connect interrelated components without having to consider how signals
flow between them.

Mathematical Model Formulation and Simplification
A topological representation maps readily to its mathematical representation and the symbolic capability of MapleSim automates the generation of system equations.
When MapleSim formulates the system equations, several mathematical simplification tools
are applied to remove any redundant equations and multiplication by zero or one. The simplification tools then combine and reduce the expressions to get a minimal set of equations
required to represent a system without losing fidelity.

Advanced Differential Algebraic Equation Solvers
Algebraic constraints are introduced in the topological approach to model definition. Problems that combine ODEs with these algebraic constraints are called Differential Algebraic
Equations (DAEs). Depending on the nature of these constraints, the complexity of the DAE
problem can vary. An index of the DAEs provides a measure of the complexity of the
problem. Complexity increases with the index of the DAEs.
The development of generalized solvers for complex DAEs is the subject of much researchin the symbolic computation field. With Maple as its computation engine, MapleSim uses

1

2 • 1 Getting Started with MapleSim

advanced DAE solvers that incorporate leading-edge symbolic and numeric techniques forsolving high-index DAEs.

Acausal and Causal ModelingReal engineered assemblies, such as motors and powertrains, consist of a network of interacting physical components. They are commonly modeled in software by block diagrams.
The lines connecting two blocks indicate that they are coupled by physical laws. Whensimulated by software, block diagrams can either be causal or acausal.
Causal Modeling
Many simulation tools are restricted to causal (or signal-flow) modeling. In these tools, a
unidirectional signal, which is essentially a time-varying number, flows into a block. The
block then performs a well-defined mathematical operation on the signal and the result
flows out of the other side. This approach is useful for modeling systems that are defined
purely by signals that flow in a single direction, such as control systems and digital filters.

Figure 1.1: Causal Model Block Diagram

This approach is analogous to an assignment, where a calculation is performed on a known
variable or set of variables on the right hand side and the result is assigned to another variable
on the left:

Acausal Modeling
Modeling how real physical components interact requires a different approach. In acausal
modeling, a signal from two connected blocks travels in both directions. The programming
analogy would be a simple equality statement:

The signal includes information about which physical quantities (for example, energy, current,
torque, heat and mass flows) must be conserved. The blocks contain information about
which physical laws (represented by equations) they must obey and, hence, which physicalquantities must be conserved.

1.1 Physical Modeling in MapleSim • 3

Figure 1.2: Acausal Model Block Diagram

MapleSim allows you to use both approaches. You can simulate a physical system (withacausal modeling) together with the associated logic or control loop (with causal modeling)in a manner that suits either task best.
Through and Across Variables
When using the acausal modeling approach, it is useful to identify the through and acrossvariables of the component you are modeling. In general terms, an across variable represents
the driving force in a system and a through variable represents the flow of a conserved
quantity. The through variable also establishes the flow direction for the sign conventionof the conserved quantity.

Figure 1.3: Simple Through and Across Variable Model

For an example of sign convention and how arrow direction represents a force acting on
the model, from the Help menu, select Examples > User's Guide Examples > Chapter
1, and then select the Constant Acceleration, Sign Convention and Arrow Convention
examples.
In the following example, in an electrical circuit, the through variable, i, is the current andthe across variable, V, is the voltage drop:Figure 1.4: Simple Through and Across Variable Electrical Model4 • 1 Getting Started with MapleSim

The following table lists some examples of through and across variables for other domains:
Table 1.1: Through and Across Variable Domain Types
DomainThroughAcrossElectrical
Magnetic

Current (A)Magnetic Flux (Wb)

Voltage (V)MMF (A)

Mechanical (translational)

Force (N)

Velocity

Mechanical (rotational)

Torque (N.m)

Angular Velocity

Hydraulic

Flow

Pressure

Heat flow

Heat flow (W)Temperature (K)As a simple example, the form of the governing equation for a resistor isThis equation, in conjunction with Kirchhoff’s conservation of current law, allows a complete
representation of a circuit.
andTo extend this example, the following schematic diagram describes an RLC circuit, anelectrical circuit consisting of a resistor, inductor, and a capacitor connected in series:

Figure 1.5: RLC Circuit

If you wanted to model this circuit manually, it can be represented with the following
characteristic equations for the resistor, inductor, and capacitor respectively:

1.1 Physical Modeling in MapleSim • 5

By applying Kirchhoff's current law, the following conservation equations are at points a,b, and c:

These equations, along with a definition of the input voltage (defined as a transient goingfrom 0 to 1 volt, 1 second after the simulation starts)

provide enough information to define the model and solve for the voltages and currents
through the circuit.
In MapleSim, all of these calculations are performed automatically; you only need to draw
the circuit and provide the component parameters. These principles can be applied equallyto all engineering domains in MapleSim and allow you to connect components in one domain
with components in others easily.
In the Basic Tutorial: Modeling an RLC Circuit and DC Motor (page 8) section of thischapter, you will model the RLC circuit described above and explore the capabilities of
MapleSim to mix causal models with acausal models. The following figure shows how theRLC circuit diagram appears when it is built in MapleSim.

Figure 1.6: RLC MapleSim Circuit6 • 1 Getting Started with MapleSim

For an another example of how a model can be represented using causal and acausal components, from the Help menu, select Examples > User's Guide Examples > Chapter 1,
and then select the Double Mass Spring Damper example.

1.2 The MapleSim Window
The MapleSim window contains the following panes and components:

Figure 1.7: MapleSim Window
Table 1.2: MapleSim Window Components
Component
Main Toolbar

Model Workspace Toolbar
Annotations Toolbar
Model Workspace

Description
Contains tools for running a simulation, viewing simulation results,
searching the MapleSim help system, and performing other common
tasks.
Contains tools for browsing your model and subsystems
hierarchically, changing the model view, viewing the corresponding
Modelica code, grouping components, and adding probes.
Contains tools for adding annotations and laying out objects.
The area in which you build and edit a model in a block diagramview.

1.2 The MapleSim Window • 7

Component

Description
Contains expandable menus with tools that you can use to build amodel and manage your MapleSim project. This pane contains fivetabs:
• Library Components (): contains palettes with sample
models and domain-specific components that you can add tomodels.

Palettes Pane

• Local Components (): contains palettes of the subsystems
and custom components in your model.
• Model Tree (your model.

): contains a model tree for navigation through• Attached Files (): contains attachments to your model,
including documents, parameter sets, and CAD drawings.
Use buttons on the Console Toolbar to display the following panes:

Console• Console Output: displays progress messages indicating thestatus of the MapleSim engine during a simulation and allows
you to clear the console using Clear Console ().
• Diagnostics Information: displays diagnostic messages fordebugging as you build your model identifying the subsystem
in which the errors are located.
Contains controls for selecting the type of messages shown in theConsole Toolbar
console ().

Contains the following tabs:• Properties ( ): allows you to view and edit modelingcomponent properties, such as names, parameter values, initialconditions, and probe settings.

Parameters Pane

• Simulation Settings (): allows you to specify simulation
options such as the duration of the simulation and optionalparameter values for the solver and simulation engine.
• Multibody Settings (): allows you to specify options forvisualizing multibody components in the 3-D Workspace andthe 3-D Playback Window.
The contents of this pane change depending on your selection in
the Model Workspace.

8 • 1 Getting Started with MapleSim

1.3 Basic Tutorial: Modeling an RLC Circuit and DC
MotorThis tutorial introduces you to the modeling components and basic tools in MapleSim. It
illustrates the ability to mix causal models with acausal models.
In this tutorial, you will perform the following tasks:
1. Build an RLC circuit model.
2. Set parameter values to specify component properties.
3. Add probes to identify values of interest for the simulation.
4. Simulate the RLC circuit model.
5. Modify the RLC circuit diagram to create a simple DC motor model.
6. Simulate the DC motor model using different parameters.
For an example of the RLC Circuit model, from the Help menu, select Examples > User's
Guide Examples > Chapter 1, and then select the RLC Circuit example. The model you
build is identical to the RLC Circuit model.

Building an RLC Circuit Model
To build the RLC circuit, you add components in the Model Workspace and connect themin a system to form a diagram. In this example, the RLC circuit model contains ground,resistor, inductor, capacitor, and signal voltage source components from the Electricalcomponent library. It also contains a step input source, which is a signal generator thatdrives the input voltage level in the circuit.
To build an RLC circuit:
1. In the Library Components tab () at the left of the Model Workspace, click thetriangle beside Electrical to expand the palette. In the same way, expand the Analog
menu, and then expand the Passive submenu.

1.3 Basic Tutorial: Modeling an RLC Circuit and DC Motor • 9

2. From the Electrical > Analog > Passive menu, drag the Ground component to theModel Workspace.

3. Add the following electrical components to the Model Workspace.
• From the Electrical > Analog > Passive> Resistors menu, add the Resistor component.

10 • 1 Getting Started with MapleSim• From the Electrical > Analog > Passive > Inductors menu, add the Inductor component.
• From the Electrical > Analog > Passive > Capacitors menu, add the Capacitor
component.
• From the Electrical > Analog > Sources > Voltage menu, add the Signal Voltage
component.
4. Drag the components in the arrangement shown below.

5. To rotate the Signal Voltage component clockwise, right-click (Control-click for Mac®)
the Signal Voltage component in the Model Workspace and select Rotate Clockwise.
6. To flip the Signal Voltage component horizontally, right-click (Control-click for Mac)the component again and select Flip Horizontal. Make sure that the positive (blue) port
is at the top.
7. To rotate the Capacitor component clockwise, right-click (Control-click for Mac) the
Capacitor icon in the Model Workspace and select Rotate Clockwise.
You can now connect the modeling components to define interactions in your system.
8. Hover your mouse pointer over the Ground component port. The port is highlighted ingreen.

9. Click the Ground input port to start the connection line.
10. Hover your mouse pointer over the negative port of the Signal Voltage component.

1.3 Basic Tutorial: Modeling an RLC Circuit and DC Motor • 11

11. Click the port once. The Ground component is connected to the Signal Voltage component.
12. Connect the remaining components in the arrangement shown below.

13. You can now add a source to your model. Expand the Signal Blocks palette, expand the
Sources menu and then expand the Real submenu.
14. From the palette, drag the Step source and place it to the left of the Signal Voltage
component in the Model Workspace. The step source has a specific signal flow, represented by the arrows on the connections. This flow causes the circuit to respond to the
input signal.
15. Connect the Step source to the Signal Voltage component. The complete RLC circuit
model is shown below.

Specifying Component Properties
To specify component properties, you can set parameter values for components in yourmodel.

12 • 1 Getting Started with MapleSim

To specifying component properties:
1. In the Model Workspace, click the Resistor component. The Properties tab ( ) at
the right of the Model Workspace displays the name and parameter values of the resistor.
2. In the R field, enter 24, and press Enter. The resistance changes to 24 ..

3. Specify the following parameter values for the other components. You can specify units
for a parameter by selecting a value from the drop-down menu found beside the parametervalue field.
• For the Inductor, specify an inductance of 160• For the Capacitor, specify a capacitance of 200.
.

• For the Step source, specify a T0 value of 0.1 .

Adding a ProbeTo specify data values for a simulation, you can attach probes to lines or ports to the model.
In this example, you will measure the voltage of the RLC circuit.
To add a probe:
1. In the Model Workspace Toolbar, click Attach probe ().

2. Hover your mouse pointer over the line that connects the Inductor and Capacitor
components. The line is highlighted.
3. Click the line once. The probe appears in the Model Workspace.
4. Move the probe to an empty location on the Model Workspace, and then click theworkspace to position the probe.
5. Select the probe. The probe properties appear under the Properties tab (of the Model Workspace.

) to the right

6. Under the Properties tab, select the Voltage check box to include the voltage quantity
in the simulation graph.
7. To display a custom name for this quantity in the Model Workspace, enter Voltage asshown below and press Enter.

1.3 Basic Tutorial: Modeling an RLC Circuit and DC Motor • 13

The probe with the custom name is added to the connection line.

For another example of how to use a probe value in a simulation, from the Help menu, selectExamples > User's Guide Examples > Chapter 1, and then select the Sensors and Probes
example.

Simulating the RLC Circuit Model
Before simulating your model, you can specify the simulation duration run time.
To simulate the RLC circuit:
1. Click the Settings tab () on the right of the Parameters Pane and in the Simulation
section, set the simulation duration time (td) to 0.5 .
2. In the Advanced Simulation section, clear the Compiler check box.
3. Click Run Simulation ( ) in the Main Toolbar. MapleSim generates the systemequations and simulates the response to the step input.
When the simulation is complete, the voltage response is plotted in a graph.

14 • 1 Getting Started with MapleSim

Figure 1.8: Voltage Response Plot

4. Save the model as RLC_Circuit1.msim. The probes and modified parameter values are
saved as part of the model.

Building a Simple DC Motor Model
You will now add an electromotive force (EMF) component and a mechanical inertia
component to the RLC circuit model to create a DC motor model. In this example, you will
add components to the RLC circuit model using the search feature.
To build a simple DC motor:
1. In the Main toolbar, type EMF in the search bar. A drop-down list displays matches foryour search results.

1.3 Basic Tutorial: Modeling an RLC Circuit and DC Motor • 15

2. Hover over the Rotational EMF in the Library Components section of the drop-downlist. The Rotational EMF component appears in a tool square beside the search field.

3. Drag the Rotational EMF component to the modeling workspace and place it to theright of the Capacitor component.
4. Enter Inertia in the search bar.
5. Drag the Inertia component to the Model Workspace and place it to the right of the
Rotational EMF component.
6. Connect the components as shown below.

Figure 1.9: EMF and Inertia connections

16 • 1 Getting Started with MapleSim

Note: To connect the positive blue port of the Rotational EMF component, click the port
once, drag your mouse pointer to the line connecting the capacitor and inductor, and thenclick the line.
7. In the Model Workspace, click the Rotational EMF component.
8. In the Properties tab (), set the value of the transformation coefficient (k) to 10.

9. Click the Step component and change the value of the parameter, T0, to 1 .

Simulating the DC Motor Model
To simulate the DC motor:
1. In the Model Workspace, delete Probe1.
2. In the Model Workspace Toolbar, click Attach probe ().

3. Hover your mouse pointer over the line that connects the Rotational EMF and Inertia
components.
4. Click the line, and then click on an empty area of the workspace to position the probe.
5. Select the probe, and in the Properties tab ( ), select the Speed and Torque checkboxes and then clear the Angle check box. The probe, with an arrow indicating the direction of the conserved quantity flow, is added to the model. The direction of the conserved quantity flow (Torque) can be reversed by selecting the probe and then clicking
on Reverse Probe ( ) in the Properties tab.
6. Rename the probe Output.
7. Click a blank area in the Model Workspace.
8. In the Settings tab (), set the simulation duration time (td) to 5 .

9. Click Run Simulation () in the Main Toolbar.

10. Click Show Simulation Results (). The following graphs appear.

1.3 Basic Tutorial: Modeling an RLC Circuit and DC Motor • 17

Figure 1.10: Plots of DC Motor Torque and Speed

11. Save the model as DC_Motor1.msim.

18 • 1 Getting Started with MapleSim

2 Building a ModelIn this chapter:• The MapleSim Component Library (page 19)• Browsing a Model (page 20)• Defining How Components Interact in a System (page 24)• Specifying Component Properties (page 25)• Creating and Managing Subsystems (page 28)• Global and Subsystem Parameters (page 43)• Attaching Files to a Model (page 59)• Creating and Managing Custom Libraries (page 60)• Annotating a Model (page 62)• Entering Text in 2-D Math Notation (page 64)• Creating a Data Set for an Interpolation Table Component (page 65)• Best Practices: Building a Model (page 66)

2.1 The MapleSim Component Library
The MapleSim component library contains hundreds of components that you can use tobuild models. All of these components are organized in palettes according to their respective
domains: signal blocks, electrical, 1-D mechanical, multibody, hydraulics, pneumatics,
thermal, and magnetic. Most of these components are based on the Modelica Standard
Library 4.0.0.
Table 2.1: MapleSim Component Library
Library
Signal Blocks
Electrical
1-D Mechanical
Multibody
Hydraulics
Pneumatics

Description
Components to manipulate or generate input and output signals.
Components to model electrical analog circuits, single phaseand polyphase systems, and machines.
Components to model 1-D translational and rotational systems.
Components, including force, motion, and joint components,
to model multibody mechanical systems.
Components to model hydraulic systems, fluid power systems,
cylinders and actuators.
Components to model Ideal pneumatic systems with cylinders,
directional control valves, orifices, and actuators.

1920 • 2 Building a Model

Library
ThermalMagnetic

Description
Components to model heat flow and heat transfer.
Components to model magnetic circuits.

The library also contains sample models that you can view and simulate, for example,
complete electrical circuits and filters. For more information about the MapleSim librarystructure and modeling components, see the MapleSim Component Library in the
MapleSim Help system.
To extend the default library, you can create a custom modeling component from a mathematical model and add it to a custom library. For more information, see Creating Custom
Modeling Components (page 73).

Viewing Help Topics for Components
To view Help topics in the MapleSim Help system, perform any of the following tasks:• Right-click (Control-click for Mac) a modeling component in any of the palettes andselect Help from the context menu.
• Search for the topic in the help search box in the main toolbar. Help topics related to yoursearch term are listed in the Help Results section.
• Search for the help pages for components in the MapleSim Help system.

Updating Models Created in a Previous Release of MapleSim
In MapleSim 2024.1, the Modelica Standard Library 3.2.3 was replaced with the Modelica
Standard Library 4.0.0. If you created a model in an earlier version of MapleSim, you can
open it in MapleSim 2024.1 or later. The model will be updated automatically to use equivalent components from the Modelica Standard Library 4.0.0. For more information, seeUsing MapleSim > Updating Models Created in a Previous Release of MapleSim in
the MapleSim Help system.

2.2 Browsing a Model
Using the Model Tree or model navigation controls, you can browse your model to viewhierarchical levels of components in the Model Workspace. You can browse to the top
level for an overall view of your system. The top level is the highest level of your model:
it represents the complete system, which can include individual modeling components andsubsystem blocks that represent groups of components. You can also browse to sublevels
in your model to view the contents of individual subsystems or components.

2.2 Browsing a Model • 21

Model Tree
The Model Tree tab ( ) is located in the Palettes Pane. Use the Model Tree to browse
through and optionally search for elements in your model. Nodes in the model tree canrepresent attachments, component types, components, parameters, or probes, depending on
the model tree view. To change the model tree view, select a view from the list below the
Find text box. The following figure shows the drop-down menu available for the 5 DoF
Robot multibody example model.

Figure 2.1: Components view in the Model Tree

The following are of the model tree views you can select from.
• Attachments: This view shows the files attached to your model. Examples of attachments
include worksheets, spreadsheets, and CAD drawings. Double-click an attachment toopen the attachment in the appropriate program. Enter a term in Find to search for documents that match your term.
• Component Types: This view organizes the model tree view according to the type ofcomponent or subsystem. Component and subsystem nodes are identified by their type

22 • 2 Building a Modelfollowed by their name. Enter a term in Find to search for component types that matchyour term (the component's name is ignored in the search).
• Components: This view organizes the model tree view according to the Name of eachcomponent or subsystem. Component and subsystem nodes are identified by their namefollowed by their type (see Figure 2.1). Enter a term in Find to search for component
and subsystem names that match your term (the component type is ignored in the search).
This is the default model tree view.
• Connectors: This view shows all the connectors in your model.
• Parameters: This view shows the parameter definitions in your model. Parameter
definitions can come from parameter tables, parameter blocks, Modelica Records, or To
Variable components. Enter a term in Find to search for parameters names that matchyour term. For more information about the parameters view (including how to find allreferences to a parameter), see Using MapleSim > Building a Model > Navigating and
Searching with the Model Tree > Parameters View in the MapleSim Help system.
• Probes: This view shows all the probes in your model. The full path to the probe is given
in brackets after the name of the probe. Enter a term in Find to search for probes withnames that match your term.
To view the parameters associated with a component or subsystem, navigate the model tree
to the component node and then select the node. This highlights the element in the Model
Workspace, changes the Model Workspace view to display the element, and populates
the Properties tab ( ) with the configurable parameters for that element. See Figure 2.2
for an illustration of component selection.

Figure 2.2: Component selection using the Model Tree

2.2 Browsing a Model • 23

If you select more than one component from the model tree, the Properties tab displays all
the common configurable parameters for the components. If you change a parameter in theProperties tab, this updates the parameter for all of the selected components.
To explore a component or subsystem, you can either double-click the node in the model
tree or expand the node and then select one of its children. The Model Workspace view
changes to the appropriate level to explore the component or subsystem.

Figure 2.3: Exploring a subsystem

For more information on the Model Tree and how to manage complex models, see theUsing MapleSim > Building a Model > Navigating and Searching with the Model Treesection of the MapleSim Help system.

Model Navigation Controls
Alternatively, you can use the model navigation controls located in the Model Workspace
Toolbar to browse between modeling components, subsystems, and hierarchical levels ina diagram displayed in the Model Workspace.

Figure 2.4: Model Navigational Controls

The following table summarizes what these controls do and gives the keyboard shortcuts
associated with them.

24 • 2 Building a Model

Table 2.2: Model Navigation Controls
Control

Keyboard Shortcut

Description

Home

Return to the Main level of your model.

Ctrl+Up Arrow
Command+Up
Arrow (Mac)
Ctrl+Down Arrow
Command+Down
Arrow (Mac)

Navigate to the parent component.

Display the contents (or children) of the selectedcomponent.

2.3 Defining How Components Interact in a System
To define interactions between modeling components, you connect them in a system. In the
Model Workspace, you can draw a connection line between two connection ports.

You can also draw a connection line between a port and another connection line.

MapleSim permits connections between compatible domains only. By default, each line
type appears in a domain-specific color.

2.4 Specifying Component Properties • 25

Table 2.3: Domain-Specific Connection Line Colors
DomainMechanical 1-D rotational
Mechanical 1-D translational
Mechanical multibody
Electrical analog
Electrical multiphase
Magnetic
Digital logic
Boolean signal
Causal signal
Integer signal
ThermalPneumaticLine Color
Black
Green
Black
Blue
Blue
OrangePurplePink
Navy blue
OrangeRed
Light blue

The connection ports for each domain are also displayed in specific colors and shapes. For
more information about connection ports, see the MapleSim Component Library > Connectors Overview in the MapleSim Help system.
Components can have either scalar or vector connection ports. A scalar port has only one
quantity associated with it while a vector port can have more than one quantity (or dimension)associated with it. Connections between ports with different dimensions are difficult tomanage because what quantities are physically connected is not obvious in the Model
Workspace. The Connections Manager simplifies these types of connections by letting
you examine which ports are connected and change them if necessary. To access the Connections Manager, select a connection line in the Model Workspace and then select theProperties tab ( ). For more information, see Using MapleSim > Building a Model >Using the Connections Manager in the MapleSim Help system.

2.4 Specifying Component Properties
To specify component properties, you can set parameter values for components in yourmodel. When you select a component in the Model Workspace, the configurable parametervalues for that component appear in the Properties tab (MapleSim window.

) located on the right side of theNote: Not all components provide editable parameter values.
You can enter parameter values in 2-D math notation, which is a formatting option that allows
you to add mathematical text such as superscripts, subscripts, and Greek characters. For
more information, see Entering Text in 2-D Math Notation (page 64).

26 • 2 Building a Model

Note: Most parameters in the MapleSim Component Library have default values. However,for some parameters, these default values are simply placeholders that may not represent
realistic values for use in a simulation. These placeholder values use a blue font to distinguishthem from other parameter values. You should replace these values with values that are
more suitable for your simulation. For more information, see Using MapleSim> Building
a Model > Specifying Parameters in the MapleSim Help system.

Specifying Parameter Units
You can use the drop-down menus beside parameter fields with dimensions to specify units
for parameter values. For example, the image below displays the configurable parameterfields for a Mass component. You can optionally specify the mass in kg, lbm, g, or slug,
and the length in m, cm, mm, ft, or in.

When you simulate a model, MapleSim automatically converts all parameter units to theInternational System of Units (SI). You can, therefore, select more than one system of units
for parameter values throughout a model.
If you want to convert the units of a signal, use the Conversion Block component from the
Signal Converters menu in the Signal Blocks palette. This component allows you to performconversions in dimensions such as time, temperature, velocity, pressure, and volume. In thefollowing example, a Conversion Block component is connected between a translational
Position Sensor and a Feedback component to convert the units of an output signal.

Figure 2.5: Specifying Units using the Conversion BlockIf you include an electrical, 1-D mechanical, hydraulic, or thermal sensor in your model,
you can also select the units in which to generate an output signal.

2.4 Specifying Component Properties • 27

Specifying Initial Conditions
You can set parameter values to specify initial conditions for components from all domains
in MapleSim. When you select a component that contains state variables in the Model
Workspace, the available initial condition fields appear in the Properties tab, along withthe other configurable parameter values for that component.
For example, the image below displays the initial position and initial velocity fields thatyou can set for a Mass component.

Figure 2.6: Initial Conditions

Specifying How Initial Conditions are Enforced
You can determine how the initial conditions that you specified for a particular component
are enforced. The options are ignore ( ), guess ( ), and enforce ( ). You can selectthese options for initial condition parameters individually by clicking the buttons besidethe applicable initial condition fields.

28 • 2 Building a ModelIf you select the ignore option, the parameter value that you enter in the initial condition
field is ignored and the solver uses a default value for the initial condition, typically zero.
This option is the default setting for all of the initial condition fields.
If you select the guess option, the solver treats the parameter value you entered in the initialcondition field as a best guess value. In other words, the best guess value is a starting point
for determining the initial configuration of the system for which there is a solution to theset of equations that describe the system. The solver initially computes a solution to thesystem of equations using this best guess value; however, if no solution is found, the solver
computes a solution to the system of equations using an initial condition value that is close
to the best guess value.
If you select the enforce option, the solver uses the parameter value that you enter in theinitial condition field as a start value for the simulation. Similar to the guess option, thesolver searches for a solution to the system of equations using the parameter value youentered in the initial condition field. However, unlike the guess option, if there is no solution,no other value is substituted, and an error message appears.
For more information about selecting these options, see Best Practices: Enforcing Initial
Conditions (page 72).
For an example of how initial conditions are enforced, from the Help menu, select Examples> User's Guide Examples > Chapter 2, and then select the Relative Positions example.

2.5 Creating and Managing Subsystems
A subsystem (or compound component) is a set of modeling components that are grouped
in a single block component. A simple DC motor subsystem is shown below.

Figure 2.7: Subsystem GroupYou can create a subsystem to group components that form a complete system, for example,
a tire or DC motor. You can also create a subsystem to improve the layout of a diagram in
the Model Workspace, add multiple copies of a system to a model, analyze a component
group in Maple or to quickly assign parameters and variables. You can organize yourmodel hierarchically by creating subsystems within other subsystems.

2.5 Creating and Managing Subsystems • 29

After you create a subsystem you will be able to assign parameters and variables to allcomponents in that subsystem using the Advanced Parameter Settings and Advanced
Variable Settings tools in the Properties tab ().

For best practices on creating subsystems in MapleSim, see Best Practices: Laying Out andCreating Subsystems (page 66).

Example: Creating a Subsystem
In the following example, you will group the electrical components of a DC motor model
into a subsystem.
To create a subsystem
1. From the Help menu, select Examples > User's Guide Examples > Chapter 2, andthen select the Simple DC Motor example.
2. Draw a box around the electrical components by dragging your mouse over them.

Figure 2.8: Creating a Subsystem

30 • 2 Building a Model

3. From the Edit menu, select Create Subsystem. Alternatively, right-click (Control-click,for Mac) the boxed area and select Create Subsystem.
4. In the dialog box, enter DC Motor.
5. Click OK. A white block, which represents the DC motor, appears in the Model
Workspace.

In this example, you created a standalone subsystem, which can be edited and manipulated
independently of other subsystems in your model. If you want to add multiple copies of thesame subsystem to your model and edit those subsystems as a group, you can create a subsystem definition. For more information, see Adding Multiple Copies of a Subsystem to a
Model (page 31).

Viewing the Contents of a Subsystem
To view the contents of a subsystem, double-click the subsystem icon in the Model
Workspace. The detailed view of a subsystem appears.

2.5 Creating and Managing Subsystems • 31

In this view, the broken line indicates the subsystem boundary. You can edit the connectionlines and components within the boundary, and add subsystem ports to connect the subsystem
to other components.
To browse to the top level of the model or to other subsystems, use the Model Navigation
controls in the Model Workspace Toolbar. For details on Model Navigation controls, seeBest Practices: Laying Out and Creating Subsystems (page 66).

Adding Multiple Copies of a Subsystem to a ModelIf you plan to add multiple copies of a subsystem to a model and want all of the copies tohave the same configuration, you can create a subsystem definition. A subsystem definitionis the base subsystem that defines the attributes and configuration that you want a series ofsubsystems to share.
For example, if you want to add three DC motor subsystems that all have identical components and resistance values in your model, you would perform the following tasks:
1. Build a DC motor subsystem with the desired configuration in the Model Workspace.
2. Use that subsystem configuration to create a subsystem definition and add it to theComponents palette under the Local Components tab.
3. Add copies of the DC motor subsystem to your model using the subsystem definition asa source.
To add copies of the DC motor subsystem to your model, you can drag the DC Motor subsystem definition icon from Components palette under the Local Components tab ()
and place it in the Model Workspace. The copies that you add to the Model Workspace
will then share a configuration that is identical to the subsystem definition in the Local
Components tab; the copies in the Model Workspace are called shared subsystems because
they share and refer to the configuration specified in their corresponding subsystem definition.

32 • 2 Building a Model

Figure 2.9: Creating Multiple Subsystems

Shared subsystems that are copied from the same subsystem definition are linked, whichmeans that changes you make to one shared subsystem will be reflected in all of the othershared subsystems that were created from the same subsystem definition. The changes arealso reflected in the subsystem definition entry in the Local Components tab. A sharedsubsystem is indicated on the model workspace by the icon .
Using the example shown above, if you change the resistance parameter of the Resistor
component in the DC Motor2 shared subsystem from 24Ω to 10Ω, the resistance value of
the Resistor component in the DC Motor1 and DC Motor3 shared subsystems and the DC
Motor subsystem definition in the Local Components tab will also be changed to 10Ω.
For more information, see Editing Subsystem Definitions and Shared Subsystems (page 34).
Example: Adding Subsystem Definitions and Shared Subsystems to a ModelIn the following example, you will create a DC Motor subsystem definition and add multiple
shared subsystems to your model.
Adding a Subsystem Definition to the Local Components Tab
To add a subsystem definition
1. In the Model Workspace, right-click (Control-click for Mac) the standalone DC motor
subsystem that you created in Example: Creating a Subsystem (page 29).
2. From the context menu, select Convert to Shared Subsystem.
3. Enter DC Motor as the name for the subsystem definition and click OK.
4. Under the Local Components tab (the Components palette.

) on the left side of the Model Workspace, expand2.5 Creating and Managing Subsystems • 33

Figure 2.10: Subsystem Definition

The subsystem definition is added to the Components palette and the subsystem in the
Model Workspace is converted into a shared subsystem called DC Motor1. This sharedsubsystem is linked to the DC Motor subsystem definition.
5. Save this model as DCMotorSubsystem.msim. You will be building on this model in
Example: Editing Shared Subsystems that are Linked to the Same Subsystem
Definition (page 34).
You can now use this subsystem definition to add multiple DC motor shared subsystems
to your MapleSim model.
Tip: If you want to use a subsystem definition in another model, add the subsystem definition
to a custom library. For more information, see Creating and Managing Custom
Libraries (page 60).
Adding Multiple DC Motor Shared Subsystems to a Model
To add multiple DC Motor shared subsystems to a model, drag the DC Motor subsystemdefinition icon from the Local Components tab and place it in the Model Workspace.

34 • 2 Building a Model

Figure 2.11: Adding Multiple Subsystems to a Model

When you create a new standalone subsystem or add shared subsystems to a model, a uniquesubscript number is appended to the subsystem name displayed in the Model Workspace.
As shown in the image above, subscript numbers are appended to the names of each DC
Motor shared subsystem. These numbers can help you to identify multiple subsystem copies
in your model.

Editing Subsystem Definitions and Shared Subsystems
If you edit a shared subsystem in the Model Workspace, your changes will be reflected in
the subsystem definition that is linked to the shared subsystem, as well as other sharedsubsystems that were copied from the same subsystem definition.
Example: Editing Shared Subsystems that are Linked to the Same Subsystem
Definition
In this example, you will create a model that contains two DC Motor shared subsystems,
and then edit the resistance values and icons for the shared subsystems. These shared subsystems are linked to the DC Motor shared subsystem definition that was created in Example:
Adding Subsystem Definitions and Shared Subsystems to a Model (page 32). You willverify that when you change one of the component values and the icon for one DC Motorshared subsystem, the other DC Motor shared subsystems in your model--as well as any
new DC Motor shared subsystems that you add in the future--will contain the changes.
Note: Before doing this example, you should have already gone through and stored theresults from Example: Adding Subsystem Definitions and Shared Subsystems to a
Model (page 32).

2.5 Creating and Managing Subsystems • 35

To use shared subsystems:
1. In MapleSim, open the DCMotorSubsystem.msim file that you created in Example:
Adding Subsystem Definitions and Shared Subsystems to a Model (page 32).
2. Under the Local Components tab (), expand the Components palette, and then draga second DC Motor shared subsystem on to the workspace, placing it below the existing
DC Motor shared subsystem.
3. Under the Library Components tab (), expand the 1-D Mechanical > Rotational> Common menu, and then drag a second Inertia component on to the workspace, placing
it below the existing Inertia component.
4. Make the following connections between the newly added components and the existing
components in the model.

5. In the Model Workspace, double-click the DC Motor1 shared subsystem. The detailed
view of the shared subsystem appears.

36 • 2 Building a Model

Figure 2.12: DC Motor Subsystem

Note that a heading with the shared subsystem name (DC Motor_1) followed by the subsystem definition name (DC Motor) appears at the top of the Model Workspace. In thedetailed view of all shared subsystems, this heading also appears to help you identify multiple
subsystem copies in your model. Also, when you select a shared subsystem, its subsystemdefinition name appears in the Type field in the Properties tab ().

6. Select the Resistor component (R1) and, in the Properties tab, click Parameters. Change
the resistance value to 50Ω.

2.5 Creating and Managing Subsystems • 37

7. In the Model Workspace Toolbar, click Icon View ().

8. You can customize the icon view of the subsystem. Click the edge of the icon boundaryand make it wider. If needed, drag the ports to the middle of the sides of the subsystemborder.
9. Using the Rectangle Tool ( ) in the Model Workspace Toolbar, click and drag yourmouse pointer to draw a shape in the box.

10. In the Model Workspace Toolbar, click Diagram ( ).
11. Click Main ( ) in the Model Workspace Toolbar to browse to the top level of themodel. Both of the DC Motor shared subsystems now display the square that you drew.

38 • 2 Building a Model

12. Under the Local Components tab on the left side of the MapleSim window, expand theComponents palette. As shown in the image below, your changes are also reflected in
the DC Motor entry in this palette.

If you double-click the DC Motor subsystems in the Model Workspace and select their
Resistor components, you will see that both of the shared subsystems now have a resistancevalue of 50Ω.
13. From the Local Components tab, drag a new copy of the DC Motor subsystem andplace it anywhere in the Model Workspace. Verify that the new copy displays the squarethat you drew and its resistance value is also 50Ω, and then delete it from the workspace.
14. Save this model as DCMotorSharedSubsystem.msim. You will be building on thismodel in Example: Removing the Link between a Shared Subsystem and Its Subsystem
Definition (page 38).
Example: Removing the Link between a Shared Subsystem and Its Subsystem
Definition
If your model contains multiple shared subsystems that are linked and you want to edit one
copy only, you can remove the link between a shared subsystem and its subsystem definition,and edit that subsystem without affecting others in the Model Workspace.

2.5 Creating and Managing Subsystems • 39

Note: Before doing this example, you should have already gone through and stored theresults from Example: Editing Shared Subsystems that are Linked to the Same Subsystem
Definition (page 34) and saved the results from that example.
To remove shared subsystem link:
1. Open the DCMotorSharedSubsystem.msim model that you created in Example: Editing
Shared Subsystems that are Linked to the Same Subsystem Definition (page 34).
2. In the Model Workspace, right-click (Control-click for Mac) the DC Motor1 sharedsubsystem.
3. Select Convert to Standalone Subsystem. The DC Motor1 subsystem is no longer
linked to the DC Motor subsystem definition in the Local Components tab; it is now
called copy of DC Motor.
4. Double-click the DC Motor1 shared subsystem.
5. Click Icon ().

6. Using the Rectangle Tool ( ), click and drag your mouse pointer to draw a shape inthe box in the Model Workspace.
7. Click Diagram ( ), and then click Main ( ) to browse to the top level of the model.
Your change is shown in the DC Motor1 shared subsystem in the Model Workspace
and the DC Motor subsystem definition in the Local Components tab. Note that yourchange is not shown in the copy of DC Motor subsystem that is no longer linked to the
DC Motor subsystem definition.
Tip: When you convert a shared subsystem to a standalone subsystem, it is a good practiceto assign the standalone subsystem a meaningful name that clearly distinguishes it fromexisting shared subsystems and subsystem definitions.

Working with Standalone Subsystems
Standalone subsystems are subsystems that are not linked to a subsystem definition. You
can create a standalone subsystem in two ways: by creating a new subsystem as shown in
Example: Creating a Subsystem (page 29) or by converting a shared subsystem to a standalone subsystem as shown in Example: Removing the Link between a Shared Subsystem
and Its Subsystem Definition (page 38). Standalone subsystems can be edited independently
without affecting other subsystems in the Model Workspace.
To identify a subsystem as a standalone subsystem, select a subsystem in the Model
Workspace and examine the Properties tab ( ). If that subsystem is a standalone subsystem, the Type field reads Standalone Subsystem.

40 • 2 Building a Model

Standalone subsystems will not show the shared subsystem icon ( ) on the Model Workspace. Also, if you double-click a standalone subsystem to browse to its detailed view, no
heading is shown for the subsystem in the Model Workspace.
When you copy and paste a standalone subsystem in the Model Workspace, you can optionally convert that subsystem into a shared subsystem and create a new subsystem definition. For more information, see Example: Copying and Pasting a Standalone
Subsystem (page 41).
Example: Resolving Warning Messages in the Debugging Console
When you convert a shared subsystem into a standalone subsystem, the subsystem is highlighted in the Model Workspace and a warning message appears, informing you that thelink to the subsystem definition has been removed.
Note: This example is an extension of Example: Removing the Link between a Shared
Subsystem and Its Subsystem Definition (page 38).
To resolve a warning message
1. Click Diagnostic Information () at the bottom of the MapleSim window to display
the debugging console. The following warning message appears in the console.

2. To work with the copy of DC Motor subsystem as a standalone subsystem, right-click(Control-click for Mac) the warning message and select Ignore duplication warnings
for 'copy for DC Motor' to hide the warning message from the debugging console.
Tip: If you want to view warning messages that you hid from the debugging console, click
Reset Ignored Warnings ( ) above the console. All of the warning messages that you
previously hid will appear in the debugging console again.

2.5 Creating and Managing Subsystems • 41

Alternatively, if you want to link the copy of DC Motor standalone subsystem to the DC
Motor subsystem definition again, you can right-click (Control-click for Mac) the warning
message and select Update 'copy of DC Motor' to use the shared subsystem 'DC Motor'.
Example: Copying and Pasting a Standalone Subsystem
Note: This example is an extension of Example: Removing the Link between a Shared
Subsystem and Its Subsystem Definition (page 38).
To copy and paste a standalone subsystem:
1. In the Model Workspace, copy and paste the copy of DC Motor standalone subsystem.
A dialog box appears. (See Figure 2.13.)
2. Select Convert the above stand-alone subsystem to a shared subsystem (Recommended). A new subsystem definition called SharedSubsystem_1 is added to the Components palette in the Local Components tab ().

42 • 2 Building a Model

Figure 2.13: Copy Subsystem Dialog

In the Model Workspace, the copy of DC Motor standalone subsystem has been converted
to a shared subsystem called copy of DC Motor and another copy of that shared subsystemcalled copy of DC Motor1 has been added to the Model Workspace. Both the copy of DC
Motor and copy of DC Motor1 shared subsystems are linked to the new SharedSubsystem_1 subsystem definition. Therefore, if you edit either copy of DC Motor or copy of
DC Motor1 in the Model Workspace, your changes will not be reflected in subsystems
that are linked to the original DC Motor subsystem definition.
Note: Alternatively, you can select Replicate the above stand-alone subsystem as a new
stand-alone subsystem to add another standalone subsystem that can be edited independently
without affecting the other subsystems in the Model Workspace.

2.6 Global and Subsystem Parameters • 43

2.6 Global and Subsystem Parameters
MapleSim lets you define global and subsystem parameter values, and assign them tocomponents using the Add or Change Parameters editor, parameter blocks, parameter
sets, and the Advanced Parameter Settings and Advanced Variable Settings in theProperties tab.

Global Parameters
If your model contains multiple components that share a common parameter value, you cancreate a global parameter using a Parameter Block. A global parameter allows you to define
a common parameter value in one location and then assign that common value to multiple
components in your model.
The following example describes how to define and assign a global parameter. To view amore detailed example, see Tutorial 1: Modeling a DC Motor with a Gearbox (page 151)
in Chapter 6 of this guide.
Example: Defining and Assigning a Global Parameter
If your model contains multiple Resistor components that have a common resistance value,
you can define a global parameter for the resistance value in the parameter editor view. Thisis done through a parameter block.
To define and assign a global parameter:
1. In the Library Components tab (), expand the Electrical palette, expand the Analog
menu, expand the Passive menu, and then expand the Resistors menu.
2. From the palette, drag three copies of the Resistor component into the Model Workspace.

3. In the Model Workspace, there is a Parameter Block (), as in the following image.

If there is not one in the model already, click Add a parameter block (Model Workspace Toolbar.

) from the44 • 2 Building a Model

4. Double-click on the parameter block in the Model Workspace. The Main subsystemdefault settings screen appears. You will use this screen to define the global parameterand assign it to the Resistor components in your model.

5. Click the first field under the Name column in the Main subsystem default settings
table.
6. Enter GlobalResistance as the global parameter name and press Enter.
7. Under Type, select Resistance[[ Ω ]] and specify a default value of 2.
8. Enter Global resistance variable as the description and press Enter.

The global parameter for the resistance value is now defined. You can now assign thecommon GlobalResistance parameter value to the individual Resistor components thatyou added to the Model Workspace.
9. Click Diagram ( ), then select the R1 component. Enter GlobalResistance as theresistance value.

9. Repeat this step for the R2 component.

2.6 Global and Subsystem Parameters • 45

The resistance value of the parameter GlobalResistance (2, as defined in the Main subsystem default settings table) has now been assigned to the resistance parameters of the R1
and R2 components.
The R1 and R2 components will now inherit any changes made to the GlobalResistanceparameter value in the Main subsystem default settings table. For example, if you change
the default value of the GlobalResistance parameter to 5 in the Main subsystem default
settings table, the resistance parameters of the R1 and R2 components will also be changed
to 5. Any change to the GlobalResistance parameter value will not apply to the R3 component because it has not been assigned GlobalResistance as a parameter value.

Subsystem Parameters
You can create a subsystem parameter if you want to create a common parameter value toshare with multiple components in a subsystem. Similar to global parameters, a subsystemparameter is a common value that you define in the parameter editor view and assign tocomponents.
There are two ways to assign subsystem parameters; one is by clicking Parameters ( )and the other is by using the Advanced Parameter Settings tool in the Properties tab( ). Parameters can only be assigned to components in the subsystem in which they aredefined. If you select a subsystem in the Model Workspace, click Parameters ( ) or
Advanced Parameter Settings, and define a parameter in the parameter editor view, theparameter that you define is assigned to components in the subsystem that you selected andany nested subsystems.
To view an example, see Tutorial 3: Modeling a Nonlinear Damper (page 166) in Chapter
6 of this guide.
Note: If you create a parameter within a subsystem and assign its value to a component at
the top level, the component at the top level will not inherit the parameter value.
Example: Assigning a Subsystem Parameter to a Shared Subsystem
If you assign a subsystem parameter to a shared subsystem in your model, the default subsystem parameter will also be assigned to other shared subsystems that are linked to it.
However, after the default subsystem parameter is assigned, you can edit the subsystemparameter value for each shared subsystem separately without affecting other parametervalues in the model.

46 • 2 Building a Model

To assign a subsystem parameter to a shared subsystem
1. From the Help menu, select Examples > Physical Domains > Multibody, and then selectthe Double Pendulum model. This model contains two shared subsystems, L1 and L2,
which are linked to a subsystem definition called L.
2. Double-click the L1 shared subsystem.
3. Click Parameters ().

4. In the L subsystem default settings table, click the empty field at the bottom of thetable.
5. Enter c as the parameter name, keep the default value as 1, and press Enter.
6. Click Diagram ( ). The new subsystem parameter, c, appears in the Properties tab() for the L1 shared subsystem.

7. Click Main ( ), select the L2 subsystem, and then examine the Properties tab. The
new subsystem parameter is also displayed for the L2 shared subsystem.
8. In the Properties tab, change the value of c to 50.
9. Click the L1 shared subsystem in the Model Workspace and examine the Properties
tab. Note that the value of its parameter, c, remains the same.

Using Parameter Blocks for Subsystem Parameters
As an alternative to defining subsystem parameters using the methods described above, you
can create a parameter block to define a set of subsystem parameters and assign them tocomponents in your model.
The following image shows a parameter block that has been added to the Model Workspace.

When you double-click this block, the parameter editor view appears. This view allows you
to define parameter values for the block.

After defining parameter values, you can assign those values to the component parameters
in your model.

2.6 Global and Subsystem Parameters • 47

To use parameter values in another model, you can add a parameter block to a custom library.
For more information about custom libraries, see Creating and Managing Custom
Libraries (page 60).
Notes:• Parameter blocks must be placed in the same subsystem as the components to which you
want to assign the parameter value.
• Parameter blocks at the same hierarchical level in a model cannot have the same parameternames. For example, two separate parameter blocks in the same subsystem cannot eachcontain a parameter called mass.
Example: Creating and Using a Parameter Block
In this example, you will create a set of parameters that can be shared by multiple components
in your model. By creating a parameter block, you only need to edit parameter values in
one location to compare results when you run multiple simulations.
To create and use a parameter block:
1. From the Help menu, select Examples > Physical Domains > 1-D Mechanical, andthen select the PreLoad example.
2. Under the Settings tab (), enter 0.012 seconds for td, the simulation duration time.

3. Click the SM1 Mass component on the workspace, and then click the Properties tab( ). You will be using a parameter block to set values for the following parameters:
m, L, s0, and v0.
4. From the Model Workspace Toolbar, click Add a parameter block (click on a blank area in the Model Workspace.

), and then

5. Click the Properties tab and enter the name SlidingMassParams for the parameter
block.
6. Double-click the SlidingMassParams parameter block in the Model Workspace. The
parameter editor view appears.

7. Click the first field in the table and define a new symbolic parameter called MASS.
8. Press Enter. The remaining fields for this row are activated.
9. From the Type drop-down menu, select Mass [[ kg ]].

48 • 2 Building a Model

10. Enter a default value of 5.
11. From the Default Units drop-down menu, select kg.
12. Enter Mass of the sliding mass for the Description field.
13. In the same way, define the following parameters and values in the Parameters subsystem default settings table.
Name
LENGTHType
LengthDefault Value Default Units
2m

Velocity
V0
S01

Length of the sliding mass
Initial velocity of the slidingmass

1
Position

Descriptionm

Initial position of the sliding
mass

The parameter editor view appears as follows when the values are defined.

14. Click Diagram ( ). When you select the parameter block in the Model Workspace,the defined parameters appear in the Properties tab on the right side of the MapleSim
window.

2.6 Global and Subsystem Parameters • 49

15. In the Model Workspace, select the SM1 mass component in the diagram.
16. In the Properties tab, assign the following values and press Enter.

50 • 2 Building a Model

The parameters of this Mass component now inherit the numeric values that you definedin the parameter block.
17. In the same way, assign the same values to the parameters of the SM2 and SM3 masscomponents in the model.
18. In the Model Workspace, delete the probe labeled Input.
19. Select the probe labeled Output.
20. In the Properties tab, clear the check box beside Velocity.
21. To simulate the model, click Run Simulation (22. Click Show Simulation Results (window.

) in the Main Toolbar.

). The following graph appears in the Analysis

2.6 Global and Subsystem Parameters • 51

23. In the Model Workspace, click the parameter block.
24. In the Properties tab, change the mass to 3.5 and the initial velocity to 5. Press Enter.
These changes apply to all of the Mass components to which you assigned the symbolic
parameter values.
25. Simulate the model again, then bring the Analysis window to the front. Another simulationgraph appears, which you can compare to your first graph.

52 • 2 Building a Model

Saving Parameter Sets
The parameters you create for your model can be stored as reusable Parameter Sets. Parameter Sets let you save, reuse, and compare different sets of parameters for the same model
displayed in the workspace. At any time you can easily apply and run different simulations,saving new values for each model. A Parameter Set provides a snapshot of all the parametersin the Model Workspace.
Parameter Sets for your model are listed in the Attached Files tab (Sets as shown in the following figure.

), under Parameter2.6 Global and Subsystem Parameters • 53

You can use, save, reuse, and compare different sets of parameters for the same model by
right-clicking (Control-click for Mac) on a Parameter Set. For more information, see theUsing MapleSim > Building a Model > Using Parameter Sets > Saving and Applying
Parameter Sets section in the MapleSim Help system.

Using Advanced Parameter and Variable Settings
At the top level of your model, in the Main subsystem default settings window, you define
the subsystem by adding parameters and setting their default values. An alternative is to
directly assign subsystem parameters, variables, and initial conditions to components inyour subsystem by using the Advanced Parameter Settings and Advanced Variable
Settings tools in the Properties tab (default values.

). Advanced Settings lets you override one or more

Advanced Parameter Settings
Advanced Parameter Settings lets you override the default values for selected subsystemcomponents. If desired, you can parametrize the override using the parametrization feature( ). A component override in one subsystem can be converted to a parameter visible inall the other subsystems.
In the following model an override was applied to the initial value of R and changed to theparameter Rcommon.

54 • 2 Building a ModelIn the Model Workspace, components with a parameter override are identified with anoverride icon ( ). In the following model, the DC Motor2 subsystem has a parameter
override.

Advanced Variable Settings
Advanced Variable Settings lets you specify initial conditions for subsystem components.
When you select Advanced Variable Settings the initial condition fields appear for all
configurable components for that subsystem.

2.6 Global and Subsystem Parameters • 55

Example: Creating a Parameter Override
To create a parameter override:
1. From the Help menu, select Examples > User's Guide Examples > Chapter 2, andthen select the Simple DC Motor example.
2. Draw a box around the electrical components by dragging your mouse over them.

3. From the Edit menu, select Create Subsystem or right-click (Control-click for Mac)the boxed area and select Create Subsystem.
4. In the dialog box, enter DC Motor, and then click OK. The DC Motor subsystem appears.

5. Right-click (Control-click for Mac) the DC Motor subsystem, select Convert to Shared
Subsystem, and then click OK. This creates the shared subsystem definition and adds
it Components palette under the Local Components tab.
6. Under the Local Components tab (), expand the Components palette, and then dragthree copies of the DC Motor shared subsystem to your Model Workspace.

56 • 2 Building a Model

7. Create three additional DC Motor subsystems as shown below.

8. Click S2, and, under the Properties tab (), set T0 to 1. Do the same for S3 and S4.

9. Click the DC Motor3 subsystem, and then click Advanced Parameter Settings under
the Properties tab ( ). The Advanced Parameter Settings window appears, showing
all of the subsystem components.

2.6 Global and Subsystem Parameters • 57

10. Expand R1 and enter a value of 100 for the Resistance parameter (R).

11. Click OK. The new parameter appears in the Properties tab as an override.

12. To change this override to make it a reusable parameter, click Parametrize ( ), enter
Rcommon as the new parameter name, and then click OK. Rcommon appears in theProperties tab as a parameter that can now be reused in the other subsystems. Note that
it is no longer an override.

58 • 2 Building a Model

13. For each of the other subsystems, click the subsystem and in the Properties tab enter
the following values for Rcommon: of• For DC Motor1, set Rcommon to 25Ω
• For DC Motor1, set Rcommon to 50Ω
• For DC Motor2, set Rcommon to 75Ω
14. For each of the subsystems, select the probe, and in the Properties tab select the Speed
check box and clear all of the other check boxes.
15. Click Run Simulation (of the subsystems.

) in the Main Toolbar. The following graphs appear for eachSpecifying Initial Condition Overrides
You can set initial condition values to override existing initial conditions for specific subsystem components. When you select a component, the available initial condition fields
and any existing overrides appear in the Properties tab (urable parameter values for that component.

), along with the other config-

2.7 Attaching Files to a Model • 59

When you select a subsystem and then click Advanced Variable Settings, all subsystemcomponents appear. You can select a component and specify the initial conditions for thatcomponent. This feature is especially useful for models that contain multiple shared subsystems.

2.7 Attaching Files to a Model
You can use the Attached Files tab ( ) to attach files of any format to a model (for example, spreadsheets or design documents created in external applications). You can savefiles attached in the Attached Files tab as part of the current model and refer to them when
you work with that model in a future MapleSim session. To save a file, right-click (Control-click for Mac) the category in which you want to save the attachment and select AttachFile.
You can also attach a file to a model from the menu bar by selecting Edit > Attach File...
. Using this method, by default, the file attaches to the Documents category. If you wantto move this attachment, you can click and drag the entry to another category.
The following image shows an Attached Files tab that contains files called CustomComponent.mw, NonLinearMSD.mw, and DamperCurve.xlsx.

Figure 2.14: Attachments

You can also use the Attached Files tab to open MapleSim templates to create custom
modeling components and ports for a model. For more information, see Analyzing andManipulating a Model (page 131) in this guide.

60 • 2 Building a Model

2.8 Creating and Managing Custom Libraries
You can create a custom library to save a collection of subsystems and custom modelingcomponents that you plan to reuse in multiple files or MapleSim sessions. Custom libraries
that you create appear in custom palettes in the Library Components tab () on the left
side of the MapleSim window and are saved as .msimlib files on your computer. These
custom palettes will appear in the MapleSim window in future MapleSim sessions.
You can use the subsystems and components from the custom library palette when building
a model, in the same way you add components from other palettes.
You can also share a custom library with other users. For example, if you store a custom
library on a network drive, other users with access to that location can load your custom
library in their MapleSim session.
Custom library palettes appear in the Library Components tab (with an icon: . A sample custom palette is shown below.

) and are indicated

For information on creating custom libraries, see Using MapleSim > Building a Model >Custom Libraries > Creating a Custom Library in the MapleSim Help system.
If you used a third-party tool to create models or model libraries based on the Modelica
4.0.0 programming language, you can import the .mo files for the models or model libraries
into MapleSim as .msimlib files. You can then use the imported models and libraries inyour MapleSim models as you would use any other modeling components. For more information, see Using MapleSim > Building a Model > Importing and Opening Modelica
Models and Libraries > Importing Modelica Libraries.

Example: Creating a Custom Library from an Existing ModelIn this example, you will create a custom library from the shared subsystem definitions ofan existing MapleSim model. The components added to the custom library will then be
available in future MapleSim sessions.

2.8 Creating and Managing Custom Libraries • 61

To create a custom library from a model:
1. From the Help menu, select Examples > Physical Domains > Multibody, and then selectthe 5 DoF Robot example.
This model has six shared subsystems, which are listed in the Components palette of the
Local Components tab ()

2. Save the model.
3. From the Tools menu, select Export to MapleSim Library.
4. Enter the name Robot for the library under Package.
Note: The package name that you specify will appear as the custom palette name in the
MapleSim interface.
5. Click OK.
6. After the library has been exported, click Close.
You are now in library edit mode (indicated by the watermark on the workspace and thelibrary properties in the Properties tab in the Parameters pane). A new custom library palette
appears in the Library Components tab () on the left side of the MapleSim window.
The palette is empty because we have not defined a hierarchy for its elements.
7. Switch to the Local Components tab (), and drag the components to the Hierarchy
tab under the root name (Robot). If desired, organize the elements into subgroups.

62 • 2 Building a Model

8. Click Reload ( ) in the Main Toolbar to save your changes and reload the palette forthe custom library in the Library Components tab with the updates. The custom library
palette now contains all these components.

2.9 Annotating a Model
You can use the tools in the Model Workspace Toolbar to draw lines, arrows, and shapes.
MapleSim also provides many tools for customizing the colors, line styles, and shape fills.

You can use the text tool ( ) in the Model Workspace Toolbar to add text annotations
to your model. In text annotations, you can enter mathematical text in 2-D math notationand modify the style, color, and font of the text. For more information about 2-D mathnotation, see Entering Text in 2-D Math Notation (page 64).

2.9 Annotating a Model • 63

Example: Adding Text Annotation to a Model
To add text annotation to a model:
1. From the Help menu, select Examples > User's Guide Examples > Chapter 2, andthen select the Simple DC Motor example.
2. From the Annotations Toolbar, click Text Tool ().

Note: If the Annotation Toolbar is not visible, click Show/Hide Drawing Tools (the Model Workspace Toolbar.

) in

3. In the Model Workspace, draw a text box for an annotation below the Step component.

When you release your left mouse button, the toolbar above the Model Workspace switches
to the text formatting toolbar.

4. Enter the following text: This block generates a step signal with a height of 1.
5. Select the text that you entered and change the font to Arial.
6. Click anywhere outside of the text box.
7. Draw another text box below the Inertia component.
8. Enter the following text: Inertia with a ω0 value of 0 rad.
Tip: To enter the omega character (ω), click Math on the context bar
to switch to
the 2-D math mode, type omega, and then press Esc. To enter the subscript, press Ctrl +Shift + the underscore key (Windows and Linux) or Command + Shift + the underscore
key (Mac) followed by 0. Press the right arrow key to move the cursor from the subscript
position. Toggle back to text entry mode by clicking Text on the context bar, and enter theremaining text.
9. Select the text that you entered and change the font to Arial.

64 • 2 Building a Model

10. Click anywhere outside of the text box to complete the annotation.

2.10 Entering Text in 2-D Math Notation
In parameter values and annotations, you can enter text in 2-D math notation, which is aformatting option for adding mathematical elements such as subscripts, superscripts, andGreek characters. As you enter text in 2-D math notation, you can use the command andsymbol completion feature to display a list of possible Maple commands or mathematicalsymbols that you can insert.
To enter 2-D math notation, select Math () in the text formatting toolbar.

The following table lists common key combinations for 2-D math notation:
Table 2.4: 2-D Math Notation Key Combinations
Task

Key Combination
1. Enter the first few characters of a symbol
name, Greek character, or Maple
command.

Command and symbol
completion (parametervalues and annotations
only)

2. Enter the key combination for yourplatform:

Example-• Esc, Mac, Windows, and Linux• Ctrl + Shift + Space, Linux
3. From the menu, select the symbol orcommand that you want to insert.

Enter a subscript for avariable

Ctrl (or Command) + Shift + underscore(_)

Enter a superscript

caret (^)

Enter a fraction

forward slash (/)

For more information, see Using MapleSim > Building a Model > Annotating a Model> Key Combinations for 2-D Math Notation in the MapleSim Help system.

2.11 Creating a Data Set for an Interpolation Table Component • 65

2.11 Creating a Data Set for an Interpolation Table
Component
You can create a data set to provide values for an interpolation table component in yourmodel. For example, you can provide custom values for input signals and electrical Current
Table and Voltage Table sources. To create a data set, you can either attach a Microsoft®
Excel® spreadsheet (.xls or .xlsx) or comma-separated values (.csv) file that contains thecustom values, or you can create a data set in Maple using the Data Generation App orRandom Data App. These apps are found in the Apps Manager ().

For more information about interpolation table components, see the MapleSim Component
Library > Signal Blocks > Interpolation Tables > Overview in the MapleSim Help system.

Example: Creating a Data Set in Maple
In this example, you will use the Data Generation App to create a data set for a MapleSim
1D Lookup Table component. In this app, you can use any Maple commands to create adata set; however, for demonstration purposes, you will create a data set using a computationthat has already been defined.
To create a data set in Maple:
1. Open a new MapleSim document.
2. In the Library Components tab (the Interpolation Tables menu.

), expand the Signal Blocks palette, and then expand

3. Add a Lookup Table 1 D component to the Model Workspace.
4. In the main toolbar, click Show Apps Manager ().

5. In the Apps palette on the left, under Utility, double-click Data Generation. The Data
Generation App opens in the Apps Manager.
6. At the bottom of the app, in the Data set name field, enter TestDataSet.
7. To make the data set available in MapleSim, click Attach Data to Model.
8. In MapleSim, under the Attached Files tab ( ), expand the Data Sets palette. The
data set file appears in the list. You can now assign this data set to the interpolation tablecomponent in the Model Workspace.
9. In the Model Workspace, select the Lookup Table 1 D component.
10. In the Properties tab (), from the datasource mode list, select attachment.

66 • 2 Building a Model

11. From the data drop-down menu, select the TestDataSet.csv file. The data set is now
assigned to the Lookup Table 1 D component.
12. Save your model in MapleSim.

2.12 Best Practices: Building a Model
This section describes best practices to consider when laying out and building a MapleSim
model.

Best Practices: Laying Out and Creating Subsystems
To start building your model, drag components from the palettes to the center of the Model
Workspace. Drag the components into the arrangement that you want in the Model
Workspace and then, if necessary, change their orientation so that the components are facingin the direction that you want. When you have established the position and orientation of
the components, connect them in the Model Workspace.
When grouping components into subsystems, make sure that you include logical component
groups that fit on one screen at a time. This will allow you to see all of the subsystemcomponents at a certain level without scrolling.
Create Subsystems for Component Groups That You Plan to Reuse
Create subsystems for component groups that you plan to reuse throughout a diagram or in
multiple files. For example, if you plan to include multiple planar link models in a pendulum
system, you can create a link subsystem so that multiple copies of that component group
could be added. If you wanted to add the link subsystem to another pendulum model, you
can create a custom library to use the subsystem in another file.
Create Subsystems for Component Groups That You Plan to Analyze
Make sure that you create subsystems for component groups that you plan to analyze inmore depth, test, or translate into source code. Several MapleSim templates allow you toanalyze and retrieve equations from particular subsystems. The Code Generation Templateallows you to generate source code from subsystems only.
For more information about performing analysis tasks, see Analyzing and Manipulating a
Model (page 131) in this guide.
Use Icon View to Control Subsystem Port Layout and Customize Subsystem
Icon
When you create a subsystem, subsytem ports are automatically created for any connectionlines that connect the subsystem to components outside the subsystem. Ports are placed on
one of the four sides of the subsystem, top, bottom, left or right.

2.12 Best Practices: Building a Model • 67

Subsystem ports can also be added to a subsystem. In both cases, the icon view of the subsystem shows the subsystem ports. You can enter Icon View ( in the Model Workspace
Toolbar) to manage the subsystem port layout.
In Icon View, you can customize the way the subsystem appears in both the components
palette and in your model.
• Move the ports.
• Show or hide the port labels using Toggle Port Labels ().

• Automatically update the size of the subsystem box ( ) or manually resize it.
• Add an image by adding a rectangle or circle, then click the drawing fill tool (and click Browse and select an image.

)• Add text or use the various drawing tools on the toolbar.
Use the Debugging Console to Identify Subsystem Copies and UnconnectedLines
You can display the debugging pane by clicking Debugging (MapleSim window.

) at the bottom of theAfter you run the simulation, the debugging pane displays diagnostic messages that canhelp you troubleshoot potential errors as you build a model. When you click Run diagnostic
tests ( ) above the debugging pane (or from the Edit menu, select Check Model),MapleSim verifies whether your model contains unconnected lines or subsystems that haveidentical content but are not linked to a subsystem definition. When either of these issues
are detected, a message that identifies the subsystem in which the issue is located appears
in the debugging console. You can right-click (Control-click for Mac) the message in the
debugging pane to display options that can help you to resolve the issue.

Best Practices: Building Electrical Models
Include a Ground Component in Electrical Circuits
In each electrical circuit model, you must add and connect a Ground component to providea reference for the voltage signals.
Verify the Connections of Current and Voltage Sources
Simulation results can be affected by the way in which a current or voltage source is connected in your model. If you receive unexpected simulation results, verify the connections
between electrical sources and other components in your model. All of the current sourcesin the MapleSim Component Library display an arrow that indicates the direction of thepositive current.

68 • 2 Building a Model

Also, all of the voltage sources display a plus sign indicating the location of the positive
voltage and a minus sign indicating the location of the negative voltage.

Consider the following Simple DC Motor model. Note that the positive port of the Signal
Voltage source at the left of the diagram is connected to the positive port of the Resistor
component.

When this model is simulated, MapleSim returns the following results for the torque andspeed quantities.

2.12 Best Practices: Building a Model • 69

On the other hand, if the negative port of the Signal Voltage source is connected to thepositive port of the Resistor component, as shown in the following model.

MapleSim returns different results for the speed and torque quantities.

Best Practices: Building 1-D Translational Models
Verify That All Force Arrows Are Pointed in the Same Direction
In MapleSim, all of the 1-D translational mechanical components are defined in a 1-D coordinate system with the positive direction defined as the direction of the gray arrow displayed by the component icon.

70 • 2 Building a Model

Any positive forces acting on the model cause the component to move in the direction of
the arrow, so make sure that all of the arrows displayed by the 1-D translational mechanicalcomponents in your model point in the same direction. As an example, note that all of theforce arrows are pointed to the right in the following model.

Figure 2.15: Verifying Force Arrows

For an example of sign convention and how arrow direction represents a force acting on
the model, from the Help menu, select Examples > User's Guide Examples > Chapter
2, and then select one of the Constant Acceleration, Sign Convention, or Arrow Convention examples.

Best Practices: Building Multibody Models
Connect the Inboard Port of a Rigid Body Frame to a Center-of-mass Frame
Make sure that you connect the inboard port of any Rigid Body Frame components in yourmodel to the center-of-mass frame of a Rigid Body component. This ensures that the local
reference frame used to describe displacements and rotations for the Rigid Body Frame
component match with the center-of-mass reference frame defined on the Rigid Body
component.
In the following planar link example, the Rigid Body Frame inboard ports (that is, the ports
with theicon) are both connected to a Rigid Body component.

Figure 2.16: Center of Mass Placement Best Practice2.12 Best Practices: Building a Model • 71

Best Practices: Building Hydraulic Models
Define Fluid Properties
When building hydraulic models, you must define the properties of the fluid that will be
used by placing the Hydraulic Fluid Properties component at the top level of your modelor at the same level as a hydraulic subsystem. If you place this component at the top levelof your model, all hydraulic components and subsystems in your model will inherit thefluid properties defined by that component instance; if you place the Hydraulic Fluid
Properties component at the same level as a subsystem, all hydraulic components in thatsubsystem and all nested subsystems will inherit the properties defined by that component
instance.
In the following example, all of the hydraulic components in the model inherit the fluid
properties defined by the Hydraulic Fluid Properties component at the top-right of the
diagram.

Figure 2.17: Hydraulic Model

For a complete tutorial on how to model hydraulic systems, see Tutorial 8: ModelingHydraulic Systems (page 213).

72 • 2 Building a Model

Best Practices: Enforcing Initial Conditions
In complex models, all of the initial conditions might not be independent of each other. In
general, use the enforce ( ) option to strictly enforce as many initial conditions as you
have degrees of freedom in your model. However, you can use the guess option ( ) for a
specified initial condition parameter value to help the solver determine the desired starting
configuration for your system faster.

3 Creating Custom Modeling Components
In this chapter:• Understanding Custom Components (page 73)• Creating Custom Components with Signal-Flow Behavior (page 76)• Creating Custom Components with Physical Connections (page 82)• Working with Custom Components in MapleSim (page 84)• Example: Creating a Nonlinear Spring-Damper Custom Component (page 85)

3.1 Understanding Custom Components
Creating custom components extends the MapleSim component library, enabling you tocreate custom modeling components based on the mathematical models that you define.
Custom components can use signals, ports with associated physical domains, or a combination of the two. You can also create libraries of custom components and create custom
components to contain particular subsystems with specialized functionality.
For a complete tutorial on how to create domain specific custom components, see Tutorial
5: Using the Custom Component Template (page 183).
There are several different Custom Component templates. These are found in the Templates
palette, under the Add Apps or Templates tab (73).

74 • 3 Creating Custom Modeling Components

Figure 3.1: The Add Apps or Templates tab

Creating a Simple Custom Component
The general process of creating a custom component for a MapleSim model consists ofspecifying the component equations for the custom component, component parameters andsystem model, specifying the port types and their values, and generating the component.
To create a custom component:
1. Start a new MapleSim model and select the Add Apps or Templates tab ().

2. From the Templates palette, double-click on Custom Component.
3. Enter a name for the template in the Create Attachment window, and then click Create
Attachment ( ). Maple opens with the DAE Custom Component template.
4. In the Define Equations area, enter the equations for your custom component. Equations,parameters, and initial conditions are all entered here. Press Enter at the end of the line.

3.1 Understanding Custom Components • 75

5. In the Configuration section, select Parameters, click Refresh All, and then assign
default values and types to model parameters.
6. Select Variables, click Refresh All, and then assign initial values and types for model
variables.
7. Select Ports, and then add ports to the custom components by clicking Add Port. You
can also control the layout of ports and the icon to use for the custom component.
It is possible to define custom ports. To do so, you must first define the custom port using
the Custom Port app. Then you can use the custom port in this app. For a complete tutorial on how to use custom ports, see Example: Custom Ports (page 193) in Chapter 6.
8. Provide the details for the port type, style, name, and port signals.
9. In the Component Generation section, enter a name for the component. This will be
the name given to the custom component in the Components palette, under the Local
Components tab () in MapleSim.

10. Click Generate MapleSim Component to create your component and to return to the
MapleSim environment. The custom component now appears in the Local Components
tab in the Components palette.

Typical Uses
The Custom Component template is the most general template and is specifically designed
to help you create custom components from algebraic expressions, differential equations,or systems of differential-algebraic equations. The Custom Component Template is a collection of pre-built controls and procedures associated specific Maple commands to easily

76 • 3 Creating Custom Modeling Components

create new MapleSim components. In addition to the Custom Component, the Modelica
Custom Component allows for the creation of a custom component via user-provided
Modelica code.
Custom Component templates are more than just containers for your equations. You canalso access all of Maple’s functionality to further develop your equations before you generate
the Custom Component for your model. This includes access to Maple’s programming
language, symbolic algebra functionality, and documentation tools to instantly analyze andverify the behavior of your component.
By using the Custom Component Template, you create a custom component in Maple byperforming the following tasks:• Attach a custom component template to your model.
• Define and enter your governing equations and properties that determine the behavior of
the component (for example, parameters and port variables).
• Specify ports for your component.
• Define the associated port variable mappings.
• Map variables from your equations to the ports.
• Generate the component and make it available in MapleSim.
• Test and analyze your mathematical model.
The Custom Component Template contains pre-built controls that allow you to performthese tasks with the same validation as for built-in components, preventing invalid connections and parameter values.

Using The Custom Component Template
For details on using this template, refer to the help page Using the MapleSim DAE Custom
Component Template.

3.2 Creating Custom Components with Signal-Flow
Behavior
Custom components simplify model construction by reducing the need to connect manysignal-flow components together. This example shows how to create a custom component
for a simple signal-flow equation.

Creating a Simple Signal-Flow Custom Component
Create a custom component that implements the following equation:

3.2 Creating Custom Components with Signal-Flow Behavior • 77

To create a custom component
1. Start a new MapleSim model and then click Add Apps or Templates ().

2. In the Templates palette, double-click on Custom Component.
3. Enter custom for the name of the attachment, and then click Create Attachment ().

4. In the Define Equations section, enter the following equation:

Note: The equation here is enclosed in square brackets because eq must be assigned a listof equations.
5. Press Enter to register the equation.

Figure 3.2: Equations Defining a Custom Component

Tip: The equations in the custom component do not have to be rearranged into an explicit
form. For example, you could replace the equation with:for which there is no explicit solution for the output
automatically.

. MapleSim solves for

6. In the Configuration section, select Ports, and then click Refresh All to update thetables.
7. Click Clear All Ports.
8. Add three new ports by clicking Add Port three times and then drag them into following
positions.

78 • 3 Creating Custom Modeling Components

Figure 3.3: Port Mappings

9. Click on the top port on the left-hand side to select it.
10. From the Type drop-down list, select Real Signal. For the Style, select the in radio
button. The port is given the default name real_i.
11. Next, associate a variable with the port signal. Select y(t) from the drop-down list as
shown in Figure 3.4.

Figure 3.4: Variable to Port Mapping

12. Assign the remaining port mappings using the settings in Table 3.1.

3.2 Creating Custom Components with Signal-Flow Behavior • 79

Table 3.1: Port Map
Port
Name
real_ireal1_i
real_oPort
Port
LocationType
Top left Real
SignalBottom Realleft
SignalRight
Real
Signal

Port
Style
in

Port
Component

inout

13. From the Icon list, select Use default.
14. Under the Component Generation section, enter custom in the Name field.
15. Click Generate MapleSim Component. The custom component equations are generated
and assigned to the model. The custom component icon appears in MapleSim under the
Local Components tab, in the Components palette.

Figure 3.5: Generated Custom Component

16. Drag the custom component into the workspace from the Components palette as shownin Table 3.2.

80 • 3 Creating Custom Modeling Components

Table 3.2: Signal Flow Components
Component Number ofComponents
CustomComponent

1

SymbolLibrary Location

Local Components (> Components

Required Settings) Custom settings

Library Components
Constant

1

Sine

1

(
) > Signal Blocks > Use default settings
Sources > Real
Library Components() > Signal Blocks > Use default settings
Sources > Real17. Connect two signal sources to the input ports on the left, and then place a probe on theright-most port (right-click and select Attach Probe), as shown below.

Figure 3.6: Completed Custom Component Model

18. Click Run Simulation ( ) in the Main Toolbar. When the simulation is complete,
the following graph appears.

3.2 Creating Custom Components with Signal-Flow Behavior • 81

Advantages of Acausal Mapping
Even though the custom component ports are specified as Signal Inputs and Signal Outputs,
MapleSim is truly acausal; signals can be inputs or outputs regardless of the pin type. For
example, if
andwere specified, and a probe was placed on, MapleSim
would automatically rearrange the specified equation into.
The concept of signal inputs and outputs are necessary for the code generation capabilities
of MapleSim, since the code is 'causalized', MapleSim expects inputs and provides outputs.

82 • 3 Creating Custom Modeling Components

Using Differential Equations in Custom Components
Instead of using library components for your model, you can also use differential equations
to define your custom component. For example, Figure 3.7 shows the equations that describe
the motion of two coupled mass-spring-dampers subjected to a driving force.

Figure 3.7: Double Mass-Spring-Damper Equations

Figure 3.8 shows how the parameters are mapped to component ports:

Figure 3.8: Port Mapping for Double Mass-Spring-Damper

3.3 Creating Custom Components with PhysicalConnections
When you create custom components based on physical connections, each connection port
has two variables associated with it: the across variable and the through variable. The
across variable represents the driving force in a system (temperature difference, pressure
difference, voltage drop, velocity or relative angular velocity), while the through variable
represents a flow of a conserved quantity (such as heat, mass, current, force or torque).

3.3 Creating Custom Components with Physical Connections • 83

Table 3.3: Characteristics of Through and Across Variables
Characteristics of Through Variables
Conserved quantity (like heat or mass)

Characteristics of Across Variables
Drives the flow of the conserved quantity

Has a direction of flow

Is a scalar

Satisfies the relationship input = output +accumulation

Defined as the difference between two points withina physical domain

Uniform across a domain

Table 3.4 shows the mathematical relationships defining the connection between various
across and through variables.
Table 3.4: Through and Across Variable Mathematical Relationship
DomainOhm’s Law

Governing Equation

Through Variable

Across Variable

Electrical Domain
Hagen–Poiseuille equation
Hydraulic Domain
Fourier's law
Thermal Domain

Deriving the System Equations for a Resistor
Table 3.5 shows a model of a simple resistor with several variables and one parameter.
Table 3.5: Resistor Variables and Parameters
Variablei(t)v(t)
vLeft(t)vRight(t)Parameter

R

Description
Current
Voltage difference
Voltage on the left port
Voltage on the right port
Resistance

Ohm’s Law defines the relationship between the voltage and the current as:

Figure 3.9 shows the equations mapped to the custom component ports.

84 • 3 Creating Custom Modeling Components

Figure 3.9: Resistor Port Mapping

The current,, on the right port has a negative sign, representing flow out of the resistor.
The current on the left port is positive, representing flow into the resistor. The resistance(R) is defined as a parameter available in the Properties tab ().

3.4 Working with Custom Components in MapleSim
In MapleSim, you can work with a custom component in the same way as you would workwith a subsystem. You can perform the following tasks:• Save a Custom Component as Part of the Current Model• Add a Custom Component to a Custom Library• Edit a Custom Component• Opening Custom Component Examples

Save a Custom Component as Part of the Current Model
When you save a model, the custom component is saved as part of the model. If you click
the Edit menu > Prune Model... then any unused custom component definition will be removed from the model. To protect the custom component from potentially being cleaned
up by the Prune Model feature, do one of the following:• Move the custom component from the Components palette of the Local Components
tab to the Hierarchy palette.
• Use the custom component in your model: drag the custom component from the Components palette to the Model Workspace.
For more information, see Using MapleSim > Building a Model > Pruning a Model in
the MapleSim Help System.

Add a Custom Component to a Custom Library
If you want to use a custom component in a file other than the current model, add the component to a custom library. For more information, see Creating and Managing Custom
Libraries (page 60).

3.5 Example: Creating a Nonlinear Spring-Damper Custom Component • 85

Edit a Custom Component
If you want to edit a custom component that you have generated, make your changes in thecorresponding Maple worksheet and regenerate the component.
To edit a custom component
1. In the MapleSim Model Workspace, double-click the custom component that you wantto edit. The corresponding Custom Component Template opens in Maple.
2. In the Maple worksheet, edit the equations, properties, or port values.
3. At the bottom of the worksheet, click Generate MapleSim Component. Your changes
are generated in the custom component displayed in MapleSim.
4. Save your changes in the .mw file and the .msim file where you added the custom component.

3.5 Example: Creating a Nonlinear Spring-Damper
Custom Component
In this example, you will use the Custom Component Template to create a nonlinear springdamper custom component. The equations defined in this example are based on theTranslational Spring Damper component in MapleSim. In this case, the stiffness anddamping coefficients are replaced with input functions to the component.
To obtain the governing relationships, you can start with a free-body diagram. The diagram
for the spring-damper system is shown in the following figure.

Figure 3.10: Nonlinear Spring-Damper Custom Component

86 • 3 Creating Custom Modeling Components

The end points, a and b, can be defined as the ports for the component; the equations arederived relative to these ports. Therefore, the general equation of motion is:where d is the damping coefficient, c is the stiffness of the spring, and srel is the relative
displacement between the two ports sa and sb, can be written as:

Also, an examination of the net force on the system shows that

, where,All of the above relationships are required to define the system behavior.

Opening the Custom Component Template
The Custom Component template is part of the MapleSim templates accessed from theMain Toolbar.
To open the custom component template:
1. In MapleSim, open the model to which you want to add the custom component.
2. From the main toolbar, click Load a Maple Worksheet ().

3. Under Templates, double-click on Custom Component.
4. Enter Nonlinear Spring-Damper as the name for the template and click Create Attachment ( ). The Custom Component Template opens in Maple.

Defining the Component Name and Equations
You can now specify the name that will appear for the component in the MapleSim interface
and define the equations.
To define the custom component:
1. In the Equations section, define the nonlinear system by entering the following equations.
>3.5 Example: Creating a Nonlinear Spring-Damper Custom Component • 87

Note that the equations are entered in a Maple list. The constants, d (damping) and c (stiffness), are replaced by the functions d(t) and c(t) to define them as input states to the system.
2. With your cursor on the equation, press Enter.
3. In the Configuration section, select Variables, and then click Refresh All to see an
updated list of variables.
You can now assign these input and output variables to ports that you will include in yourgenerated custom component.

Defining Component Ports
In the Ports section of the template, you assign input and output variables to ports that willappear in the generated component, and specify the layout of these ports.
To define the ports:
1. In the Configuration section, select Ports.
2. Click Clear All Ports.
3. Click Add Port four times. Four squares appear on the diagram. These represent theports that you will lay out and define.

4. Drag the ports to position them with one on each side and two on the top of the diagram.

88 • 3 Creating Custom Modeling Components

5. Select the port on the left side of the diagram.
6. From the Type drop-down menu, select Translational.
7. For the style of the port, select b. The port's default name is tflange_b.
8. First, define the signal position. Ensure Position = unassigned is selected in the list underSignal. From the drop-down list under Signal, select s_b(t).
9. Next, define the signal force. Select Force = unassigned in the list under Signal. From
the drop-down list under Signal, select F_b(t). The left port is now defined as a translational flange and associated with the position variable s_b(t) and force variable F_b(t).
10. Select the port on the right side of the diagram.
11. From the Type drop-down menu, select Translational.
12. For the style of the port, select a. The port's default name is tflange_a.
13. First, define the signal position. Ensure Position = unassigned is selected in the list underSignal. From the drop-down list under Signal, select s_a(t).
14. Next, define the signal force. Select Force = unassigned in the list under Signal. From
the drop-down list under Signal, select F_a(t). The right port is now defined as a translational flange and associated with the position variable s_a(t) and force variable F_a(t).
15. Select the port at the top left of the diagram and then do the following.
• From the Type drop-down menu, select Real Signal.
• For Style, select in.
• Change Name to cin.
• Under Signal, select c(t) from the drop-down list.
This port is now defined as a signal input and associated with the stiffness variable c(t).
16. Select the port at the top right of the diagram and then do the following:• From the Type drop-down menu, select Real Signal.
• For Style, select in.
• Change Name to din.
• Under Signal, select d(t) from the drop-down menu.
This port is now defined as a signal input and associated with the damping variable d(t).
17. From the Icon list, select Use default.

3.5 Example: Creating a Nonlinear Spring-Damper Custom Component • 89

The ports will be displayed in this arrangement when you generate the custom component
in MapleSim.

Checking Dimensions
This step is optional.
1. In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. Algebraic expressions in the system equations that are dimensionally inconsistent are displayed in the math-container.
2. To correct the dimensions, select Variables, and then assign the following dimensions
for the system variables in the Type column:• For c(t), enter Force/Distance.
• For d(t), enter Force/Velocity.
• For F(t), enter Force.
• For s_rel(t), enter Length.
• For v_rel(t), enter Velocity.
3. Click Refresh All. The algebraic expressions Force/Distance and Force/Velocity areconverted to the corresponding Modelica types, TranslationalSpringConstant andTranslationalDampingConstant, respectively (you could have entered these directly).

90 • 3 Creating Custom Modeling Components

4. Select Dimensional Analysis, and then click Check Dimensions. The result should be
the two equations shown below.

This is a benign inconsistency indicating that the real input signals cin(t) and din(t) actually
have implied units.

Generating the Custom Component
Generate the custom component to add it to the component to the Components palette in
the Local Components tab.
1. In the Component Generation section, enter NonLinearMSD in the Name text box.
2. Click Generate MapleSim Component. The generated custom component appears in
MapleSim in the Components palette of the Local Components tab ().

You can add the custom component to a model by dragging it into the Model Workspace
as you would any other component.
3. Save your MapleSim model as NonlinearSpringDamper.msim. Tutorial 3: Modelinga Nonlinear Damper (page 166) in Chapter 6 uses this custom component in a model.

4 Simulating and Visualizing a ModelIn this chapter:• How MapleSim Simulates a Model (page 91)• Simulating a Model (page 93)• Simulation Progress Messages (page 100)
• Managing Simulation Results and Snapshots (page 101)
• Customizing Plot Window Configurations (page 103)
• Visualizing a Multibody Model (page 109)
• Best Practices: Simulating and Visualizing a Model (page 129)

4.1 How MapleSim Simulates a Model
Modelica Description
The equations for many components in the MapleSim library are described using the Modelica physical modeling language. On the other hand, the equations for multibody components
are generated by a special-purpose engine, which uses advanced mathematical techniques
to ensure that the equations are as concise and efficient as possible, and then converted toModelica.
For more information about Modelica, visit http://www.modelica.org

Model Description
Each component in your model contains a system of equations that describes its behavior;
these systems of equations can consist of purely algebraic equations or differential equations.
Also, a component may define any number of events, which can change the component
behavior during a simulation by enabling or disabling part of the equations in the systemor changing state values. Connections between two or more components generate additional
equations that describe how these components interact.

System Equations
The topology equations (how the components interact) as well as the terminal (component)
equations are then collected into one large system and parameter values are also substituted
in. Now, the MapleSim simulation engine has a potentially large system of hybrid differential
algebraic equations. This means that the system has differential equations with algebraic
constraints, as well as discrete events.

9192 • 4 Simulating and Visualizing a Model

Simplified Equations
A process called index reduction reduces the algebraic constraints as much as possible. At
the core of this phase is an algorithm that constructs an index-1 DAE system, modified withother symbolic simplification techniques, to reduce the number of equations and variables.
Many of these techniques deal with handling of hybrid systems.
You can set initial values for some of the variables by specifying parameter values for certain
components in the Properties tab on the right side of the MapleSim window. If the specified
initial conditions are inconsistent, an error will be detected during the simulation. To help
solve this issue, use the Initialization Diagnostics App.

Integration and Event Handling
When all of these preprocessing steps are complete, the integration and event handlingprocess begins. Based on the solver type you chose, a sophisticated DAE solver numericallyintegrates the system of equations. For the variable solver, algebraic constraints are constantly
monitored to avoid constraint drift, which would otherwise affect the solution accuracy.
For fixed solver type, algebraic constraints are monitored at each fixed time step.
During integration, inequality conditions that are part of the model are monitored and an
event is triggered when one or more of these conditions change. Whenever such an event
is encountered, the numeric solver stops and the simulation engine computes a new configuration of the system of equations based on the event conditions. This step also involves
recomputing initial conditions for the new system configuration. The solver is then restarted
and continues to numerically solve the system until another event is triggered or the simulation end time is reached.
Note: Event handling occurs for both variable and fixed step solvers. The difference is thatfor fixed step solvers, events are only processed at fixed time steps, whereas with a variable
solver, the solver will adjust the time step so that events are processed at exactly the timethey occur during the integration.

Simulation Results
In the last step of the simulation process, the results are generated and displayed usinggraphs showing the quantities of interest and, optionally for multibody mechanical systems,
a 3-D animation.

4.2 Simulating a Model • 93

The simulation process is summarized in the following chart:

Figure 4.1: Simulation Process

Note that the information in this section is a simplified description of the simulation process.
For more information on the DAE solvers used by the simulation engine, see thedsolve/numeric topic in the Maple Help system.

4.2 Simulating a Model
To view the behavior or response of physical properties (for example, current or voltage),
add probes to connection lines, ports, or components in your 2-D or 3-D model. In
MapleSim, probes allow you to identify the variables of interest that are associated withconnection ports.

94 • 4 Simulating and Visualizing a ModelIf you add a probe to measure a through variable, an arrow appears to indicate the directionof the positive flow in the Model Workspace.

You can specify the simulation duration, the type of solver to use, and other parametervalues for the solver, simulation engine, and 3-D Workspace. After running a simulation,a graph appears for each specified quantity.
You can change the original probe or parameter values and run another simulation to compare
the results, or use the Rerun Simulation feature to rerun the simulation without recompilingthe entire model.
For details on this process, refer to Using MapleSim > Simulating a Model > Rerunning
a Simulation without Further Compiling. For an example, see Tutorial 1: Modeling a
DC Motor with a Gearbox (page 151) in Chapter 6 of this guide.
For an example of sign convention and how arrow direction represents a force acting on
the model, select the Help menu > Examples > User's Guide Examples > Chapter 4, andthen select one of the Constant Acceleration, Sign Convention, or Arrow Convention
examples.

Simulation and Advanced Simulation Settings
The parameters used for your simulation are found under the Simulation Settings tab in
the Parameters pane. From here you can access sections for Simulation and Advanced
Simulation settings.
To access the simulation settings, click Simulation Settings tab (Parameters pane.

) on the right of the

For a description of the Multibody and 3-D Visualization settings see 3-D Visualizationand Multibody Settings (page 109).

4.2 Simulating a Model • 95

Simulation Settings
In the Simulation section you can specify the simulation duration time, the number of plot
points, the solver, and other parameters specific to the solver. See Table 4.1 for a listingand description of the parameters available in the Simulation settings section.
Table 4.1: Simulation Settings
Parameter

Default

Description
The duration time of the simulation. You can specify any
positive value, including floating-point values.

10s

Note: The duration time is not the same as the end time ofyour simulation. The end time for the simulation is given
by td + ts, where ts is the start time for the simulation (seeTable 4.2).
The type of solver to use for the simulation.
• Variable: use a variable time step to maintain error
tolerances.

Solver Type

Variable• Fixed: use a fixed time step and disregard integration
error.
Note: The fixed step solvers are identical to those used by
MapleSim's exported code.

96 • 4 Simulating and Visualizing a Model

Parameter

Default

Description
DAE solver used during the simulation. The following
choices are available when Solver Type is set to Variable.
• CK45 (semi-stiff): use a semi-stiff DAE solver (ck45
method).
• RKF45 (non-stiff): use a non-stiff DAE solver (rkf45
method).
• Rosenbrock (stiff): use a stiff DAE solver (Rosenbrockmethod).

SolverVariable: CK45
(semi-stiff)
If your model is complex, you may want to use a stiff DAE
solver to reduce the time required to simulate a model.
Fixed: Euler

The following choices are available when Solver Type isset to Fixed.
• Euler: use a forward Euler solver.
• Implicit Euler: use an implicit Euler solver (suitable forstiff systems).
• RK2: use a second-order Runge-Kutta solver.
• RK3: use a third-order Runge-Kutta solver.
• RK4: use a fourth-order Runge-Kutta solver.

Step size

0.001

Plot Points

2000

The limit on the absolute error tolerance for a successful
integration step if you are using a variable-step solver to
run the simulation. You can specify a floating-point value
for this option.
The limit on the relative error tolerance for a successful
integration step if you are using a variable-step solver to
run the simulation. You can specify a floating-point value
for this option.
Uniform size of the sampling periods if you are using afixed-step solver to run the simulation. You can specify afloating-point value for this option.
Minimum number of points to be plotted in a simulation.
The data points are distributed evenly according to thesimulation duration value. You can specify a positive
integer. Additional points can be added for events (see Plot
Events in Table 4.2).
Note: This option allows you to specify the number of points
for display purposes only. The actual number of points usedduring the simulation may differ from the number of points
in the simulation graph.

4.2 Simulating a Model • 97

Advanced Simulation Settings
In the Advanced Simulation section you can specify the simulation start time, a state
snapshot to use, compilation options, and other settings. Some of these settings are specificto the solver type (variable or fixed) selected in the Simulation settings. See Table 4.2 fora listing and description of the parameters available in the Advanced Simulation settings.
Table 4.2: Advanced Simulation Settings
Parameter

Default

SolverType

Description
The simulation start time. You can specify any
floating-point value, including negative values.

0

Use Snapshot

Jacobian

None

Symbolic

All

All

All

Baumgarte

All

Projection

All

Projection
Iterations

50

All

Note: The simulation start time affects the end time ofyour simulation, but not the duration time for thesimulation, td. The end time for the simulation is given
by td + ts.
A snapshot captures the state of your simulation at a
specific time. If you use a snapshot in your simulation,
you can override the initial conditions used in yourmodel and replace them with the state your model wasin at the time of the snapshot.
See Managing Simulation Results andSnapshots (page 101) for more information on snapshots.
Choose between a symbolic or numeric approximation
to the system Jacobian. A symbolic formulation resultsin faster and more accurate simulations but can takelonger to formulate.
Note: A numeric formulation can only be used with stiff
solvers (Rosenbrock or Implicit Euler).
Apply Baumgarte constraint stabilization to your model.
Select to enter values for the derivative gain (α) and the
proportional gain (β) that are appropriate for your model.
Apply constraint projection to your model. Select toproject back the solution found at each step of thesimulation to the constraint manifold. The projection
ends when either the maximum number of Projection
Iterations is reached or the defection falls below the
Projection Tolerance.
The maximum number of constraint projection iterations.
Note: This parameter is only available when Projection
is selected.

98 • 4 Simulating and Visualizing a Model

Parameter

Default

SolverType

Projection
Tolerance

0.00001

Fixed

Event
Projection

Fixed

Event
Iterations

100

All

Event
Hysteresis

1. x 10-7

Fixed

InitialHysteresis

1. x 10-10

Variable

Index 1 Error
Control

Index 1
Tolerance

Variable1

Variable

Minimum
Step Size

0

Variable

Maximum
Step Size

0 / no limit

Variable

Description
The tolerance value at which the projection iterations
are terminated. You can specify any positive
floating-point value.
Select to have constraint projection occur during event
iterations, but with slower integration results. Not
selecting, may cause the simulation to fail if the eventchanges the solution to the point of not allowing theapplication of constraint projection at the next step.
The maximum number of event iterations allowed before
the integrator throws an error. You can specify any
positive integer value.
The width of the event hysteresis band. You can specify
a floating-point value greater than or equal to zero. If
set to zero, this parameter is disabled.
The width of the event hysteresis for all event triggers
at the start of the simulation. You can specify afloating-point value greater than or equal to zero.
Note: Used by variable step solvers.
When selected, error control is applied to all algebraic
variables. By default, error control is only applied toalgebraic variables that trigger events, are plotted, or are
outputs of functions.
Controls the relative error on algebraic variables
compared to differential variables. For example, a valueof 10 means that algebraic variables can have 10 times
the error of differential variables.
Set the minimum step size. This option should be usedwith caution, as if the solver is unable to achieve therequested error tolerance with this minimum then it willtake the step anyway.
Set the maximum step size. (0 indicates no limit)
Specifies the method of variable scaling to apply to thesystem. The available choices are:• None: do not apply scaling

Scaling

Minimum

Variable• Minimum: use the minimum nominal value• Maximum: use the maximum nominal value• Geometric: use the geometric mean of the nominal
values4.2 Simulating a Model • 99

Parameter

Default

SolverType

Minimize
EventsVariable

Plot EventsAll

SolverDiagnostics

All

Compiler

Variable

CompileOptimized

All

Description
This option specifies whether to use heuristics to reduce
the number of events encountered during yoursimulation. When selected, the mapping of piecewisetransitions into events does not occur.
Specifies whether to include extra plot points at event
points during the simulation.
When selected, the simulation generates diagnostics
describing constraint iterations, constraint residual, event
iterations, and step size, and plots them after thesimulation is complete in a Solver Diagnostics plot
configuration in the Simulation Results tab. For systems
with the projection option cleared, this incurs additional
computational cost.
For models with an inconsistent system of equations or
run-time issues, select this option to display details about
the variables, equations, and components that are causing
the errors.
Specifies whether a native C compiler is used during thesimulation. When this option is selected, Maple
procedures generated by the simulation engine aretranslated to C code, which is compiled by an external
C compiler.
If your model is complex, you may want to select thisoption to reduce the time required to run a simulation.
Optimize the code during compilation. If this parameter
is not selected, compile time will be reduced but yoursimulation will take longer to run.

Editing Probe Values
Click the Model Tree tab ( ), and then select Probes from the list. This lists all of theprobes that you have added to the current MapleSim model.

If a probe is attached at the top level of your model, Main appears in parentheses besidethe probe name; otherwise, the subsystem for the attached probe appears beside the probe

100 • 4 Simulating and Visualizing a Model

name. In the image shown above, two probes have been attached to a model: Probe1 is at
the top level of the model and Probe2 is in a subsystem called Main.Nonlinear Damper_1(that is, the Nonlinear Damper_1 subsystem in Main).
You can click the entries in this palette to browse to a probe in the Model Workspace, andview and edit the probe values in the Properties tab ( ). You can also right-click (Control-click for Mac) entries in this palette and manipulate probes using context menus.
For more information, see Using MapleSim > Simulating a Model > Using Probes >Editing Probe Values in the MapleSim Help system.

Storing Parameter Sets to Compare Simulation Results
You can store a group of parameter values that are assigned to a model in a parameter set.
You can then run a simulation using one parameter set, replace those parameter values withanother parameter set, and run another simulation to compare the results.
For more information, see the Using MapleSim > Building a Model > Using Parameter
Sets > Saving and Applying Parameter Sets section in the MapleSim Help system.

4.3 Simulation Progress Messages
During a simulation, you can view progress messages in the Console pane located below
the Model Workspace. These messages indicate the status of the MapleSim engine as it
generates a mathematical model; these messages can help you to debug simulation errors.
Messages for each step of the simulation are placed in their own section (for example,
Generating Equations or Computing Initial Values). When a new step starts, the preceding
section is automatically collapsed. To see the messages for a section, expand the section byclicking on the gray arrow for that section. Alternatively, use the arrow keys to navigate
the Console pane:• Press the Right Arrow key to expand a section.
• Press the Left Arrow key to collapse a section.
• Press the Down Arrow key to move to the following section.
• Press the Up Arrow key to move to the preceding section.

4.4 Managing Simulation Results and Snapshots • 101

Figure 4.2: Simulation Results Progress Messages

Optionally, before running a simulation, you can specify the amount of detail in progressmessages by clicking Console Output () at the bottom of the MapleSim window andselecting a level (Normal or Verbose) from the drop-down menu.

To clear the messages from the console, click Clear the message console ().

4.4 Managing Simulation Results and Snapshots
The Stored Results palette in the Simulation Results tab allows you to view, save, andexport results generated from multiple simulations. In addition, for each of your stored
results, you can save and export snapshots that record all of the state variables for yourmodel at a particular time during the simulation.

Storing Results
Whenever you simulate a model, the results are saved as Latest Results in the Stored
Results palette. This entry contains all the graphs, progress messages, and (if applicable)
the 3-D animation generated from your simulation. However, each new simulation overwrites
the results stored in the Latest Results entry.
To store a simulation result under a new name, right-click (Control-click for Mac) on theLatest Results entry, select Save from the context menu, and then provide a name for thestored result. You can save simulation results to compare and refer to multiple graphs generated during the current MapleSim session.

102 • 4 Simulating and Visualizing a ModelIf you save the stored result and then save your model, when you open the model in a future
MapleSim session, the stored result will be available in the Stored Results palette. However,Latest Results are not saved when you close and reopen the model.

Saving and Using Snapshots
You can save the state information by taking a snapshot of your simulation at a particulartime and saving the snapshot as part of a stored result. Saving a snapshot allows you to use
the state information in subsequent simulations. To manage snapshots, including creating
new snapshots and selecting a snapshot to use in the next simulation, see the Advanced
Simulation settings (see Table 4.2).

Figure 4.3: Snapshots in the Advanced Simulation Settings

When you use a snapshot in this way, the information recorded in the snapshot provides
the initial conditions for subsequent simulations.
When no snapshot is selected for use in simulation, the Run Simulation icon in the toolbar
is. When a snapshot is selected for use in simulation, the Run Simulation icon changes
to . When a snapshot is used in a simulation, that information is available in the tooltipof the resulting entry in the Stored Results palette.

4.5 Customizing Plot Window Configurations • 103

Figure 4.4: The Stored Results Palette and Snapshots

For more information, refer to the Using MapleSim > Simulating a Model > Managing
Simulation Results > Managing Simulation Snapshots section of the MapleSim Helpsystem.

4.5 Customizing Plot Window Configurations
By default, probed quantities are plotted in separate simulation graphs in a plot windowcalled Probe Plots. In each graph, the quantity values are plotted along the -axis versus
the simulation time values along the -axis.
You can optionally create custom plot window configurations. You might want to create acustom plot window if, for example, you want to compare multiple quantities in the samegraph, plot one quantity versus another, or view a simulation graph for a specific quantity
without editing other probe values. You can even compare quantities from two different
models. You can further customize a plot window by for instance customizing plot titles
and specifying the number of columns to appear in the plot window.
For details on creating a plot window, refer to Generating a New Plot Window Configuration. For more information on plot windows, refer to the Using MapleSim > Simulating
a Model > Working with Plot Window Configurations section of the MapleSim Helpsystem.
When you create a new plot window, it will be populated with data without having to run
the simulation again.
Tip: When you save and reopen a model with stored results, the plots may initially show
the message No data available. You can load the plots by right-clicking on an entry in theStored Results palette and selecting Show Probe Plots.
If you want to work with your simulation data in another application, you can export yourresults to a Microsoft Excel (.xls) or comma-separated value (.csv) file. For details, referto the Exporting Simulation Graph Data help page.
In the following examples, you will create custom plot window configurations.

104 • 4 Simulating and Visualizing a Model

Example: Plotting Multiple Quantities in Individual Graphs
In this example, you will view the Probe Plots and then create a plot window configurationin which you will add a second variable to each custom plot.
To view the Probe Plots:
1. From the Help menu, select Examples > Physical Domains > Multibody, and then selectthe Double Pendulum example.
2. Click Run Simulation () in the Main Toolbar.

3. Click Show Simulation Results ( ). The Analysis window opens with the Simulation
Results tab selected. The 3-D Playback Window and the Probe Plots are in the Simulation
Results tab. See Figure 4.5.

Figure 4.5: Simulation Graphs

4.5 Customizing Plot Window Configurations • 105

To create a custom plot window configuration:
1. In the Plot Windows palette, double-click on the following plots to hide them from view:
Output1.w, Output2.a, Output2.phi, Output2.w. The plot window should now show justtwo plots, Output1.a and Output1.phi.
2. Click the Duplicate the Plot Window button ().

3. Enter the name Acceleration and Angle Comparison in the Duplicate Plot Window
dialog box. Click OK. A new plot window with the name Acceleration and Angle
Comparison is created containing the currently visible plots.
Tip: To return the Probe Plots to its original view, right-click on Probe Plots in the PlotWindows palette and select Show All Plots.
4. In the plots window, select the plot Output1.a from the Acceleration and Angle
Comparison plot window.
5. In the Variables palette, under Output2, select a.
6. Click Add Selected Variable to Selected Plot (Output1.a and Output2.a.

). The plot now shows two curves,

7. In the plots window, select the plot Output1.phi from the Acceleration and Angle
Comparison plot window.
8. In the Variables palette, under Output2, select phi and click Add Selected Variable
to Selected Plot ( ). (Alternatively, drag phi onto the plot.) The plot now shows bothcurves.
9. In the Plot Windows palette, under Acceleration and Angle Comparison, right-clickon Output1.a (the name of the first plot), and select Rename.
10. Enter the name Acceleration (a). This changes the title of the plot.
11. In the Plot Windows palette, under Acceleration and Angle Comparison, right-clickon Output1.phi (the name of the second plot), and select Rename.
12. Enter the name Angle (phi).
The resulting plots are shown in Figure 4.6.

106 • 4 Simulating and Visualizing a Model

Figure 4.6: Custom Plot Window

Example: Plotting One Quantity versus AnotherIn this example, you will create a custom plot window to plot the X and Y position of eachof the links of a double pendulum.
To plot one quantity versus another in a custom plot window:
1. From the Help menu, select Examples > Physical Domains > Multibody, and then selectthe Double Pendulum example.
2. In the Model Workspace toolbar, click Attach Probe ().

3. Click the right port of the L1 shared subsystem.
4. Click on an empty area of the Model Workspace to position the probe.
5. In the Properties tab (Length[2].

), label this probe FirstLink, and then select Length[1] and6. Add another probe that measures the Length[1] and Length[2] quantities to the rightport of the L2 shared subsystem, and label this probe SecondLink.
7. Click Run Simulation () in the Main Toolbar.

8. Click Show Simulation Results ( ). The Analysis window opens, displaying the Probe
Plots in the Simulation Results tab.
9. We want the plots window to only show two plots, FirstLink.r_0[2] and SecondLink.r_0[2], which will be the basis for creating a new plot window configuration. In

4.5 Customizing Plot Window Configurations • 107

the Plot Windows palette, double-click on the names of the other plots to hide themfrom view.
10. Click Duplicate the Plot Window ().

11. Enter the name X versus Y in the Duplicate Plot Window dialog box. Click OK. A new
plot window with the name X versus Y is created containing the currently visible plots.
Tip: To return the Probe Plots to its original view, right-click on Probe Plots in the PlotWindows palette and select Show All Plots.
12. In the Plot Windows palette, under X versus Y, right-click on FirstLink.r_0[2] (thename of the first plot), and select Rename.
13. Enter the name Top Link. This changes the title of the plot.
14. Similarly, change the name of the plot SecondLink.r_0[2] to Bottom Link.
15. In the plots window, select the plot Top Link from the X versus Y plot window.
16. In the Variables palette, select FirstLink: r_0[1].
17. Click Place Selected Variable on x-Axis ().

18. In the plot window, select the plot Bottom Link from the X versus Y plot window.
19. In the Variables palette, select SecondLink: r_0[1].
20. Click Place Selected Variable on x-Axis ().

21. In the Plotting Toolbar, use the slider to change the number of plot columns to 1.
The resulting plots are shown in Figure 4.7.

108 • 4 Simulating and Visualizing a Model

Figure 4.7: Plot One Quantity Versus Another

The plots above show the motion of the end point of each link in the pendulum. The bottom
link follows a more disorderly path because of the interaction with the top link.

4.6 Visualizing a Multibody Model • 109

4.6 Visualizing a Multibody ModelIn MapleSim, the 3-D visualization environment allows you to build and analyze 3-Dgraphical representations of multibody systems. As you build a model and change its parameters, you can validate the 3-D configuration of the model and visually analyze yoursimulation results. You can build 3-D models by dragging and connecting objects in the 3D Workspace, and you can visualize your simulation results by playing animations that
depict the movement of the objects.
As you build a block diagram in the Model Workspace, the corresponding changes areautomatically reflected in the 3-D representation in the 3-D Workspace. Similarly, when
you build a model in the 3-D Workspace, the corresponding changes are automatically reflected in the block diagram in the Model Workspace. Changes that you make in either ofthe workspaces are shown in both the Model Workspace and 3-D Workspace as you edit
your model.
In the 3-D Workspace, you can view your model from any direction. Also, you can attach
3-D shapes to parts of your model to create a realistic-looking system representation. Theseshapes can either be imported from an external CAD file or selected from the Multibody> Visualization palette in the Library Components tab.
After simulating your model, you can animate your 3-D model in the 3-D Playback Window.
You can control playback options to focus on specific components and their motions, forinstance by specifying camera tracking options to center an object in the 3-D Playback
Window during an animation. You can also attach trace lines to show where components
move during an animation.
Tip: The quality of the visualization is affected if any open plot windows are behind the 3D Playback Window. If you are experiencing playback issues, try moving the 3-D Playback
Window so that it does not overlap a plot window. Alternatively, minimize or close any
open plot windows.
CAD geometry and visualization shapes are drawn transparent in the 3-D Workspace andnon-transparent in the 3-D Playback Window.
For more information about adding 3-D shapes and using the 3-D Workspace, see the Using
MapleSim > Visualizing a Model section of the MapleSim Help system.

3-D Visualization and Multibody Settings
The parameters used for 3-D visualization of multibody mechanical components are foundunder the Multibody Settings tab of the Parameters pane in sections for Animation,
Multibody, and Visualization settings.

110 • 4 Simulating and Visualizing a Model

To access the simulation settings, click Multibody Settings tab (Parameters pane.

) on the right of theAnimation Settings
Under Animation, ensure the 3-D Animation check box is enabled if you want to see ananimation of your simulation runs.
Multibody Settings
You can specify the following parameter values for models containing multibody mechanical components:
Table 4.3: Multibody Parameter Values
Parameter
Gravity

Default
9.81

Description
The acceleration due to gravity at the surface of the Earth.
The default units are in

Gravity vector.

Direction of gravity.

Visualization Settings
You can specify the following 3-D Visualization values for models containing multibody
mechanical components:
Table 4.4: 3-D Visualization Parameter Values
Parameter
EnableTranslational
Snapping
Translation Snap
Delta
Enable Rotational
Snapping
Rotation Snap
Delta

Default

Description
When selected, components are positioned at the closest
location in 3-D space based on the translation snap delta value.

1

Specifies the translation snap delta spacing.
When selected, components are positioned at the closest
location in 3-D space based on the rotation snap delta value.

Pi/2

Perspective Grid
Extent10

Grid Spacing

1

Specifies the rotational snap delta spacing.
Specifies the size of the grid drawn in the perspective view.
The grid extends this distance in both directions on thehorizontal plane.
Specifies the space between grid lines.

4.6 Visualizing a Multibody Model • 111

Parameter
Base Radius

Default
0.02

Enable View
ChangeAnimations

Description
Implicit geometry consists of spheres and cylinders
representing multibody components in the 3-D Workspace.
Cylinders are drawn using Base Radius, while spheres (for
Rigid Bodies and Joints) are drawn using Base Radius * 2.
When enabled, a smooth transition occurs when switching
between 3-D orthographic and perspective views and whenusing Fit Scene, Fit Selected, or Fit Animation in the 3-D
Workspace and 3-D Playback Window.

The 3-D Workspace
The 3-D Workspace is the area in which you build and view 3-D models in the MapleSim
window. It is found in the 3-D Workspace tab of the Analysis window.
To open 3-D Workspace:• From the View menu, select Show 3-D Workspace... The Analysis window opens
showing the 3-D Workspace. Alternatively, from the MapleSim main toolbar, click Show
3-D Workspace ( ).

Figure 4.8: 3-D Workspace112 • 4 Simulating and Visualizing a Model

Table 4.5: 3-D Workspace Controls
Component

Description
The area in which you build and view a 3-D model. The arrows at
the origin indicate the directions of the world axes and aredesignated by color:X - red

3-D Workspace

Y - greenZ - blue
You can use the grid as a reference to determine the relative sizes
and positions of elements in your 3-D model.
Contains tools for hiding and displaying components in the 3-D
3-D Toolbar
Workspace, toggling between different modes, selecting camera
navigation tools, and changing the 3-D model view.
Part of the 3-D toolbar, these are controls for building andConstruct Mode Controls
assembling a 3-D model, and connecting 3-D objects.

You can hover your mouse pointer over any of the buttons on the toolbar to view its tooltip.

Viewing and Browsing 3-D Models
In the 3-D Workspace, you can view and browse a 3-D model from the perspective viewor one of the orthographic views using the 3-D View Controls tool.

Figure 4.9: 3-D View Controls

The perspective view allows you to examine and browse a model from all angles in 3-D
space. It allows you to see 3-D spatial relationships between elements in your model. In theperspective view, objects that are closer to the camera appear larger than those that are further
away from the camera.
In the following image, a double pendulum model is shown from the perspective view.

4.6 Visualizing a Multibody Model • 113

Figure 4.10: Perspective View Double Pendulum

You can also view your 3-D model from front, top, and side orthographic views. Orthographic
views use parallel projection as opposed to perspective projection, so your 3-D model appears
as a flattened object because no depth information is shown. Orthographic views are
sometimes referred to as "true length" views because they display undistorted lines anddistances in the view plane that is orthogonal to the camera direction; these views are usefulfor analyzing spatial relationships or clearances between objects.
In the following image, the double pendulum model is shown from the top orthographic
view.

Figure 4.11: Orthographic View Double Pendulum

You can browse a model and change the model view while an animation is static or playing.
In all of the views, you can pan and zoom into or out from your model. In the perspective
view, you can also move the camera to view your model from above or below, and fromany direction around your model.

114 • 4 Simulating and Visualizing a Model

Tip: Before panning, zooming, or moving the camera around a large 3-D model, hover yourmouse pointer over the object that you want to focus on. MapleSim adjusts the navigation
controls according to the object on which you place the mouse pointer.

Adding Shapes to a 3-D Model
Adding Implicit Geometry
By default, basic spheres and cylinders called implicit geometry appear in the 3-D Workspace
to represent physical components in your model. For example, consider the following double
pendulum model, which contains two revolute joints and two subsystems that represent
planar links.

In the 3-D Workspace, the implicit geometry of the fully assembled pendulum model appears
as follows.

Figure 4.12: Implicit Geometry Double Pendulum

In this example, the spheres represent the revolute joints and rigid bodies, and the cylinders
represent the planar links.
Implicit geometry that is not connected to other implicit geometry is drawn in a light graycolor; implicit geometry that is assembled is drawn in a dark gray color, with the exceptionof joint objects, which are drawn in red.
Note: Components that you exclude from a simulation in the Model Workspace do notappear in the 3-D Workspace.

4.6 Visualizing a Multibody Model • 115

Adding Attached Shapes
If you want to create a more realistic representation of your model, you can add shapes andlines called attached shapes to your model. To do so, you first add and connect attachedshape components from the Multibody >Visualization palette to your block diagram in
the Model Workspace.
When you simulate your model, the attached shapes appear in the 3-D Workspace, in addition to the implicit geometry. In the following image, attached shapes have been added torepresent the pendulum stem and bob pictorially. Also, a trace line—the curved line in theimage—can be set to depict the locus of points that will be traced by a particular part of themodel during a simulation.

Figure 4.13: Attached Shapes

You can customize the color, size, scale, and other visual aspects of the attached shapes by
setting parameter values for individual components in the Properties tab before simulating
the model.
If you want to view only the implicit geometry in the 3-D Workspace, you can hide theattached shapes by clicking Show/hide attached shapes ( ) in the 3-D Toolbar. If you
want to view the attached shapes only, you can hide the implicit geometry by clicking
Show/hide implicit geometry ().

For more information about attached shape components, see the MapleSim Component
Library > Multibody > Visualization > Overview in the MapleSim Help system.
Note: If your model contains Flexible Beam components, deflection of the beam will not
be depicted in the implicit geometry of your 3-D model.
Example: Adding Attached Shapes to a Double Pendulum ModelIn the following example, you will add cylinder shapes to represent the pendulum stem anda sphere component to represent the pendulum bob. You will also add a Path Trace component to display the path on which the revolute joint will move during an animation.

116 • 4 Simulating and Visualizing a Model

To add attached shapes
1. From the Help menu, select Examples > Physical Domains > Multibody, and then selectthe Double Pendulum example.
2. Expand the Multibody palette and then expand the Visualization menu.
3. Add two Cylindrical Geometry components below the planar link subsystems in the
Model Workspace.
4. Connect the components as shown below.

5. From the same menu, add a Spherical Geometry component and place it to the right of
the L2 shared subsystem.
6. Right-click (Control-click for Mac) the Spherical Geometry component and select Flip
Horizontal.
7. Add a Path Trace component and place it between the two Cylindrical Geometrycomponents.
8. Connect the components as shown below.

9. Select the first Cylindrical Geometry component (C1 in the previous figure) in the
Model Workspace.

4.6 Visualizing a Multibody Model • 117

10. In the Properties tab (of the cylinder to 0.2.

) on the right side of the MapleSim window, change the radius

11. To select a color for the cylinder, click the box beside the color field and click one of
the color swatches.
12. Select the second Cylindrical Geometry component (C2 in the previous figure) in the
Model Workspace.
13. Change the radius of this cylinder to 0.2 and change the color.
14. Select the Spherical Geometry component (S1 in the previous figure).
15. Change the radius of the sphere to 0.8 and change the color.
16. To simulate the model, click Run Simulation () in the Main Toolbar.

When the simulation is complete, the Analysis window opens with the Simulation Results
tab selected. The 3-D Playback Window displays your model with the attached shapes.

17. To animate the model, click Play () in the 3-D Playback Window.

For another example of how to use the Path Trace component, from the Help menu, selectExamples > User's Guide Examples > Chapter 4, and then select the Lorenz Attractor
example.

Building a Model in the 3-D Workspace
You can build MapleSim models by adding and connecting objects in the 3-D Workspace.
To add multibody components to a 3-D model, put the 3-D Workspace beside the main
MapleSim window, then drag the desired components from the Multibody palette, the Favorites palette, a custom library that you created, or from the search pane in the Library
Components tab to the 3-D Workspace.
In the 3-D Workspace, you can add, connect, and lay out 3-D objects, and set initial conditions for joints and other multibody components by using graphical controls in the 3-D
Workspace.

118 • 4 Simulating and Visualizing a Model

Any changes that you make to your 3-D model are automatically shown in the block diagram
representation in the Model Workspace and vice versa. For example, if you add and connect
a Flexible Beam component in the 3-D Workspace, the block diagram representation of
the Flexible Beam with the added connection lines appear in the Model Workspace at thesame time.
Notes:• Subsystems cannot be created in the 3-D Workspace. They must be created in the
Model Workspace.
• Components from the multibody Forces and Moments, Sensors, and Visualization
component libraries cannot be dragged into the 3-D Workspace. You must add thesecomponents in the Model Workspace.
Moving Objects in the 3-D Workspace
In the 3-D Workspace, you can position individual objects or groups of objects by clicking
and dragging the 3-D manipulators.

To display the 3-D manipulator for a single unconnected object, click the object once in the
3-D Workspace. You can then click and drag the blue arrow of the 3-D manipulator tomove the object along the Z axis, the green arrow to move the object along the Y axis, andthe red arrow to move the object along the X axis. You can also click and drag the sphereat the center of the 3-D manipulator to move the object in all directions.
For a group of connected objects, the configuration of your model determines where the 3D manipulators are located.
• If your 3-D model contains a Fixed Frame component, click the square that represents
the Fixed Frame component to display the 3-D manipulator.
• If your model does not contain a Fixed Frame component, click the object that defines
the initial conditions for your system to display the 3-D manipulator. For example, if
your model contains a Rigid Body component with its initial condition parameters set
to Strictly Enforce, that Rigid Body component displays the 3-D manipulator. When amodel is moved in the 3-D Workspace, the initial conditions are updated for all of theother Rigid Body components that depend on the Rigid Body component that has its
initial conditions set to Strictly Enforce.

4.6 Visualizing a Multibody Model • 119• If your model does not contain a Fixed Frame component or a Rigid Body component
with its initial conditions set to Strictly Enforce, click any of the objects in your 3-D
model to display the 3-D manipulator. When you move the group of objects, the initialconditions of all of the multibody components in your model are set to Treat as Guess.
Note: To display 3-D manipulators, the multibody components in your model must containnumeric parameter values. If custom parameter values defined in a parameter block, global
parameter, or subsystem parameter are assigned to a multibody component, no 3-D manipulator will appear when you click that component in the 3-D Workspace.
Assembling a 3-D Model
A 3-D model must be assembled before you can animate it. Assembling a 3-D model refers
to synchronizing the model that appears in the 3-D Workspace with the initial configurationof your model defined by the assigned parameter values and initial condition guess values.
The synchronization process occurs automatically when you simulate your model. Alternatively, click Update 3-D View ( ) in the 3-D Toolbar to assemble the model. In the 3D Workspace, assembled implicit geometry is drawn in a dark gray color, with the exceptionof joint objects, which are drawn in red.
Note: You can only assemble 3-D models with a valid configuration and valid connectionlines. For example, if you attempt to assemble a 3-D model with missing connection lines,
an error message appears in the console pane and no animation is generated.
For more information, see Assembling a 3-D Model in the MapleSim Help system.
Using the Unenforced Constraints Button to Manipulate Joints in the 3-D
Workspace
You can select a joint object in the 3-D Workspace and click Do Not Enforce Kinematic
Constraints () to specify that the kinematic constraints of the joint are not enforced inthe 3-D Workspace as you build your model. Joints with unenforced kinematic constraints
appear in pink in the 3-D Workspace and their initial conditions are not shown in the 3-D
Workspace as you build your model.
You may want to use Do Not Enforce Kinematic Constraints () if, for example, you
are creating a closed-loop model in the 3-D Workspace and you need a joint to remain ina specific position as you are building and laying out your 3-D model.
Notes:• The do not enforce constraints button does not affect the actual initial conditions specified
for your joint components in the Properties tab; it affects the initial conditions depictedin the 3-D Workspace for display purposes only.

120 • 4 Simulating and Visualizing a Model• Initial conditions for other joints with enforced kinematic constraints will be shown in
the 3-D Workspace, but will not affect related joints with unenforced kinematic constraints.
For example, consider a double pendulum 3-D model that contains a revolute joint with
unenforced kinematic constraints and a second revolute joint with enforced kinematic constraints. If you change the initial angle of the joint with enforced kinematic constraints, thejoint with the unenforced kinematic constraints will remain in its original position while
the joint with enforced kinematic constraints will be shown at the new initial angle. To
display all of the new initial conditions in the 3-D Workspace, you must assemble yourmodel by running a simulation or clicking Update 3-D View ().

Displaying Attached Shapes as You Build a 3-D Model
When you connect Cylindrical Geometry, Tapered Cylinder Geometry, Box Geometry,or Spherical Geometry components to your block diagram in the Model Workspace, thecorresponding attached shapes appear in both the 3-D Workspace and the 3-D Playback
Window. The attached shape appears in the 3-D Workspace after you connect all of its
ports to compatible ports of multibody components in the Model Workspace.
Working with CAD Geometry
CAD geometry can also be shown in both the 3-D Workspace and the 3-D Playback
Window. When you add a CAD Geometry component anywhere in the Model Workspace,
the corresponding CAD image appears in the 3-D Workspace regardless of whether the
CAD Geometry component is connected to other components in your model. If a CAD
Geometry component is not connected to other components, it will be drawn at the originof the 3-D grid; if a CAD Geometry component is connected to another component, it will
be drawn at the origin of the coordinate frame of the modeling component to which it is
attached.
You can define the translational and rotational offset for CAD images either before or afterconnecting the corresponding CAD Geometry component to your model. To define these
offsets, select the CAD Geometry component in the Model Workspace and specify parameter values in the Properties tab.

4.6 Visualizing a Multibody Model • 121

Example: Building and Animating a Double Pendulum Model in the 3-D
WorkspaceIn this example, you will build and animate a double pendulum model. You will performthe following tasks:
To build and animate a double pendulum:
1. Add and move objects in the 3-D Workspace.
2. Connect the 3-D objects.
3. Set initial conditions for the joints in your model.
4. Animate the 3-D model.
Adding and Moving Objects in the 3-D Workspace
To add or move an object:
1. Open a new MapleSim document.
2. From the MapleSim main toolbar, click Show 3-D Workspace (window beside the main MapleSim window.
3. Click Always-On-Top (the MapleSim window.

), and arrange that). This keeps the Analysis window in focus as you work in

4. Under the Library Components tab, expand the Multibody palette, and then expand
the Bodies and Frames menu.
5. From the palette, drag a Fixed Frame component into the 3-D Workspace. A graysquare, which represents the Fixed Frame component, is added to the 3-D Workspace
and its 3-D manipulator appears.

You can use this manipulator to position objects in the 3-D Workspace.
6. Position the Fixed Frame object at the origin of the grid by clicking and dragging the
3-D manipulator arrow controls.

122 • 4 Simulating and Visualizing a Model

7. From the Multibody > Joints and Motions menu, drag a Revolute component into the
3-D Workspace and place it to the right of the Fixed Frame.

8. From the Multibody > Bodies and Frames menu, drag a Rigid Body Frame component
into the 3-D Workspace and place it to the right of the Revolute component.

9. From the same menu, drag a Rigid Body component into the 3-D Workspace and place
it to the right of the Rigid Body Frame.
Tip: To zoom into and out from the 3-D Workspace, hover your mouse pointer over theobject that you want to focus on and rotate your mouse wheel. When zooming with themouse wheel, the location under the pointer remains in place, allowing you to zoom in onthat location. To pan your model, hold the Shift key and drag your mouse pointer in the 3D Workspace.

4.6 Visualizing a Multibody Model • 123

10. From the same menu, drag another Rigid Body Frame component into the 3-D Workspace and place it to the right of the Rigid Body. The components for the first pendulum
link have been added.

11. Repeat steps 6 to 9 to add components for a second pendulum link to the right of the last
Rigid Body Frame component that you added.

Connecting 3-D Objects
You will now connect the objects that you added in the previous task.

124 • 4 Simulating and Visualizing a Model

To connect objects:
1. Click Connect ports ().

2. Hover your mouse pointer over the Fixed Frame object. A green dot appears.

3. Click the green dot once to start the connection line.
4. Hover your mouse pointer over the first Revolute joint component. The gray panel atthe bottom of the 3-D Workspace displays the names of the Revolute joint frames.

5. Click the Revolute joint component once. A context menu displays the names of theframes to which you can connect the line.

4.6 Visualizing a Multibody Model • 125

6. Select R1.frame_a. The components are connected in the 3-D Workspace.

Note that the joint component is drawn in red when it is connected.
7. Click Connect ports () to start the next connection line.

8. Click the sphere that represents the Revolute joint. A context menu displays the framesof the Revolute joint, as well as the Fixed Frame to which it is connected.

9. From the context menu, select R1.frame_b.

126 • 4 Simulating and Visualizing a Model

10. Drag your mouse pointer to the end of the cylinder that represents the Rigid Body Frameand click the green dot.

frame_b of the first revolute joint, R1, is now connected to frame_a of the first rigid body
frame, RBF1.
11. Click Connect ports to start a new connection line.
12. Hover your mouse pointer over the other end of the cylinder that represents the RBF1
component and click the cylinder once.
13. Drag your mouse pointer to the sphere that represents the first Rigid Body component,
RB1, and click it once. RB1 is now connected to RBF1.
14. In the same way, connect frame_a of RB1 to frame_a of the second Rigid Body Frame,
RBF2.
Note: Click the connect button to start each connection line.

15. Connect frame_b of the second Rigid Body Frame to frame_a of the second Revolutejoint.
16. Connect frame_b of the second Revolute joint to frame_a of the third Rigid Body
Frame.

4.6 Visualizing a Multibody Model • 127

17. Connect third Rigid Body Frame to the second Rigid Body, and then connect the second
Rigid Body to the fourth Rigid Body Frame. The complete 3-D model appears below.

In the 2-D model workspace, you will see that all of the components are added and connectedaccordingly.
Tip: As you are building a 3-D model, it is a good practice to switch to the block diagram
view periodically to check whether the block diagram is laid out the way you want.
Setting Initial Conditions for the Joint Components
You can set initial conditions for joint components by using graphical controls in the 3-D
Workspace.
Note: Joint components that have been assigned custom parameter values defined in aparameter block, global parameter, or subsystem parameter will not allow the use ofgraphical controls for setting initial conditions. In these cases, use the fields in the Properties
tab to set the initial conditions.
To set initial conditions:
1. In the 3-D Workspace, to set the initial angle of the first revolute joint, click the spherethat represents the first revolute joint in the 3-D Workspace. The red sphere, which
represents the joint component, is removed temporarily from the 3-D Workspace andthe manipulator for the joint appears.

128 • 4 Simulating and Visualizing a Model

2. Hover your mouse pointer over the manipulator. The manipulator appears in yellow.
3. Click and drag your mouse pointer around the manipulator to display the meter that
represents the initial angle value that you want to set for the revolute joint. A pie graphshaped meter appears in orange.

When you drag your mouse pointer, you can adjust the initial angle value for the degree of
freedom represented by the graphic. The angle value increases if you drag the mousepointer up or to the right, and decreases if you drag the mouse pointer down or to the left.
4. Release your mouse button when the meter is at the approximate initial condition valuethat you want. In the Properties tab ( ), the θ0 parameter displays the value that you
selected. The implicit geometry is set to that value in the 3-D Workspace.
Tips:• Alternatively, you can set initial conditions for your model by entering a value for the θ0parameter in the Properties tab. Initial conditions that you specify in the Properties tab
will be shown in the 3-D model.
• To specify precise initial angle conditions, turn on snapping by selecting Enable Rotational Snapping under Visualization in the Multibody Settings tab ().

Animating the 3-D Model
You will now simulate your 3-D model to generate the animation that can be viewed in the
playback window.

4.7 Best Practices: Simulating and Visualizing a Model • 129

To animate the 3-D model:
1. Simulate your model by clicking Run Simulation ( ) in the Main Toolbar. When thesimulation is complete, the Analysis window opens, containing both simulation plots
and the 3-D Playback Window.
2. Select the 3-D Playback Window. ( If the playback window is not visible, double-click
3-D Playback Window in the Plot Windows palette in the left pane of the Analysis
window to view it.)
3. To play the animation, click Play () in the Playback Toolbar.

Exporting a Movie of the 3-D Model
The Export Movie feature allows you to export a recorded simulation as a movie file (forexample AVI) for playback outside of MapleSim or to share with others who may not have
MapleSim. For more information, see Using MapleSim > Visualizing a 3-D Model >Exporting a Simulation as a Movie in the MapleSim Help system.

4.7 Best Practices: Simulating and Visualizing a Model
This section describes best practices to consider when simulating and visualizing a model.

Use an External C Compiler to Run Simulations with Longer Durations
When you set the compiler parameter to true in the Simulation Settings tab (), Maple
procedures generated by the simulation engine are translated to C code and then compiled
by an external C compiler. As a result, the time required to run a simulation can be reduced.
In general, when you use a C compiler to simulate a model, the compilation process will
be faster in simulations with longer durations.

Compare Results Generated by Sections of Your Model
For debugging purposes, you may want to view simulation results for a specific section or
subsystem in your model. By selecting a section in your model and clicking Disable ( )above the Model Workspace or pressing Ctrl + E (Command + E for Mac), you can exclude part of your model from the next simulation that you run. When you simulate yourmodel, results will appear only for the model sections that you did not exclude. This featureallows you to view simulation results generated by specific sections in your model andcompare results without having to delete components from the Model Workspace or build
multiple models.
For more information, see Using MapleSim > Simulating a Model > Excluding Objects
From a Simulation in the MapleSim Help system.

130 • 4 Simulating and Visualizing a Model5 Analyzing and Manipulating a ModelIn this chapter:• Overview (page 131)
• Retrieving Equations and Properties from a Model (page 135)
• Analyzing Linear Systems (page 135)
• Optimizing Parameters (page 136)
• Generating and Exporting C Code from a Model (page 138)
• Generating a Custom Component from External C Code/Library Definition (page 146)
• Working with Maple Embedded Components (page 149)

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 tocommands, embedded components, plotting tools, and many other technical features toanalyze 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 accessthe 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.
Table 5.1: MapleSim Apps
App Name
Component Creation

Task

131

132 • 5 Analyzing and Manipulating a Model

App Name
1-D Motion Generation
Custom Port
DCV Builder
External C/Library Block
Kinematic Cam Generation
Linearization
Model Analysis
Equation Extraction

Initialization Diagnostics

Modal Analysis
Monte Carlo Simulation
Multibody Analysis
Optimization
Parameter Sweep
Utility
Code Generation

Task
Create motion profiles for 1-D motion that adhere to defined velocity,
acceleration, and jerk constraints.
Create a custom port for a custom component. For more information,
see Creating Custom Modeling Components (page 73).
Create a custom hydraulic directional control valve.
Define and generate a MapleSim custom component from external C
Code/DLL.
Model the kinematic behavior of cams and followers.
Linearize a MapleSim continuous subsystem. Perform linear analysis
on the linear system object, such as generating Bode plots and Root
Locus plots.
Retrieve equations from linear or nonlinear models. For more
information, see Tutorial 7: Using the Equation Extraction
App (page 208).
Resolve inconsistent initial conditions and errors detected during thesimulation, as well as give insight into the original configuration of
the system.
Visualize the vibration modes of a multibody model.
Define a random distribution for a parameter and run a simulation
using the distribution.
Retrieve multibody equations in a form that is suitable for manipulation
and analysis.
Analyze and edit the parameters of a model and view possible
simulation results in a graph. For more information, see Optimizing
Parameters (page 136).
Execute a parameter sweep.

Translate your model into C code. For more information, see
Generating and Exporting C Code from a Model (page 138).
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 (page 65).
Excel Connectivity
Import MapleSim parameter sets from an Excel spreadsheet, or export
MapleSim parameter sets to an Excel spreadsheet.
Define and generate a set of random data points to be used in
Random Data
MapleSim, for example, a data set for an interpolation tablecomponent.
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.

5.1 Overview • 133

App Name
Temperature Distribution

Task
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 towhich 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 (from the available templates. The templates open in Maple.

). Select

Table 5.2: MapleSim Templates
Template Name
Custom Component
Worksheet

Task
Create a custom modeling component based on a mathematical model.
For more information, see Creating Custom Modeling
Components (page 73).
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.

134 • 5 Analyzing and Manipulating a Model

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, theparameter for the initial value of the angular velocity appears as ω0 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 ina 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 convertingyour model or part of your model into a subsystem, you can more easily identify the set ofmodeling components that you want to explore, define the set of inputs and outputs for thesubsystem, 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 andCreating Subsystems (page 66).
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 Modelfor 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 tohave 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 levelof your model into a single subsystem.

5.2 Retrieving Equations and Properties from a Model • 135

5.2 Retrieving Equations and Properties from a Model
You can use the Equation Extraction App to retrieve, define, and analyze equations andproperties such as parameters and variables in your model. Additional features within thisapp 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 (page 208).
To retrieve equations and properties:
1. In MapleSim, open the model for which you want to retrieve equations or properties.
2. In the main toolbar, click Show Apps Manager (Apps tab selected.

). The Analysis window opens with

3. From the Apps palette, under Model Analysis, double-click Equation Extraction to
open this app.
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 systemparameters 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 asubsystem.
To analyze a linear system model from MapleSim:
1. In MapleSim, open the linear system model that you want to analyze.
2. In the main toolbar, click Show Apps Manager (Apps tab selected.

). The Analysis window opens with

3. From the Apps palette, under Component Creation, double-click Linearization to
open this app.
4. Using the navigation tools above the model diagram, select the subsystem for which you
want to view equations.

136 • 5 Analyzing and Manipulating a Model

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. See the following section,
Linear System Analysis, for details.
9. 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 Componentstab (). 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 theeffects 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 thensimulate 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
1. In MapleSim, open the linear system model that you want to analyze.
2. In the main toolbar, click Show Apps Manager (Apps tab selected.

). The Analysis window opens with

5.4 Optimizing Parameters • 137

3. From the Apps palette, under Model Analysis, double-click Optimization to open thisapp.
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 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.
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 performthe 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 Parametersin Model.

138 • 5 Analyzing and Manipulating a Model

5.5 Generating and Exporting C Code from a ModelIf 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 thelevel 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 thatthe 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

5.5 Generating and Exporting C Code from a Model • 139

Preparing the Model for Export in MapleSim
The basic structure for exporting models is the subsystem where you define the input andoutput signals from the generated code. By creating a subsystem you also improve thevisual layout of a system in the Model Workspace. The following figure shows a subsystemwith 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 atthe 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, generatingcode for the RLC subsystem, only the parameters R, L and C will default to being modifiablein the exported code.

140 • 5 Analyzing and Manipulating a Model

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 theparameters 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, thatcode 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. In the main toolbar, click Show Apps Manager (Apps tab selected.

). The Analysis window opens with

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

5.5 Generating and Exporting C Code from a Model • 141

Customizing, Defining, and Assigning Parameter Values to SpecificPorts
The Configuration interface lets you customize, define and assign parameter values to specific ports. Subsystem components to which you assign the parameter inherit a parametervalue 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.

Outputs: Contains the model output variables.
Export All/Export None: Allows you to either select or remove all of the parameters forexport.
Add an additional output port for subsystem state variables: Select this option to add
an additional port for the selected subsystem state variable.

142 • 5 Analyzing and Manipulating a Model

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 forexport.
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 statevariables.
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.

5.5 Generating and Exporting C Code from a Model • 143

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 inthe source code. You can then recompile your code and run it to see the effect on yourmodel.
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144 • 5 Analyzing and Manipulating a Modelaccuracy 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 moreaccurate 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 resultof 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 accuracyof 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.

5.5 Generating and Exporting C Code from a Model • 145

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. In the main toolbar, click Show Apps Manager ().

4. From the Apps palette, under Utility, double-click Code Generation to open this app.
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. 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.
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 theapp.

146 • 5 Analyzing and Manipulating a Model

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 Codeand 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 avariety of software tools as additional Connector toolboxes.
With this app, you can define the external inputs and outputs, specify the function nameand 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 systemusing the External C Code/Library Definition app.
The process of creating an external code custom component for a MapleSim model consistsof 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

5.6 Generating a Custom Component from External C Code/Library Definition • 147

Opening the External C Code/Library Definition App
1. In the main toolbar, click Show Apps Manager ().

2. 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 (page 203) walks you through this step.
If you save to an attachment, the attachment is saved in the Attached Files tab (Other.
Click Validate C to verify the validity of the provided C code.

) under

148 • 5 Analyzing and Manipulating a Model

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 anarray, 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 (page 203).

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 • 149

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 LinkModelcommand 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 yourmodel 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 theproperties 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 toanalyze 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, andclick 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).

150 • 5 Analyzing and Manipulating a Model

6 MapleSim Tutorials
MapleSim Tutorials help you get started with MapleSim and learn about the key features,
tools, templates and systems available in MapleSim, by leading you through a series of descriptive tasks, problems and examples using best practices. Many of these examples canbe found in the Help > Examples > User's Guide Examples menu, in the order that they
are presented in the User's Guide.
In this chapter:• Tutorial 1: Modeling a DC Motor with a Gearbox (page 151)
• Tutorial 2: Modeling a Cable Tension Controller (page 160)
• Tutorial 3: Modeling a Nonlinear Damper (page 166)
• Tutorial 4: Modeling a Planar Slider-Crank Mechanism (page 175)
• Tutorial 5: Using the Custom Component Template (page 183)
• Tutorial 6: Using the External C Code/DLL Custom Component App (page 203)
• Tutorial 7: Using the Equation Extraction App (page 208)
• Tutorial 8: Modeling Hydraulic Systems (page 213)

6.1 Tutorial 1: Modeling a DC Motor with a Gearbox
In this tutorial, you will extend a DC motor model and perform the following tasks:• Add a gearbox to the DC motor model• Simulate the DC motor with gearbox model• Group the DC motor components into a subsystem• Use a Parameter Block to assign global parameters to the model• Add signal block components and a PI controller to the model• Simulate the modified DC motor model using different conditions

Adding a Gearbox to a DC Motor ModelIn this example, you will build the gearbox by adding and connecting an ideal gearbox
component, a backlash component with a linear spring and damper, and an inertia component
from the 1-D Mechanical library. You can use the selection tool to drag and position components in the Model Workspace.

151

152 • 6 MapleSim Tutorials

To add a gearbox:
1. From the Help menu, select Examples > User's Guide Examples > Chapter 1, andthen select the Simple DC Motor example.
2. Delete the existing probe from the workspace.
3. Select the Library Components tab () and then perform the following tasks:• From the 1-D Mechanical > Rotational > Bearings and Gears menu, add an Ideal
Gear component to the Model Workspace and place it to the right of the Inertia
component.
• From the 1-D Mechanical > Rotational > Springs and Dampers menu, add an
Elasto-Backlash component to the Model Workspace and place it to the right of
the Ideal Gear component.
• From the 1-D Mechanical > Rotational > Common menu, add another Inertia
component to the Model Workspace and place it to the right of the Elasto-Backlash
component.
4. Connect the components as shown in the following figure.

5. In the Model Workspace, click the Ideal Gear component.
6. In the Properties tab (to accept the value.

), change the transmission ratio, r, to 10 and then press Enter

7. Specify the following parameter values for the other components:• For the Elasto-Backlash component, in the b field, change the total backlash value
to 0.3rad. In the d field, change the damping constant to 104.

• For the first Inertia component (I2), in the J field, change the moment of inertia value
to 10kg⋅m2.
• For the second Inertia component (I3), in the J field, change the moment of inertia
value to 1kg⋅m2.
• For the Step source, in the height field, change the value to 100.

6.1 Tutorial 1: Modeling a DC Motor with a Gearbox • 153

Simulating the DC Motor with the Gearbox Model
To simulate the DC motor:
1. From the Model Workspace Toolbar, click Attach probe ().

2. Hover your mouse pointer over the line that connects the Elasto-Backlash component
and the second Inertia component (I3). The line is highlighted.
3. Click the line once, and then click a spot in the workspace to anchor the probe.
4. Select the probe in the Model Workspace.
5. To include the angle (phi), speed (w), acceleration (a), and torque (tau) values in thesimulation graphs, in the Properties tab (Acceleration, and Torque.

), select Angle, Angular Velocity, Angular

6. Click a blank area in the Model Workspace.
7. Under the Settings tab (), set the td parameter to 10 seconds and press Enter.

8. Click Run Simulation () in the Main Toolbar.

9. Click Show Simulation Results (window.

). The following graphs appear in the Analysis

154 • 6 MapleSim Tutorials

10. To verify the results, from the Help menu, select Examples > User's Guide Examples> Chapter 6, and then select the DC Motor with Gearbox example.

Grouping the DC Motor Components into a Subsystem
To group the DC motor components:
1. Draw a box around the electrical components and the first inertia component by dragging
your mouse over these components.

6.1 Tutorial 1: Modeling a DC Motor with a Gearbox • 155

2. From the Edit menu, select Create Subsystem.
3. In the Create Subsystem dialog box, enter DC Motor.
4. Click OK. A white block, which represents the DC motor, appears in the Model
Workspace.

Tip: To view the components in the subsystem, double-click the DC Motor subsystem in
the Model Workspace. To browse to the top level of the model, click Main ( ) in the
Model Workspace Toolbar.

Assigning Global Parameters to a Model
You can define a global parameter and assign its value to multiple components in yourmodel.
To assign global parameters:
1. Click Main (model.

) in the Model Workspace Toolbar to browse to the top level of the

2. In the Model Workspace, double-click sysParams (Default Settings view.

) to switch to the Parameter156 • 6 MapleSim Tutorials

3. In the first row of the Main subsystem default settings table, enter Rglobal in the Name
field and press Enter.
4. Specify a default value of 24 and enter Global resistance value as the description.
5. In the second row of the table, enter Jglobal in the Name field and press Enter.
6. Specify a default value of 10 and enter Global moment of inertia value as the description.

7. Click Diagram View ( ) in the Model Workspace Toolbar to return to the model
diagram. The new Rglobal and Jglobal parameters appear in the Properties tab (You can now assign these parameter values to other components in your model.

).

8. Select Make Parameters Available for Rerun.

9. In the Model Workspace, select the Inertia component I3.
10. In the Properties tab ( ), in the Value field for the moment of inertia parameter, enter
Jglobal and press Enter. The moment of inertia parameter now inherits the numericvalue of the global parameter Jglobal (in this example, 10).
11. Double-click the 'DC Motor' subsystem.
12. In the Model Workspace, select the EMF1 component.

6.1 Tutorial 1: Modeling a DC Motor with a Gearbox • 157

13. Properties tab (), in the Value field for k, the transformation coefficient, enterand press Enter.

Note: This value is an approximation of the transformation coefficient.
14. Similarly, in the Properties tab ( ) for the R1 component, in the Value field for the
resistance parameter, enter Rglobal and press Enter.
15. Click Main () to browse to the top level of your model.

16. Save the model as DC_Motor2.msim.
17. Press Play () to run the simulation.

Rerunning the Simulation with Different Parameter Values
You can use Parameter Blocks to make specific parameters tunable allowing you to rerun
simulations without having to perform a full reformulation.
Since Make Parameters Available for Rerun was selected, you can make updates to theseparameters in the Rerun Simulation Panel, where you can explore and compare the resultsthat these changes have on the simulation.
1. Click the Rerun Simulation tab) on the left side of the Analysis Window to bring
you to the Rerun Simulation panel.
2. Change the value of Jglobal to 5.
3. Press the Rerun button () to rerun the simulation with the new value for Rglobal.

4. Plots of the Latest Results and Latest Rerun simulations are available for comparison in
the Probe Plots window.

158 • 6 MapleSim Tutorials

Changing Input and Output Values
In this example, you will change the input and output values of the model to simulate different
conditions.
To change input and output values:
1. Under the Library Components tab (), browse to the 1-D Mechanical > Rotational> Sensors menu and then add the Rotational Speed Sensor component to the Model
Workspace and place it below the gearbox components.
2. Right-click (Control-click for Mac) the Rotational Speed Sensor component and selectFlip Horizontal.
3. Delete the connection line between the Step source and the DC Motor subsystem.
4. From the Signal Blocks > Controllers menu, add the PI component to the Model
Workspace and place it to the left of the DC Motor subsystem.
5. From the Signal Blocks > Mathematical > Operators menu, add the Feedback component to the Model Workspace and place it to the left of the PI component.
6. Connect the components as shown below.

6.1 Tutorial 1: Modeling a DC Motor with a Gearbox • 159

Tip: To draw a perpendicular line, click a point in the Model Workspace to anchor the line
and then move your mouse cursor in a different direction to draw the second line segment.
7. Click the PI component in the Model Workspace.
8. In the Properties tab (seconds in the T field.

), specify a gain of 20 in the k field, and a time constant of 3

9. Simulate the model again. When the simulation is complete, the following graphs appear.

160 • 6 MapleSim Tutorials

10. Save the model as DC_Motor3.msim.
11. To verify the results, from the Help menu, select Examples > User's Guide Examples> Chapter 6, and then select the DC Motor Subsystem with Gearbox and PI Controller
example.

6.2 Tutorial 2: Modeling a Cable Tension Controller
In this tutorial, you will extend the DC motor example to model a cable that is stretchedwith a pre-defined tension. The tension is defined by a Constant source and the PI controller
provides the voltage to drive the motor. You will perform the following tasks:• Build a cable tension controller model• Specify component properties• Simulate the cable tension controller model

Building a Cable Tension Controller ModelIn this example, you will build the cable tension controller model using a combination of
1-D mechanical rotational and translational components. You will also group components
into a Gear subsystem and add subsystem ports.

6.2 Tutorial 2: Modeling a Cable Tension Controller • 161

To build the cable tension controller:
1. Open the DC_Motor3.msim file that you created in the previous tutorial and save thefile as Cable_Tension.msim.
2. Delete the probe attached to the line that connects the Elasto-Backlash and Inertia
components.
3. Delete the Rotational Speed Sensor component and its connection lines.
4. Select the Ideal Gear, Elasto-Backlash, and Inertia components and group them into
a subsystem called Gear Components.
5. From the Library Components tab (Workspace:), add the following components to the Model• From the 1-D Mechanical > Rotational > Bearings and Gears menu, add the Ideal
Gear R 2 T component and place it to the right of the Gear Components subsystem.
• From the 1-D Mechanical > Translational > Sensors menu, add the Force Sensor
component and place it to the right of the Ideal Gear R 2 T component.
• From the 1-D Mechanical > Translational > Springs and Dampers menu, add theSpring component and place it to the right of the Force Sensor component.
• From the 1-D Mechanical > Translational > Common menu, add the Fixed component and place it to the right of the Spring component.
6. Right-click (Control-click for Mac) the Fixed component in the Model Workspace andselect Rotate Counterclockwise.
7. Delete the Step source and replace it with a Constant source from the Library > Signal
Blocks > Sources > Real menu.
Tip: You can connect the Constant source by dragging it onto the unconnected line end.
8. Double-click the 'Gear Components' subsystem. You will now add a port to connect
this subsystem with other components.
9. Click the negative (white) flange of the Inertia component and drag your mouse cursor
to the boundary that surrounds the subsystem components.

10. Click the line once. The subsystem port is added to the line.

162 • 6 MapleSim Tutorials

11. Click Main (model.

) in the Model Workspace Toolbar to browse to the top level of your

12. Connect the components as shown below.

Specifying Component Properties
To specify component properties:
1. In the Model Workspace, double-click the 'Gear Components' subsystem.
2. In the Properties tab (components:), specify the following parameter values for the subsystem• For the Ideal Gear component, change r to 0.01.
• For the Inertia component, change J to 0.1kg⋅m2.
3. Click Main (model.

) in the Model Workspace Toolbar to browse to the top level of the

4. Double-click the sysParams Parameter Block to open the Parameter Settings editor.
5. In the Parameters Settings editor specify the following parameter values for the othercomponents:• Name the first parameter Spring. Select Real for the Type, and enter 2110⋅109 as theDefault Value. Press Enter.
• Name the second parameter Time, select Real for the Type, then enter 0.1 for the
Default Value. Press Enter.
• Name the third parameter Constant, select Real for the Type, then enter 77.448 forthe Default Value.

6.2 Tutorial 2: Modeling a Cable Tension Controller • 163

6. Select the Spring component in the Model Workspace, then select the Properties tab.
7. In the c field, enter Spring.
8. Next, select the PI controller from the Model Workspace, then select the Properties tab.
9. In the T field, enter Time.
10. Next, select the Constant source from the Model Workspace, then, as before, select theProperties tab.
11. In the k field enter Constant.
12. Select sysParams in the Model Workspace, then select the Properties tab.
13. Ensure that Make Parameters Available for Rerun is selected.

Rerunning the Simulation with Different Parameter Values
As mentioned in Tutorial 1: Modeling a DC Motor with a Gearbox (page 151), you can use
Parameter Blocks to make specific parameters tunable allowing you to rerun simulations
without having to perform a full reformulation.
Since Make Parameters Available for Rerun was selected in step 8, you can make updates
to these parameters in the Rerun Simulation Panel, where you can compare the results thatthese changes have on the simulation.
1. Click the Rerun Simulation tab) on the left side of the Analysis Window to bring
you to the Rerun Simulation panel.
2. Change the value of Spring to
3. Press the Rerun button (.

) to rerun the simulation with the new value for Rglobal.

4. Plots of the Latest Results and Latest Rerun simulations are available for comparison in
the Probe Plots window.

164 • 6 MapleSim Tutorials

Simulating the Cable Tension Controller
To simulate the cable tension controller:
1. Click Attach probe ().

2. Click the line that connects the Feedback and PI components and then click the workspace to position the probe.
3. Select the probe in the Model Workspace.
4. In the Properties tab (), select the Real quantity and change its name to Error.

5. Add another probe that measures the Real quantity to the line connecting the PI component and 'DC Motor' subsystem. Change the quantity name to Controller.

6.2 Tutorial 2: Modeling a Cable Tension Controller • 165

Figure 6.1: Cable Tension Controller

6. Click a blank area in the Model Workspace.
7. In the Settings tab (), specify the following parameters:• Set the simulation duration time, td, to 5 .
• Select Variable from the Solver Type drop-down menu.
• Select Rosenbrock (stiff) from the Solver drop-down menu.
8. Click the Run Simulation () in the Main Toolbar.

9. Click Show Simulation Results (window.

10. Save the file.

). The following graphs appear in the Analysis

166 • 6 MapleSim Tutorials

6.3 Tutorial 3: Modeling a Nonlinear Damper
In this tutorial, you will model a nonlinear damper with a linear spring. This tutorial builds
upon the concepts demonstrated in the previous tutorials. You will perform the following
tasks:• Generate a custom spring damper defined by differential equations• Provide custom damping coefficient values as input signals• Build the nonlinear damper with linear spring model• Assign a variable to a subsystem• Simulate the nonlinear damper with linear spring model

Generating a Spring Damper Custom Component
This example uses the Nonlinear Spring Damper Custom Component created in Example:
Creating a Nonlinear Spring-Damper Custom Component (page 85) in Chapter 3.

Providing Damping Coefficient Values
You can provide custom values for interpolation table components that you add to yourmodel. In this example, you will provide damping coefficient values in an external file.

6.3 Tutorial 3: Modeling a Nonlinear Damper • 167

To create damping coefficient values:
1. Create either a Microsoft Excel spreadsheet (.xlsx) or comma-separated values (.csv)
file that contains the following values:

The first column contains values for the relative displacement of the damper and the second
column contains values for the damping coefficients.
2. Save the file as DamperCurve.xlsx or DamperCurve.csv.
3. In MapleSim, open the NonlinearSpringDamper.msim model you created in Example:
Creating a Nonlinear Spring-Damper Custom Component (page 85) in Chapter 3.
4. Select the Attachment Files tab ().

5. Right-click (Control-click for Mac) Data Sets and select Attach File.
6. Browse to and select the Excel spreadsheet or .csv file that you created, and click Attach.... The file containing the data set is attached to your model. You will use this filein the next task.

Building the Nonlinear Damper ModelIn this example, you will build the nonlinear damper using components from the component
library.
To build the nonlinear damper:
1. Select the Local Components tab (), and then drag the NonLinearMSD custom
component into the Model Workspace.
2. Select the Library Components tab (the Model Workspace:), and then add the following components to• From the Signal Blocks > Mathematical > Operators menu, add a Gain component
and place it above the NonLinearMSD component.
• From the Signal Blocks > Sources > Real menu, add a Constant component andplace it between the NonLinearMSD and Gain components.

168 • 6 MapleSim Tutorials• From the Signal Blocks > Interpolation Tables menu, add a Lookup Table 1 Dcomponent and place it to the left of the Gain component.
• From the 1-D Mechanical > Translational > Sensors menu, add a Position Sensor
component and place it to the left of the Lookup Table 1 D component.
3. Connect the components as shown in the following figure.

4. Add the following components to the Model Workspace:• From the 1-D Mechanical > Translational > Common menu, add Mass and Forcecomponents and place them to the left of the Position Sensor component.
• From the same menu, add a Fixed component, place it to the right of the NonLinearMSD component, and then rotate it counterclockwise.
• From the Signal Blocks > Sources > Real menu, add a Step source.
5. Connect the components as shown in the following figure.

6.3 Tutorial 3: Modeling a Nonlinear Damper • 169

Figure 6.2: Nonlinear Damper Model

6. In the Model Workspace, select the Lookup Table 1 D component.
7. Under the Properties tab (), select attachment from the data source list.

8. Select the attachment you created (either DamperCurve.xlsx or DamperCurve.csv)
from the data list.

170 • 6 MapleSim Tutorials

9. In the Model Workspace, select the Constant component.
10. In the Properties tab, in the Name field, change the component name to Stiffness.

11. Select the Step component, and then set height to 100.
12. Select the Mass component, and then change the mass, m, to 100kg.
13. Draw a box around all of the components in the nonlinear damper model.

6.3 Tutorial 3: Modeling a Nonlinear Damper • 171

14. Group the selected components into a subsystem called Nonlinear Damper. The complete
model is shown in the following figure.

Assigning a Parameter to a Subsystem
To assign a parameter to a subsystem:
1. In the Model Workspace, double-click the 'Nonlinear Damper' subsystem.
2. In the Model Workspace Toolbar, double-click sysParams()

172 • 6 MapleSim Tutorials

3. In the first row of the Parameter default settings view, define a spring constant parameter called Ks, and then press Enter.
4. In the same row, specify the Type as Translational Spring Constant, define a default
value of 1000, enteras Default Units and enter Spring constant as the Description.

You can now assign the parameter value Ks to other components in the Nonlinear
Damper subsystem.

5. In the Model Workspace Toolbar, click Diagram View ( ). The Ks parameter appears
as a field in the Properties tab with the defined default value.

6. In the Model Workspace, select the Stiffness component and change the constant output
parameter, k, to Ks. This component now inherits the numeric value of Ks (in this example, 1000). Therefore, if you edit the numeric value of Ks at the subsystem level, thek parameter also inherits that change.

6.3 Tutorial 3: Modeling a Nonlinear Damper • 173

Simulating the Nonlinear Damper with Linear Spring Model
To simulate the nonlinear damper:
1. Click Main (model.

) in the Model Workspace Toolbar to browse to the top level of the

2. From the Model Workspace Toolbar, click Attach probe (the probe icon when you move into the workspace.

). The cursor changes to

3. To attach the probe, click the line that connects the Mass component and the Nonlinear
Damper subsystem and then click a spot in the workspace to anchor the probe.
4. In the Model Workspace, select the probe.
5. Under the Properties tab (), select the length, speed, and acceleration quantities.

6. Click a blank area in the Model Workspace. The length, speed, and acceleration
quantities (s, v, a) appear beside the probe.
7. Double-click the 'Nonlinear Damper' subsystem.
8. Add a probe to the line that connects the Gain and the NonLinearMSD custom component and then click a spot in the workspace to anchor the probe.
9. In the Model Workspace, select the probe.
10. Under the Properties tab, select the Real quantity and change its name to Damping.

174 • 6 MapleSim Tutorials

11. Under the Settings tab (), set the td parameter to 10 seconds.

12. Click Run Simulation () in the Main Toolbar.

13. Click Show Simulation Results (window.

). The following graphs appear in the Analysis

6.4 Tutorial 4: Modeling a Planar Slider-Crank Mechanism • 175

14. Save the file as NonLinearMSD.msim.

6.4 Tutorial 4: Modeling a Planar Slider-Crank
Mechanism
Using components from the Multibody mechanical library, you will model the planar slidercrank mechanism shown in the following figure.

Figure 6.3: Planar Slider-Crank Mechanism

This model consists of a revolute joint, A, which is attached to a planar link. This planarlink is attached to a connecting rod by a second revolute joint, B. The connecting rod connects
to a sliding mass by a third revolute joint, C, and the sliding mass connects to ground by aprismatic joint. In practice, this mechanism converts rotational motion at the crank totranslational motion at the sliding mass or vice versa. For the system shown in the diagram,
gravity is assumed to be the only external force, acting along the negative Y-axis (the yaxis for the inertial frame).
In this tutorial, you will perform the following tasks:• Create a planar link subsystem• Define and assign subsystem parameters• Create the crank and connecting rod elements• Add the fixed frame, sliding mass, and joint elements to the model• Specify initial conditions• Simulate the planar slider-crank mechanism

Creating a Planar Link Subsystem
The preceding diagram shows that the slider-crank has two associated planar links: the crank(the link from point A to B) and the connecting rod (the link from B to C). In both cases,

176 • 6 MapleSim Tutorials

these links have their longitudinal axis along their local x-axis (x1 and x2, respectively).
Therefore, you will first create a generic planar link with two ports. The inboard port (base)will be locatedlocatedunits along the x-axis of the link, and the outboard port (tip) will beunits along the x-axis of the link. In this example, L refers to the length of thelink and the center-of-mass is assumed to be in the middle of the link.
To create a planar link subsystem:
1. Open a new MapleSim document.
2. Under the Library Components tab (), browse to the Multibody > Bodies andFrames menu, and then add two Rigid Body Frame components and a Rigid Body
component.
3. In the Model Workspace, right-click (Control-click for Mac) one of the Rigid Body
Frame components, and then select Flip Horizontal.
4. Right-click (Control-click for Mac) the Rigid Body component, and then select Rotate
Counterclockwise.
5. Drag the components in the arrangement shown below.

Notes:• If you cannot see the labels for your components, from the View menu, select Show
Labels.
• The labels for your components may differ from the labels in the preceding figure(that is, RB1, RBF1, and RBF2). You can change the labels in your model by selecting
the component, and then entering the new label in the Name field under the Properties
tab. For this tutorial, the labels shown in the preceding figure will be used when referring to specific components.
6. Draw a connection line between the RB1 component and the right frame of the RBF1
component.

6.4 Tutorial 4: Modeling a Planar Slider-Crank Mechanism • 177

7. Draw another connection line between the RB1 component and the left frame of the
RBF2 component.

8. Draw a box around the components by dragging your mouse over them.

9. From the Edit menu, select Create Subsystem.
10. In the Create Subsystem dialog box, enter Link, and then click OK.
You will now add ports to connect this subsystem to other components.
11. Double-click the Link subsystem.
12. Click the left frame of the RBF1 component and drag your mouse pointer to the left ofthe subsystem boundary.

178 • 6 MapleSim Tutorials

13. Click the line once. A subsystem port is added.
14. In the same way, using the right frame of the RBF2 component, create another port on
the right side of the subsystem boundary.

Defining and Assigning Parameters
In this task, you will define a subsystem parameter, L, to represent the length of the link
and assign the parameter value as a variable to the parameters of the Rigid Body Frame
components. The Rigid Body Frame components will then inherit the numeric value of L.
To define and assign parameters:
1. If you are not already in the Link subsystem, click Main (Toolbar, and then double-click the Link subsystem.

) in the Model Workspace

2. In the Model Workspace Toolbar, click Parameters (), or from the Properties tab( ) click Add or Change Parameters. The Standalone Subsystem default settings
window appears.

6.4 Tutorial 4: Modeling a Planar Slider-Crank Mechanism • 179

3. In the first row of the Standalone Subsystem default settings table, enter L in the Name
field, and then press Enter.
4. Specify a default value of 1 and enter Length as the description.
5. Scroll to the RBF1 component section.
6. In the Value field for , specify a position offset of, and then select mfrom the Units drop-down menu. To enter a fraction, use the forward slash key (/).
7. Scroll to the RBF2 component section.
8. In the Value field for , specify a position offset of, and then select m fromthe Units drop-down menu.
9. Click Diagram View ( ).

Creating the Crank and Connecting Rod Elements
In this task, to create the crank and connecting rod elements, you will add a Link subsystemdefinition to your model and create Crank and ConnectingRod shared subsystems. You
will also assign a different length value to the connecting rod element.
To create the crank and connecting rod elements:
1. Click Main ( ) in the Model Workspace Toolbar to browse to the top level of yourmodel. The Link subsystem appears in the Model Workspace.
2. Right-click (Control-click for Mac) the Link subsystem, and then select Convert toShared Subsystem. The Create Shared Subsystem window appears. Click OK. A
Link subsystem definition is added to the Components palette in the Local Componentstab () and the Link subsystem in the Model Workspace is converted to a sharedsubsystem.
3. Select the Link1 shared subsystem in the Model Workspace and in the Properties tab(), enter Crank in the Name field.

4. From the Local Components tab, drag the Link icon to the Model Workspace, placing
it to the right of the Crank shared subsystem.
5. In the Model Workspace, select the second copy of the Link shared subsystem.
6. In the Properties tab (the following figure.

), change the shared subsystem name to ConnectingRod. See180 • 6 MapleSim Tutorials

7. For the ConnectingRod, change the value of the Length parameter (L) to 2.

Adding the Fixed Frame, Sliding Mass, and Joint Elements
In this task, you will add a Fixed Frame component, a Rigid Body component to represent
the sliding mass, and the Revolute joint components.
To add the fixed frame, sliding mass, and joint elements:
1. Under the Library Components tab (), expand the Multibody > Bodies and Frames
menu, select the Fixed Frame component, and then place it to the left of the Crankshared subsystem.
2. From the same menu, select the Rigid Body component and place it slightly below andto the right of the ConnectingRod shared subsystem.
3. Add the following joints:• From the Multibody > Joints and Motions menu, add a Revolute joint between the
Fixed Frame component and the crank, a second Revolute joint between the crankand the connecting rod, and a third Revolute joint between the connecting rod andthe rigid body.
• From the same menu, add a Prismatic joint and place it below the Crank subsystem.
4. Select the Rigid Body component in the Model Workspace and rename it SlidingMass.
5. Right-click (Control-click for Mac) the SlidingMass component and select Flip Horizontal.
6. In the same way, right-click (Control-click for Mac) the Revolute joint that is locatedbetween the connecting rod and the rigid body and select Flip Horizontal. See the following figure.

6.4 Tutorial 4: Modeling a Planar Slider-Crank Mechanism • 181

7. Connect the components as shown in the following figure.

Tip: In this example, the default axes of motion for the revolute and prismatic joints line
up with the desired axes of motion. For example, the revolute joints initially assume thatthey rotate about the z-axis of the inboard frame, which always coincides with the inertial
Z-axis for XY-planar systems. If you create nonplanar models, you may need to changethese axes to make sure that they allow motion along or about the correct directions.

Specifying Initial Conditions
You can specify initial condition values for certain components in your model.
To specify initial conditions:
1. For the first revolute joint (R1 in the preceding figure), in the θ0 field, change the initial
angle torad.

Tip: To enter π, type pi, press Esc , and then select the π symbol from the menu.
2. From the ICθ,ω drop-down menu, select Strictly Enforce.
When MapleSim solves for the initial conditions, the first angle will be set to

rad before

the angles are set for the other joints.

Simulating the Planar Slider-Crank Mechanism
To simulate the planar slider-crank mechanism:
1. From the Model Workspace Toolbar, click Attach probe ().

2. In the Model Workspace, click the white 1-D translational flange (flange_b) at the top
right of the Prismatic component icon and position the probe.
3. Click the probe in the Model Workspace.

182 • 6 MapleSim Tutorials

4. In the Properties tab (), select the Length quantity to measure the displacement.

5. In the same way, add a probe that measures the Angle quantity to the white 1-D rotational
flange (flange_b) at the top right of the R1 component icon (that is, the revolute joint
between the Fixed Frame and Crank components).
6. Click a blank area in the Model Workspace.
7. In the Settings tab (), expand Simulation and set the td parameter to 10 seconds.

8. Click Run Simulation () in the Main Toolbar.

9. Click Show Simulation Results (window.

). The following graphs appear in the Analysis

10. Select the 3-D Playback Window, and then click Play (a video of the simulation.

) in the 3-D Toolbar to see

Tip: The quality of the visualization is affected if any open plot windows are behind the 3D Playback Window. If you are experiencing playback issues, try moving the 3-D Playback
Window so that it does not overlap a plot window. Alternatively, minimize or close any
open plot windows.

6.5 Tutorial 5: Using the Custom Component Template • 183

11. Save the file as SliderCrank.msim.

6.5 Tutorial 5: Using the Custom Component Template
This tutorial describes the use of the Custom Component template in various domains in
MapleSim. With this template, you can define system parameters and variables, set the levelof equation optimization, generate the equations, and then further analyze the resulting
equations. You can use any Maple commands to perform detailed equation analysis, assign
model equations to a variable or parameter, and define additional system variables andparameters. These features are especially useful in generating reusable equations when there
is more than one subsystem.
The Custom Component Templates contain pre-built embedded components that let you
extract, manipulate, and analyze the symbolic system equations generated by any MapleSim
model. Using various components from the library, you will create models, set initial conditions and component properties, and assign new values to parameters and variables.
In this tutorial, you will use the Custom Component template to extract the equations forvarious models by performing the following tasks:• Create the model• Attach a Custom Component template for the model• Enter your governing equations• Set initial conditions by specifying the component properties• Assign new values to parameters and variables• View, manipulate, and reassign equations• Simulate and translate an equation to a transfer function• Map variables from your equations to the ports• Specify ports for your block• Create a custom port using the Custom Port app
For a description of the Custom Component Template see Creating Custom Modeling
Components (page 73).

Example: Modeling a Temperature Dependent Resistor
In this tutorial example, you will create a model of a circuit using a custom component fora temperature dependent resistor whose resistance varies as, where,, andare parameters.

184 • 6 MapleSim Tutorials

To create the custom component:
1. Start a new MapleSim model and then, in the main toolbar, click Load a Maple Worksheet().

2. Double-click on the Custom Component entry in the Templates palette.
3. Enter TempResistor and then click Create Attachment (Component template is loaded.

). The Maple Custom

4. In the Define Equations section, enter in the following system equations to define yourcomponent. Press Enter at the end of the line.

5. In the Configuration section, select Parameters, and then click Refresh All.
6. Select Ports in the Configuration section.
7. Click Clear All Ports.
8. Click Add Port. A new port appears on the left side. This will become the positiveelectrical pin.
9. From the Type drop-down list, select Electrical.
10. Click the Style radio button labeled +.
11. In the list box select Voltage = unassigned and then select vp(t) in the drop-down list
under Signal. This assigns the across variable of the port.
12. In the list box select Current = unassigned and then select i(t) in the drop-down list
under Signal. This assigns the through variable of the port.

13. Click Add Port. A new port appears on the right side. This will become the negativeelectrical pin.
14. From the Type drop-down box, select Electrical.
15. Click the Style radio button labeled -. This changes the port style to an unfilled box.

6.5 Tutorial 5: Using the Custom Component Template • 185

16. In the list box select Voltage = unassigned and then select vn(t) in the drop-down list
under Signal. This assigns the across variable of the port.
17. In the list box select Current = unassigned, select i(t) in the drop-down list under Signal,and then click the +/- button to negate the sign of the signal.

18. Click Add Port. A new port appears on the top edge. Drag the port to the center of thebottom edge.
19. From the Type drop-down box, select Thermal.
20. Click the Style radio button labeled a.
21. Select T(t) for the Temperature variable and qdot(t) for the Heat Flow Rate variable.
22. From the Icon list, select Use default.
23. In the Configuration section, select Variables, and then click Refresh All. This updates
entries in the Type column of the Variables table.
24. In the Variables table, scroll down to see the r(t) and v(t) variables. The types for r(t)and v(t) are still listed as real.
25. Change the Type entries for r(t) and v(t) to Resistance and Voltage, respectively, andthen click Refresh All to ensure these are accepted (if not, they revert to real).
26. In the Configuration section, select Parameters.
27. In the Parameters table, enter Resistance for the type of R0, and ThermodynamicTemperature for both T0 and Tk. Assign the Default for T0 to 300. (The units are Kelvin.)
Click Refresh All to ensure these are accepted.
Note: You can also find the type names used in the preceding step by expanding the Type
Reference section and searching for the appropriate Domain and Type.
28. In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The message "no issues found" should appear in the text area.
29. In the Component Generation section, change the Name to TempResistor.
30. Click Generate MapleSim Component to create your component and to bring you backinto the MapleSim environment. The custom component now appears under the Local
Components tab (), in the Components palette.

31. Drag the custom component into your model area.

186 • 6 MapleSim Tutorials

32. Create the model shown in Figure 6.4 with the components and settings specified inTable 6.1.
Note: When you build the model, make sure to attach the probe to the custom component
to measure the electrical and thermal quantities.
Table 6.1: Temperature Dependent Resistor Components
Component

SymbolComponent Location

Required Settings

TempResistor
Custom Component

Local Components >Components

Constant Voltage

Library Components > Electrical
Use default settings> Analog > Common

GroundLibrary Components > Electrical
Use default settings> Analog > Common

Thermal Resistor

Library Components > Thermal
Set R = 10 K/W> Heat Transfer Components

Heat Capacitor

Library Components > Thermal Set C = 0.1 J/K
Set= 280K> Heat Transfer Components

Fixed Temperature

Library Components > Thermal
Set T = 298K
> Sources

Use default settings

33. Right-click (Control-click for Mac) on the TempResistor custom component, selectAttach probe, and then click on the workspace to place the probe. See the following
figure.

6.5 Tutorial 5: Using the Custom Component Template • 187

Figure 6.4: Temperature Dependent Resistor

34. Select the probe, select the Properties tab (), and then select the following quantities:• Current• ThermoDynamicTemperature• HeatFlowRate• Resistance
35. Click Run Simulation () in the Main Toolbar.

36. Click Show Simulation Results (window.

). The following graphs appear in the Analysis

188 • 6 MapleSim Tutorials

Example: Compliant Contact and Piecewise Functions
In this tutorial example, you will create a model of a bouncing ball using a custom component
to model the compliant ground contact.

Figure 6.5: Falling Ball

The prismatic joint in Figure 6.5 models a falling ball by allowing translation of a rigid
body along the vertical y-axis. To change the falling ball into a bouncing ball, a custom

6.5 Tutorial 5: Using the Custom Component Template • 189

component models the compliant ground contact using a spring-damper arrangement. The
custom component attaches to the 1-D translational ports on the prismatic joint with thefollowing conditions:• The ball will hit ground at s=0 and cause the spring damper to compress (and hence ballposition will be at s<0).
• The spring-damper will impart a restoring force of F(t) to the ball until it is above at s=0.
Figure 6.6 shows a diagram of this process.

Figure 6.6: Bouncing Ball Dynamics

where

To create the custom component:
1. Start a new MapleSim model and then, in the main toolbar, click Load a Maple Worksheet().

2. Double-click on the Custom Component entry in the Templates palette.
3. Enter contact for the name of the attachment and then click Create Attachment (The Maple Custom Component template is loaded.

).

4. In the Define Equations area, enter in the following equation, parameters, and initialconditions to define your custom component. Press Enter at the end of the line.

5. In the Configuration section, select Ports.

190 • 6 MapleSim Tutorials

6. Click Refresh All.
7. Click Clear All Ports.
8. Click Add Port.
9. Make the left port a Translational type. Use style a (the default). Associate its Position
variable with sa(t) and its Force variable with Fa(t).
10. Click Add Port to add a second port to the right side.
11. Make the right port a Translational type. Select style b. Associate its Position variablewith sb(t) and its Force variable with Fb(t).
12. From the Icon list, select Use default.
13. Click Refresh All.
14. In the Configuration section, select Variables.
15. Click Refresh All.
16. In the table, change the Type of s(t) to Position, and then click Refresh All.
17. In the Configuration section, select Parameters, and then click Refresh All.
18. Change the Default value for B to 10.
19. Change the Default value for K to 1000, and change its Type to real.
20. Click Refresh All.
21. In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The following expression appears:. This indicates that the units (dimensions) are notconsistent; the units associated with each element in the sum are displayed. You canchoose to ignore the inconsistency, and the model will work as desired because
MapleSim's engine does not use units. Checking dimensional consistency, however, isan easy way to avoid simple algebraic errors. To eliminate the inconsistency, the proper
types must be added to parameters B and K.
22. Select Parameters, and then enter Force/Velocity and Force/Distance for the types for
B and K, respectively.
23. Click Refresh All. The types update to the equivalent dimensional types, TranslationalDampingConstant and TranslationalSpringConstant.
24. Select Dimensional Analysis, and then click Check Dimensions. "No issues found"
will appear.
25. In the Component Generation section, change the Name to contact.

6.5 Tutorial 5: Using the Custom Component Template • 191

26. Click Generate MapleSim Component to create your component and to bring you backinto the MapleSim environment. The custom component now appears in the Components
palette in the Local Components tab ().

27. Drag the custom component into your workspace and assemble the components shownin Figure 6.7 using the specified model components and their settings from Table 6.2.
Ensure that the prismatic joint translates along the y direction.

Figure 6.7: Bouncing Ball

192 • 6 MapleSim Tutorials

Table 6.2: Bouncing Ball Multibody Components
Component

SymbolComponent Location

Required Settings

CustomComponent

Local Components >Components

Use default settings

Rigid Body

Library Components >Multibody > Bodies andFramesUse default settings

Fixed Frame

Library Components >Multibody > Bodies andFramesUse default settings

For the prismatic joint to translate along
the y direction, settoPrismatic

Library Components >Multibody > Joints andMotions

For the prismatic joint to try enforcing
your translational initial conditions, set
ICs,v to Treat as GuessFor an initial displacement, the prismatic
joint requires a value > 0. Set
to28. Click Run Simulation () in the Main Toolbar.

29. When the simulation is complete, the Simulation Results tab of the Analysis window
displays the probe plot.

6.5 Tutorial 5: Using the Custom Component Template • 193

Figure 6.8: Bouncing Ball Result

30. To play the animation of the bouncing ball, select the 3-D Playback Window in the
Simulation Results tab, and then click Play () in the Playback Toolbar.

31. Use the navigation controls on the toolbar to pan, zoom, or move the camera around yourmodel to find a good view. For more information, see 3-D Toolbar.
32. To create a smoother animation, click the Change 3-D settings icon () and selectInterpolate Intermediate Frames from the drop-down menu. For more information,
see Animating a 3-D Model with Interpolated Frames.

Example: Custom Ports
In this tutorial example you will create a pair of custom ports with causal signals, power,
and velocity, that are generated by a dummy vehicle model and combined by a monitor
block that computes the force, using the relation. For the dummy vehicle

model we will assume the power is constant,, and the velocity is given by, where ,, and are parameters.

194 • 6 MapleSim Tutorials

Create Custom Ports
We need to create two custom ports, an output port named bus_out and an input port named
bus_in.
1. Start a new MapleSim model, and then in the main toolbar, click Show Apps Manager(). The Analysis window opens with Apps tab selected.

2. Double-click on the Custom Port entry under Component Creation in the Apps palette.
The Maple Custom Port Definition app is loaded.
3. In the Configuration section, select Signals, and then click Add Signal to add a newsignal.
4. Enter p as the name of the signal, enter Power as the type, select the output radio button,and enter Vehicle power in the desc column.
Tip: You can find a type by browsing the Type Reference section. If you click the nameof a type, it is copied to the type field.
5. Click Add Signal again to add a second signal.
6. Enter v as the signal name, enter Velocity as the type, select the output radio button,and enter Vehicle velocity in the desc column.
7. In the Generate Port section, enter bus_out in the Name field, vehicle bus port as a
Description, and select the output radio button.
8. Click Generate MapleSim Port to create the output port. You will automatically return
to your MapleSim model.
9. Return to the same app to create the input port.
10. In the Signals section, for both signals, select the input radio button and click Apply.
11. In the Generate Port section, change bus_out to bus_in and click the input style radio
button.
12. Click Generate MapleSim Port to create the input port. You will automatically return
to your MapleSim model.
The two custom ports you have defined appear in the Components palette of the Local
Components tab. See Figure 6.9.

6.5 Tutorial 5: Using the Custom Component Template • 195

Figure 6.9: Custom Ports

Create Engine Model
We will first create the dummy vehicle model.
1. In MapleSim, in the main toolbar, click Load a Maple Worksheet ().

2. Double-click on the Custom Component entry in the Templates palette, and then click
Create Attachment ( ). The Maple Custom Component template is loaded.
3. In the Define Equations section, enter the following system equations to define yourcomponent, and then press Enter at the end of the line.

4. In the Configuration section, select Parameters, and then click Refresh All.
5. Change the Type fields forively.

,, andto Power, Acceleration, and Velocity, respect-

6. In the Configuration section, select Ports.
7. Click Clear All Ports.
8. Click Add Port. A new port appears on the left edge. Drag it to the right edge.
9. From the Type drop-down menu, select Custom. (It is at the bottom of the list.)
10. In the text area below the Type drop-down menu, enter bus_out.
11. Select the out style radio button.
12. Click Apply Custom.
13. From the Icon list, select Use default.
14. Using the drop-down menu and list box at the bottom of this section, assign the powersignal toand the velocity signal to. Figure 6.10 shows the completed Ports
section of the template.

196 • 6 MapleSim Tutorials

Figure 6.10: Using a Custom Port

15. In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The message no issues found should appear.
16. In the Component Generation section, change the name to engine, and then click
Generate MapleSim Component.
The engine component appear in the Components palette of the Local Componentstab.
Create Monitor Model
1. In MapleSim, in the main toolbar, click Load a Maple Worksheet ().

2. Double-click on the Custom Component entry in the Templates palette, and then click
Create Attachment ( ). The Maple Custom Component template is loaded.
3. In the Define Equations section, enter in the following system equation to define yourcomponent, and then press Enter at the end of the line.

4. In the Configuration section, select Parameters, and then click Refresh All.
5. Select Ports, and then click Clear All Ports.
6. Click Add Port. A new port appears on the left edge. This will be the bus input.
7. From the Type drop-down menu, select Custom (at the bottom of the list).

6.5 Tutorial 5: Using the Custom Component Template • 197

8. In the text area below the Type drop-down menu, enter the custom type name: bus_in.
9. Click Apply Custom.
10. Using the drop-down menu and list box at the bottom of this section, assign the powersignal toand the velocity signal to.
11. Click Add Port. A new port appears on the right edge. This will be the computed force
output.
12. From the Type drop-down menu, select Real Signal. Click the out style radio button.
Assign the value signal to.
13. From the Icon list, select Use default.
14. Click Refresh All.
15. In the Configuration section, select Variables, and then click Refresh All.
16. Enter Force for the Type field of signal.

17. Select Dimensional Analysis, and then click Check Dimensions. The message
should appear. It indicates that the output port,a real signal but is equated to, which has units of force (Newtons).

, is

18. In the Component Generation section, change the name to monitor.
19. Click Generate MapleSim Component.
Complete Model
1. In MapleSim, drag the engine and monitor components from the Components palettein the Local Components tab () into the workspace.

2. Connect the output of the engine block to the input of the monitor block. Then, attach
a probe to the output of the monitor block as shown below.

198 • 6 MapleSim Tutorials

3. Run the simulation. The Simulation Results tab in the Analysis window shows the following probe plot:

Advanced Uses for Custom Components
You can use the entire range of Maple functionality to derive your system equations in the
Custom Component template. This section provides a sample advanced application.
Example: Modeling a Centrifugal Pump from a Head Flow Rate Curve
The following hydraulics example demonstrates how to apply extrapolated data from acentrifugal pump into a custom component. Creating a centrifugal pump custom component
involves the following tasks.
• Obtain data from a graph• Generate an equation by fitting the best curve for your data set

6.5 Tutorial 5: Using the Custom Component Template • 199• Obtain multi-argument operators• Apply operators and generate custom component

Figure 6.11: Centrifugal Pump Head Flow Rate Curve
Table 6.3: Centrifugal Pump Data
Flow Rate(cubic meters)
0.01
0.02
0.03
0.04
0.05

Pressure Head(meters)0.00980.00874
0.007250.005
0.0025

Table 6.4: Circular Pipe Parameters
SymbolDescription
Pipe hydraulic diameter
Pipe length
Height of internal pipe roughness
Maximum Reynolds number in laminar regime
Minimum Reynolds number in turbulent regime

Value

200 • 6 MapleSim Tutorials

Table 6.5: Centrifugal Pump Components
Component Symbol

Tank

Hydraulic
Fluid
Properties

Component
Location
Library
Components >Hydraulics >Reference
Components

Library
Components >Hydraulics >Reference
Components

Its Use

Value

This component defines a basepressure (similar to ground in the Use default
electrical domain) and represents a settings
connection to atmosphere.
All hydraulic models need a
Use default
Hydraulic Fluid Properties
settings :component. Similar to a Parameter
block, it is placed in the Model
rhoFluid:
Workspace to define the following
hydraulic fluid properties:• rhoFluid: liquid density

K:• K: Bulk Modulus defines the fluid nuFluid:
compressibility• nuFluid: Kinematic Viscosity
defined as dynamic viscosity divided
by liquid density
The circular pipe defines a pressure
Use default
drop in the hydraulic line. The
settings (seepressure drop is given by the Darcy
Table 6.4)
equation.

Circular
Pipe

Library
Components >Hydraulics >Restrictions

CustomComponent

This custom component defines
Local Components
hydraulic pressure and flow rate
> Components
properties for the hydraulic line.

Figure 6.12: Centrifugal Pump Custom Component

User defined6.5 Tutorial 5: Using the Custom Component Template • 201

To create the custom component:
1. Start a new MapleSim model and then, in the main toolbar, click Load a Maple Worksheet().

2. Double-click on the Custom Component entry in the Templates palette.
3. Click Create Attachment (). The Maple Custom Component template is loaded.

4. In the Define Equations section, place your cursor in the first Maple command line (thatis, the one containing eq), and then insert two document blocks (from the main menu,
select Edit > Document Blocks > Create Document Block twice).
5. Replace the contents of the first line with the following Maple command, and then press
Enter at the end of the line. This command places the values from Table 6.3 into thelist L.

6. Enter the following Maple command in the second document block, and then press Enter
at the end of the line.This command fits a quadratic curve to the data points.

7. Enter the following system of equations, parameters, and initial conditions to define yourcomponent in the third document block, and then press Enter at the end of the line. This
command implements the polynomial in a custom component by defining your equationsin terms of the regression curve and parameters for the block.

8. In the Configuration section, select Ports.
9. Click Clear All Ports.
10. Click Add Port to add a port on the left edge. Select the Hydraulic type, and assign thePressure variable toand the Volume Flow Rate variable to.
11. Click Add Port to add a port on the right edge. Select the Hydraulic type, choose styleb, assign the Pressure variable
and the Volume Flow Rate variable[click the +/- button to change the sign].
12. From the Icon list, select Use default, and then click Refresh All.
13. In the Configuration section, select Parameters, and then click Refresh All.

202 • 6 MapleSim Tutorials

14. Change the default for to 9.81 and assign its type to Acceleration. For rho, change
its default to 1000 and its type to Density. Click Refresh All.
15. Select Variables, and then click Refresh All.
16. Change the type forto Pressure.

17. Select Dimensional Analysis, and then click Check Dimensions. The following expression appears:. This indicates adimensional inconsistency, however, because it is benign we can leave it as is. If you
prefer to remove the inconsistency, you could replacein the original expressions
with, assign the parameterthe default value 1 with type VolumeFlowRate,and protect it (add an X to the Protected column).
18. In the Component Generation section, change the Name to CentrifugalPump.
19. Click Generate MapleSim Component to create your component and to bring you backinto the MapleSim environment. The custom component now appears in the Components
palette in the Local Components tab ().

20. Drag the custom component into the Model Workspace and create the model shown in
Figure 6.12 using the specified model components and their settings from Table 6.5.
Tip: To attach the probe on the Circular Pipe component, right-click (Control-click forMac) on component, select Attach probe, and then position the probe by clicking on theworkspace.
Note: To display the pressure and volume flow rate quantities for your output, select theprobe, and then select the Pressure and VolumeFlowRate quantities from the Propertiestab.
21. Click Run Simulation () in the Main Toolbar.

22. Click Show Simulation Results (window.

). The following graphs appear in the Analysis

6.6 Tutorial 6: Using the External C Code/DLL Custom Component App • 203

6.6 Tutorial 6: Using the External C Code/DLL Custom
Component App
In this tutorial, you will use the External C/Library Block app to import external C Codeparameters and build your model by performing the following tasks:• 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• Build the Simple External Function modelThis model consists of three components: a Step function, a Constant Vector, and an External C Code/DLL custom component.
The external C Code parameters are defined by a function that takes in:• a double scalar input• an input double array of size 2• an output double array of size 3
and then returns a double scalar.

204 • 6 MapleSim Tutorials

To create the external code custom component:
1. Start a new MapleSim model that will call the external code.
2. In the main toolbar, click Show Apps Manager (Apps tab selected.

). The Analysis window opens with

3. Double-click on the External C/Library Block entry in the Component Creation category of the Apps palette. The External C Code/Library Definition app opens.
4. In the Code/Library Location section, for Source Location, select the Text Area radio
button. Doing so opens a text area in which C code is to be entered. For a Windows
platform, the initial content is the code shown in Figure 6.13. For a Unix platform, thecode is shown in Figure 6.14.

Figure 6.13: External C Code Definition for Windows

Figure 6.14: External C Code Definition for Unix

6.6 Tutorial 6: Using the External C Code/DLL Custom Component App • 205

5. Select the Attachment radio button just above the code edit region.
6. Enter a name for the attachment, say f1.c, in the text area to the right of the Attachment
radio button, then click the Attach button to attach the file to the MapleSim file.
7. Select the Attachment radio button for the Source Location, near the top of the app
and ensure that f1.c is selected in the drop-down menu.
8. Click Validate C to validate the code.
9. In the Configuration section, select Function, and then enter f1 for the Function Name.

10. In the Configuration section, select Parameters.
11. Click Add Parameter, set the Name to a and click Apply to apply the changes to theselected parameter.
12. Click Add Parameter, set the Name to b, select the Array? box, set Dim to 2 and click
Apply.
13. Click Add Parameter, set the Name to c, select Passed by Reference, select the Array?
box, set Dim to 3 and click Apply.
14. In the Configuration section, select Return.
15. Use the following values for the C function return parameter.

16. In the Component Generation section, enter ExternalCode in the Block Name field.
17. Click Generate Component. In MapleSim, the custom component appears in the Local
Components tab (MapleSim window.

), located in the Components palette, on the left side of the

To use the external code custom component:
1. Using the specified model components and their settings from Table 6.6, drag the components into the Model Workspace and set their values.

206 • 6 MapleSim Tutorials

Note: Ensure that the model component parameter values are set in your model. When you
select a component in the Model Workspace, the configurable parameter values for thatcomponent appear in the Properties tab (window.

) located on the right side of the MapleSim

Table 6.6 shows the required components and their settings.
Table 6.6: External C Code DLL Custom Components and Required Settings
Component

SymbolComponent
Location

Required Settings

CustomComponent

Local Components >Use default settings
Components

Constant Vector

Library Components> Signal Blocks >Constant output value, set
Sources > Real

Step

Height: 4
Library Components
Offset: 0> Signal Blocks >Sources > RealT0 : 5

2. Connect the Step component to custom component input port a.

to6.6 Tutorial 6: Using the External C Code/DLL Custom Component App • 207

3. Connect the Constant Vector component to custom component input port b.
4. Attach a probe to the custom component output port c and enter the following values:

5. Attach a probe to the custom component output port r and enter the following values:

6. Click Run Simulation () in the Main Toolbar.

7. Click Show Simulation Results (window.

). The following graphs appear in the Analysis

208 • 6 MapleSim Tutorials

8. To verify the results, from the Help menu, select Examples > User's Guide Examples> Chapter 6, and then select the Simple External C Code Function example.

6.7 Tutorial 7: Using the Equation Extraction App
In this tutorial, you will use the Equation Extraction App to extract the equations for amodel by performing the following tasks:• Open the model• Open the Equation Extraction App• View, manipulate, and reassign equations
The Equation Extraction App contains pre-built embedded components that lets you extract,
manipulate, and analyze the symbolic system equations generated by any MapleSim model.

6.7 Tutorial 7: Using the Equation Extraction App • 209

You can select variables and parameters of interest and assign them user-definable names.
These features are useful in generating reusable equations when there is more than one
subsystem.

App Description
The Equation Extraction App is a collection of pre-built controls and procedures associatedwith specific Maple commands to easily generate equations from MapleSim models.
The Equation Extraction App consists of two main areas, Equation Details and View
Equations.
Subsystem Selection
This section loads the MapleSim model and shows all subsystems and their components.
From the toolbar, you can select a subsystem and load its subsystem equations.
Load Selected Subsystem: Loads the subsystem parameters and variables. If no subsystem
is selected, equations for the whole model will be loaded when you click Load Selected
Subsystem.

Equation Details
In this area you can customize and define ports, DAE variables, and parameters for thegenerated equations.
Ports
For acausal ports, you can configure a port so that either the flow-variable or the acrossvariable is considered an input (known).
One of the two signals must be selected as input. Select each port and then select either
Flow or Across to specify which signal is the input.
DAE Variables
Select and rename DAE variables of interest.
Variables: Contains the model DAE variables.

210 • 6 MapleSim Tutorials

New Name: Rename a DAE variable by selecting the variable and specifying a new variablename in the New Name field.
Keep: Mark a variable of interest by selecting the variable and then selecting Keep. If you
use this feature, Extract Equations only displays equations of variables marked with Keep.
If no variables or parameters are marked as keep, all equations are displayed.
Use Subscripts: Use subscripted variable names.
Reset Substitutions: Restores the original names of all variables.
Parameters
Select and rename parameters of interest.
Parameters: Contains the model parameters.
New Name: Rename a model parameter by selecting the parameter and specifying a newname in the New Name field.
Keep: Mark a parameter of interest by selecting the parameter and then selecting Keep. If
you use this feature, Extract Equations only displays equations of variables marked with
Keep. If no variables or parameters are marked as keep, all equations are displayed.
Symbolic: Specify which parameters are left in symbolic form. By default, parameters areevaluated in the equations. (Or, use Toggle Symbolic to toggle this setting for all parameters.)
Use Subscripts: Use subscripted parameter names.
Reset Substitutions: Restores the original names of all parameters.
View Equations
This area shows the system of equations in symbolic form with the assigned parameters.
You can select which equations you want to look at by selecting one of the equation types(DAEs, Definitions, Relations, Events, ODEs, AEs). For more information about equation
types, see GetEquations.
The code edit region shows Maple code that can be used in a Worksheet template to accessthe equations.

6.7 Tutorial 7: Using the Equation Extraction App • 211

Generating the Equations
For this example, we will use the model from the Example: Compliant Contact and Piecewise
Functions (page 188), part of Tutorial 5: Using the Custom Component Template (page 183).
This model is also found in the Help > Examples > User's Guide Examples > Chapter
6 menu. In this model, a bouncing ball is analyzed using a prismatic joint to model a fallingball and a custom component to model the compliant ground contact using a spring-damper
arrangement.
You will group these components into a subsystem to use in the Equation Extraction App.
Generating the System Equations
To generate the system equations:
1. From the Help menu, select Examples > User's Guide Examples > Chapter 6, andthen select Compliant Contact and Piecewise Functions.

212 • 6 MapleSim Tutorials

2. Place the Prismatic joint, contact custom component, probe, and Rigid Body in a subsystem called sub. This allows the Equation Extraction app to generate equations specifically for the selected subsystem.

3. In the main toolbar, click Show Apps Manager (Apps tab selected.

). The Analysis window opens with

4. Double-click on the Equation Extraction entry in the Apps palette. The Equation Extraction App opens in the Analysis window. The toolbar in the Subsystem Selection
window shows all of the subsystems in your model.
5. From the toolbar, select the sub subsystem.

6.8 Tutorial 8: Modeling Hydraulic Systems • 213

6. Click Load Selected Subsystem. The subsystem's component ports, DAE variables, andparameters load automatically in the Ports, DAE Variables, and Parameters areas.
7. Click Extract Equations in the View Equations section.
The system equations appear in the View Equations area.

6.8 Tutorial 8: Modeling Hydraulic Systems
This tutorial provides you with a basic description of hydraulic systems and helps you understand how to model these systems in MapleSim. Using components from the Hydrauliclibrary, you will create models, set initial conditions and component properties, and assign
new values to parameters and variables.
The hydraulic components are designed primarily to convert hydraulic flow into mechanicalmotion, but can also be used to model pure hydraulic circuits.

214 • 6 MapleSim Tutorials

In this tutorial, you will perform tasks based on the following basic principles and concepts:• Basic Hydraulic Library Components• Basic Hydraulic Equations• Analysis of Simple Hydraulic Networks• First Principles Modeling• Mechanical and Hydraulic Systems
The following sections provide conceptual models that you can build using the Hydrauliclibrary components:• Controlling Hydraulic Flow Path
• Actuating Multibody Systems with Hydraulic Components• Compressibility of Hydraulic Liquids• Fluid Inertia Models• Water Hammer Models• Hydraulic Custom Components

Computational Issues
Hydraulic networks tend to be numerically stiff. Generally, the stiff Rosenbrock solver isrecommended.

Basic Hydraulic Library Components
This tutorial uses the following basic Hydraulic library components.

6.8 Tutorial 8: Modeling Hydraulic Systems • 215

Table 6.7: Basic Hydraulic Library Components
Component

Tank

Hydraulic
Fluid
Properties

SymbolLibrary Location

Its UseThis component defines a base pressure
Hydraulics > Reference(similar to ground in the electrical domain)
Components
and represents a connection to the atmosphere.
All hydraulic models need a Hydraulic Fluid
Properties component. Similar to a Parameter
block, it is placed in the Model Workspace
to define the following hydraulic fluid
properties:

Hydraulics > Reference
Components• rhoFluid: fluid density• K: Bulk Modulus is the fluid compressibility• nuFluid: Kinematic Viscosity is the dynamic
viscosity divided by liquid density
Hydraulic
Motor

Hydraulic
CylinderActuators convert hydraulic flow into the
motion of a mechanical body. MapleSim
Hydraulics > Actuators offers a Hydraulic Cylinder (for translationalmotion) and a Hydraulic Motor (for rotationalmotion).

Fixed Flow
Rate
Hydraulics > Sources

You can specify either the flow rate or thepressure of the hydraulic source (withMapleSim calculating the other quantity). If
a Pressure Source is used, then MapleSimbalances the load in the hydraulic systemagainst the pressure source to find the flow
rate, and vice versa.

Hydraulics >Restrictions

The circular pipe introduces a pressure drop
in a hydraulic line. The pressure drop is givenby the Darcy equation, with the friction factor
being determined by using predefined
equations.

Fixed Pressure
SourceCircular Pipe

216 • 6 MapleSim Tutorials

Basic Hydraulic Equations
The Bernoulli and the Darcy equations are the fundamental equations necessary to analyze
hydraulic systems and define the fluid pressure and flow rate characteristics for any point
along a flow. This tutorial uses the following basic fluid equations.
• Bernoulli Equation• Darcy Equation• Friction Factor
Bernoulli Equation
The Bernoulli Equation defines the pressure and flow rate characteristics of incompressible
fluid flow in a pipe. For any point along a streamline, the following relationship applies.

Darcy Equation
For an incompressible fluid flowing through a pipe with a constant diameter, the pressure
drop due to pipe friction is given by the Darcy equation.

Hence6.8 Tutorial 8: Modeling Hydraulic Systems • 217

Table 6.8: Bernoulli and Darcy Equation Notation
SymbolDescription

P

Pressureρ

Densityg

Gravitational constantV

Velocityz

Elevation

L

Pipe lengthDfPipe diameter
Friction factor

UnitsdimensionlessHence pressure must be applied to overcome internal frictional effects within the liquid (inlaminar flow), and the effect of the surface roughness of the pipe (in turbulent flow). Frictional losses (and any other loads in the system) have to be balanced against the appliedpressure to determine the flow rate.
In MapleSim’s mechanical-hydraulic systems, the vertical displacement (z) is insignificant
compared to the other terms, and is ignored.
Friction Factor
In laminar flow, the internal frictional ( ) effect is determined by the following equations:=whereis the internal friction
Re is the Reynolds number
D is the pipe diameter
V is the fluid velocity andν is the dynamic viscosity

218 • 6 MapleSim Tutorials

In turbulent flow, the frictional effects of the surface roughness of the pipe are characterized
by the Haaland Equation.

The Reynolds number (Re) indicates whether flow in a pipe is in laminar or turbulent flow,or is in transition between the two. For example, the circular pipe parameters in Table 6.9
gives the Reynolds number for laminar (ReL) and turbulent (ReT) flow. Between thesetwo parameters, the friction factor is determined by linear interpolation.
Table 6.9: Circular Pipe Parameters
SymbolDescription

ValuesPipe length
Height of internal pipe roughness
Maximum Reynolds number in laminar regime
Minimum Reynolds number in turbulent regime
Pipe hydraulic diameter

Analysis of Simple Hydraulic Networks
This section simulates a simple hydraulic system and analyzes the results from first principles
and explains how to:• Create a simple laminar pipe flow hydraulic system• Analyze the governing equations by applying various laws (for example, conservationof mass, Bernoulli Equation, Darcy Equation)
Flow Through a Pipe
Figure 6.15 analyzes pressure and laminar flow rate characteristics through a pipe whenpressure is applied to overcome internal frictional effects.
To analyze flow through a pipe:
1. Create the following model using the specified model components and their settingsfrom Table 6.10.
Tip: To attach the probe on the Circular Pipe component, right-click (Control-click forMac) on the component, select Attach probe, and then position the probe by clicking on
the workspace.

6.8 Tutorial 8: Modeling Hydraulic Systems • 219

Figure 6.15: Flow Through a Pipe
Table 6.10: Hydraulic Components
Component
Tank

Quantity
2

SymbolLibrary Location

ValuesHydraulics > ReferenceUse default settings
Components
Use default settings:

Hydraulic Fluid
Properties

1

rhoFluid:
Hydraulics > Reference
Components
K:
nuFluid: 0.000018

Fixed Pressure
Source1Hydraulics > Sources Set P =Circular Pipe

1

Hydraulics >Restrictions

Use default settings

2. Click the probe and select the Real (the instantaneous Reynolds number), Pressure, andVolumeFlowRate probe parameters.

220 • 6 MapleSim Tutorials

3. Click Run Simulation () in the Main Toolbar.

4. Click Show Simulation Results (flow rate of). The following graph appears showing the predicted

6.8 Tutorial 8: Modeling Hydraulic Systems • 221

Confirming the Modeling Results from First Principles
When analyzing the system shown in Figure 6.15, apply the Darcy equation.

Assuming that the system is in laminar flow, then

Hence

Where
V = 0.0408
Using V in the flow rate equation yields the following result:=This is the same value given by MapleSim. Using the calculated value of V gives Re= 22.7.
This is far less than the critical value of 2000, and hence the system is in laminar flow.

Overview of Controlling Hydraulic Flow Path
A spool valve has a sharp-edged variable area orifice that enables or partially restricts flow
in a pipe, and can assist in switching flow from one part of a hydraulic network to another.
A spool valve has three ports.

222 • 6 MapleSim Tutorials

Table 6.11: Spool Valve
Spool Valve

Name
PortA

Description
Upstream port

ID
portA

PortB

Downstream port

portB

Area

Real input; area of orifice Area
in selected units

The top port (inp) accepts a signal input that is equal to the open valve area. By regulating
the valve area, flow switches on or off. The left and right ports (portA and portB) are hydraulic connectors. In the following diagram, the model switches flow from the top leg tothe bottom leg when the simulation time reaches 5 seconds. That is, initially, the top spool
valve is open and the bottom is closed. After 5 seconds, the top spool valve closes and thebottom opens.

Figure 6.16: Controlling Flow Path

Mechanical and Hydraulic Systems
In the following examples you will use multidomain components to simulate translationalmotion in mechanical and hydraulic models with the following sources:• Fixed Flow Rate Source• Fixed Pressure Source6.8 Tutorial 8: Modeling Hydraulic Systems • 223

Simulating Translational Motion with a Fixed Flow Rate Source
The following model converts flow from a fixed flow source to translational motion using
the components and their settings from Table 6.12.

Figure 6.17: Fixed Flow Rate Source224 • 6 MapleSim Tutorials

Table 6.12: Translational Motion with Fixed Flow Rate Sources
Component

Quantity

Tank

SymbolLibrary Location
Hydraulics > Reference
Components

1

ValuesUse default settings

Use default settings:
rhoFluid:
Hydraulic Fluid
Properties

Hydraulics > Reference
Components

1

K:
nuFluid: 0.000018

Fixed Flow Rate

1

Hydraulics > Sources

Use default settings

Hydraulic
Cylinder1Hydraulics > Actuators

Use default settings

Mass

1

1-D Mechanical >Use default settings
Translational > Common

Translational
Fixed

1

1-D Mechanical >Use default settings
Translational > Common

Note: The Hydraulic cylinder has a cross-sectional area A ofRate has a flow Q of

, while the Fixed Flow.

The cylinder pushes the sliding mass at a speed of==This is confirmed by running the simulation and probing the speed of the sliding mass.

6.8 Tutorial 8: Modeling Hydraulic Systems • 225

Simulating Translational Motion with a Fixed Pressure Source
Replace the Fixed Flow Rate with the Fixed Pressure Source component shown in
Figure 6.18 and Table 6.13. The following model converts flow from a fixed pressuresource to translational motion.

Figure 6.18: Translational Motion with Fixed Pressure Source226 • 6 MapleSim Tutorials

Table 6.13: Translational Motion with a Fixed Pressure Source
Component
Fixed Pressure
SourceSymbolLibrary Location

Hydraulics > Sources

Value

Use default settings

The force on the Sliding Mass is equal to the cross-sectional area of the hydraulic cylinder
A multiplied by the pressure P of the hydraulic fluid.
==

The acceleration of the Sliding Mass is given by:==

Therefore,

By probing the acceleration, speed, and displacement of the Sliding Mass, these values are
confirmed with the results in Figure 6.19.

6.8 Tutorial 8: Modeling Hydraulic Systems • 227

Figure 6.19: Fixed Pressure Source Results

Overview of Actuating Multibody Systems with Hydraulic Components
In the following model, connect the 1-D translational port on the hydraulic cylinder to the
1-D translational port on the multibody prismatic joint using a translation fixed flange anda rigid body mass from Table 6.14. Use the default settings for each component.

Figure 6.20: Translational Fixed Flange Hydraulic component

228 • 6 MapleSim Tutorials

Similarly in the following model, connect the 1-D rotational port on the hydraulic motor to
the 1-D rotational port on the multibody revolute joint using a rotational fixed flange and arigid body mass from Table 6.14. Use the default settings for each component.

Figure 6.21: Rotational Fixed Flange Hydraulic component
Table 6.14: Actuating Multibody Components
Component

SymbolLibrary Location

Fixed Flow Rate

Hydraulics > Sources

Rotational Fixed Flange

1-D Mechanical > Rotational > Common

Translational Fixed Flange

1-D Mechanical > Translational > Common

Tank

Hydraulics > Reference Components

Hydraulic Cylinder

Hydraulics > Actuators

6.8 Tutorial 8: Modeling Hydraulic Systems • 229

Component

SymbolLibrary Location

Hydraulic Motor

Hydraulics > Actuators

Prismatic

Multibody > Joints and Motions

Rigid Body Frame

Multibody > Bodies and Frames

Rigid Body

Multibody > Bodies and Frames

Revolute

Multibody > Joints and Motions

Fixed Frame

Multibody > Bodies and Frames

Pascal's Principle
Pascal's Principle states that pressure applied to a closed hydraulic system is transmitted
everywhere equally. This principle shows that an applied force can be amplified to moveloads that would otherwise not be possible.
The model in Figure 6.22 demonstrates a simple example of Pascal's Principle. A 1 N force(acting on a 0.1
hydraulic cylinder) transmits hydraulic pressure to a 1
hydrauliccylinder, which lifts a 1kg load vertically. Normally, a 9.81 N force maintains the heightof a 1 kg force, but this simple hydraulic system multiplies the magnitude of a 1 N load bya factor of 10 or.

230 • 6 MapleSim Tutorials

Figure 6.22: Pascal's Principle Example

Overview of Compressibility of Hydraulic Liquids
The compliant cylinder and constant volume chamber components (Table 6.16) model thecompressibility of hydraulic liquids under high pressure. The compliant cylinder component
also models pipe wall compliance. Both have to be attached to a node between pipes or inertias as shown in Figure 6.23.

Figure 6.23: Hydraulic Liquids Compressibility
Table 6.15: Hydraulic Liquids Compressibility Components
Component

SymbolLibrary Location

Value6.8 Tutorial 8: Modeling Hydraulic Systems • 231

Signal Pressure

Hydraulics > Sources

Use default settings

Tank

Hydraulics > Reference
Components

Use default settings

LinearResistance

Hydraulics > Restrictions

Use default settings

Table 6.16: Confined Hydraulic System Components
Component

Quantity

SymbolLibrary Location

Value

Compliant
Cylinder1Hydraulics > Chambers Use default settings

Constant
Volume1Hydraulics > Chambers Use default settings

Overview of Fluid Inertia Models
The Fluid Inertia component models the inertia of liquid accelerating or decelerating in apipe and is analogous to mechanical inertia. Fluid Inertia can be significant for large diameter
pipes and when the acceleration/deceleration is large. This component is useful whenmodeling water hammer.
Table 6.17: Fluid Inertia
Component

Quantity

Fluid Inertia

1

SymbolLibrary Location
Hydraulics >Restrictions

System without Fluid Inertia
Figure 6.24 shows a system without fluid inertia.

Value
Use default settings

232 • 6 MapleSim Tutorials

Figure 6.24: System without Fluid Inertia

System with Fluid Inertia
Figure 6.24 shows a system with fluid inertia.

Figure 6.25: System with Fluid Inertia

Figure 6.26 shows typical system flow rates with (green) and without (red) fluid inertia.
Introducing fluid inertia adds a lag into the system.

6.8 Tutorial 8: Modeling Hydraulic Systems • 233

Figure 6.26: System with and without Fluid Inertia

Overview of Water Hammer Models
Water hammer occurs when a valve suddenly stops (or significantly restricts) flow in a pipe,
resulting in a pressure surge due to a momentum change in the fluid inertia. This pressure
surge bounces off the closed valve and travels up and down the pipe, potentially causing
significant damage to the entire pipe. Water hammer is traditionally modeled by the numerical solution of the following equations.

Where:
V(x,t) is the pipe velocity
P(x,t) is the pipe pressureρ is the liquid density
D is the pipe diameter234 • 6 MapleSim Tutorials

t is the pipe wall thickness
K is the liquid bulk modulus
E is Young’s modulus for the pipe
is the friction factor
These equations (with the appropriate boundary and initial conditions) are typically solved
numerically, requiring custom code to solve the equations using the method of characteristics.
Example: Water Hammer
Another method of simulating water hammer involves building a lumped parameter pipelinemodel. The pipeline model includes effects such as flow inertia, flow resistance (throughpipe friction), pipe compliance, and fluid compressibility.
The following figure shows a discretized pipeline with inertial and resistive properties, initially pressurized at one end to create flow. After two seconds, a valve at the other end isclosed, resulting in a pressure surge.

Figure 6.27: Water Hammer

Each subsystem consists of a compliant cylinder, a pipe, and a fluid inertia component asshown in Figure 6.28. A pipeline (of total length L and volume V) with N segments has
pipes, each with a length,

6.8 Tutorial 8: Modeling Hydraulic Systems • 235

N+1 fluid inertia components, each with a length,

N constant volume chambers, each with a volume,Figure 6.28: Discretized Pipeline Segment

To build the water hammer model:
1. Build the model with the components and connections shown in Figure 6.27 andFigure 6.28.
2. Configure the Fluid Properties component with the values specified in Table 6.18.
Table 6.18: Fluid Properties Values
ParameterName
rhoFluid
K
nuFluid

SymbolDescription

Value

Fluid density

1000 kg m-3

Fluid bulk modulus

200 106 Pa

Fluid kinematic viscosity

3. Configure the parameter block with the parameters and values shown in Table 6.19.

236 • 6 MapleSim Tutorials

Table 6.19: Water Hammer Parameters
Parameter Name
Description
Number of pipe segments
N
Pipe hydraulic diameter (D)Dia
Pipe Length
Len
Pipe Young's modulus (E)Emefthickness

Value
20
0.1 m
25 m
70 109 Pa
0.0001 m
0.001 mPipe internal roughness
Pipe wall thickness (t)4. For the Fixed Pressure component (FP2 in Figure 6.27), set the pressure (P) to 500kPa.
5. Configure the Circular Pipe components in Main and the HydraulicPipeline sharedsubsystem with the following settings.
Parameter
Name
D
L

Setting
Dia

ReL

ef
2000

ReT

4000

6. Configure the Fluid Inertia components in Main and the HydraulicPipeline sharedsubsystem with the following settings.
Parameter
Name
A

SettingL
rhoFluid

7. Configure the Compliant Cylinder component in the HydraulicPipeline shared subsystem with the following settings.

6.8 Tutorial 8: Modeling Hydraulic Systems • 237

Parameter
Name
α
k
L

Setting

DDo

Dia
Dia + 2*thickness

Em

Em

0
1.4

8. For the First Order component, under the Properties tab (0.01.

), set T to 0.01s and y0 to

9. Configure the Step component with the following settings.
• For height, enter -0.009999.
• For offset, enter 0.01.
• For T0, enter 2s.
10. Under the Settings tab, configure the following Simulation parameters.
• For td, enter 3s.
• For Solver Type, select Variable.
• For Solver, select Rosenbrock (stiff).
Figure 6.29 plots the pressure and flow rate at the end of a pipe for a valve that rapidly
closes after 2 seconds.

238 • 6 MapleSim Tutorials

Figure 6.29: Water Hammer Pressure Flow Rate

The maximum pressure is about 5 x 106Pa, with the liquid reaching a flow rate of 0.099
The maximum pressure can also be calculated using the Joukowsky equation,.

6.8 Tutorial 8: Modeling Hydraulic Systems • 239

If you substitute the parameters from Table 6.18 and Table 6.19 into the preceding equations,and then assume:∆Q=0.099
you get∆P ≈ 5×106PaThis result agrees with the MapleSim model.
Example: Attenuating Water Hammer with an Accumulator
A hydraulic accumulator is a reservoir, often located near a valve, that stores non-compressible hydraulic fluid under pressure. An accumulator acts as a safety valve by allowing fluid
to enter the reservoir when the pressure increases beyond a certain threshold value. Thisaction attenuates the magnitude and frequency of the pressure waves.
MapleSim does not have a built-in accumulator block, but this functionality is easily modeledwith the Custom Component template using the following equations. For a complete description on how to create custom components, see Creating Custom Modeling
Components (page 73).

240 • 6 MapleSim Tutorials

Table 6.20: Accumulator Parameters Custom Component
Description
Vmax
ppr
Pmax

Values0.1 m
1000003000000

Ks
Vpr

m
0

The following figure shows the same pipeline with a pressure accumulator. After two
seconds, a valve at the other end is closed, resulting in a pressure surge. Figure 6.30 shows
the pressure surge at the end of a pipeline with an accumulator.

6.8 Tutorial 8: Modeling Hydraulic Systems • 241

Figure 6.30: Pressure Surge with an Accumulator

Overview of Hydraulic Custom Components
Two examples of hydraulic custom components are centrifugal pumps and vertical pipes.
For a complete description on how to create custom components, see Creating Custom
Modeling Components (page 73).
Centrifugal Pumps
Typically, manufacturers provide head flow rate charts for centrifugal pumps, as shown in
Figure 6.31.

242 • 6 MapleSim Tutorials

Figure 6.31: Head Flow Rate

Data from these charts is easily implemented into a custom component.
To implement chart data:
1. Read several sets of head flow rate points from the plot.
2. Fit these data points to a polynomial using the Maple curve-fitting functionality.
3. Implement the polynomial into a custom component. Figure 6.32, for example, shows
the custom component equations for a centrifugal pump (including the best-fit parameters).
Note: Since the equation is a polynomial, several solutions may exist.

Figure 6.32: Centrifugal Pump Custom Component Equations

Note: Assigning the value rhoFluid to the Density parameter sets the density to be the value
defined in the Hydraulic Fluid Properties component.
Vertical Pipes
Since gravity head is usually insignificant in mechanical-hydraulic systems, the base pipe
component in MapleSim does not model vertical pipe travel. For low-pressure systems,
gravity head can be significant. Figure 6.33 shows the custom component equations tosimulate gravity head.

6.8 Tutorial 8: Modeling Hydraulic Systems • 243

Figure 6.33: Gravity Head Custom Component Equations

244 • 6 MapleSim Tutorials

7 Reference: MapleSim Keyboard Shortcuts
Table 7.1: Operations on a File
Task
Create a new modelOpen an existing model

Windows and Linux
Ctrl + N
Ctrl + O
Ctrl + F4 (Windows)

Mac
Command + N
Command + O
Command + W

Close the active document
Save the model as an .msim file
Load Maple worksheet
Print
Print Layout Mode
Page Setup

Ctrl + W (Linux)
Ctrl + S
F10
Ctrl + P
Ctrl + Shift + L
Ctrl + Shift + P

Command + S
F10Command + P
Command + Shift + L
Command + Shift + P

Table 7.2: Building a Model in the Block Diagram View
Task
Windows and Linux
Cancel operation while drawing a
Escconnection
Rotate the selected modeling
Ctrl + R
component 90 degrees clockwise
Rotate the selected modeling
Ctrl + L
component 90 degrees
counter-clockwise
Flip the selected modeling component
Ctrl + H
horizontally
Flip the selected modeling component
Ctrl + F
verticallyGroup the selected modeling
Ctrl + G
components into a subsystem
Ctrl + D
Reroute the selected connections
Reroute all connections
Ctrl + A, Ctrl + D

MacEscCommand + R
Command + L
Command + K
Command + F
Command + G
Command + D
Command + A,
Command + D

Table 7.3: Adding Annotations to a Model
Task
Move selected objects to the backMove selected objects backward
Move selected objects forward

Windows and Linux
Ctrl + Shift + B
Ctrl + Alt + B
Ctrl + Alt + F

245

Mac
Ctrl + Shift + B
Ctrl + Alt + B
Ctrl + Alt + F

246 • 7 Reference: MapleSim Keyboard Shortcuts

Task
Move selected objects to the front

Windows and Linux
Ctrl + Shift + F

MacCtrl + Shift + F

Table 7.4: Browsing a Model in the Block Diagram View
Task
View the selected modelingcomponent or subsystem in detailView the parent level of the current
subsystem
Return to Main
Navigate to parent component

Windows and Linux
Ctrl + M, or Ctrl + Down
Arrow

Mac
Command + M, or Command+ Down Arrow

Ctrl + Up Arrow

Command + Up Arrow

Home
Home
Ctrl + Up Arrow
Command + Up Arrow
Ctrl + numeric keypad plus Command + numeric keypadplus key, or
key, or

Zoom into the model workspace
Ctrl and move the mousewheel forward
Ctrl + numeric keypadminus key, orCommand and move the mousewheel forward
Command + numeric keypadminus key, orCtrl and move the mousewheel backward

Command and move the mousewheel backward

Zoom out from the model workspace

Scale the model diagram to fit in the
Ctrl + T
model workspace
Reset zoom factor to the default zoom
Ctrl + 0 (zero)factor (100%)

Command + T
Command + 0 (zero)• 247

Table 7.5: Browsing a Model in the 3-D View
Task
Connect ports
Delete the currently selected item
Fit scene
Select mode
Pan mode
Zoom mode
Rotate mode

Windows and LinuxMac
Ctrl + Shift + C
Command + Shift + C
Backspace or Delete
Delete
V
V
Esc
Esc
F2
F2
F3
F3
F4
F4
Left mouse button click andMouse click and dragMove the camera around a 3-D model dragor Command + mouse clickin the perspective view
or Ctrl + left mouse buttonand drag
click and dragRight mouse button click and Right mouse button click and
drag
drag
Panning a 3-D modelor Shift + left mouse button or
click and dragShift + mouse click and dragZoom into or out from the 3-D
workspace

Mouse scroll wheel forward
Mouse wheel scroll forward(zoom in), or backward(zoom in), or backward (zoom(zoom out)
out)
or middle mouse click andor middle mouse click and dragdrag
or Alt + mouse click and drag,or Alt + left mouse button
or mouse wheel
click and drag
X
X
Y
Y

Z

Z

Shift + X
Shift + Y

Shift + X
Shift + Y

Shift + Z

Shift + Z

R or Ctrl + 4

R or Command + 4

Change perspective view to lookdown the negative X, Y, or Z axis

Change perspective view to lookdown the positive X, Y, or Z axis
Change perspective view to look at
the right side of the scene248 • 7 Reference: MapleSim Keyboard Shortcuts

Task
Windows and Linux
Change perspective view to look at
L or Ctrl + 3
the left side of the scene
Change perspective view to look at
T or Ctrl + 5
the top side of the scene
Change perspective view to look at
M or Ctrl + 6
the bottom side of the scene
Change perspective view to look at
F or Ctrl + 1
the Front side of the scene
Change perspective view to look at
B or Ctrl + 2
the Back side of the scene
Save the current camera pose. (OnlyS
one camera pose can be saved.)
Return to the last saved camera pose. H
Shift + F5
Refresh 3-D viewMac
L or Command + 3
T or Command + 5
M or Command + 6
F or Command + 1
B or Command + 2
SH
Shift + F5

Table 7.6: Simulating a Model
Task
Run simulation
View Simulation Results.

Windows and Linux
F5
F6

Mac
F5
F6

If the Simulation Results is currently
in focus, bring MapleSim window into
focus.
View Rerun Simulation Window.
Shift + F6

Shift + F6

If the Rerun Simulation Window iscurrently in focus, bring MapleSim
window into focus.
View 3-D Workspace.

F7

F7

If the 3-D Workspace is currently infocus, bring MapleSim window into
focus.
View Apps Manager.
F8

F8

If the Apps Manager is currently infocus, bring MapleSim window into
focus.
Toggle enable/disable selected
Ctrl + E
components or connections to exclude
selection from the next simulation

Command + E• 249

Table 7.7: Navigating the Console Pane
Task
Expands a section
Collapses a section
Moves cursor to the following or
previous section

Windows and Linux
Right Arrow
Left Arrow
Up or Down ArrowMac
Right Arrow
Left Arrow
Up or Down Arrow

Table 7.8: Modifying the Plot Window Layout
Task
Windows and Linux
Shift + T
Tile plot windows
Shift + C
Cascade plot windows
Fit plots in plot window.
Automatically adjust row heights to
Shift + F
fit all plots in a plot window in theavailable vertical space.

Mac
Shift + T
Shift + C
Shift + F

Table 7.9: Editing a Modelica Custom Component
Task
View the Modelica Code Editor.

Windows and LinuxIf the Modelica Code Editor isF9currently in focus, bring MapleSim
window into focus.
Ctrl + N
New Modelica custom component
Ctrl + S
Save Modelica custom component
Ctrl + F
Find and replace
Ctrl + G
Go to a line
Autocomplete on part of a keyword
Ctrl + Spaceor component name
Insert a Modelica syntax templateafter typing a typing a term like block,
if, ife, or for. See Using MapleSim >Building a Model > Modelica
Ctrl + Shift + Space
Custom Components > Modelica
Code Editor > Syntax Templates for
a complete list of terms.
Toggle left navigation pane (ifCtrl + Tab
unlocked)Mac

F9Command + N
Command + S
Command + F
Command + G
Command + SpaceCommand + Shift + SpaceCommand + Tab

250 • 7 Reference: MapleSim Keyboard Shortcuts

Table 7.10: Miscellaneous
Task
Perform a search
Open Help window
Compare models

Windows and Linux
Alt + SF1
F12Mac
Alt + SF1
F12

For keyboard shortcuts for 2-D math notation, refer to Using MapleSim > Building a
Model > Annotating a Model > Key Combinations for 2-D Math Notation.

Glossary
Term

Description
Formatting option that allows you to enter mathematical
2-D math notation
text, such as superscripts, subscripts, and Greek characters.
The area of the MapleSim window in which you can build
3-D workspaceand edit a 3-D model.
Shapes that you can display in a 3-D model to create arealistic representation of a system model. Attached shapes
Attached shapes
include cylinders, trace lines, and CAD geometry that you
import from another file.
CameraThe point of view from which a 3-D scene is viewed.
The process by which a camera follows the movement ofa target 3-D component that you select. The target
Camera tracking
component is centered in the 3-D playback window during
an animation.
A user-defined component that you can create and add toCustom componenta MapleSim model using the Custom Component Template.
A collection of modeling components and subsystems that
Custom library
can be saved in a user-defined palette and used in a future
MapleSim session.
Configurable graphical controls, buttons, meters, and otherinteractive components that you can add to a Maple standard
Embedded component
worksheet to analyze, manipulate, and visualize equations
and Maple commands.
Default cylinders and spheres that are displayed in a 3-D
Implicit geometry
model to represent modeling components.
A collection of routines or commands that can be used in
Maple. Most Maple packages provide a set of commands
Maple package
for a particular mathematical or scientific domain, or fieldof study.
The default collection of domain-specific modelingcomponents included in MapleSim. These modeling
MapleSim component librarycomponents can be found in the gray palettes in the
Libraries tab.
The area of the MapleSim window in which you can build
Model workspaceand edit a model in a block diagram view.
A type of 3-D view that uses parallel projection and displays
lines in the view plane at their "true length." In MapleSim,
Orthographic view
you can view a model from front, top, and side orthographic
views.
A 3-D view that allows you to examine and browse a model
Perspective view
from any direction in 3-D space.

251

252 • Glossary

Term
Probe

Shared subsystem

Standalone subsystem
Subsystem
Subsystem definition

Description
The tool used to identify quantities of interest in order tosimulate a MapleSim model.
A subsystem copy that shares the same configuration asother subsystems. All shared subsystems are linked to aparticular subsystem definition, which defines theconfiguration.
A subsystem that is not linked to a subsystem definitionand can be edited and manipulated independent of othersubsystems in a model.
A collection of modeling components grouped in a single
block.
A subsystem block that defines the configuration for a seriesof shared subsystems.

IndexSymbols
2-D math notation, 64
3-D animation, 128
enable, 110
3-D display controls
3-D manipulators, 118
adding a trace, 115
attached shapes, 115, 120
implicit geometry, 114
initial conditions, 127
3-D model construction, 117
3-D playback window, 109
3-D view navigation, 112
3-D views
orthographic, 112
perspective, 112
3-D workspace, 111
axis designation, 112A
acausal mapping, 81
acausal modeling, 2, 5, 8
across variables, 3
custom components, 82
adding a probe, 12advanced simulation settings, 97
alpha, 97
analyzing models
using the API, 149with apps and templates, 133
animating the 3-D model, 128
annotations, 62
API, 149
apps
code generation, 138
equation extraction, 135
parameter optimization, 136apps and templates
analyzing your model with, 133

arrow convention, 67, 69
attaching files to a model, 59
attachments palette, 59

BBaumgarte, 97
alpha, 97
beta, 97
best practices, 71
building 1-D translational models, 69
building electrical models, 67
building hydraulic models, 71
building multibody models, 70
enforcing initial conditions, 72
laying out and creating subsystems, 66
simulating and visualizing a model, 129
beta, 97
building a model
adding and moving objects in the 3-D
workspace, 121
assembling a 3-D Model, 119
displaying attached shapes as you builda 3-D Model, 120
moving objects in the 3-D workspace,
118
using do not enforce constraints, 119C
CAD geometry, 120
causal modeling, 2, 5, 8
code generation
C code, 138
initialization, 140
options, 142
subsystem, 139
compile optimized, 99
compiler, 99
connection lines, 24colors, 24
connection ports, 24
conserved quantity flow
arrow convention, 16, 70, 94

253

254 • Index

constraint handling options, 143constraint projection, 97, 143
during event iterations, 98
iterations, 97
tolerance, 98
constraint stabilization, 97
construct mode, 117
custom components
defining equations, 86
defining ports, 87
Editing, 85
external C code/DLL, 147, 207
modeling from extrapolated data, 198
template, 201
understanding custom components, 75
custom libraries, 60
custom plot window, 103

D
DAE variables, 209
data sets
creating in Maple, 65
generating for model, 59
debugging console, 40
diagnostic messages, 7, 67
differential algebraic equations, 1
DLL
custom component, 147
drawing, 62
DynamicSystems package, 149E
embedded components, 149
equationsapp, 211
retrieving, 135
error tolerance, 96
event hysteresis, 98
event iterations, 98
event projection, 98
ExamplesAdding Attached Shapes to a Double
Pendulum Model, 115
Adding Text Annotation to a Model, 63
Assigning a Subsystem Parameter to a
Shared Subsystem, 45
Building a Double Pendulum Model inthe 3-D Workspace, 121
Copying and Pasting a Standalone Subsystem, 41
Creating a Custom Library from an Existing Model, 60
Creating a Data Set in Maple, 65Creating a Parameter Override, 55
creating a subsystem, 29
Creating and Using a Parameter Block,47
Defining and Assigning a Global Parameter, 43
Editing Shared Subsystems that are
Linked to the Same Subsystem Definition,
34
Nonlinear Spring-Damper Custom Component, 89
Plotting Multiple Quantities in Individual
Graphs, 104
Plotting One Quantity Versus Another,
106
Removing the Link between a Shared
Subsystem and Its Subsystem Definition,
38
Resolving Warning Messages in the Debugging Console, 40
external C code/DLL
custom component, 147, 207

F
fixed time step, 95
flow direction, 3Gglobal parameters, 155, 163
gridIndex • 255

3-D grid, 120
using CAD geometry, 120

Hhelp pane, 20
hydraulic systems, 243
basic hydraulic equations, 216
basic hydraulic library components, 214,
218
Bernoulli equation, 216
compressibility, 230
custom accumulator component, 239
custom component, 241
Darcy equation, 216
fluid inertia, 231
friction factor, 217
Joukowsky equation, 238
multibody hydraulic, 227
multidomain, 222
Pascal's principle, 229
spool valve, 221translational motion, 225
water hammer, 233

I
implicit geometry, 114
index 1 error control, 98
index 1 tolerance, 98
initial conditions, 54
best practices for enforcing initial conditions, 72
overrides, 58
specifying, 27
specifying how initial conditions are enforced, 27
initial hysteresis, 98
initialization, 140interpolation tables, 166

J
Jacobian, 97

K
keyboard shortcuts, 245
kinematic constraints, 119Llatest resultsfrom simulation, 101
linear systems
analyzing, 135
linearization, 135
LinkModel, 149M
MapleSim component library, 5, 8, 19
MapleSim model
embedded components, 149
MapleSim window, 7
minimize events, 99
model tree, 21
model workspace, 6Modelica, 91
Modelica custom component, 75
modeling components
connecting, 10
modelsbuilding, 8
multibody
best practices for building multibody
models, 70
settings, 109
multibody parameter values, 110P
palettes, 7, 19
parameter blockfor global parameters, 43
for subsystem parameters, 46
parameter optimization, 136
parameter override, 55
parameters
advanced parameter settings, 45, 53
advanced variable settings, 53

256 • Index

defining, 43
global parameters, 43parameter sets, 52, 100
parameter values, 11, 25
subsystem parameters, 45
physical components, 83
physical models
analyzing, 131
navigating, 23
plot events, 99
plot points, 96
plot windows, 107
plots
add second variable to graph, 104
set x-axis variable, 106
port and parameter management, 141probes, 93
adding, 12
arrow convention, 16, 70, 94
probes palette, 99
progress information messages, 101
projection, 97
projection iterations, 97
projection tolerance, 98

Rrerun simulation, 94, 157

S
scaling, 98
settings
advanced simulation, 97
simulation, 95
sign convention, 3
signal flow, 81
simulating, 99
simulation
duration time, 95
initial conditions, 102settings, 95
start time, 97
simulation graphs, 107

simulation parameters
compiler, 99
settings, 94
simulation results
clear message console, 101
comparing, 101
exporting graph data, 103
managing, 101
progress messages, 100
snapshots, 102
storing, 101
viewing, 101
snapshots, 102
using, 97
solver, 96
solver diagnostics, 99
solver type, 95
specifying component properties, 11
standalone subsystem, 39
state, 102
step size, 96
stored resultsfrom simulation, 101
subsystem(s)adding a port, 161
adding multiple copies of a subsystem toa model, 31
adding subsystem definitions and sharedsubsystems to a model, 32
code generation, 139
creating and managing, 28, 154
definition, 31
editing multiple instances, 34
linking, 32
parameters, 45
shared, 31
standalone, 39Ttemplates, 133
custom component, 86
understanding custom components, 76
through variables, 3Index • 257

arrow convention, 16, 70, 94
custom components, 82
time
simulation duration, 95
simulation end, 97
simulation start, 97
time step, 95
trace lines, 109, 115
example, 115, 117tutorials, 151
Basic Tutorial: Modeling an RLC Circuitand DC Motor, 17U
units
specifying parameter units, 26Vvariable scaling, 98
variable time step, 95
visualization, 109transparency, 109
visualization parameters
settings, 109

258 • Index