Contents Previous Next Index
6 MapleSim Tutorials
MapleSim Tutorials help you get started with MapleSim and learn about the key features, tools, templates and systems available in MapleSim, by leading you through a series of descriptive tasks, problems and examples using best practices. Many of these examples 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:
Tutorial 1: Modeling a DC Motor with a Gearbox
Tutorial 2: Modeling a Cable Tension Controller
Tutorial 3: Modeling a Nonlinear Damper
Tutorial 4: Modeling a Planar Slider-Crank Mechanism
Tutorial 5: Using the Custom Component Template
Tutorial 6: Using the External C Code/DLL Custom Component App
Tutorial 7: Using the Equation Extraction App
Tutorial 8: Modeling Hydraulic Systems
6.1 Tutorial 1: Modeling a DC Motor with a Gearbox
In this tutorial, you will extend a DC motor model and perform the following tasks:
Add a gearbox to the DC motor model
Simulate the DC motor with gearbox model
Group the DC motor components into a subsystem
Use a Parameter Block to assign global parameters to the model
Add signal block components and a PI controller to the model
Simulate the modified DC motor model using different conditions
Adding a Gearbox to a DC Motor 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.
To add a gearbox:
From the Help menu, select Examples > User's Guide Examples > Chapter 1, and then select the Simple DC Motor example.
Delete the existing probe from the workspace.
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.
Connect the components as shown in the following figure.
In the Model Workspace, click the Ideal Gear component.
In the Properties tab ( ), change the transmission ratio, r, to 10 and then press Enter to accept the value.
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 104N⋅m⋅srad.
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:
From the Model Workspace Toolbar, click Attach probe ( ).
Hover your mouse pointer over the line that connects the Elasto-Backlash component and the second Inertia component (I3). The line is highlighted.
Click the line once, and then click a spot in the workspace to anchor the probe.
Select the probe in the Model Workspace.
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.
Click a blank area in the Model Workspace.
Under the Settings tab ( ), set the td parameter to 10 seconds and press Enter.
Click Run Simulation ( ) in the Main Toolbar.
Click Show Simulation Results ( ). The following graphs appear in the Analysis window.
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:
Draw a box around the electrical components and the first inertia component by dragging your mouse over these components.
From the Edit menu, select Create Subsystem.
In the Create Subsystem dialog box, enter DC Motor.
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:
Click Main ( ) in the Model Workspace Toolbar to browse to the top level of the model.
In the Model Workspace, double-click sysParams ( ) to switch to the Parameter Default Settings view.
In the first row of the Main subsystem default settings table, enter Rglobal in the Name field and press Enter.
Specify a default value of 24 and enter Global resistance value as the description.
In the second row of the table, enter Jglobal in the Name field and press Enter.
Specify a default value of 10 and enter Global moment of inertia value as the description.
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.
Select Make Parameters Available for Rerun.
In the Model Workspace, select the Inertia component I3.
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).
Double-click the 'DC Motor' subsystem.
In the Model Workspace, select the EMF1 component.
Properties tab ( ), in the Value field for k, the transformation coefficient, enter Rglobal ⋅ Jglobal10 and press Enter.
Note: This value is an approximation of the transformation coefficient.
Similarly, in the Properties tab ( ) for the R1 component, in the Value field for the resistance parameter, enter Rglobal and press Enter.
Click Main ( ) to browse to the top level of your model.
Save the model as DC_Motor2.msim.
Press Play ( ) to run the simulation.
Rerunning the Simulation with Different Parameter Values
You can use Parameter Blocks to make specific parameters tunable allowing you to rerun simulations without having to perform a full reformulation.
Since Make Parameters Available for Rerun was selected, you can make updates to these parameters in the Rerun Simulation Panel, where you can explore and compare the results that these changes have on the simulation.
Click the Rerun Simulation tab ) on the left side of the Analysis Window to bring you to the Rerun Simulation panel.
Change the value of Jglobal to 5.
Press the Rerun button ( ) to rerun the simulation with the new value for Rglobal.
Plots of the Latest Results and Latest Rerun simulations are available for comparison in the Probe Plots window.
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:
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.
Right-click (Control-click for Mac) the Rotational Speed Sensor component and select Flip Horizontal.
Delete the connection line between the Step source and the DC Motor subsystem.
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.
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.
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.
Click the PI component in the Model Workspace.
In the Properties tab ( ), specify a gain of 20 in the k field, and a time constant of 3 seconds in the T field.
Simulate the model again. When the simulation is complete, the following graphs appear.
Save the model as DC_Motor3.msim.
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:
Open the DC_Motor3.msim file that you created in the previous tutorial and save the file as Cable_Tension.msim.
Delete the probe attached to the line that connects the Elasto-Backlash and Inertia components.
Delete the Rotational Speed Sensor component and its connection lines.
Select the Ideal Gear, Elasto-Backlash, and Inertia components and group them into a subsystem called Gear Components.
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.
Right-click (Control-click for Mac) the Fixed component in the Model Workspace and select Rotate Counterclockwise.
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.
Double-click the 'Gear Components' subsystem. You will now add a port to connect this subsystem with other components.
Click the negative (white) flange of the Inertia component and drag your mouse cursor to the boundary that surrounds the subsystem components.
Click the line once. The subsystem port is added to the line.
Click Main ( ) in the Model Workspace Toolbar to browse to the top level of your model.
Specifying Component Properties
To specify component properties:
In the Model Workspace, double-click the 'Gear Components' subsystem.
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.
Double-click the sysParams Parameter Block to open the Parameter Settings editor.
In the Parameters Settings editor specify the following parameter values for the other components:
Name the first parameter Spring. Select Real for the Type, and enter 2110⋅109 as the Default Value. Press Enter.
Name the second parameter Time, select Real for the Type, then enter 0.1 for the Default Value. Press Enter.
Name the third parameter Constant, select Real for the Type, then enter 77.448 for the Default Value.
Select the Spring component in the Model Workspace, then select the Properties tab.
In the c field, enter Spring.
Next, select the PI controller from the Model Workspace, then select the Properties tab.
In the T field, enter Time.
Next, select the Constant source from the Model Workspace, then, as before, select the Properties tab.
In the k field enter Constant.
Select sysParams in the Model Workspace, then select the Properties tab.
Ensure that Make Parameters Available for Rerun is selected.
As mentioned in Tutorial 1: Modeling a DC Motor with a Gearbox, you can use Parameter Blocks to make specific parameters tunable allowing you to rerun simulations without having to perform a full reformulation.
Since Make Parameters Available for Rerun was selected in step 8, you can make updates to these parameters in the Rerun Simulation Panel, where you can compare the results that these changes have on the simulation.
Change the value of Spring to 1.0⋅109.
Simulating the Cable Tension Controller
To simulate the cable tension controller:
Click Attach probe ( ).
Click the line that connects the Feedback and PI components and then click the workspace to position the probe.
In the Properties tab ( ), select the Real quantity and change its name to Error.
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
In the Settings tab ( ), specify the following parameters:
Set the simulation duration time, td, to 5s.
Select Variable from the Solver Type drop-down menu.
Select Rosenbrock (stiff) from the Solver drop-down menu.
Click the Run Simulation ( ) in the Main Toolbar.
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:
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.
Save the file as DamperCurve.xlsx or DamperCurve.csv.
In MapleSim, open the NonlinearSpringDamper.msim model you created in Example: Creating a Nonlinear Spring-Damper Custom Component in Chapter 3.
Select the Attachment Files tab ( ).
Right-click (Control-click for Mac) Data Sets and select Attach File.
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:
Select the Local Components tab ( ), and then drag the NonLinearMSD custom component into the Model Workspace.
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.
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.
Figure 6.2: Nonlinear Damper Model
In the Model Workspace, select the Lookup Table 1 D component.
Under the Properties tab ( ), select attachment from the data source list.
Select the attachment you created (either DamperCurve.xlsx or DamperCurve.csv) from the data list.
In the Model Workspace, select the Constant component.
In the Properties tab, in the Name field, change the component name to Stiffness.
Select the Step component, and then set height to 100.
Select the Mass component, and then change the mass, m, to 100kg.
Draw a box around all of the components in the nonlinear damper model.
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:
In the Model Workspace, double-click the 'Nonlinear Damper' subsystem.
In the Model Workspace Toolbar, double-click sysParams( )
In the first row of the Parameter default settings view, define a spring constant parameter called Ks, and then press Enter.
In the same row, specify the Type as Translational Spring Constant, define a default value of 1000, enter Nmas Default Units and enter Spring constant as the Description. You can now assign the parameter value Ks to other components in the Nonlinear Damper subsystem.
In the Model Workspace Toolbar, click Diagram View ( ). The Ks parameter appears as a field in the Properties tab with the defined default value.
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:
From the Model Workspace Toolbar, click Attach probe ( ). The cursor changes to the probe icon when you move into the workspace.
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.
In the Model Workspace, select the probe.
Under the Properties tab ( ), select the length, speed, and acceleration quantities.
Click a blank area in the Model Workspace. The length, speed, and acceleration quantities (s, v, a) appear beside the probe.
Double-click the 'Nonlinear Damper' subsystem.
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.
Under the Properties tab, select the Real quantity and change its name to Damping.
Under the Settings tab ( ), set the td parameter to 10 seconds.
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
Creating a Planar Link Subsystem
The preceding diagram shows that the slider-crank has two associated planar links: the crank (the link from point A to B) and the connecting rod (the link from B to C). In both cases, 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 −L2 units along the x-axis of the link, and the outboard port (tip) will be located L2 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:
Open a new MapleSim document.
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.
In the Model Workspace, right-click (Control-click for Mac) one of the Rigid Body Frame components, and then select Flip Horizontal.
Right-click (Control-click for Mac) the Rigid Body component, and then select Rotate Counterclockwise.
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.
Draw a connection line between the RB1 component and the right frame of the RBF1 component.
Draw another connection line between the RB1 component and the left frame of the RBF2 component.
Draw a box around the components by dragging your mouse over them.
In the Create Subsystem dialog box, enter Link, and then click OK.
You will now add ports to connect this subsystem to other components.
Double-click the Link subsystem.
Click the left frame of the RBF1 component and drag your mouse pointer to the left of the subsystem boundary.
Click the line once. A subsystem port is added.
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:
If you are not already in the Link subsystem, click Main ( ) in the Model Workspace Toolbar, and then double-click the Link subsystem.
In the Model Workspace Toolbar, click Parameters ( ), or from the Properties tab ( ) click Add or Change Parameters. The Standalone Subsystem default settings window appears.
In the first row of the Standalone Subsystem default settings table, enter L in the Name field, and then press Enter.
Specify a default value of 1 and enter Length as the description.
Scroll to the RBF1 component section.
In the Value field for r&conjugate0;, specify a position offset of −L2, 0, 0, and then select m from the Units drop-down menu. To enter a fraction, use the forward slash key (/).
Scroll to the RBF2 component section.
In the Value field for r&conjugate0;, specify a position offset of L2, 0, 0, and then select m from the Units drop-down menu.
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:
Click Main ( ) in the Model Workspace Toolbar to browse to the top level of your model. The Link subsystem appears in the Model Workspace.
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.
Select the Link1 shared subsystem in the Model Workspace and in the Properties tab ( ), enter Crank in the Name field.
From the Local Components tab, drag the Link icon to the Model Workspace, placing it to the right of the Crank shared subsystem.
In the Model Workspace, select the second copy of the Link shared subsystem.
In the Properties tab ( ), change the shared subsystem name to ConnectingRod. See the following figure.
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:
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.
From the same menu, select the Rigid Body component and place it slightly below and to the right of the ConnectingRod shared subsystem.
Add the following joints:
From the Multibody > Joints and Motions menu, add a Revolute joint between the Fixed Frame component and the crank, a second Revolute joint between the 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.
Select the Rigid Body component in the Model Workspace and rename it SlidingMass.
Right-click (Control-click for Mac) the SlidingMass component and select Flip Horizontal.
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.
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:
For the first revolute joint (R1 in the preceding figure), in the q0 field, change the initial angle to π4rad.
Tip: To enter π, type pi, press Esc , and then select the π symbol from the menu.
From the ICq,w drop-down menu, select Strictly Enforce.
When MapleSim solves for the initial conditions, the first angle will be set to π4rad before the angles are set for the other joints.
Simulating the Planar Slider-Crank Mechanism
To simulate the planar slider-crank mechanism:
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.
Click the probe in the Model Workspace.
In the Properties tab ( ), select the Length quantity to measure the displacement.
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).
In the Settings tab ( ), expand Simulation and set the td parameter to 10 seconds.
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.
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
Enter your governing equations
Set initial conditions by specifying the component properties
Assign new values to parameters and variables
View, manipulate, and reassign equations
Simulate and translate an equation to a transfer function
Map variables from your equations to the ports
Specify ports for your block
Create a custom port using the Custom Port app
For a description of the Custom Component Template see Creating Custom Modeling Components.
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 rt=R0⋅1+Tt−T02Tk2, where R0, T0, and Tk are parameters.
To create the custom component:
Start a new MapleSim model and then, in the main toolbar, click Load a Maple Worksheet ( ).
Double-click on the Custom Component entry in the Templates palette.
Enter TempResistor and then click Create Attachment ( ). The Maple Custom Component template is loaded.
In the Define Equations section, enter in the following system equations to define your component. Press Enter at the end of the line.
eq≔vt=vpt−vnt,rt=R0⋅1+Tt−T02Tk2,vt=it⋅rt,qdott=it⋅vt;
In the Configuration section, select Parameters, and then click Refresh All.
Select Ports in the Configuration section.
Click Clear All Ports.
Click Add Port. A new port appears on the left side. This will become the positive electrical pin.
From the Type drop-down list, select Electrical.
Click the Style radio button labeled +.
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.
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.
Click Add Port. A new port appears on the right side. This will become the negative electrical pin.
From the Type drop-down box, select Electrical.
Click the Style radio button labeled -. This changes the port style to an unfilled box.
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.
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.
Click Add Port. A new port appears on the top edge. Drag the port to the center of the bottom edge.
From the Type drop-down box, select Thermal.
Click the Style radio button labeled a.
Select T(t) for the Temperature variable and qdot(t) for the Heat Flow Rate variable.
From the Icon list, select Use default.
In the Configuration section, select Variables, and then click Refresh All. This updates entries in the Type column of the Variables table.
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.
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).
In the Configuration section, select Parameters.
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.
In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The message "no issues found" should appear in the text area.
In the Component Generation section, change the Name to TempResistor.
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.
Drag the custom component into your model area.
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.
Component
Symbol
Component Location
Required Settings
TempResistor Custom Component
Local Components > Components
Use default settings
Constant Voltage
Library Components > Electrical > Analog > Common
Ground
Thermal Resistor
Library Components > Thermal > Heat Transfer Components
Set R = 10 K/W
Heat Capacitor
Set C = 0.1 J/K Set T__0 = 280K
Fixed Temperature
Library Components > Thermal > Sources
Set T = 298K
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
Select the probe, select the Properties tab ( ), and then select the following quantities:
Current
ThermoDynamicTemperature
HeatFlowRate
Resistance
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
fx=K st+Bdstdt, if st < 0
fx=0 if st ≥ 0
Enter contact for the name of the attachment and then click Create Attachment ( ). The Maple Custom Component template is loaded.
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.
eq≔st=sat−sbt, 0=Fat + Fbt, Fat=piecewisest<0, K⋅st + B⋅ⅆⅆ t st,0;
In the Configuration section, select Ports.
Click Refresh All.
Click Add Port.
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).
Click Add Port to add a second port to the right side.
Make the right port a Translational type. Select style b. Associate its Position variable with sb(t) and its Force variable with Fb(t).
In the Configuration section, select Variables.
In the table, change the Type of s(t) to Position, and then click Refresh All.
Change the Default value for B to 10.
Change the Default value for K to 1000, and change its Type to real.
In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The following expression appears: Bⅆⅆtstm3 kgs2 A+Kstm. 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.
Select Parameters, and then enter Force/Velocity and Force/Distance for the types for B and K, respectively.
Click Refresh All. The types update to the equivalent dimensional types, TranslationalDampingConstant and TranslationalSpringConstant.
Select Dimensional Analysis, and then click Check Dimensions. "No issues found" will appear.
In the Component Generation section, change the Name to contact.
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 ( ).
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
Custom Component
Rigid Body
Library Components > Multibody > Bodies and Frames
Fixed Frame
Prismatic
Library Components > Multibody > Joints and Motions
For the prismatic joint to translate along the y direction, set
ⅇ⏞1 to 0,1,0
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
s0 to 10m
When the simulation is complete, the Simulation Results tab of the Analysis window displays the probe plot.
Figure 6.8: Bouncing Ball Result
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.
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.
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 ft = ptvt. For the dummy vehicle model we will assume the power is constant, pt=P, and the velocity is given by vt=v0+a⋅t, where P, 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.
Start a new MapleSim model, and then in the main toolbar, click Show Apps Manager ( ). The Analysis window opens with Apps tab selected.
Double-click on the Custom Port entry under Component Creation in the Apps palette. The Maple Custom Port Definition app is loaded.
In the Configuration section, select Signals, and then click Add Signal to add a new signal.
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.
Click Add Signal again to add a second signal.
Enter v as the signal name, enter Velocity as the type, select the output radio button, and enter Vehicle velocity in the desc column.
In the Generate Port section, enter bus_out in the Name field, vehicle bus port as a Description, and select the output radio button.
Click Generate MapleSim Port to create the output port. You will automatically return to your MapleSim model.
Return to the same app to create the input port.
In the Signals section, for both signals, select the input radio button and click Apply.
In the Generate Port section, change bus_out to bus_in and click the input style radio button.
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.
In MapleSim, in the main toolbar, click Load a Maple Worksheet ( ).
Double-click on the Custom Component entry in the Templates palette, and then click Create Attachment ( ). The Maple Custom Component template is loaded.
In the Define Equations section, enter the following system equations to define your component, and then press Enter at the end of the line.
eq≔pt=P, vt=v0+a⋅t
Change the Type fields for P, a, and v0 to Power, Acceleration, and Velocity, respectively.
Click Add Port. A new port appears on the left edge. Drag it to the right edge.
From the Type drop-down menu, select Custom. (It is at the bottom of the list.)
In the text area below the Type drop-down menu, enter bus_out.
Select the out style radio button.
Click Apply Custom.
Using the drop-down menu and list box at the bottom of this section, assign the power signal to pt and the velocity signal to vt. Figure 6.10 shows the completed Ports section of the template.
Figure 6.10: Using a Custom Port
In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. The message no issues found should appear.
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
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.
eq≔ft=ptvt
Select Ports, and then click Clear All Ports.
Click Add Port. A new port appears on the left edge. This will be the bus input.
From the Type drop-down menu, select Custom (at the bottom of the list).
In the text area below the Type drop-down menu, enter the custom type name: bus_in.
Using the drop-down menu and list box at the bottom of this section, assign the power signal to pt and the velocity signal to vt.
Click Add Port. A new port appears on the right edge. This will be the computed force output.
From the Type drop-down menu, select Real Signal. Click the out style radio button. Assign the value signal to ft.
In the Configuration section, select Variables, and then click Refresh All.
Enter Force for the Type field of signal ft.
Select Dimensional Analysis, and then click Check Dimensions. The message real_ot=ftN should appear. It indicates that the output port, real_ot, is a real signal but is equated to ft, which has units of force (Newtons).
In the Component Generation section, change the name to monitor.
Click Generate MapleSim Component.
Complete Model
In MapleSim, drag the engine and monitor components from the Components palette in the Local Components tab ( ) into the workspace.
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.
Run the simulation. The Simulation Results tab in the Analysis window shows the following probe plot:
Advanced Uses for Custom Components
You can use the entire range of Maple functionality to derive your system equations in the Custom Component template. This section provides a sample advanced application.
Example: Modeling a Centrifugal Pump from a Head Flow Rate Curve
The following hydraulics example demonstrates how to apply extrapolated data from 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
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
Description
Value
D
Pipe hydraulic diameter
0.01 m
L
Pipe length
5 m
ε
Height of internal pipe roughness
1.5⋅10−5 m
ReL
Maximum Reynolds number in laminar regime
2000
ReT
Minimum Reynolds number in turbulent regime
4000
Its Use
Tank
Library Components > Hydraulics > Reference Components
This component defines a base pressure (similar to ground in the electrical domain) and represents a connection to atmosphere.
Hydraulic Fluid Properties
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: 850kgm3
K: 8000 bar
nuFluid: 0.000018m2s
Circular Pipe
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)
This custom component defines hydraulic pressure and flow rate properties for the hydraulic line.
User defined
Figure 6.12: Centrifugal Pump Custom Component
Click Create Attachment ( ). The Maple Custom Component template is loaded.
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).
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≔0.01,0.0098,0.02,0.00874,0.03,0.00725,0.04,0.005,0.05,0.0025
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≔unapplyCurveFittingLeastSquaresL,x,curve=a⋅x2+b⋅x+c,x
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.
eq≔Pt=fQt⋅ρ⋅g,Pt=Prt−Plt,ρ=1000,g=9.81
Click Add Port to add a port on the left edge. Select the Hydraulic type, and assign the Pressure variable to Plt and the Volume Flow Rate variable to Qt.
Click Add Port to add a port on the right edge. Select the Hydraulic type, choose style b, assign the Pressure variable Prt and the Volume Flow Rate variable −Qt [click the +/- button to change the sign].
From the Icon list, select Use default, and then click Refresh All.
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.
Select Variables, and then click Refresh All.
Change the type for Pt to Pressure.
Select Dimensional Analysis, and then click Check Dimensions. The following expression appears: 51750000−13Qt25m6s2−137Qt5000m3s. 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 Qt in the original expressions with QtQ1, assign the parameter Q1 the default value 1 with type VolumeFlowRate, and protect it (add an X to the Protected column).
In the Component Generation section, change the Name to CentrifugalPump.
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.
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:
Start a new MapleSim model that will call the external code.
In the main toolbar, click Show Apps Manager ( ). The Analysis window opens with Apps tab selected.
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.
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
Select the Attachment radio button just above the code edit region.
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.
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.
Click Validate C to validate the code.
In the Configuration section, select Function, and then enter f1 for the Function Name.
Click Add Parameter, set the Name to a and click Apply to apply the changes to the selected parameter.
Click Add Parameter, set the Name to b, select the Array? box, set Dim to 2 and click Apply.
Click Add Parameter, set the Name to c, select Passed by Reference, select the Array? box, set Dim to 3 and click Apply.
In the Configuration section, select Return.
Use the following values for the C function return parameter.
In the Component Generation section, enter ExternalCode in the Block Name field.
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:
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 appear in the Properties tab ( ) located on the right side of the MapleSim window.
Table 6.6 shows the required components and their settings.
Constant Vector
Library Components > Signal Blocks > Sources > Real
Constant output value, set K to 5,8
Step
Height: 4
Offset: 0
T0 : 5
Connect the Step component to custom component input port a.
Connect the Constant Vector component to custom component input port b.
Attach a probe to the custom component output port c and enter the following values:
Attach a probe to the custom component output port r and enter the following values:
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
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:
From the Help menu, select Examples > User's Guide Examples > Chapter 6, and then select Compliant Contact and Piecewise Functions.
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.
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.
From the toolbar, select the sub subsystem.
Click Load Selected Subsystem. The subsystem's component ports, DAE variables, and parameters load automatically in the Ports, DAE Variables, and Parameters areas.
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.
This tutorial uses the following basic Hydraulic library components.
Library Location
Hydraulics > Reference Components
This component defines a base pressure (similar to ground in the electrical domain) and represents a connection to the atmosphere.
• rhoFluid: fluid density
• K: Bulk Modulus is the fluid compressibility
• nuFluid: Kinematic Viscosity is the dynamic viscosity divided by liquid density
Hydraulic Motor
Hydraulic Cylinder
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).
Fixed Flow Rate
Fixed Pressure Source
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.
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
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.
pρ⋅g+ V22⋅g+z=constant
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.
▵P = f⋅L⋅V2D⋅2⋅g
Hence
pρ⋅g+ V22⋅g+z+f⋅L⋅V2D⋅2⋅g=constant
Units
P
Pressure
Pa
ρ
Density
kgm3
g
Gravitational constant
ms2
V
Velocity
ms
z
Elevation
m
Pipe diameter
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.
In laminar flow, the internal frictional (f) effect is determined by the following equations:
f =64Re
Re = D⋅Vv
where f 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.
f=11.8 log106.9Re+ε3.7⋅D1.112
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.
Values
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:
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
Quantity
2
1
Use default settings:
Set P = 1⋅103 Pa
Click the probe and select the Real (the instantaneous Reynolds number), Pressure, and VolumeFlowRate probe parameters.
Click Show Simulation Results ( ). The following graph appears showing the predicted flow rate of Q = 3.21⋅10−6m3s.
Confirming the Modeling Results from First Principles
When analyzing the system shown in Figure 6.15, apply the Darcy equation.
ΔPρ⋅g=f⋅L⋅ V2D2 g
Assuming that the system is in laminar flow, then
f=64Re
1⋅103850×9.81=640.01× V0.000018×50.01 × V22 × 9.81
0.1199256461=2.935779816 V
Where
V = 0.0408 ms
Using V in the flow rate equation yields the following result:
Q =14 VπD2 = 0.0408×π×0.01 24=3.2 x 10−6 m3s
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.
Spool Valve
Name
ID
PortA
PortB
Area
Upstream port
Downstream port
Real input; area of orifice in selected units
portA
portB
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
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
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
Mass
1-D Mechanical > Translational > Common
Translational Fixed
Note: The Hydraulic cylinder has a cross-sectional area A of 1 m2, while the Fixed Flow Rate has a flow Q of 1m3s.
The cylinder pushes the sliding mass at a speed of
V=QA= 1 m3s−11 m2 = 1ms
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
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.
F=A ⋅ P = 1 m2 ⋅ 1 Pa = 1 N
The acceleration of the Sliding Mass is given by:
F=m ⋅a = 1 m2 ⋅ 1 Pa = 1 N
1 N = 1 kg⋅a
Therefore,
a=1ms2
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
Rotational Fixed Flange
1-D Mechanical > Rotational > Common
Translational Fixed Flange
Multibody > Joints and Motions
Rigid Body Frame
Multibody > Bodies and Frames
Revolute
Pascal's Principle
Pascal's Principle states that pressure applied to a closed hydraulic system is transmitted everywhere equally. This principle shows that an applied force can be amplified to move loads that would otherwise not be possible.
The model in Figure 6.22 demonstrates a simple example of Pascal's Principle. A 1 N force (acting on a 0.1 m2 hydraulic cylinder) transmits hydraulic pressure to a 1 m2 hydraulic cylinder, which lifts a 1kg load vertically. Normally, a 9.81 N force maintains the height of a 1 kg force, but this simple hydraulic system multiplies the magnitude of a 1 N load by a factor of 10 or 1 m20.1 m2.
Figure 6.22: Pascal's Principle Example
Overview of Compressibility of Hydraulic Liquids
The compliant cylinder and constant volume chamber components (Table 6.16) model the compressibility of hydraulic liquids under high pressure. The compliant cylinder component also models pipe wall compliance. Both have to be attached to a node between pipes or inertias as shown in Figure 6.23.
Figure 6.23: Hydraulic Liquids Compressibility
Signal Pressure
Linear Resistance
Compliant Cylinder
Hydraulics > Chambers
Constant Volume
Overview of Fluid Inertia Models
The Fluid Inertia component models the inertia of liquid accelerating or decelerating in a pipe and is analogous to mechanical inertia. Fluid Inertia can be significant for large diameter pipes and when the acceleration/deceleration is large. This component is useful when modeling water hammer.
Fluid Inertia
System without Fluid Inertia
Figure 6.24 shows a system without fluid inertia.
Figure 6.24: System without Fluid Inertia
System with Fluid Inertia
Figure 6.24 shows a system with fluid inertia.
Figure 6.25: System with Fluid Inertia
Figure 6.26 shows typical system flow rates with (green) and without (red) fluid inertia. Introducing fluid inertia adds a lag into the system.
Figure 6.26: System with and without Fluid Inertia
Overview of Water Hammer Models
Water hammer occurs when a valve suddenly stops (or significantly restricts) flow in a pipe, resulting in a pressure surge due to a momentum change in the fluid inertia. This pressure surge bounces off the closed valve and travels up and down the pipe, potentially causing significant damage to the entire pipe. Water hammer is traditionally modeled by the numerical solution of the following equations.
dVx,tdt+1ρdPx,tdt+fVx,tVx,t2 D
dVx,tdx+1KsdPx,tdt=0
Ks=11K+DEt
Where:
V(x,t) is the pipe velocity
P(x,t) is the pipe pressure
r is the liquid density
t is the pipe wall thickness
K is the liquid bulk modulus
E is Young’s modulus for the pipe
f is the friction factor
These equations (with the appropriate boundary and initial conditions) are typically solved numerically, requiring custom code to solve the equations using the method of characteristics.
Example: Water Hammer
Another method of simulating water hammer involves building a lumped parameter pipeline model. The pipeline model includes effects such as flow inertia, flow resistance (through pipe friction), pipe compliance, and fluid compressibility.
The following figure shows a discretized pipeline with inertial and resistive properties, initially pressurized at one end to create flow. After two seconds, a valve at the other end is closed, resulting in a pressure surge.
Figure 6.27: Water Hammer
Each subsystem consists of a compliant cylinder, a pipe, and a fluid inertia component as shown in Figure 6.28. A pipeline (of total length L and volume V) with N segments has N+1 pipes, each with a length,
LN+1
N+1 fluid inertia components, each with a length,
N constant volume chambers, each with a volume,
VN
Figure 6.28: Discretized Pipeline Segment
To build the water hammer model:
Build the model with the components and connections shown in Figure 6.27 and Figure 6.28.
Configure the Fluid Properties component with the values specified in Table 6.18.
Parameter Name
rhoFluid
Fluid density
1000 kg m-3
K
Fluid bulk modulus
200 106 Pa
nuFluid
ν
Fluid kinematic viscosity
10 −3rhoFluid m2s
Configure the parameter block with the parameters and values shown in Table 6.19.
N
Number of pipe segments
20
Dia
Pipe hydraulic diameter (D)
0.1 m
Len
Pipe Length
25 m
Em
Pipe Young's modulus (E)
70 109 Pa
ef
Pipe internal roughness
0.0001 m
thickness
Pipe wall thickness (t)
0.001 m
For the Fixed Pressure component (FP2 in Figure 6.27), set the pressure (P) to 500kPa.
Configure the Circular Pipe components in Main and the HydraulicPipeline shared subsystem with the following settings.
Setting
LenN+1
ε
Configure the Fluid Inertia components in Main and the HydraulicPipeline shared subsystem with the following settings.
A
14π Dia2
Configure the Compliant Cylinder component in the HydraulicPipeline shared subsystem with the following settings.
α
0
k
1.4
LenN
Do
Dia + 2*thickness
For the First Order component, under the Properties tab ( ), set T to 0.01s and y0 to 0.01.
Configure the Step component with the following settings.
For height, enter -0.009999.
For offset, enter 0.01.
For T0, enter 2s.
Under the Settings tab, configure the following Simulation parameters.
For td, enter 3s.
For Solver Type, select Variable.
For Solver, select Rosenbrock (stiff).
Figure 6.29 plots the pressure and flow rate at the end of a pipe for a valve that rapidly closes after 2 seconds.
Figure 6.29: Water Hammer Pressure Flow Rate
The maximum pressure is about 5 x 106Pa, with the liquid reaching a flow rate of 0.099m3s. The maximum pressure can also be calculated using the Joukowsky equation,
∆P=ρc∆QA
c=Keρ
Ke=11K+DEt
If you substitute the parameters from Table 6.18 and Table 6.19 into the preceding equations, and then assume:
∆Q=0.099m3s
you get
∆P ≈ 5×106Pa
This result agrees with the MapleSim model.
Example: Attenuating Water Hammer with an Accumulator
A hydraulic accumulator is a reservoir, often located near a valve, that stores non-compressible hydraulic fluid under pressure. An accumulator acts as a safety valve by allowing fluid to enter the reservoir when the pressure increases beyond a certain threshold value. This action attenuates the magnitude and frequency of the pressure waves.
MapleSim does not have a built-in accumulator block, but this functionality is easily modeled with the Custom Component template using the following equations. For a complete description on how to create custom components, see Creating Custom Modeling Components.
eq≔qt=VF.t,VFt=Ksptpt≤pprVpr+k⋅pt−pprppr<ptandpt<pmaxVmax+Ks pt−pmaxpmax≤p(t),k=Vmax−Vprpmax−ppr
params ≔ Vmax=0.1,ppr=105,pmax=3⋅106,Ks=4⋅10−10,Vpr=0
initialconditions ≔ VF0=0
Vmax
ppr
100000
Pmax
3000000
Ks
10 x 10−10 m
Vpr
The following figure shows the same pipeline with a pressure accumulator. After two seconds, a valve at the other end is closed, resulting in a pressure surge. Figure 6.30 shows the pressure surge at the end of a pipeline with an accumulator.
Figure 6.30: Pressure Surge with an Accumulator
Overview of Hydraulic Custom Components
Two examples of hydraulic custom components are centrifugal pumps and vertical pipes. For a complete description on how to create custom components, see Creating Custom Modeling Components.
Centrifugal Pumps
Typically, manufacturers provide head flow rate charts for centrifugal pumps, as shown in Figure 6.31.
Figure 6.31: Head Flow Rate
Data from these charts is easily implemented into a custom component.
To implement chart data:
Read several sets of head flow rate points from the plot.
Fit these data points to a polynomial using the Maple curve-fitting functionality.
Implement the polynomial into a custom component. Figure 6.32, for example, shows the custom component equations for a centrifugal pump (including the best-fit parameters).
Note: Since the equation is a polynomial, several solutions may exist.
Figure 6.32: Centrifugal Pump Custom Component Equations
Note: Assigning the value rhoFluid to the Density parameter sets the density to be the value defined in the Hydraulic Fluid Properties component.
Vertical Pipes
Since gravity head is usually insignificant in mechanical-hydraulic systems, the base pipe component in MapleSim does not model vertical pipe travel. For low-pressure systems, gravity head can be significant. Figure 6.33 shows the custom component equations to simulate gravity head.
Figure 6.33: Gravity Head Custom Component Equations
Download Help Document
