Custom Statements

Custom statements allow advanced users to expand the set of MotionSolve model elements by adding new standard model element vocabulary. Custom statements can be mapped to one or more model elements.

Custom statements can be mapped to elements of the same type or of different types. You can choose the element name as well as the attribute names.

When a custom element has the same name as a pre-defined MotionSolve model element, the custom model element takes precedence. In other words, custom model elements override pre-defined model elements.

For instance, consider a PID controller:

The PID controller calculation involves three separate parameters: proportional, integral, and derivative values:

Proportional value determines the reaction to the current error and is represented by:(1) $K [u]$
Integral value determines the reaction based on the sum of recent errors:(2) $\frac{1}{s} [u] = x_{1}$
Write this equation in another form:(3) ${\dot{x}}_{1} = u$
Derivative value determines the reaction based on the rate at which the error has been changing, having two parts:(4) $C [u] = x_{3}$
Alternatively:(5) $x_{3} - C [u] = 0$
And:(6) $s [x_{3}] = x_{2}$
Alternatively:(7) ${\dot{x}}_{3} - x_{2} = 0$
The weighted sum of these three actions is used to adjust the process via a control element, such as the position of a control valve:(8) $x_{1} + x_{2} + K [u] = y$

The proportional, integral, and derivative terms are summed to calculate the output of the PID controller.

Thus, you get the custom element (8) with three Control_Diffs (one explicit and two implicit) and one Reference_Variable.

Create a Custom Statement

Edit the mapping file.

An entry is made to the mapping file declaring the custom function as shown in the image below:

Figure 2. Editing the Mapping File to Declare a Custom Function

Figure 3.

The general syntax for the CustomElement element is as follows:

<CustomFunction
   SYMBOL              = "string"
  <Attribute
    ID                 = "integer"
    NAME               = "string"
    TYPE               = "string"
    DEFAULT            = "real"
  />
... (to be repeated for each attribute)
  <Component
    ID                 = "integer"
    CTYPE              = "string"
[In addition, all attributes needed to define the Component completely based on its type]
/>
... (to be repeated for each component)
/>

Table 1. Children. ATTRIBUTE: Specifies the definition of a particular attribute of the custom element.
Attribute	Description
ID	Attribute identification number, (integer>0). This is a number that is unique among all attributes of the custom element.
NAME	Name of the attribute that needs to be used in the MotionSolve XML.
TYPE	Specifies the data type for the value of the attribute.
DEFAULT	Specifies the default value to be used for the attribute.

Table 2. Children. COMPONENT - Specifies the definition of a particular component of the custom element.
Attribute	Description
ID	Component identification number, (integer>0). This is a number that is unique among all components of the custom element.
CTYPE	Specifies the type of the component. Supported component types include: Non-Usersub Cases GRAPHICS MARKER PART POINT_MASS STRING Single Usersub Cases GFOSUB VFOSUB VTOSUB SFOSUB FIESUB CURSUB SURSUB UCOSUB GCOSUB MOTSUB REQSUB VARSUB DIFSUB SENSUB SEVSUB SPLINE_READ GRASUB Multiple Usersub Cases CNFSUB, CFFSUB [either one is good (and equivalent)] COUSUB [maps to COUSUB/COUXX/COUXX2] GSESUB

Define the path to the mapping file.
1. Modify the environment variable Variable name as MS_CUSTOM_MAPPING_FILE to point to the mapping file, as shown in the image below:
  
  Figure 4. Set the Environment Variable
Create VARSUB and DIFSUB-like user-written subroutines and build a DLL as shown in the image below:

Figure 5. User Defined Subroutine, DLL, and Corresponding XML Files

Figure 6.

From this point forward, the VARSUB function name for the PID controller is VAR_PID and the DIFSUB function names are DIF_PID1, DIF_PID2, and DIF_PID3. These are the custom functions that can be used in models just like pre-defined MotionSolve functions. You can use them anywhere in a model as you would a standard, MotionSolve model element.

For instance, the element on the left in the image below is internally interpreted by MotionSolve into the set of elements shown on the right.

Figure 7. Internal and Custom Representations

MotionSolve internally interprets custom elements using a combination of standard elements, according to the instructions in the mapping file. Click <Save/> to check the resultant mapping.