Contents Previous Next Index
2 Building a Model
In this chapter:
The MapleSim Component Library
Browsing a Model
Defining How Components Interact in a System
Specifying Component Properties
Creating and Managing Subsystems
Global and Subsystem Parameters
Attaching Files to a Model
Creating and Managing Custom Libraries
Annotating a Model
Entering Text in 2-D Math Notation
Creating a Data Set for an Interpolation Table Component
Best Practices: Building a Model
2.1 The MapleSim Component Library
The MapleSim component library contains hundreds of components that you can use to build 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.
Library
Description
Signal Blocks
Components to manipulate or generate input and output signals.
Electrical
Components to model electrical analog circuits, single phase and polyphase systems, and machines.
1-D Mechanical
Components to model 1-D translational and rotational systems.
Multibody
Components, including force, motion, and joint components, to model multibody mechanical systems.
Hydraulics
Components to model hydraulic systems, fluid power systems, cylinders and actuators.
Pneumatics
Components to model Ideal pneumatic systems with cylinders, directional control valves, orifices, and actuators.
Thermal
Components to model heat flow and heat transfer.
Magnetic
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 library structure 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.
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 and select Help from the context menu.
Search for the topic in the help search box in the main toolbar. Help topics related to your search 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, see Using 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 view hierarchical 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 and subsystem blocks that represent groups of components. You can also browse to sublevels in your model to view the contents of individual subsystems or components.
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 can represent 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 to open 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 of component or subsystem. Component and subsystem nodes are identified by their type followed by their name. Enter a term in Find to search for component types that match your term (the component's name is ignored in the search).
Components: This view organizes the model tree view according to the Name of each component or subsystem. Component and subsystem nodes are identified by their name followed 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 match your term. For more information about the parameters view (including how to find all references 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 with names 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
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 the Properties 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 the Using MapleSim > Building a Model > Navigating and Searching with the Model Tree section 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 in a 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.
Control
Keyboard Shortcut
Home
Return to the Main level of your model.
Ctrl+Up Arrow
Command+Up Arrow (Mac)
Navigate to the parent component.
Ctrl+Down Arrow
Command+Down Arrow (Mac)
Display the contents (or children) of the selected component.
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.
Domain
Line Color
Mechanical 1-D rotational
Black
Mechanical 1-D translational
Green
Mechanical multibody
Electrical analog
Blue
Electrical multiphase
Orange
Digital logic
Purple
Boolean signal
Pink
Causal signal
Navy blue
Integer signal
Red
Pneumatic
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 to manage 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 the Properties 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 your model. When you select a component in the Model Workspace, the configurable parameter values for that component appear in the Properties tab ( ) located on the right side of the MapleSim window.
Note: 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.
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 distinguish them 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 parameter fields 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 the International 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 perform conversions in dimensions such as time, temperature, velocity, pressure, and volume. In the following 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 Block
If 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.
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 with the other configurable parameter values for that component.
For example, the image below displays the initial position and initial velocity fields that you 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 select these options for initial condition parameters individually by clicking the buttons beside the applicable initial condition fields.
If 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 initial condition 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 the set of equations that describe the system. The solver initially computes a solution to the system 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 the initial condition field as a start value for the simulation. Similar to the guess option, the solver searches for a solution to the system of equations using the parameter value you entered 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.
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 Group
You 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 your model hierarchically by creating subsystems within other subsystems.
After you create a subsystem you will be able to assign parameters and variables to all components 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 and Creating Subsystems.
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
From the Help menu, select Examples > User's Guide Examples > Chapter 2, and then select the Simple DC Motor example.
Draw a box around the electrical components by dragging your mouse over them.
Figure 2.8: Creating a Subsystem
From the Edit menu, select Create Subsystem. Alternatively, right-click (Control-click, for Mac) the boxed area and select Create Subsystem.
In the dialog box, enter DC Motor.
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 the same 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.
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.
In this view, the broken line indicates the subsystem boundary. You can edit the connection lines 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, see Best Practices: Laying Out and Creating Subsystems.
Adding Multiple Copies of a Subsystem to a Model
If you plan to add multiple copies of a subsystem to a model and want all of the copies to have the same configuration, you can create a subsystem definition. A subsystem definition is the base subsystem that defines the attributes and configuration that you want a series of subsystems 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:
Build a DC motor subsystem with the desired configuration in the Model Workspace.
Use that subsystem configuration to create a subsystem definition and add it to the Components palette under the Local Components tab.
Add copies of the DC motor subsystem to your model using the subsystem definition as a 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.
Figure 2.9: Creating Multiple Subsystems
Shared subsystems that are copied from the same subsystem definition are linked, which means that changes you make to one shared subsystem will be reflected in all of the other shared subsystems that were created from the same subsystem definition. The changes are also reflected in the subsystem definition entry in the Local Components tab. A shared subsystem 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 24W to 10W, 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 10W.
For more information, see Editing Subsystem Definitions and Shared Subsystems.
Example: Adding Subsystem Definitions and Shared Subsystems to a Model
In 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
In the Model Workspace, right-click (Control-click for Mac) the standalone DC motor subsystem that you created in Example: Creating a Subsystem.
From the context menu, select Convert to Shared Subsystem.
Enter DC Motor as the name for the subsystem definition and click OK.
Under the Local Components tab ( ) on the left side of the Model Workspace, expand the Components palette.
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 shared subsystem is linked to the DC Motor subsystem definition.
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.
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.
Adding Multiple DC Motor Shared Subsystems to a Model
To add multiple DC Motor shared subsystems to a model, drag the DC Motor subsystem definition icon from the Local Components tab and place it in the Model Workspace.
Figure 2.11: Adding Multiple Subsystems to a Model
When you create a new standalone subsystem or add shared subsystems to a model, a unique subscript 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 shared subsystems 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. You will verify that when you change one of the component values and the icon for one DC Motor shared 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 the results from Example: Adding Subsystem Definitions and Shared Subsystems to a Model.
To use shared subsystems:
In MapleSim, open the DCMotorSubsystem.msim file that you created in Example: Adding Subsystem Definitions and Shared Subsystems to a Model.
Under the Local Components tab ( ), expand the Components palette, and then drag a second DC Motor shared subsystem on to the workspace, placing it below the existing DC Motor shared subsystem.
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.
Make the following connections between the newly added components and the existing components in the model.
In the Model Workspace, double-click the DC Motor1 shared subsystem. The detailed view of the shared subsystem appears.
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 the detailed 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 subsystem definition name appears in the Type field in the Properties tab ( ).
Select the Resistor component (R1) and, in the Properties tab, click Parameters. Change the resistance value to 50Ω.
In the Model Workspace Toolbar, click Icon View ( ).
You can customize the icon view of the subsystem. Click the edge of the icon boundary and make it wider. If needed, drag the ports to the middle of the sides of the subsystem border.
Using the Rectangle Tool ( ) in the Model Workspace Toolbar, click and drag your mouse pointer to draw a shape in the box.
In the Model Workspace Toolbar, click Diagram ( ).
Click Main ( ) in the Model Workspace Toolbar to browse to the top level of the model. Both of the DC Motor shared subsystems now display the square that you drew.
Under the Local Components tab on the left side of the MapleSim window, expand the Components 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 resistance value of 50W.
From the Local Components tab, drag a new copy of the DC Motor subsystem and place it anywhere in the Model Workspace. Verify that the new copy displays the square that you drew and its resistance value is also 50W, and then delete it from the workspace.
Save this model as DCMotorSharedSubsystem.msim. You will be building on this model in Example: Removing the Link between a Shared Subsystem and Its Subsystem Definition.
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.
Note: Before doing this example, you should have already gone through and stored the results from Example: Editing Shared Subsystems that are Linked to the Same Subsystem Definition and saved the results from that example.
To remove shared subsystem link:
Open the DCMotorSharedSubsystem.msim model that you created in Example: Editing Shared Subsystems that are Linked to the Same Subsystem Definition.
In the Model Workspace, right-click (Control-click for Mac) the DC Motor1 shared subsystem.
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.
Double-click the DC Motor1 shared subsystem.
Click Icon ( ).
Using the Rectangle Tool ( ), click and drag your mouse pointer to draw a shape in the box in the Model Workspace.
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 your change 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 practice to assign the standalone subsystem a meaningful name that clearly distinguishes it from existing 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 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. 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.
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.
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 the link 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.
To resolve a warning message
Click Diagnostic Information ( ) at the bottom of the MapleSim window to display the debugging console. The following warning message appears in the console.
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.
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
To copy and paste a standalone subsystem:
In the Model Workspace, copy and paste the copy of DC Motor standalone subsystem. A dialog box appears. (See Figure 2.13.)
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 ( ).
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 subsystem called 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
MapleSim lets you define global and subsystem parameter values, and assign them to components using the Add or Change Parameters editor, parameter blocks, parameter sets, and the Advanced Parameter Settings and Advanced Variable Settings in the Properties tab.
Global Parameters
If your model contains multiple components that share a common parameter value, you can create 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 a more detailed example, see Tutorial 1: Modeling a DC Motor with a Gearbox 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. This is done through a parameter block.
To define and assign a global parameter:
In the Library Components tab ( ), expand the Electrical palette, expand the Analog menu, expand the Passive menu, and then expand the Resistors menu.
From the palette, drag three copies of the Resistor component into the Model Workspace.
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 ( ) from the Model Workspace Toolbar.
Double-click on the parameter block in the Model Workspace. The Main subsystem default settings screen appears. You will use this screen to define the global parameter and assign it to the Resistor components in your model.
Click the first field under the Name column in the Main subsystem default settings table.
Enter GlobalResistance as the global parameter name and press Enter.
Under Type, select Resistance[[ W ]] and specify a default value of 2.
Enter Global resistance variable as the description and press Enter.
The global parameter for the resistance value is now defined. You can now assign the common GlobalResistance parameter value to the individual Resistor components that you added to the Model Workspace.
Click Diagram ( ), then select the R1 component. Enter GlobalResistance as the resistance value.
9. Repeat this step for the R2 component.
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 GlobalResistance parameter 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 to share with multiple components in a subsystem. Similar to global parameters, a subsystem parameter is a common value that you define in the parameter editor view and assign to components.
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 are defined. If you select a subsystem in the Model Workspace, click Parameters ( ) or Advanced Parameter Settings, and define a parameter in the parameter editor view, the parameter that you define is assigned to components in the subsystem that you selected and any nested subsystems.
To view an example, see Tutorial 3: Modeling a Nonlinear Damper 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 subsystem parameter value for each shared subsystem separately without affecting other parameter values in the model.
To assign a subsystem parameter to a shared subsystem
From the Help menu, select Examples > Physical Domains > Multibody, and then select the Double Pendulum model. This model contains two shared subsystems, L1 and L2, which are linked to a subsystem definition called L.
Double-click the L1 shared subsystem.
Click Parameters ( ).
In the L subsystem default settings table, click the empty field at the bottom of the table.
Enter c as the parameter name, keep the default value as 1, and press Enter.
Click Diagram ( ). The new subsystem parameter, c, appears in the Properties tab ( ) for the L1 shared subsystem.
Click Main ( ), select the L2 subsystem, and then examine the Properties tab. The new subsystem parameter is also displayed for the L2 shared subsystem.
In the Properties tab, change the value of c to 50.
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 to components 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.
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.
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 parameter names. For example, two separate parameter blocks in the same subsystem cannot each contain 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:
From the Help menu, select Examples > Physical Domains > 1-D Mechanical, and then select the PreLoad example.
Under the Settings tab ( ), enter 0.012 seconds for td, the simulation duration time.
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.
From the Model Workspace Toolbar, click Add a parameter block ( ), and then click on a blank area in the Model Workspace.
Click the Properties tab and enter the name SlidingMassParams for the parameter block.
Double-click the SlidingMassParams parameter block in the Model Workspace. The parameter editor view appears.
Click the first field in the table and define a new symbolic parameter called MASS.
Press Enter. The remaining fields for this row are activated.
From the Type drop-down menu, select Mass [[ kg ]].
Enter a default value of 5.
From the Default Units drop-down menu, select kg.
Enter Mass of the sliding mass for the Description field.
In the same way, define the following parameters and values in the Parameters subsystem default settings table.
Name
Type
Default Value
Default Units
LENGTH
Length m
2
m
Length of the sliding mass
V0
Velocity ms
1
ms
Initial velocity of the sliding mass
S0
Position m
Initial position of the sliding mass
The parameter editor view appears as follows when the values are defined.
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.
In the Model Workspace, select the SM1 mass component in the diagram.
In the Properties tab, assign the following values and press Enter.
The parameters of this Mass component now inherit the numeric values that you defined in the parameter block.
In the same way, assign the same values to the parameters of the SM2 and SM3 mass components in the model.
In the Model Workspace, delete the probe labeled Input.
Select the probe labeled Output.
In the Properties tab, clear the check box beside Velocity.
To simulate the model, click Run Simulation ( ) in the Main Toolbar.
Click Show Simulation Results ( ). The following graph appears in the Analysis window.
In the Model Workspace, click the parameter block.
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.
Simulate the model again, then bring the Analysis window to the front. Another simulation graph appears, which you can compare to your first graph.
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 parameters in the Model Workspace.
Parameter Sets for your model are listed in the Attached Files tab ( ), under Parameter Sets as shown in the following figure.
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 the Using 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 in your subsystem by using the Advanced Parameter Settings and Advanced Variable Settings tools in the Properties tab ( ). Advanced Settings lets you override one or more default values.
Advanced Parameter Settings
Advanced Parameter Settings lets you override the default values for selected subsystem components. If desired, you can parametrize the override using the parametrization feature ( ). A component override in one subsystem can be converted to a parameter visible in all the other subsystems.
In the following model an override was applied to the initial value of R and changed to the parameter Rcommon.
In the Model Workspace, components with a parameter override are identified with an override 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.
Example: Creating a Parameter Override
To create a parameter override:
From the Edit menu, select Create Subsystem or right-click (Control-click for Mac) the boxed area and select Create Subsystem.
In the dialog box, enter DC Motor, and then click OK. The DC Motor subsystem appears.
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.
Under the Local Components tab ( ), expand the Components palette, and then drag three copies of the DC Motor shared subsystem to your Model Workspace.
Create three additional DC Motor subsystems as shown below.
Click S2, and, under the Properties tab ( ), set T0 to 1. Do the same for S3 and S4.
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.
Expand R1 and enter a value of 100 for the Resistance parameter (R).
Click OK. The new parameter appears in the Properties tab as an override.
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 the Properties tab as a parameter that can now be reused in the other subsystems. Note that it is no longer an override.
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 25W
For DC Motor1, set Rcommon to 50W
For DC Motor2, set Rcommon to 75W
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.
Click Run Simulation ( ) in the Main Toolbar. The following graphs appear for each of the subsystems.
Specifying 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 ( ), along with the other configurable parameter values for that component.
When you select a subsystem and then click Advanced Variable Settings, all subsystem components appear. You can select a component and specify the initial conditions for that component. 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 save files 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 Attach File.
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 want to 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 and Manipulating a Model in this guide.
2.8 Creating and Managing Custom Libraries
You can create a custom library to save a collection of subsystems and custom modeling components 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 ( ) and are indicated with an icon: . A sample custom palette is shown below.
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 in your 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 Model
In this example, you will create a custom library from the shared subsystem definitions of an existing MapleSim model. The components added to the custom library will then be available in future MapleSim sessions.
To create a custom library from a model:
From the Help menu, select Examples > Physical Domains > Multibody, and then select the 5 DoF Robot example.
This model has six shared subsystems, which are listed in the Components palette of the Local Components tab ( )
Save the model.
From the Tools menu, select Export to MapleSim Library.
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.
Click OK.
After the library has been exported, click Close.
You are now in library edit mode (indicated by the watermark on the workspace and the library 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.
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.
Click Reload ( ) in the Main Toolbar to save your changes and reload the palette for the 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 notation and modify the style, color, and font of the text. For more information about 2-D math notation, see Entering Text in 2-D Math Notation.
Example: Adding Text Annotation to a Model
To add text annotation to a model:
From the Annotations Toolbar, click Text Tool ( ).
Note: If the Annotation Toolbar is not visible, click Show/Hide Drawing Tools ( ) in the Model Workspace Toolbar.
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.
Enter the following text: This block generates a step signal with a height of 1.
Select the text that you entered and change the font to Arial.
Click anywhere outside of the text box.
Draw another text box below the Inertia component.
Enter the following text: Inertia with a w0 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 the remaining text.
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 a formatting option for adding mathematical elements such as subscripts, superscripts, and Greek characters. As you enter text in 2-D math notation, you can use the command and symbol completion feature to display a list of possible Maple commands or mathematical symbols 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:
Task
Key Combination
Example
Command and symbol completion (parameter values and annotations only)
Enter the first few characters of a symbol name, Greek character, or Maple command.
Enter the key combination for your platform:
Esc, Mac, Windows, and Linux
Ctrl + Shift + Space, Linux
From the menu, select the symbol or command that you want to insert.
-
Enter a subscript for a variable
Ctrl (or Command) + Shift + underscore ( _ )
x__a
Enter a superscript
caret (^)
x2
Enter a fraction
forward slash (/)
18
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
You can create a data set to provide values for an interpolation table component in your model. 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 the custom values, or you can create a data set in Maple using the Data Generation App or Random 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 a data set; however, for demonstration purposes, you will create a data set using a computation that has already been defined.
To create a data set in Maple:
Open a new MapleSim document.
In the Library Components tab ( ), expand the Signal Blocks palette, and then expand the Interpolation Tables menu.
Add a Lookup Table 1 D component to the Model Workspace.
In the main toolbar, click Show Apps Manager ( ).
In the Apps palette on the left, under Utility, double-click Data Generation. The Data Generation App opens in the Apps Manager.
At the bottom of the app, in the Data set name field, enter TestDataSet.
To make the data set available in MapleSim, click Attach Data to Model.
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 table component in the Model Workspace.
In the Model Workspace, select the Lookup Table 1 D component.
In the Properties tab ( ), from the datasource mode list, select attachment.
From the data drop-down menu, select the TestDataSet.csv file. The data set is now assigned to the Lookup Table 1 D component.
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 facing in 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 subsystem components 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 in more depth, test, or translate into source code. Several MapleSim templates allow you to analyze and retrieve equations from particular subsystems. The Code Generation Template allows you to generate source code from subsystems only.
For more information about performing analysis tasks, see Analyzing and Manipulating a Model 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 connection lines 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.
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 Unconnected Lines
You can display the debugging pane by clicking Debugging ( ) at the bottom of the MapleSim window.
After you run the simulation, the debugging pane displays diagnostic messages that can help 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 have identical 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 provide a 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 sources in the MapleSim Component Library display an arrow that indicates the direction of the positive current.
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 and speed quantities.
On the other hand, if the negative port of the Signal Voltage source is connected to the positive 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.
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 mechanical components in your model point in the same direction. As an example, note that all of the force 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 your model 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 the icon) are both connected to a Rigid Body component.
Figure 2.16: Center of Mass Placement Best Practice
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 model or at the same level as a hydraulic subsystem. If you place this component at the top level of your model, all hydraulic components and subsystems in your model will inherit the fluid 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 that subsystem 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: Modeling Hydraulic Systems.
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.
Download Help Document
