3 Creating Custom Modeling Components

All Products Maple MapleSim

Home : Support : Online Help : MapleSim : User's Guide : 3 Creating Custom Modeling Components

3 Creating Custom Modeling Components

In this chapter:

•	Understanding Custom Components

•	Creating Custom Components with Signal-Flow Behavior

•	Creating Custom Components with Physical Connections

•	Working with Custom Components in MapleSim

•	Example: Creating a Nonlinear Spring-Damper Custom Component

3.1 Understanding Custom Components

Creating custom components extends the MapleSim component library, enabling you to create custom modeling components based on the mathematical models that you define. Custom components can use signals, ports with associated physical domains, or a combination of the two. You can also create libraries of custom components and create custom components to contain particular subsystems with specialized functionality.

For a complete tutorial on how to create domain specific custom components, see Tutorial 5: Using the Custom Component Template.

There are several different Custom Component templates. These are found in the Templates palette, under the Add Apps or Templates tab ( ).

Figure 3.1: The Add Apps or Templates tab

Creating a Simple Custom Component

The general process of creating a custom component for a MapleSim model consists of specifying the component equations for the custom component, component parameters and system model, specifying the port types and their values, and generating the component.

To create a custom component:

1.	Start a new MapleSim model and select the Add Apps or Templates tab ( ).

2.	From the Templates palette, double-click on Custom Component.

3.	Enter a name for the template in the Create Attachment window, and then click Create Attachment ( ). Maple opens with the DAE Custom Component template.

4.	In the Define Equations area, enter the equations for your custom component. Equations, parameters, and initial conditions are all entered here. Press Enter at the end of the line.

$eq ≔ [s (t) = sa (t) - sb (t), 0 = Fa (t) + Fb (t), Fa (t) = piecewise (s (t) < 0, K \cdot s (t) + B \cdot \frac{&DifferentialD;}{&DifferentialD; t} s (t), 0), K = 1000, B = 10]$

5.	In the Configuration section, select Parameters, click Refresh All, and then assign default values and types to model parameters.

6.	Select Variables, click Refresh All, and then assign initial values and types for model variables.

Select Ports, and then add ports to the custom components by clicking Add Port. You can also control the layout of ports and the icon to use for the custom component.
It is possible to define custom ports. To do so, you must first define the custom port using the Custom Port app. Then you can use the custom port in this app. For a complete tutorial on how to use custom ports, see Example: Custom Ports in Chapter 6.

8.	Provide the details for the port type, style, name, and port signals.

9.	In the Component Generation section, enter a name for the component. This will be the name given to the custom component in the Components palette, under the Local Components tab ( ) in MapleSim.

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

Typical Uses

The Custom Component template is the most general template and is specifically designed to help you create custom components from algebraic expressions, differential equations, or systems of differential-algebraic equations. The Custom Component Template is a collection of pre-built controls and procedures associated specific Maple commands to easily create new MapleSim components. In addition to the Custom Component, the Modelica Custom Component allows for the creation of a custom component via user-provided Modelica code.

Custom Component templates are more than just containers for your equations. You can also access all of Maple’s functionality to further develop your equations before you generate the Custom Component for your model. This includes access to Maple’s programming language, symbolic algebra functionality, and documentation tools to instantly analyze and verify the behavior of your component.

By using the Custom Component Template, you create a custom component in Maple by performing the following tasks:

•	Attach a custom component template to your model.

•	Define and enter your governing equations and properties that determine the behavior of the component (for example, parameters and port variables).

•	Specify ports for your component.

•	Define the associated port variable mappings.

•	Map variables from your equations to the ports.

•	Generate the component and make it available in MapleSim.

•	Test and analyze your mathematical model.

The Custom Component Template contains pre-built controls that allow you to perform these tasks with the same validation as for built-in components, preventing invalid connections and parameter values.

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

3.2 Creating Custom Components with Signal-Flow Behavior

Custom components simplify model construction by reducing the need to connect many signal-flow components together. This example shows how to create a custom component for a simple signal-flow equation.

Creating a Simple Signal-Flow Custom Component

Create a custom component that implements the following equation:

$x (t) = y (t) + z (t)$

To create a custom component

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

2.	In the Templates palette, double-click on Custom Component.

3.	Enter custom for the name of the attachment, and then click Create Attachment ( ).

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

$eq ≔ [x (t) = y (t) + z (t)] &semi;$

Note: The equation here is enclosed in square brackets because eq must be assigned a list of equations.

5.	Press Enter to register the equation.

Figure 3.2: Equations Defining a Custom Component

Tip: The equations in the custom component do not have to be rearranged into an explicit form. For example, you could replace the equation with:

$eq ≔ [x (t) + \log (x {(t)}^{2}) = y (t) + z (t)] &semi;$

for which there is no explicit solution for the output $x (t)$ . MapleSim solves for $x (t)$ automatically.

6.	In the Configuration section, select Ports, and then click Refresh All to update the tables.

7.	Click Clear All Ports.

8.	Add three new ports by clicking Add Port three times and then drag them into following positions.

Figure 3.3: Port Mappings

9.	Click on the top port on the left-hand side to select it.

10.	From the Type drop-down list, select Real Signal. For the Style, select the in radio button. The port is given the default name real_i.

11.	Next, associate a variable with the port signal. Select y(t) from the drop-down list as shown in Figure 3.4.

Figure 3.4: Variable to Port Mapping

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

Table 3.1: Port Map

Port Name	Port Location	Port Type	Port Style	Port Component
real_i	Top left	Real Signal	in	$y (t)$
real1_i	Bottom left	Real Signal	in	$z (t)$
real_o	Right	Real Signal	out	$x (t)$

13.	From the Icon list, select Use default.

14.	Under the Component Generation section, enter custom in the Name field.

15.	Click Generate MapleSim Component. The custom component equations are generated and assigned to the model. The custom component icon appears in MapleSim under the Local Components tab, in the Components palette.

Figure 3.5: Generated Custom Component

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

Table 3.2: Signal Flow Components

Component	Number of Components	Symbol	Library Location	Required Settings
Custom Component	1		Local Components ( ) > Components	Custom settings
Constant	1		Library Components ( ) > Signal Blocks > Sources > Real	Use default settings
Sine	1		Library Components ( ) > Signal Blocks > Sources > Real	Use default settings

17.	Connect two signal sources to the input ports on the left, and then place a probe on the right-most port (right-click and select Attach Probe), as shown below.

Figure 3.6: Completed Custom Component Model

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

Advantages of Acausal Mapping

Even though the custom component ports are specified as Signal Inputs and Signal Outputs, MapleSim is truly acausal; signals can be inputs or outputs regardless of the pin type. For example, if $x (t)$ and $z (t)$ were specified, and a probe was placed on $y (t)$ , MapleSim would automatically rearrange the specified equation into $y (t) = x (t) + z (t)$ .

The concept of signal inputs and outputs are necessary for the code generation capabilities of MapleSim, since the code is 'causalized', MapleSim expects inputs and provides outputs.

Using Differential Equations in Custom Components

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

Figure 3.7: Double Mass-Spring-Damper Equations

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

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

3.3 Creating Custom Components with Physical Connections

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

Table 3.3: Characteristics of Through and Across Variables

Characteristics of Through Variables

Characteristics of Across Variables

Conserved quantity (like heat or mass)

Has a direction of flow

Satisfies the relationship input = output + accumulation

Uniform across a domain

Drives the flow of the conserved quantity

Is a scalar

Defined as the difference between two points within a physical domain

Table 3.4 shows the mathematical relationships defining the connection between various across and through variables.

Table 3.4: Through and Across Variable Mathematical Relationship

Domain	Governing Equation	Through Variable	Across Variable
Ohm’s Law Electrical Domain	$I = \frac{V}{R}$	$I$	$V$
Hagen–Poiseuille equation Hydraulic Domain	$\frac{&DifferentialD; m}{&DifferentialD; t} = \frac{π D^{4} ρ}{128 L μ} \cdot P$	$\frac{&DifferentialD; m}{&DifferentialD; t}$	$P$
Fourier's law Thermal Domain	$\frac{&DifferentialD; Q}{&DifferentialD; t} = h A T$	$\frac{&DifferentialD; Q}{&DifferentialD; t}$	$T$

Deriving the System Equations for a Resistor

Table 3.5 shows a model of a simple resistor with several variables and one parameter.

Table 3.5: Resistor Variables and Parameters

Variable	Parameter	Description
i(t)		Current
v(t)		Voltage difference
vLeft(t)		Voltage on the left port
vRight(t)		Voltage on the right port
	R	Resistance

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

$v (t) = V_{right (t)} - V_{left (t)}$

$v (t) = i (t) \cdot R$

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

Figure 3.9: Resistor Port Mapping

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

3.4 Working with Custom Components in MapleSim

In MapleSim, you can work with a custom component in the same way as you would work with a subsystem. You can perform the following tasks:

•	Save a Custom Component as Part of the Current Model

•	Add a Custom Component to a Custom Library

•	Edit a Custom Component

•	Opening Custom Component Examples

Save a Custom Component as Part of the Current Model

When you save a model, the custom component is saved as part of the model. If you click the Edit menu > Prune Model... then any unused custom component definition will be removed from the model. To protect the custom component from potentially being cleaned up by the Prune Model feature, do one of the following:

•	Move the custom component from the Components palette of the Local Components tab to the Hierarchy palette.

•	Use the custom component in your model: drag the custom component from the Components palette to the Model Workspace.

For more information, see Using MapleSim > Building a Model > Pruning a Model in the MapleSim Help System.

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

Edit a Custom Component

If you want to edit a custom component that you have generated, make your changes in the corresponding Maple worksheet and regenerate the component.

To edit a custom component

1.	In the MapleSim Model Workspace, double-click the custom component that you want to edit. The corresponding Custom Component Template opens in Maple.

2.	In the Maple worksheet, edit the equations, properties, or port values.

3.	At the bottom of the worksheet, click Generate MapleSim Component. Your changes are generated in the custom component displayed in MapleSim.

4.	Save your changes in the .mw file and the .msim file where you added the custom component.

3.5 Example: Creating a Nonlinear Spring-Damper Custom Component

In this example, you will use the Custom Component Template to create a nonlinear spring-damper custom component. The equations defined in this example are based on the Translational Spring Damper component in MapleSim. In this case, the stiffness and damping coefficients are replaced with input functions to the component.

To obtain the governing relationships, you can start with a free-body diagram. The diagram for the spring-damper system is shown in the following figure.

Figure 3.10: Nonlinear Spring-Damper Custom Component

The end points, a and b, can be defined as the ports for the component; the equations are derived relative to these ports. Therefore, the general equation of motion is:

$d \cdot \frac{&DifferentialD;}{&DifferentialD; t} s_{rel} (t) + c \cdot s_{rel} (t) = F (t)$

where d is the damping coefficient, c is the stiffness of the spring, and s_rel is the relative displacement between the two ports s_a and s_b, can be written as:

$s_{rel} (t) = s_{b} (t) - s_{a} (t)$

Also, an examination of the net force on the system shows that $F (t) = F_{b} (t)$ , where,

$F_{a} (t) + F_{b} (t) = 0$

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

Opening the Custom Component Template

The Custom Component template is part of the MapleSim templates accessed from the Main Toolbar.

To open the custom component template:

1.	In MapleSim, open the model to which you want to add the custom component.

2.	From the main toolbar, click Load a Maple Worksheet ( ).

3.	Under Templates, double-click on Custom Component.

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

Defining the Component Name and Equations

You can now specify the name that will appear for the component in the MapleSim interface and define the equations.

To define the custom component:

1.	In the Equations section, define the nonlinear system by entering the following equations.

>	$eq ≔ [d (t) &ast; (diff (s_rel (t), t)) + c (t) &ast; s_rel (t) = F (t), s_rel (t) = s_b (t) - s_a (t), v_rel (t) = diff (s_rel (t), t), F (t) = F_b (t), F_a (t) + F_b (t) = 0] &semi;$

Note that the equations are entered in a Maple list. The constants, d (damping) and c (stiffness), are replaced by the functions d(t) and c(t) to define them as input states to the system.

2.	With your cursor on the equation, press Enter.

3.	In the Configuration section, select Variables, and then click Refresh All to see an updated list of variables.

You can now assign these input and output variables to ports that you will include in your generated custom component.

Defining Component Ports

In the Ports section of the template, you assign input and output variables to ports that will appear in the generated component, and specify the layout of these ports.

To define the ports:

1.	In the Configuration section, select Ports.

2.	Click Clear All Ports.

3.	Click Add Port four times. Four squares appear on the diagram. These represent the ports that you will lay out and define.

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

5.	Select the port on the left side of the diagram.

6.	From the Type drop-down menu, select Translational.

7.	For the style of the port, select b. The port's default name is tflange_b.

8.	First, define the signal position. Ensure Position = unassigned is selected in the list under Signal. From the drop-down list under Signal, select s_b(t).

9.	Next, define the signal force. Select Force = unassigned in the list under Signal. From the drop-down list under Signal, select F_b(t). The left port is now defined as a translational flange and associated with the position variable s_b(t) and force variable F_b(t).

10.	Select the port on the right side of the diagram.

11.	From the Type drop-down menu, select Translational.

12.	For the style of the port, select a. The port's default name is tflange_a.

13.	First, define the signal position. Ensure Position = unassigned is selected in the list under Signal. From the drop-down list under Signal, select s_a(t).

14.	Next, define the signal force. Select Force = unassigned in the list under Signal. From the drop-down list under Signal, select F_a(t). The right port is now defined as a translational flange and associated with the position variable s_a(t) and force variable F_a(t).

15.	Select the port at the top left of the diagram and then do the following.

•	From the Type drop-down menu, select Real Signal.

•	For Style, select in.

•	Change Name to cin.

•	Under Signal, select c(t) from the drop-down list.

This port is now defined as a signal input and associated with the stiffness variable c(t).

16.	Select the port at the top right of the diagram and then do the following:

•	From the Type drop-down menu, select Real Signal.

•	For Style, select in.

•	Change Name to din.

•	Under Signal, select d(t) from the drop-down menu.

This port is now defined as a signal input and associated with the damping variable d(t).

17.	From the Icon list, select Use default.

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

Checking Dimensions

This step is optional.

1.	In the Configuration section, select Dimensional Analysis, and then click Check Dimensions. Algebraic expressions in the system equations that are dimensionally inconsistent are displayed in the math-container.

2.	To correct the dimensions, select Variables, and then assign the following dimensions for the system variables in the Type column:

•	For c(t), enter Force/Distance.

•	For d(t), enter Force/Velocity.

•	For F(t), enter Force.

•	For s_rel(t), enter Length.

•	For v_rel(t), enter Velocity.

3.	Click Refresh All. The algebraic expressions Force/Distance and Force/Velocity are converted to the corresponding Modelica types, TranslationalSpringConstant and TranslationalDampingConstant, respectively (you could have entered these directly).

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

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

Generating the Custom Component

Generate the custom component to add it to the component to the Components palette in the Local Components tab.

1.	In the Component Generation section, enter NonLinearMSD in the Name text box.

2.	Click Generate MapleSim Component. The generated custom component appears in MapleSim in the Components palette of the Local Components tab ( ).

You can add the custom component to a model by dragging it into the Model Workspace as you would any other component.

3.	Save your MapleSim model as NonlinearSpringDamper.msim. Tutorial 3: Modeling a Nonlinear Damper in Chapter 6 uses this custom component in a model.

Contents Previous Next Index

Download Help Document

Maple

Maple Add-Ons

MapleSim

MapleSim Add-Ons

Systems Engineering

Consulting Services

Maple T.A. and Möbius

Education

Industries

Automotive and Aerospace

Robotics

Machine Design & Industrial Automation

Other

Application Areas

Product Pricing

Purchasing

Institutional Student Licensing

Maplesoft Elite Maintenance (EMP)

Support

Product Training

Online Product Help

Webinars & Events

Publications

Content Hubs

Examples & Applications

Community

About Maplesoft

Media Center

User Community

Contact

Online Help

All Products Maple MapleSim

Maple

Powerful math software that is easy to use

Maple Add-Ons

MapleSim

Advanced System Level Modeling

MapleSim Add-Ons

Systems Engineering

Consulting Services

Maple T.A. and Möbius

Education

Industries

Automotive and Aerospace

Robotics

Machine Design & Industrial Automation

Other

Application Areas

Product Pricing

Purchasing

Institutional Student Licensing

Maplesoft Elite Maintenance (EMP)

Support

Product Training

Online Product Help

Webinars & Events

Publications

Content Hubs

Examples & Applications

Community

About Maplesoft

Media Center

User Community

Contact

Online Help

All Products Maple MapleSim