4 Simulating and Visualizing a Model - MapleSim Help

Home : Support : Online Help : MapleSim : User's Guide : 4 Simulating and Visualizing a Model

4 Simulating and Visualizing a Model

In this chapter:

 •

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 to Modelica.   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 system or 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.
 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 with other 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 handling process begins. Based on the solver type you chose, a sophisticated DAE solver numerically integrates 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 that for 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 time they occur during the integration.

Simulation Results

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

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 the dsolve/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 with connection ports.

If you add a probe to measure a through variable, an arrow appears to indicate the direction of the positive flow in the Model Workspace.

You can specify the simulation duration, the type of solver to use, and other parameter values 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.

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, and then select one of the Constant Acceleration, Sign Convention, or Arrow Convention examples.

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 ( ) on the right of the Parameters pane.

For a description of the Multibody and 3-D Visualization settings see 3-D Visualization and Multibody Settings.

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 listing and description of the parameters available in the Simulation settings section.

Table 4.1: Simulation Settings

Parameter

Default

Description

${t}_{d}$

10s

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

Note: The duration time is not the same as the end time of your simulation. The end time for the simulation is given by td + ts, where ts is the start time for the simulation (see Table 4.2).

Solver Type

Variable

The type of solver to use for the simulation.

 • Variable: use a variable time step to maintain error tolerances.
 • 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.

Solver

Variable: CK45 (semi-stiff)

Fixed: Euler

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 (Rosenbrock method).

If your model is complex, you may want to use a stiff DAE solver to reduce the time required to simulate a model.

The following choices are available when Solver Type is set to Fixed.

 • Euler: use a forward Euler solver.
 • Implicit Euler: use an implicit Euler solver (suitable for stiff 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.

${\mathrm{ε}}_{\mathrm{abs}}$

$0.00001$

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.

${\epsilon }_{\mathrm{rel}}$

$0.00001$

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.

Step size

0.001

Uniform size of the sampling periods if you are using a fixed-step solver to run the simulation. You can specify a floating-point value for this option.

Plot Points

2000

Minimum number of points to be plotted in a simulation. The data points are distributed evenly according to the simulation 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 used during the simulation may differ from the number of points in the simulation graph.

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 specific to the solver type (variable or fixed) selected in the Simulation settings. See Table 4.2 for a listing and description of the parameters available in the Advanced Simulation settings.

Parameter

Default

Solver Type

Description

${t}_{s}$

0

All

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

Note: The simulation start time affects the end time of your simulation, but not the duration time for the simulation, td. The end time for the simulation is given by td + ts.

Use Snapshot

None

All

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 your model and replace them with the state your model was in at the time of the snapshot.

Jacobian

Symbolic

All

Choose between a symbolic or numeric approximation to the system Jacobian. A symbolic formulation results in faster and more accurate simulations but can take longer to formulate.

Note: A numeric formulation can only be used with stiff solvers (Rosenbrock or Implicit Euler).

Baumgarte

All

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.

Projection

All

Apply constraint projection to your model. Select to project back the solution found at each step of the simulation 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.

Projection Iterations

50

All

The maximum number of constraint projection iterations.

Note: This parameter is only available when Projection is selected.

Projection Tolerance

0.00001

Fixed

The tolerance value at which the projection iterations are terminated. You can specify any positive floating-point value.

Event Projection

Fixed

Select to have constraint projection occur during event iterations, but with slower integration results. Not selecting, may cause the simulation to fail if the event changes the solution to the point of not allowing the application of constraint projection at the next step.

Event Iterations

100

All

The maximum number of event iterations allowed before the integrator throws an error. You can specify any positive integer value.

Event Hysteresis

1. x 10-7

Fixed

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.

Initial Hysteresis

1. x 10-10

Variable

The width of the event hysteresis for all event triggers at the start of the simulation. You can specify a floating-point value greater than or equal to zero.

Note: Used by variable step solvers.

Index 1 Error Control

Variable

When selected, error control is applied to all algebraic variables. By default, error control is only applied to algebraic variables that trigger events, are plotted, or are outputs of functions.

Index 1 Tolerance

1

Variable

Controls the relative error on algebraic variables compared to differential variables. For example, a value of 10 means that algebraic variables can have 10 times the error of differential variables.

Minimum Step Size

0

Variable

Set the minimum step size.  This option should be used with caution, as if the solver is unable to achieve the requested error tolerance with this minimum then it will take the step anyway.

Maximum Step Size

0 / no limit

Variable

Set the maximum step size.  (0 indicates no limit)

Scaling

Minimum

Variable

Specifies the method of variable scaling to apply to the system. The available choices are:

 • None: do not apply scaling
 • Minimum: use the minimum nominal value
 • Maximum: use the maximum nominal value
 • Geometric: use the geometric mean of the nominal values

Minimize Events

Variable

This option specifies whether to use heuristics to reduce the number of events encountered during your simulation. When selected, the mapping of piecewise transitions into events does not occur.

Plot Events

All

Specifies whether to include extra plot points at event points during the simulation.

Solver Diagnostics

All

When selected, the simulation generates diagnostics describing constraint iterations, constraint residual, event iterations, and step size, and plots them after the simulation 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.

Compiler

Variable

Specifies whether a native C compiler is used during the simulation. When this option is selected, Maple procedures generated by the simulation engine are translated to C code, which is compiled by an external C compiler.

If your model is complex, you may want to select this option to reduce the time required to run a simulation.

Compile Optimized

All

Optimize the code during compilation. If this parameter is not selected, compile time will be reduced but your simulation will take longer to run.

Editing Probe Values

Click the Model Tree tab ( ), and then select Probes from the list. This lists all of the probes 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 beside the probe name; otherwise, the subsystem for the attached probe appears beside the probe 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, and view 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.

 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 with another 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 by clicking 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.

 Figure 4.2: Simulation Results Progress Messages

Optionally, before running a simulation, you can specify the amount of detail in progress messages by clicking Console Output ( ) at the bottom of the MapleSim window and selecting 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, and export 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 your model 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 the Latest Results entry, select Save from the context menu, and then provide a name for the stored result. You can save simulation results to compare and refer to multiple graphs generated during the current MapleSim session.   If 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 particular time 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 tooltip of the resulting entry in the Stored Results palette.

 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 Help system.

4.5 Customizing Plot Window Configurations

By default, probed quantities are plotted in separate simulation graphs in a plot window called Probe Plots. In each graph, the quantity values are plotted along the $y$-axis versus the simulation time values along the $x$-axis.

You can optionally create custom plot window configurations.  You might want to create a custom plot window if, for example, you want to compare multiple quantities in the same graph, 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 Help system.

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 the Stored Results palette and selecting Show Probe Plots.

If you want to work with your simulation data in another application, you can export your results to a Microsoft Excel (.xls) or comma-separated value (.csv) file.  For details, refer to Exporting Simulation Graph Data.

In the following examples, you will create custom plot window configurations.

Example: Plotting Multiple Quantities in Individual Graphs

In this example, you will view the Probe Plots and then create a plot window configuration in 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 select the 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

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 just two 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 Plot Windows 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 ( ).  The plot now shows two curves, Output1.a and Output2.a.
 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 both curves.
 9 In the Plot Windows palette, under Acceleration and Angle Comparison, right-click on 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-click on 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.

 Figure 4.6: Custom Plot Window

Example: Plotting One Quantity versus Another

In this example, you will create a custom plot window to plot the X and Y position of each of 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 select the 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 ( ), label this probe FirstLink, and then select Length[1] and Length[2].
 6 Add another probe that measures the Length[1] and Length[2] quantities to the right port 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 the Plot Windows palette, double-click on the names of the other plots to hide them from 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 Plot Windows palette and select Show All Plots.
 12 In the Plot Windows palette, under X versus Y, right-click on FirstLink.r_0[2] (the name 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.

 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

In MapleSim, the 3-D visualization environment allows you to build and analyze 3-D graphical 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 your simulation results. You can build 3-D models by dragging and connecting objects in the 3-D 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 are automatically 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 of the 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. These shapes 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, for instance 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 3-D 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 and non-transparent in the 3-D Playback Window.

3-D Visualization and Multibody Settings

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

To access the simulation settings, click Multibody Settings tab ( ) on the right of the Parameters pane.

 Animation Settings Under Animation, ensure the 3-D Animation check box is enabled if you want to see an animation 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 Default Description Gravity 9.81 The acceleration due to gravity at the surface of the Earth. The default units are in $\frac{m}{{s}^{2}}$. Gravity vector $\left[0,-1,0\right]$ 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 Default Description Enable Translational Snapping When selected, components are positioned at the closest location in 3-D space based on the translation snap delta value. Translation Snap Delta 1 Specifies the translation snap delta spacing. Enable Rotational Snapping When selected, components are positioned at the closest location in 3-D space based on the rotation snap delta value. Rotation Snap Delta Pi/2 Specifies the rotational snap delta spacing. Perspective Grid Extent 10 Specifies the size of the grid drawn in the perspective view. The grid extends this distance in both directions on the horizontal plane. Grid Spacing 1 Specifies the space between grid lines. Base Radius 0.02 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. Enable View Change Animations When enabled, a smooth transition occurs when switching between 3-D orthographic and perspective views and when using 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

Table 4.5: 3-D Workspace Controls

Component

Description

3-D Workspace

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 are designated by color:

 X - red   Y - green   Z - blue

You can use the grid as a reference to determine the relative sizes and positions of elements in your 3-D model.

3-D Toolbar

Contains tools for hiding and displaying components in the 3-D Workspace, toggling between different modes, selecting camera navigation tools, and changing the 3-D model view.

Construct Mode Controls

Part of the 3-D toolbar, these are controls for building and 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 view or 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 the perspective 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.

 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 and distances in the view plane that is orthogonal to the camera direction; these views are useful for 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 from any direction around your model.

Tip: Before panning, zooming, or moving the camera around a large 3-D model, hover your mouse 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

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 gray color; implicit geometry that is assembled is drawn in a dark gray color, with the exception of joint objects, which are drawn in red.

Note: Components that you exclude from a simulation in the Model Workspace do not appear in the 3-D Workspace.

If you want to create a more realistic representation of your model, you can add shapes and lines called attached shapes to your model. To do so, you first add and connect attached shape 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 to represent the pendulum stem and bob pictorially. Also, a trace line—the curved line in the image—can be set to depict the locus of points that will be traced by a particular part of the model 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 the attached 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 ( ).

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 Model

In the following example, you will add cylinder shapes to represent the pendulum stem and a 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.

 1 From the Help menu, select Examples > Physical Domains > Multibody, and then select the 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 Geometry components.
 8 Connect the components as shown below.

 9 Select the first Cylindrical Geometry component (C1 in the previous figure) in the Model Workspace.
 10 In the Properties tab ( ) on the right side of the MapleSim window, change the radius of the cylinder to 0.2.
 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, select Examples > 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.

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 the same 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 these components 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 to move the object along the Z axis, the green arrow to move the object along the Y axis, and the red arrow to move the object along the X axis. You can also click and drag the sphere at 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 3-D 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 a model is moved in the 3-D Workspace, the initial conditions are updated for all of the other Rigid Body components that depend on the Rigid Body component that has its initial conditions set to Strictly Enforce.
 • 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 initial conditions 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 contain numeric 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 configuration of 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 3-D Workspace, assembled implicit geometry is drawn in a dark gray color, with the exception of joint objects, which are drawn in red. Note: You can only assemble 3-D models with a valid configuration and valid connection lines. 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 in the 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 in a 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 depicted in the 3-D Workspace for display purposes only.
 • 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, the joint 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 your model 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, the corresponding 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.

Example: Building and Animating a Double Pendulum Model in the 3-D Workspace

In this example, you will build and animate a double pendulum model. You will perform the 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 ( ), and arrange that window beside the main MapleSim window.
 3 Click Always-On-Top ( ). This keeps the Analysis window in focus as you work in the MapleSim window.
 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 gray square, 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.
 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 the object that you want to focus on and rotate your mouse wheel. When zooming with the mouse wheel, the location under the pointer remains in place, allowing you to zoom in on that location. To pan your model, hold the Shift key and drag your mouse pointer in the 3-D Workspace.

 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.

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 at the 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 the frames to which you can connect the line.
 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 frames of the Revolute joint, as well as the Fixed Frame to which it is connected.

 9 From the context menu, select R1.frame_b.
 10 Drag your mouse pointer to the end of the cylinder that represents the Rigid Body Frame and 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 Revolute joint.
 16 Connect frame_b of the second Revolute joint to frame_a of the third Rigid Body Frame.
 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 connected accordingly.

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 a parameter block, global parameter, or subsystem parameter will not allow the use of graphical 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 sphere that 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 and the manipulator for the joint appears.

 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 graph-shaped 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 mouse pointer 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 value that you want. In the Properties tab ( ), the q0 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 q0 parameter 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.

To animate the 3-D model:

 1 Simulate your model by clicking Run Simulation ( ) in the Main Toolbar. When the simulation 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 (for example 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 your model, results will appear only for the model sections that you did not exclude. This feature allows you to view simulation results generated by specific sections in your model and compare 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.