MapleSim Tutorials help you get started with MapleSim and learn about the key features, tools, templates and systems available in MapleSim, by leading you through a series of descriptive tasks, problems and examples using best practices. Many of these examples can be found in the Help > Examples > User's Guide Examples menu, in the order that they are presented in the User's Guide.

In this chapter:

6.1 Tutorial 1: Modeling a DC Motor with a Gearbox

In this tutorial, you will extend a DC motor model and perform the following tasks:

 • Add a gearbox to the DC motor model
 • Simulate the DC motor with gearbox model
 • Group the DC motor components into a subsystem
 • Assign global parameters to the model
 • Add signal block components and a PI controller to the model
 • Simulate the modified DC motor model using different conditions

Adding a Gearbox to a DC Motor Model

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

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

 5 In the Model Workspace, click the Ideal Gear component.
 6 In the Properties tab ( ), change the transmission ratio, r, to 10 and then press Enter to accept the value.
 7 Specify the following parameter values for the other components:
 • For the Elasto-Backlash component, in the b field, change the total backlash value to 0.3rad. In the d field, change the damping constant to 104$\frac{N\cdot m\cdot s}{\mathrm{rad}}$.
 • For the first Inertia component (I2), in the J field, change the moment of inertia value to 10kg$m2.  • For the second Inertia component (I3), in the J field, change the moment of inertia value to 1kg$m2.
 • For the Step source, in the height field, change the value to 100.

Simulating the DC Motor with the Gearbox Model

To simulate the DC motor:

 1 From the Model Workspace Toolbar, click Attach probe ( ).
 2 Hover your mouse pointer over the line that connects the Elasto-Backlash component and the second Inertia component (I3). The line is highlighted.
 3 Click the line once, and then click a spot in the workspace to anchor the probe.
 4 Select the probe in the Model Workspace.
 5 To include the angle (phi), speed (w), acceleration (a), and torque (tau) values in the simulation graphs, in the Properties tab ( ), select Angle, Angular Velocity, Angular Acceleration, and Torque.
 6 Click a blank area in the Model Workspace.
 7 Under the Settings tab ( ), set the td parameter to 10 seconds and press Enter.
 8 Click Run Simulation ( ) in the Main Toolbar.
 9 Click Show Simulation Results ( ).  The following graphs appear in the Analysis window.

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

Grouping the DC Motor Components into a Subsystem

To group the DC motor components:

 1 Draw a box around the electrical components and the first inertia component by dragging your mouse over these components.

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

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

Assigning Global Parameters to a Model

You can define a global parameter and assign its value to multiple components in your model.

To assign global parameters:

 1 Click Main ( ) in the Model Workspace Toolbar to browse to the top level of the model.
 2 From the Model Workspace Toolbar, click Parameters ( ) to switch to the parameter editor view.
 3 In the first row of the Main subsystem default settings table, enter Rglobal in the Name field and press Enter.
 4 Specify a default value of 24 and enter Global resistance value as the description.
 5 In the second row of the table, enter Jglobal in the Name field and press Enter.
 6 Specify a default value of 10 and enter Global moment of inertia value as the description.

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

 8 In the Model Workspace, select the Inertia component I3.
 9 In the Properties tab ( ), in the Value field for the moment of inertia parameter, enter Jglobal and press Enter.  The moment of inertia parameter now inherits the numeric value of the global parameter Jglobal (in this example, 10).
 10 Double-click the 'DC Motor' subsystem.
 11 In the Model Workspace, select the EMF1 component.
 12 In the Properties tab ( ), in the Value field for k, the transformation coefficient, enter Rglobal$Jglobal and press Enter. Note: This value is an approximation of the transformation coefficient.  13 Similarly, in the Properties tab ( ) for the R1 component, in the Value field for the resistance parameter, enter Rglobal and press Enter.  14 Click Main ( ) to browse to the top level of your model.  15 Save the model as DC_Motor2.msim. Changing Input and Output Values In this example, you will change the input and output values of the model to simulate different conditions. To change input and output values:  1 Under the Library Components tab ( ), browse to the 1-D Mechanical > Rotational > Sensors menu and then add the Rotational Speed Sensor component to the Model Workspace and place it below the gearbox components.  2 Right-click (Control-click for Mac) the Rotational Speed Sensor component and select Flip Horizontal.  3 Delete the connection line between the Step source and the DC Motor subsystem.  4 From the Signal Blocks > Controllers menu, add the PI component to the Model Workspace and place it to the left of the DC Motor subsystem.  5 From the Signal Blocks > Mathematical > Operators menu, add the Feedback component to the Model Workspace and place it to the left of the PI component.  6 Connect the components as shown below. Tip: To draw a perpendicular line, click a point in the Model Workspace to anchor the line and then move your mouse cursor in a different direction to draw the second line segment.  7 Click the PI component in the Model Workspace.  8 In the Properties tab ( ), specify a gain of 20 in the k field, and a time constant of 3 seconds in the T field.  9 Simulate the model again. When the simulation is complete, the following graphs appear.  10 Save the model as DC_Motor3.msim.  11 To verify the results, from the Help menu, select Examples > User's Guide Examples > Chapter 6, and then select the DC Motor Subsystem with Gearbox and PI Controller example. 6.2 Tutorial 2: Modeling a Cable Tension Controller In this tutorial, you will extend the DC motor example to model a cable that is stretched with a pre-defined tension. The tension is defined by a Constant source and the PI controller provides the voltage to drive the motor. You will perform the following tasks:  • Build a cable tension controller model  • Specify component properties  • Simulate the cable tension controller model Building a Cable Tension Controller Model In this example, you will build the cable tension controller model using a combination of 1-D mechanical rotational and translational components. You will also group components into a Gear subsystem and add subsystem ports. To build the cable tension controller:  1 Open the DC_Motor3.msim file that you created in the previous tutorial and save the file as Cable_Tension.msim.  2 Delete the probe attached to the line that connects the Elasto-Backlash and Inertia components.  3 Delete the Rotational Speed Sensor component and its connection lines.  4 Select the Ideal Gear, Elasto-Backlash, and Inertia components and group them into a subsystem called Gear Components.  5 From the Library Components tab ( ), add the following components to the Model Workspace:  • From the 1-D Mechanical > Rotational > Bearings and Gears menu, add the Ideal Gear R 2 T component and place it to the right of the Gear Components subsystem.  • From the 1-D Mechanical > Translational > Sensors menu, add the Force Sensor component and place it to the right of the Ideal Gear R 2 T component.  • From the 1-D Mechanical > Translational > Springs and Dampers menu, add the Spring component and place it to the right of the Force Sensor component.  • From the 1-D Mechanical > Translational > Common menu, add the Fixed component and place it to the right of the Spring component.  6 Right-click (Control-click for Mac) the Fixed component in the Model Workspace and select Rotate Counterclockwise.  7 Delete the Step source and replace it with a Constant source from the Library > Signal Blocks > Sources > Real menu. Tip: You can connect the Constant source by dragging it onto the unconnected line end.  8 Double-click the 'Gear Components' subsystem. You will now add a port to connect this subsystem with other components.  9 Click the negative (white) flange of the Inertia component and drag your mouse cursor to the boundary that surrounds the subsystem components.  10 Click the line once. The subsystem port is added to the line.  11 Click Main ( ) in the Model Workspace Toolbar to browse to the top level of your model.  12 Connect the components as shown below. Specifying Component Properties To specify component properties:  1 In the Model Workspace, double-click the 'Gear Components' subsystem.  2 In the Properties tab ( ), specify the following parameter values for the subsystem components:  • For the Ideal Gear component, change r to 0.01.  • For the Inertia component, change J to 0.1kg$m2.
 3 Click Main ( ) in the Model Workspace Toolbar to browse to the top level of the model.
 4 Specify the following parameter values for the other components:
 • For the Spring component, in the c field, change the spring constant value to 2110\$109$\frac{N}{m}$.
 • For the PI controller, change the T value to 0.1s.
 • For the Constant source, change the constant output value k to 77.448.

Simulating the Cable Tension Controller

To simulate the cable tension controller:

 1 Click Attach probe ( ).
 2 Click the line that connects the Feedback and PI components and then click the workspace to position the probe.
 3 Select the probe in the Model Workspace.
 4 In the Properties tab ( ), select the Real quantity and change its name to Error.
 5 Add another probe that measures the Real quantity to the line connecting the PI component and 'DC Motor' subsystem. Change the quantity name to Controller.

 Figure 6.1: Cable Tension Controller

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

 10 Save the file.

6.3 Tutorial 3: Modeling a Nonlinear Damper

In this tutorial, you will model a nonlinear damper with a linear spring. This tutorial builds upon the concepts demonstrated in the previous tutorials. You will perform the following tasks:

 • Generate a custom spring damper defined by differential equations
 • Provide custom damping coefficient values as input signals
 • Build the nonlinear damper with linear spring model
 • Assign a variable to a subsystem
 • Simulate the nonlinear damper with linear spring model
 Generating a Spring Damper Custom Component This example uses the Nonlinear Spring Damper Custom Component created in Example: Creating a Nonlinear Spring-Damper Custom Component in Chapter 3.

Providing Damping Coefficient Values

You can provide custom values for interpolation table components that you add to your model. In this example, you will provide damping coefficient values in an external file.

To create damping coefficient values:

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

The first column contains values for the relative displacement of the damper and the second column contains values for the damping coefficients.

 2 Save the file as DamperCurve.xlsx or DamperCurve.csv.
 3 In MapleSim, open the NonlinearSpringDamper.msim model you created in Example: Creating a Nonlinear Spring-Damper Custom Component in Chapter 3.
 4 Select the Attachment Files tab ( ).
 5 Right-click (Control-click for Mac) Data Sets and select Attach File.
 6 Browse to and select the Excel spreadsheet or .csv file that you created, and click Attach.... The file containing the data set is attached to your model. You will use this file in the next task.

Building the Nonlinear Damper Model

In this example, you will build the nonlinear damper using components from the component library.

To build the nonlinear damper:

 1 Select the Local Components tab ( ), and then drag the NonLinearMSD custom component into the Model Workspace.
 2 Select the Library Components tab ( ), and then add the following components to the Model Workspace:
 • From the Signal Blocks > Mathematical > Operators menu, add a Gain component and place it above the NonLinearMSD component.
 • From the Signal Blocks > Sources > Real menu, add a Constant component and place it between the NonLinearMSD and Gain components.
 • From the Signal Blocks > Interpolation Tables menu, add a Lookup Table 1 D component and place it to the left of the Gain component.
 • From the 1-D Mechanical > Translational > Sensors menu, add a Position Sensor component and place it to the left of the Lookup Table 1 D component.
 3 Connect the components as shown in the following figure.

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

 Figure 6.2: Nonlinear Damper Model

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

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

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

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

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

Assigning a Parameter to a Subsystem

To assign a parameter to a subsystem:

 1 In the Model Workspace, double-click the 'Nonlinear Damper' subsystem.
 2 In the Model Workspace Toolbar, click Parameters ( ).
 3 In the first row of the Standalone Subsystem default settings table, define a spring constant parameter called Ks, and then press Enter.
 4 In the same row, specify a default value of 1000 and enter Spring constant as the description. You can now assign the parameter value Ks to other components in the Nonlinear Damper subsystem.

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

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

Simulating the Nonlinear Damper with Linear Spring Model

To simulate the nonlinear damper:

 1 Click Main ( ) in the Model Workspace Toolbar to browse to the top level of the model.
 2 From the Model Workspace Toolbar, click Attach probe ( ). The cursor changes to the probe icon when you move into the workspace.
 3 To attach the probe, click the line that connects the Mass component and the Nonlinear Damper subsystem and then click a spot in the workspace to anchor the probe.
 4 In the Model Workspace, select the probe.
 5 Under the Properties tab ( ), select the length, speed, and acceleration quantities.

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

 11 Under the Settings tab ( ), set the td parameter to 10 seconds.
 12 Click Run Simulation ( ) in the Main Toolbar.
 13 Click Show Simulation Results ( ).  The following graphs appear in the Analysis window.

 14 Save the file as NonLinearMSD.msim.

6.4 Tutorial 4: Modeling a Planar Slider-Crank Mechanism

Using components from the Multibody mechanical library, you will model the planar slider-crank mechanism shown in the following figure.

 Figure 6.3: Planar Slider-Crank Mechanism

This model consists of a revolute joint, A, which is attached to a planar link. This planar link is attached to a connecting rod by a second revolute joint, B. The connecting rod connects to a sliding mass by a third revolute joint, C, and the sliding mass connects to ground by a prismatic joint.  In practice, this mechanism converts rotational motion at the crank to translational motion at the sliding mass or vice versa. For the system shown in the diagram, gravity is assumed to be the only external force, acting along the negative Y-axis (the y-axis for the inertial frame).

In this tutorial, you will perform the following tasks:

 • Create a planar link subsystem
 • Define and assign subsystem parameters
 • Create the crank and connecting rod elements
 • Add the fixed frame, sliding mass, and joint elements to the model
 • Specify initial conditions
 • Simulate the planar slider-crank mechanism

The preceding diagram shows that the slider-crank has two associated planar links: the crank (the link from point A to B) and the connecting rod (the link from B to C). In both cases, these links have their longitudinal axis along their local x-axis (x1 and x2, respectively). Therefore, you will first create a generic planar link with two ports. The inboard port (base) will be located  $-\frac{L}{2}$ units along the x-axis of the link, and the outboard port (tip) will be located $\frac{L}{2}$ units along the x-axis of the link. In this example, L refers to the length of the link and the center-of-mass is assumed to be in the middle of the link.

To create a planar link subsystem:

 1 Open a new MapleSim document.
 2 Under the Library Components tab ( ), browse to the Multibody > Bodies and Frames menu, and then add two Rigid Body Frame components and a Rigid Body component.
 3 In the Model Workspace, right-click (Control-click for Mac) one of the Rigid Body Frame components, and then select Flip Horizontal.
 4 Right-click (Control-click for Mac) the Rigid Body component, and then select Rotate Counterclockwise.
 5 Drag the components in the arrangement shown below.

Notes:

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

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

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

 9 From the Edit menu, select Create Subsystem.
 10 In the Create Subsystem dialog box, enter Link, and then click OK.

You will now add ports to connect this subsystem to other components.

 12 Click the left frame of the RBF1 component and drag your mouse pointer to the left of the subsystem boundary.

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

Defining and Assigning Parameters

In this task, you will define a subsystem parameter, L, to represent the length of the link and assign the parameter value as a variable to the parameters of the Rigid Body Frame components. The Rigid Body Frame components will then inherit the numeric value of L.

To define and assign parameters:

 1 If you are not already in the Link subsystem, click Main ( ) in the Model Workspace Toolbar, and then double-click the Link subsystem.
 2 In the Model Workspace Toolbar, click Parameters ( ), or from the Properties tab ( ) click Add or Change Parameters.  The Standalone Subsystem default settings window appears.
 3 In the first row of the Standalone Subsystem default settings table, enter L in the Name field, and then press Enter.
 4 Specify a default value of 1 and enter Length as the description.
 5 Scroll to the RBF1 component section.
 6 In the Value field for ${\stackrel{\mathbf{&conjugate0;}}{\mathbit{r}}}_{}$, specify a position offset of , and then select m from the Units drop-down menu. To enter a fraction, use the forward slash key (/).
 7 Scroll to the RBF2 component section.
 8 In the Value field for ${\stackrel{\mathbf{&conjugate0;}}{\mathbit{r}}}_{}$, specify a position offset of , and then select m from the Units drop-down menu.
 9 Click Diagram View ( ).

Creating the Crank and Connecting Rod Elements

In this task, to create the crank and connecting rod elements, you will add a Link subsystem definition to your model and create Crank and ConnectingRod shared subsystems. You will also assign a different length value to the connecting rod element.

To create the crank and connecting rod elements:

 1 Click Main ( ) in the Model Workspace Toolbar to browse to the top level of your model. The Link subsystem appears in the Model Workspace.
 2 Right-click (Control-click for Mac) the Link subsystem, and then select Convert to Shared Subsystem.  The Create Shared Subsystem window appears.  Click OK.  A Link subsystem definition is added to the Components palette in the Local Components tab ( ) and the Link subsystem in the Model Workspace is converted to a shared subsystem.
 3 Select the Link1 shared subsystem in the Model Workspace and in the Properties tab ( ), enter Crank in the Name field.
 4 From the Local Components tab, drag the Link icon to the Model Workspace, placing it to the right of the Crank shared subsystem.
 5 In the Model Workspace, select the second copy of the Link shared subsystem.
 6 In the Properties tab ( ), change the shared subsystem name to ConnectingRod.  See the following figure.

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

Adding the Fixed Frame, Sliding Mass, and Joint Elements

In this task, you will add a Fixed Frame component, a Rigid Body component to represent the sliding mass, and the Revolute joint components.

To add the fixed frame, sliding mass, and joint elements:

 1 Under the Library Components tab ( ), expand the Multibody > Bodies and Frames menu, select the Fixed Frame component, and then place it to the left of the Crank shared subsystem.
 2 From the same menu, select the Rigid Body component and place it slightly below and to the right of the ConnectingRod shared subsystem.
 • From the Multibody > Joints and Motions menu, add a Revolute joint between the Fixed Frame component and the crank, a second Revolute joint between the crank and the connecting rod, and a third Revolute joint between the connecting rod and the rigid body.
 • From the same menu, add a Prismatic joint and place it below the Crank subsystem.
 4 Select the Rigid Body component in the Model Workspace and rename it SlidingMass.
 5 Right-click (Control-click for Mac) the SlidingMass component and select Flip Horizontal.
 6 In the same way, right-click (Control-click for Mac) the Revolute joint that is located between the connecting rod and the rigid body and select Flip Horizontal.  See the following figure.

 7 Connect the components as shown in the following figure.

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

Specifying Initial Conditions

You can specify initial condition values for certain components in your model.

To specify initial conditions:

 1 For the first revolute joint (R1 in the preceding figure), in the q0 field, change the initial angle to $\frac{\mathrm{π}}{4}$rad.

Tip: To enter π, type pi, press Esc , and then select the π symbol from the menu.

 2 From the ICq,w drop-down menu, select Strictly Enforce.

When MapleSim solves for the initial conditions, the first angle will be set to $\frac{\mathrm{π}}{4}$rad before the angles are set for the other joints.

Simulating the Planar Slider-Crank Mechanism

To simulate the planar slider-crank mechanism:

 1 From the Model Workspace Toolbar, click Attach probe ( ).
 2 In the Model Workspace, click the white 1-D translational flange (flange_b) at the top right of the Prismatic component icon and position the probe.
 3 Click the probe in the Model Workspace.
 4 In the Properties tab ( ), select the Length quantity to measure the displacement.
 5 In the same way, add a probe that measures the Angle quantity to the white 1-D rotational flange (flange_b) at the top right of the R1 component icon (that is, the revolute joint between the Fixed Frame and Crank components).
 6 Click a blank area in the Model Workspace.
 7 In the Settings tab ( ), expand Simulation and set the td parameter to 10 seconds.
 8 Click Run Simulation ( ) in the Main Toolbar.
 9 Click Show Simulation Results ( ).  The following graphs appear in the Analysis window.

 10 Select the 3-D Playback Window, and then click Play ( ) in the 3-D Toolbar to see a video of the simulation.

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.

 11 Save the file as SliderCrank.msim.

6.5 Tutorial 5: Using the Custom Component Template

This tutorial describes the use of the Custom Component template in various domains in MapleSim.  With this template, you can define system parameters and variables, set the level of equation optimization, generate the equations, and then further analyze the resulting equations.  You can use any Maple commands to perform detailed equation analysis, assign model equations to a variable or parameter, and define additional system variables and parameters.  These features are especially useful in generating reusable equations when there is more than one subsystem.

The Custom Component Templates contain pre-built embedded components that let you extract, manipulate, and analyze the symbolic system equations generated by any MapleSim model. Using various components from the library, you will create models, set initial conditions and component properties, and assign new values to parameters and variables.

In this tutorial, you will use the Custom Component template to extract the equations for various models by performing the following tasks:

 • Create the model
 • Attach a Custom Component template for the model
 • Set initial conditions by specifying the component properties
 • Assign new values to parameters and variables
 • View, manipulate, and reassign equations
 • Simulate and translate an equation to a transfer function
 • Map variables from your equations to the ports
 • Specify ports for your block
 • Create a custom port using the Custom Port app

For a description of the Custom Component Template see Creating Custom Modeling Components.

Example: Modeling a Temperature Dependent Resistor

In this tutorial example, you will create a model of a circuit using a custom component for a temperature dependent resistor whose resistance varies as $r\left(t\right)=\mathrm{R0}\cdot \left(1+\frac{{\left(T\left(t\right)-\mathrm{T0}\right)}^{2}}{{\mathrm{Tk}}^{2}}\right)$, where $\mathrm{R0}$, $\mathrm{T0}$, and $\mathrm{Tk}$ are parameters.

To create the custom component:

 1 Start a new MapleSim model and then select the Add Apps or Templates tab ( ).
 2 Double-click on the Custom Component entry in the Templates palette.
 3 Enter TempResistor and then click Create Attachment ( ). The Maple Custom Component template is loaded.
 4 In the Define Equations section, enter in the following system equations to define your component. Press Enter at the end of the line.

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

 13 Click Add Port. A new port appears on the right side. This will become the negative electrical pin.
 14 From the Type drop-down box, select Electrical.
 15 Click the Style radio button labeled -. This changes the port style to an unfilled box.
 16 In the list box select Voltage = unassigned and then select vn(t) in the drop-down list under Signal. This assigns the across variable of the port.
 17 In the list box select Current = unassigned, select i(t) in the drop-down list under Signal, and then click the +/- button to negate the sign of the signal.

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

Note: When you build the model, make sure to attach the probe to the custom component to measure the electrical and thermal quantities.

Table 6.1: Temperature Dependent Resistor Components
 Component Symbol Component Location Required Settings TempResistor Custom Component Local Components > Components Use default settings Library Components > Electrical > Analog > Common Use default settings Library Components > Electrical > Analog > Common Use default settings Library Components > Thermal > Heat Transfer Components Set R = 10 K/W Library Components > Thermal > Heat Transfer Components Set C = 0.1 J/K Set $\mathrm{T__0}$ = 280K Library Components > Thermal > Sources Set T = 298K
 33 Right-click (Control-click for Mac) on the TempResistor custom component, select Attach probe, and then click on the workspace to place the probe. See the following figure.

 Figure 6.4: Temperature Dependent Resistor

 34 Select the probe, select the Properties tab ( ), and then select the following quantities:
 • Current
 • ThermoDynamicTemperature
 • HeatFlowRate
 • Resistance
 35 Click Run Simulation ( ) in the Main Toolbar.
 36 Click Show Simulation Results ( ).  The following graphs appear in the Analysis window.

Example: Compliant Contact and Piecewise Functions

In this tutorial example, you will create a model of a bouncing ball using a custom component to model the compliant ground contact.

 Figure 6.5: Falling Ball

The prismatic joint in Figure 6.5 models a falling ball by allowing translation of a rigid body along the vertical y-axis. To change the falling ball into a bouncing ball, a custom component models the compliant ground contact using a spring-damper arrangement. The custom component attaches to the 1-D translational ports on the prismatic joint with the following conditions:

 • The ball will hit ground at s=0 and cause the spring damper to compress (and hence ball position will be at s<0).
 • The spring-damper will impart a restoring force of F(t) to the ball until it is above at s=0.

Figure 6.6 shows a diagram of this process.

 Figure 6.6: Bouncing Ball Dynamics

where

To create the custom component:

 1 Start a new MapleSim model and then select the Add Apps or Templates tab ( ).
 2 Double-click on the Custom Component entry in the Templates palette.
 3 Enter contact for the name of the attachment and then click Create Attachment ( ). The Maple Custom Component template is loaded.
 4 In the Define Equations area, enter in the following equation, parameters, and initial conditions to define your custom component. Press Enter at the end of the line.



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

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

 Figure 6.7: Bouncing Ball

Table 6.2: Bouncing Ball Multibody Components
 Component Symbol Component Location Required Settings Custom Component Local Components > Components Use default settings Library Components > Multibody > Bodies and Frames Use default settings Library Components > Multibody > Bodies and Frames Use default settings Library Components > Multibody > Joints and Motions For the prismatic joint to translate along the y direction, set ${\stackrel{\mathbf{⏞}}{\mathbf{ⅇ}}}_{\mathbf{1}}$ to $\left[\mathbf{0}\mathbf{,}\mathbf{1}\mathbf{,}\mathbf{0}\right]$ For the prismatic joint to try enforcing your translational initial conditions, set ICs,v to Treat as Guess For an initial displacement, the prismatic joint requires a value > 0.  Set ${\mathbit{s}}_{\mathbf{0}}$ to $\mathbf{10}\mathbit{m}$
 28 Click Run Simulation ( ) in the Main Toolbar.
 29 When the simulation is complete, the Simulation Results tab of the Analysis window displays the probe plot.

 Figure 6.8: Bouncing Ball Result

 30 To play the animation of the bouncing ball, select the 3-D Playback Window in the Simulation Results tab, and then click Play ( ) in the Playback Toolbar.
 31 Use the navigation controls on the toolbar to pan, zoom, or move the camera around your model to find a good view.  For more information, see 3-D Toolbar.
 32 To create a smoother animation, click the Change 3-D settings icon ( ) and select Interpolate Intermediate Frames from the drop-down menu.  For more information, see Animating a 3-D Model with Interpolated Frames.

Example: Custom Ports

In this tutorial example you will create a pair of custom ports with causal signals, power, and velocity, that are generated by a dummy vehicle model and combined by a monitor block that computes the force, using the relation . For the dummy vehicle model we will assume the power is constant, $p\left(t\right)=P$, and the velocity is given by $v\left(t\right)=\mathrm{v0}+a\cdot t$, where $P$, $\mathrm{v0}$, and $a$ are parameters.

Create Custom Ports

We need to create two custom ports, an output port named bus_out and an input port named bus_in.

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

 Figure 6.9: Custom Ports

Create Engine Model

We will first create the dummy vehicle model.

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

 4 In the Configuration section, select Parameters, and then click Refresh All.
 5 Change the Type fields for $P$, $a$, and $\mathrm{v0}$ to Power, Acceleration, and Velocity, respectively.
 6 In the Configuration section, select Ports.
 7 Click Clear All Ports.
 8 Click Add Port. A new port appears on the left edge. Drag it to the right edge.
 9 From the Type drop-down menu, select Custom. (It is at the bottom of the list.)
 10 In the text area below the Type drop-down menu, enter bus_out.
 11 Select the out style radio button.
 12 Click Apply Custom.
 13 From the Icon list, select Use default.
 14 Using the drop-down menu and list box at the bottom of this section, assign the power signal to $p\left(t\right)$ and the velocity signal to $v\left(t\right)$.  Figure 6.10 shows the completed Ports section of the template.

 Figure 6.10: Using a Custom Port

 15 In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The message no issues found should appear.
 16 In the Component Generation section, change the name to engine, and then click Generate MapleSim Component. The engine component appear in the Components palette of the Local Components tab.

Create Monitor Model

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

 4 In the Configuration section, select Parameters, and then click Refresh All.
 5 Select Ports, and then click Clear All Ports.
 6 Click Add Port. A new port appears on the left edge.  This will be the bus input.
 7 From the Type drop-down menu, select Custom (at the bottom of the list).
 8 In the text area below the Type drop-down menu, enter the custom type name: bus_in.
 9 Click Apply Custom.
 10 Using the drop-down menu and list box at the bottom of this section, assign the power signal to $p\left(t\right)$ and the velocity signal to $v\left(t\right)$.
 11 Click Add Port. A new port appears on the right edge. This will be the computed force output.
 12 From the Type drop-down menu, select Real Signal. Click the out style radio button. Assign the value signal to $f\left(t\right)$.
 13 From the Icon list, select Use default.
 14 Click Refresh All.
 15 In the Configuration section, select Variables, and then click Refresh All.
 16 Enter Force for the Type field of signal $f\left(t\right)$.
 17 Select Dimensional Analysis, and then click Check Dimensions. The message $\mathrm{real_o}\left(t\right)=f\left(t\right)⟦N⟧$ should appear. It indicates that the output port, $\mathrm{real_o}\left(t\right)$, is a real signal but is equated to $f\left(t\right)$, which has units of force (Newtons).
 18 In the Component Generation section, change the name to monitor.

Complete Model

 1 In MapleSim, drag the engine and monitor components from the Components palette in the Local Components tab ( ) into the workspace.
 2 Connect the output of the engine block to the input of the monitor block. Then, attach a probe to the output of the monitor block as shown below.

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

You can use the entire range of Maple functionality to derive your system equations in the Custom Component template. This section provides a sample advanced application.

Example: Modeling a Centrifugal Pump from a Head Flow Rate Curve

The following hydraulics example demonstrates how to apply extrapolated data from a centrifugal pump into a custom component. Creating a centrifugal pump custom component involves the following tasks.

 • Obtain data from a graph
 • Generate an equation by fitting the best curve for your data set
 • Obtain multi-argument operators
 • Apply operators and generate custom component

 Figure 6.11: Centrifugal Pump Head Flow Rate Curve

Table 6.3: Centrifugal Pump Data
 Flow Rate (cubic meters) Pressure Head (meters) 0.01 0.0098 0.02 0.00874 0.03 0.00725 0.04 0.005 0.05 0.0025

Table 6.4: Circular Pipe Parameters
 Symbol Description Value $\mathrm{D}$ Pipe hydraulic diameter $L$ Pipe length $\mathrm{ε}$ Height of internal pipe roughness $\mathrm{ReL}$ Maximum Reynolds number in laminar regime $2000$ $\mathrm{ReT}$ Minimum Reynolds number in turbulent regime $4000$

Table 6.5: Centrifugal Pump Components
 Component Symbol Component Location Its Use Value Library Components > Hydraulics > Reference Components This component defines a base pressure (similar to ground in the electrical domain) and represents a connection to atmosphere. Use default settings Library Components > Hydraulics > Reference Components All hydraulic models need a Hydraulic Fluid Properties component. Similar to a Parameter block, it is placed in the Model Workspace to define the following hydraulic fluid properties: • rhoFluid: liquid density • K: Bulk Modulus defines the fluid compressibility • nuFluid: Kinematic Viscosity defined as dynamic viscosity divided by liquid density Use default settings : rhoFluid:    $850\frac{\mathrm{kg}}{{m}^{3}}$ K:      nuFluid:  $0.000018\frac{{m}^{2}}{s}$ Library Components > Hydraulics > Restrictions The circular pipe defines a pressure drop in the hydraulic line.  The pressure drop is given by the Darcy equation. Use default settings (see Table 6.4) Custom Component Local Components > Components This custom component defines hydraulic pressure and flow rate properties for the hydraulic line. User defined

 Figure 6.12: Centrifugal Pump Custom Component

To create the custom component:

 1 Start a new MapleSim model and then select the Add Apps or Templates tab ( ).
 2 Double-click on the Custom Component entry in the Templates palette.
 3 Click Create Attachment ( ). The Maple Custom Component template is loaded.
 4 In the Define Equations section, place your cursor in the first Maple command line (that is, the one containing eq), and then insert two document blocks (from the main menu, select Edit > Document Blocks > Create Document Block twice).
 5 Replace the contents of the first line with the following Maple command, and then press Enter at the end of the line. This command places the values from Table 6.3 into the list L.

$L≔\left[\left[0.01,0.0098\right],\left[0.02,0.00874\right],\left[0.03,0.00725\right],\left[0.04,0.005\right],\left[0.05,0.0025\right]\right]$

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

$f≔\mathrm{unapply}\left(\mathrm{CurveFitting}\left[\mathrm{LeastSquares}\right]\left(L,x,\mathrm{curve}=a\cdot {x}^{2}+b\cdot x+c\right),x\right)$

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

$\mathrm{eq}≔\left[P\left(t\right)=f\left(Q\left(t\right)\right)\cdot \mathrm{ρ}\cdot g,P\left(t\right)=\mathrm{Pr}\left(t\right)-\mathrm{Pl}\left(t\right),\mathrm{ρ}=1000,g=9.81\right]$

 8 In the Configuration section, select Ports.
 9 Click Clear All Ports.
 10 Click Add Port to add a port on the left edge. Select the Hydraulic type, and assign the Pressure variable to $\mathrm{Pl}\left(t\right)$ and the Volume Flow Rate variable to $Q\left(t\right)$.
 11 Click Add Port to add a port on the right edge. Select the Hydraulic type, choose style b, assign the Pressure variable $\mathrm{Pr}\left(t\right)$ and the Volume Flow Rate variable $-Q\left(t\right)$ [click the +/- button to change the sign].
 12 From the Icon list, select Use default, and then click Refresh All.
 13 In the Configuration section, select Parameters, and then click Refresh All.
 14 Change the default for $g$ to 9.81 and assign its type to Acceleration. For rho, change its default to 1000 and its type to Density. Click Refresh All.
 15 Select Variables, and then click Refresh All.
 16 Change the type for $P\left(t\right)$ to Pressure.
 17 Select Dimensional Analysis, and then click Check Dimensions. The following expression appears: $\frac{517}{50000}-\frac{13{Q\left(t\right)}^{2}}{5}⟦\frac{{m}^{6}}{{s}^{2}}⟧-\frac{137Q\left(t\right)}{5000}⟦\frac{{m}^{3}}{s}⟧$. This indicates a dimensional inconsistency, however, because it is benign we can leave it as is.  If you prefer to remove the inconsistency, you could replace $Q\left(t\right)$ in the original expressions with $\frac{Q\left(t\right)}{\mathrm{Q1}}$, assign the parameter $\mathrm{Q1}$ the default value 1 with type VolumeFlowRate, and protect it (add an X to the Protected column).
 18 In the Component Generation section, change the Name to CentrifugalPump.
 19 Click Generate MapleSim Component to create your component and to bring you back into the MapleSim environment. The custom component now appears in the Components palette in the Local Components tab ( ).
 20 Drag the custom component into the Model Workspace and create the model shown in Figure 6.12 using the specified model components and their settings from Table 6.5.

Tip: To attach the probe on the Circular Pipe component, right-click (Control-click for Mac) on component, select Attach probe, and then position the probe by clicking on the workspace.

Note: To display the pressure and volume flow rate quantities for your output, select the probe, and then select the Pressure and VolumeFlowRate quantities from the Properties tab.

 21 Click Run Simulation ( ) in the Main Toolbar.
 22 Click Show Simulation Results ( ).  The following graphs appear in the Analysis window.

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

In this tutorial, you will use the External C/Library Block app to import external C Code parameters and build your model by performing the following tasks:

 • Specify the custom component name
 • Specify the location of the external C/library
 • Define the external C/Library code options
 • Specify the directory of the generated Modelica code
 • Generate and save the external code custom component
 • Build the Simple External Function model

This model consists of three components: a Step function, a Constant Vector, and an External C Code/DLL custom component.

The external C Code parameters are defined by a function that takes in:

 • a double scalar input
 • an input double array of size 2
 • an output double array of size 3

and then returns a double scalar.

To create the external code custom component:

 1 Start a new MapleSim model that will call the external code.
 2 Select the Add Apps or Templates tab ( ).
 3 Double-click on the External C/Library Block entry in the Component Creation category of the Apps palette. The External C Code/Library Definition app opens.
 4 In the Code/Library Location section, for Source Location, select the Text Area radio button. Doing so opens a text area in which C code is to be entered. For a Windows platform, the initial content is the code shown in Figure 6.13.  For a Unix platform, the code is shown in Figure 6.14.

 Figure 6.13: External C Code Definition for Windows

 Figure 6.14: External C Code Definition for Unix

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

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

 16 In the Component Generation section, enter ExternalCode in the Block Name field.

 17 Click Generate Component. In MapleSim, the custom component appears in the Local Components tab ( ), located in the Components palette, on the left side of the MapleSim window.

To use the external code custom component:

 1 Using the specified model components and their settings from Table 6.6, drag the components into the Model Workspace and set their values.

Note:  Ensure that the model component parameter values are set in your model.  When you select a component in the Model Workspace, the configurable parameter values for that component aMoppear in the Properties tab ( ) located on the right side of the MapleSim window.

Table 6.6 shows the required components and their settings.

Table 6.6: External C Code DLL Custom Components and Required Settings
 Component Symbol Component Location Required Settings Custom Component Local Components > Components Use default settings Library Components > Signal Blocks > Sources > Real Constant output value, set $\mathbit{K}$ to $\left[\mathbf{5}\mathbf{,}\mathbf{8}\right]$ Library Components > Signal Blocks > Sources > Real Height: 4 Offset: 0 T0 : 5

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

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

 6 Click Run Simulation ( ) in the Main Toolbar.
 7 Click Show Simulation Results ( ).  The following graphs appear in the Analysis window.

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

6.7 Tutorial 7: Using the Equation Extraction App

In this tutorial, you will use the Equation Extraction App to extract the equations for a model by performing the following tasks:

 • Open the model
 • Open the Equation Extraction App
 • View, manipulate, and reassign equations

The Equation Extraction App contains pre-built embedded components that lets you extract, manipulate, and analyze the symbolic system equations generated by any MapleSim model.

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

App Description

The Equation Extraction App is a collection of pre-built controls and procedures associated with specific Maple commands to easily generate equations from MapleSim models.

The Equation Extraction App consists of two main areas, Equation Details and View Equations.

 Subsystem Selection This section loads the MapleSim model and shows all subsystems and their components.  From the toolbar, you can select a subsystem and load its subsystem equations. Load Selected Subsystem:  Loads the subsystem parameters and variables. If no subsystem is selected, equations for the whole model will be loaded when you click Load Selected Subsystem.

Equation Details

In this area you can customize and define ports, DAE variables, and parameters for the generated equations.

 Ports For acausal ports, you can configure a port so that either the flow-variable or the across-variable is considered an input (known). One of the two signals must be selected as input.  Select each port and then select either Flow or Across to specify which signal is the input.
 DAE Variables Select and rename DAE variables of interest.   Variables:  Contains the model DAE variables. New Name:  Rename a DAE variable by selecting the variable and specifying a new variable name in the New Name field. Keep:  Mark a variable of interest by selecting the variable and then selecting Keep.  If you use this feature, Extract Equations only displays equations of variables marked with Keep.  If no variables or parameters are marked as keep, all equations are displayed. Use Subscripts:  Use subscripted variable names. Reset Substitutions:  Restores the original names of all variables.
 Parameters Select and rename parameters of interest.   Parameters:  Contains the model parameters. New Name:  Rename a model parameter by selecting the parameter and specifying a new name in the New Name field. Keep:  Mark a parameter of interest by selecting the parameter and then selecting Keep.  If you use this feature, Extract Equations only displays equations of variables marked with Keep.  If no variables or parameters are marked as keep, all equations are displayed. Symbolic:  Specify which parameters are left in symbolic form.  By default, parameters are evaluated in the equations.  (Or, use Toggle Symbolic to toggle this setting for all parameters.) Use Subscripts:  Use subscripted parameter names. Reset Substitutions:  Restores the original names of all parameters.
 View Equations This area shows the system of equations in symbolic form with the assigned parameters. You can select which equations you want to look at by selecting one of the equation types (DAEs, Definitions, Relations, Events, ODEs, AEs). For more information about equation types, see GetEquations. The code edit region shows Maple code that can be used in a Worksheet template to access the equations.

Generating the Equations

For this example, we will use the model from the Example: Compliant Contact and Piecewise Functions, part of Tutorial 5: Using the Custom Component Template.  This model is also found in the  Help > Examples > User's Guide Examples > Chapter 6 menu.  In this model, a bouncing ball is analyzed using a prismatic joint to model a falling ball and a custom component to model the compliant ground contact using a spring-damper arrangement.

You will group these components into a subsystem to use in the Equation Extraction App.

Generating the System Equations

To generate the system equations:

 1 From the Help menu, select Examples > User's Guide Examples > Chapter 6, and then select Compliant Contact and Piecewise Functions.

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

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

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

The system equations appear in the View Equations area.

6.8 Tutorial 8: Modeling Hydraulic Systems

This tutorial provides you with a basic description of hydraulic systems and helps you understand how to model these systems in MapleSim. Using components from the Hydraulic library, you will create models, set initial conditions and component properties, and assign new values to parameters and variables.

The hydraulic components are designed primarily to convert hydraulic flow into mechanical motion, but can also be used to model pure hydraulic circuits.

In this tutorial, you will perform tasks based on the following basic principles and concepts:

 • Basic Hydraulic Library Components
 • Basic Hydraulic Equations
 • Analysis of Simple Hydraulic Networks
 • First Principles Modeling
 • Mechanical and Hydraulic Systems

The following sections provide conceptual models that you can build using the Hydraulic library components:

 • Controlling Hydraulic Flow Path
 • Actuating Multibody Systems with Hydraulic Components
 • Compressibility of Hydraulic Liquids
 • Fluid Inertia Models
 • Water Hammer Models
 • Hydraulic Custom Components
 Computational Issues Hydraulic networks tend to be numerically stiff. Generally, the stiff Rosenbrock solver is recommended.

Basic Hydraulic Library Components

This tutorial uses the following basic Hydraulic library components.

Table 6.7: Basic Hydraulic Library Components
 Component Symbol Library Location Its Use Hydraulics > Reference Components This component defines a base pressure (similar to ground in the electrical domain) and represents a connection to the atmosphere. Hydraulics > Reference Components All hydraulic models need a Hydraulic Fluid Properties component. Similar to a Parameter block, it is placed in the Model Workspace to define the following hydraulic fluid properties: • rhoFluid: fluid density • K: Bulk Modulus is the fluid compressibility • nuFluid: Kinematic Viscosity is the dynamic viscosity divided by liquid density Hydraulics > Actuators Actuators convert hydraulic flow into the motion of a mechanical body.  MapleSim offers a Hydraulic Cylinder (for translational motion) and a Hydraulic Motor (for rotational motion). Hydraulics > Sources You can specify either the flow rate or the pressure of the hydraulic source (with MapleSim calculating the other quantity). If a Pressure Source is used, then MapleSim balances the load in the hydraulic system against the pressure source to find the flow rate, and vice versa. Hydraulics > Restrictions The circular pipe introduces a pressure drop in a hydraulic line. The pressure drop is given by the Darcy equation, with the friction factor being determined by using predefined equations.

Basic Hydraulic Equations

The Bernoulli and the Darcy equations are the fundamental equations necessary to analyze hydraulic systems and define the fluid pressure and flow rate characteristics for any point along a flow. This tutorial uses the following basic fluid equations.

 • Bernoulli Equation
 • Darcy Equation
 • Friction Factor
 Bernoulli Equation The Bernoulli Equation defines the pressure and flow rate characteristics of incompressible fluid flow in a pipe. For any point along a streamline, the following relationship applies.

Darcy Equation

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

Hence

Table 6.8: Bernoulli and Darcy Equation Notation
 Symbol Description Units P Pressure $\mathrm{Pa}$ ρ Density $\frac{\mathrm{kg}}{{m}^{3}}$ g Gravitational constant $\frac{m}{{s}^{2}}$ V Velocity $\frac{m}{s}$ z Elevation $m$ L Pipe length $m$ D Pipe diameter $m$ f Friction factor dimensionless

Hence pressure must be applied to overcome internal frictional effects within the liquid (in laminar flow), and the effect of the surface roughness of the pipe (in turbulent flow). Frictional losses (and any other loads in the system) have to be balanced against the applied pressure to determine the flow rate.

In MapleSim’s mechanical-hydraulic systems, the vertical displacement (z) is insignificant compared to the other terms, and is ignored.

Friction Factor

In laminar flow, the internal frictional ($\mathbit{f}$) effect is determined by the following equations:

$\mathrm{Re}$ = $\frac{\mathrm{D}\cdot V}{v}$

where
is the internal friction

Re is the Reynolds number

D is the pipe diameter

V is the fluid velocity and

n is the dynamic viscosity

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

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

Table 6.9: Circular Pipe Parameters
 Symbol Description Values $L$ Pipe length $\mathrm{ε}$ Height of internal pipe roughness $\mathrm{ReL}$ Maximum Reynolds number in laminar regime $2000$ $\mathrm{ReT}$ Minimum Reynolds number in turbulent regime $4000$ $\mathrm{D}$ Pipe hydraulic diameter

Analysis of Simple Hydraulic Networks

This section simulates a simple hydraulic system and analyzes the results from first principles and explains how to:

 • Create a simple laminar pipe flow hydraulic system
 • Analyze the governing equations by applying various laws (for example, conservation of mass, Bernoulli Equation, Darcy Equation)

Flow Through a Pipe

Figure 6.15 analyzes pressure and laminar flow rate characteristics through a pipe when pressure is applied to overcome internal frictional effects.

To analyze flow through a pipe:

 1 Create the following model using the specified model components and their settings from Table 6.10.

Tip: To attach the probe on the Circular Pipe component, right-click (Control-click for Mac) on the component, select Attach probe, and then position the probe by clicking on the workspace.

 Figure 6.15: Flow Through a Pipe

Table 6.10: Hydraulic Components
 Component Quantity Symbol Library Location Values 2 Hydraulics > Reference Components Use default settings 1 Hydraulics > Reference Components Use default settings: rhoFluid:    $850\frac{\mathrm{kg}}{{m}^{3}}$ K:      nuFluid:    0.000018$\frac{{m}^{2}}{s}$ 1 Hydraulics > Sources Set P = 1 Hydraulics > Restrictions Use default settings
 2 Click the probe and select the Real (the instantaneous Reynolds number), Pressure, and VolumeFlowRate probe parameters.

 3 Click Run Simulation ( ) in the Main Toolbar.
 4 Click Show Simulation Results ( ).  The following graph appears showing the predicted flow rate of

 Confirming the Modeling Results from First Principles When analyzing the system shown in Figure 6.15, apply the Darcy equation. Assuming that the system is in laminar flow, then $f=\frac{64}{\mathrm{Re}}$ Hence   Where V = 0.0408 $\frac{m}{s}$   Using V in the flow rate equation yields the following result:    =   This is the same value given by MapleSim.  Using the calculated value of V gives Re= 22.7. This is far less than the critical value of 2000, and hence the system is in laminar flow.

Overview of Controlling Hydraulic Flow Path

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

Table 6.11: Spool Valve
 Spool Valve Name Description ID PortA PortB Area Upstream port Downstream port Real input; area of orifice in selected units portA portB Area

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

 Figure 6.16: Controlling Flow Path

Mechanical and Hydraulic Systems

In the following examples you will use multidomain components to simulate translational motion in mechanical and hydraulic models with the following sources:

 • Fixed Flow Rate Source
 • Fixed Pressure Source

Simulating Translational Motion with a Fixed Flow Rate Source

The following model converts flow from a fixed flow source to translational motion using the components and their settings from Table 6.12.

 Figure 6.17: Fixed Flow Rate Source

Table 6.12: Translational Motion with Fixed Flow Rate Sources
 Component Quantity Symbol Library Location Values 1 Hydraulics > Reference Components Use default settings 1 Hydraulics > Reference Components Use default settings: rhoFluid:    $850\frac{\mathrm{kg}}{{m}^{3}}$ K:      nuFluid:    0.000018$\frac{{m}^{2}}{s}$ 1 Hydraulics > Sources Use default settings 1 Hydraulics > Actuators Use default settings 1 1-D Mechanical > Translational > Common Use default settings 1 1-D Mechanical > Translational > Common Use default settings

Note: The Hydraulic cylinder has a cross-sectional area A of , while the Fixed Flow Rate has a flow Q of $1\frac{{m}^{3}}{s}$.

The cylinder pushes the sliding mass at a speed of

$V=\frac{Q}{A}$= = $1\frac{m}{s}$

This is confirmed by running the simulation and probing the speed of the sliding mass.

Simulating Translational Motion with a Fixed Pressure Source

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

 Figure 6.18: Translational Motion with Fixed Pressure Source

Table 6.13: Translational Motion with a Fixed Pressure Source
 Component Symbol Library Location Value Hydraulics > Sources Use default settings

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

= =

The acceleration of the Sliding Mass is given by:

= = 



Therefore,

$a=1\frac{m}{{s}^{2}}$

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

 Figure 6.19: Fixed Pressure Source Results

Overview of Actuating Multibody Systems with Hydraulic Components

In the following model, connect the 1-D translational port on the hydraulic cylinder to the 1-D translational port on the multibody prismatic joint using a translation fixed flange and a rigid body mass from Table 6.14. Use the default settings for each component.

 Figure 6.20: Translational Fixed Flange Hydraulic component

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

 Figure 6.21: Rotational Fixed Flange Hydraulic component

Table 6.14: Actuating Multibody Components
 Component Symbol Library Location Hydraulics > Sources 1-D Mechanical > Rotational > Common 1-D Mechanical > Translational > Common Hydraulics > Reference Components Hydraulics > Actuators Hydraulics > Actuators