Using the MapleSim DAE Custom Component Template - MapleSim Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : MapleSim : Using MapleSim : Building a Model : tasks/building/definingCustomComponent

Using the MapleSim DAE Custom Component Template

The Custom Component template simplifies the process of creating a MapleSim custom component from Maple equations.  A custom component can also be created by using MapleToModelica and the MapleSim API.

The following sections describe the use of the corresponding sections of the template.

 

Equations

Parameters

Variables

Ports

Dimensional Analysis

Component Generation

Example using the Custom Component Template

Equations

Use this section to define the equations of the custom component.

• 

Assign the global variable eq the system equations.

– 

The equations may be a list or set of equations, or a DynamicSystems system object.

– 

If equations are given, the system variables must be functions of t, the independent time variable.

– 

Parameters, which can be assigned default numeric values, are represented as symbols. See the Parameters section, below, for assigning parameter values.

– 

Initial equations that relate variables can be specified by using, say, x0 and Dx0 to refer to the initial value and derivative, respectively, of the variable xt.

– 

Initial conditions on variables should be specified via the data-table in the Variables section, see below.

– 

A typical assignment is eq:=it=Cⅆⅆtvct,vt=Rit+vct,vc0=Ri0.

Equation Expressions

• 

You can express conditionals as Maple piecewise expressions. For example, a unit-step at t&equals;1 can be expressed as piecewiset<1&comma;0&comma;1.

• 

The noEvent function can be wrapped around an expression to prevent it from otherwise triggering an event during simulation.  For example, noEventpiecewisext<1&comma;1&comma;xt prevents an event from occurring when xt crosses 1.

Parameters

Use this section to assign default values and types to the model parameters.

• 

To initialize the table, assign eqs (see above) and click the Refresh All button.

• 

The table displays the parameters of the model equations. Change the values by directly editing the entries.

• 

The Default column contains the default values for the parameters. The standard default is 1.

– 

A default value may consist of an algebraic expression of other parameters, including parameters not used elsewhere; they will be added to the table when the Refresh All button is clicked.

• 

The Type column specifies the type of each parameter.

– 

The basic types are boolean, integer, and real, with real being the default.

• 

The Protected column specifies whether the parameter is protected or public.

– 

An "X" in the column indicates the parameter is protected.

– 

To protect a parameter, enter any value except 0 in the cell then click Refresh All.

– 

To unprotect a protected parameter, either enter a 0 in the cell or delete the content of the cell, then click Refresh All.

– 

By default all parameters are public.

– 

Protected parameters do not appear in the MapleSim Properties tab.

• 

The Description column contains strings that describe the parameter; these become the roll-over text when hovering over a parameter in the MapleSim Properties tab.  The initial value is the name of the parameter.

• 

The Sort column provides a means to rearrange the row-order of the table.

– 

The row-order of the table determines the order that the parameters appear in the MapleSim Properties tab.

– 

By default, the table is sorted alphabetically by the parameter names.

– 

To change the order, enter integers into the sort column corresponding to the row to which the row should move, then click Refresh All.

Type Reference

Use this section to search for available SI types.

• 

To display the proper SI units in the Properties tab and allow a dimensional analysis of the model (see Dimensional Analysis, below), a real parameter can be given a specialized type.

• 

To view the available types, open the Type Reference subsection, select a domain from the Domain list, then search the Types list.  Selecting a dimension copies it to a text box, from where you can cut and paste it into the table.

Variables

Use this section to assign initial values and types for model variables.

• 

To initialize the table, assign eqs (see above) and click the Refresh All button.

• 

The table displays variables in the model equations. Click Refresh All after reassigning eqs, modifying port assignments, or changing entries in this table.

• 

The Guess column contains guess-values for the initial values of the variables.  The standard default is no guess-value. Guess-values are used during initialization to determine a valid initialization state.

• 

The Enforced column specifies whether the guess-value of the variable is enforced, which means it must be initialized to that value.

– 

To enforce the guess value of a variable, enter any value except 0 in the Enforced column, then click Refresh All.

– 

To remove the enforcement, either enter a 0 in the Enforced column, or delete the content of the cell, then click Refresh All.

– 

By default, none of the guess-values are enforced.

• 

The Type column specifies the type of each variable.

– 

The basic types are boolean, integer, and real, with real being the default.

– 

Port variables, that is, those associated with a port signal, are automatically typed. Signals associated with acausal ports cannot be retyped, but those associated with real ports can be.

– 

The types of non-port variables can be replaced with a specialized type to allow a dimensional analysis of the equations (see Type Reference and Dimensional Analysis, below).

• 

The Protected column specifies whether the variable is protected or public.

– 

An "X" in the column indicates the variable is protected.

– 

To protect a variable, enter any value except 0 in the cell then click Refresh All.

– 

To unprotect a protected variable, either enter a 0 in the cell or delete the content of the cell, then click Refresh All.

– 

By default all variables are public.

– 

Protected variables cannot be probed.

• 

The Description column contains strings that describe the variable.  The initial value is the base name of the variable.

• 

The Sort column provides a means to rearrange the row-order of the table.

– 

The row-order of the table determines the order that the variables appear as probes in the MapleSim probe tool.

– 

By default, the table is sorted alphabetically by the variable names.

– 

To change the order, enter integers into the sort column corresponding to the row to which the row should move, then click Refresh All.

Type Reference

Use this section to search for available SI types.

• 

To allow a dimensional analysis of the model (see Dimensional Analysis, below), you can give a variable a specialized type.

• 

To view the available types, open the Type Reference subsection, select a domain in the Domain list, then search the Types list.  Selecting a dimension copies it to a text box, from where you can cut and paste it into the table.

Ports

Use this section to assign the icon and ports of the component.

• 

Click Add Port to add a port.

– 

A new port will appear in the plot.

– 

Drag it to the desired position on the boundary of the component. If the Snap to Grid check box is selected, the port will snap to the nearest grid location. That ensures that the resulting component will have its ports aligned with the main MapleSim grid.

• 

Select the port type in the Type drop-down list.

– 

To specify a custom type, select custom, enter the name of the custom type into the text box that appears, and then click Apply Custom.

A custom port can be created with the Custom Port template. For details, see the Creating Custom Modeling Components chapter of the MapleSim User's Guide.

• 

Choose the style of the port by selecting one of the radio buttons.

• 

If the chosen port type is causal (real, boolean, or integer), the Dimension text box appears.  Use it to assign a dimension to the port; the default is 1.

• 

Specify a name for the port by editing the Name field. A suggested name is given, based on the port type and style.

• 

Click Delete Port to delete a selected port.

• 

Click Clear all Ports to delete all ports.

Signals

• 

Use the Signal field and related components to associate port signals with system variables.

– 

The signal types and associated variables appear in a drop-down list.

– 

The variable of the signal selected in from the list also appears in the Signal field.

– 

Unassigned signals have unassigned as the variable name; all signals must be assigned to generate a component.

• 

Click an entry in the drop-down list to select that signal.

– 

Choose a variable for it by picking one from the drop-down list or typing directly into the text box and clicking Assign.

– 

Variables are inert functions of time, for example, xt.

– 

Click the button marked +/- to negate the signal.

• 

You can enter all the variables of a port in the Signal text box by entering them as a list.  For example, if the port has two signals, say voltage and current, you can type [v,i](t) into the text box and click Assign, assuming your system has variables named vt and it.

Icon

• 

Use the Icon Size radio buttons to change the size of the icon.  You can use this setting to increase the number of port positions that are on-grid.

• 

Clear the Snap to Grid check box to allow positioning ports off-grid.

• 

You can select a custom icon for the component using the Icon drop-down list. There are three default options:

– 

Use default : Use the default icon image.

– 

Copy component : Copy an icon from an existing component. A text area embedded component appears below the drop-down list. Enter the fully qualified path name of a Modelica component in the text area. For example, Modelica.Electrical.Analog.Basic.Resistor.

– 

External image : Attach an external image file and use it as the icon. A file dialog opens. Navigate to the desired image file.

Any image files attached to the MapleSim document are also shown in the drop-down list.  Select one to use it as the icon image.

Dimensional Analysis

Use this section to perform a dimensional analysis of the model equations to ensure that the units are consistent.

• 

Click Check Dimensions.  This checks dimensions of each of the equations of the generated Modelica code.  If there are no inconsistencies, the message no issues found is displayed. Otherwise the portions of the equations that are inconsistent are displayed, each on a separate line.  Units are attached to the inconsistent portions to indicate the problem.

• 

The use of this section is optional.  An inconsistency in the units/dimensions of the generated Modelica code does not prevent it from being generated nor used, but it may indicate a design problem with the equations.

Component Generation

Use this section to create the custom component.

• 

Enter the name for the custom component in the Name field. The name cannot contain spaces or special characters (for example, & and *).

• 

Click Preview Modelica to see the Modelica code for the generated component.

• 

Click Generate MapleSim Component to generate the component (this also updates the Modelica code preview). In MapleSim, the custom component is available under the Components palette in the Definitions tab.

Example using the Custom Component Template

• 

For examples using this template, refer to the Creating Custom Modeling Components chapter of the MapleSim User's Guide.

See Also

Creating Custom Modeling Components

Managing Subsystems and Custom Components

 


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam