Substitutions

$ Value Substitution Prefix Operator

% Data Substitution Prefix Operator

{ } Enfolding Braces

! Comment Operator

Substitutions are fundamental script operators that can appear in all parts of a definition.  They provide a means to communicate information between definition sections and segments, bring a dynamic aspect to component graphics, and to help in formatting code and comments.  

The substitution operators available are as listed below:

• Value Substitution Prefix: $

• • Contextual Substitution of Text

  • $#DIM: Substituting Port Dimension

  • $#Component: Substituting Component Instance ID

• Data Substitution Prefix: %

• Enfolding Operators (Braces): { }

• Comment Operator: !

$ Value Substitution Prefix Operator

The $ Value Substitution Prefix Operator (or simply '$') is the most important of the substitution operators, and is used quite heavily in component definition design.  The $ operator is normally pre-pended to a variable, where the variable may represent a numerical value (or even other text) that has been defined at some previous point in the evaluation process.  Regardless of what the variable represents, its value will be substituted whenever a $ operator is prefixed to it.

The $ operator may only precede variable names defined as one of the following:

• A port connection Symbol name

• An input parameter field, text field, or choice list Symbol name

• Any variable defined in the Computations segment

• A key name

There are numerous ways in which the $ operator may be utilized.  One method is the substitution of literal values, in place of a component variable name:  The literal value of component variable – be it a port connection, input parameter or Computations variable – will be directly substituted upon compilation.  Literal value substitution may also be used to format comments.

EXAMPLE 10-1:

The literal value entered into an input parameter field can be substituted directly into source code by prefixing $ to the Symbol name of the field.

NOTE:  The input parameter value substituted for freq is the resulting value following unit processing.  See the section entitled Unit System in Operations and Feature Overview for more details on units.

EXAMPLE 10-2:

The value of an output port connection entitled DataOut is defined by a Fortran statement.  Upon compile of the project, the internal compiler will declare a variable to represent the DataOut port connection in the associated Fortran file:  The $ operator will ensure that this new variable is substituted in the proper places.

EXAMPLE 10-3:

A user component utilizes a function, which requires an angle input argument in degrees to convert to radians.  The data input in this case is a port connection, defined in the Graphic section of the component definition, and has a Symbol name in.  The function output out is defined as an output port connection.

NOTE:  See the #FUNCTION Directive for more details on declaring Fortran functions.

EXAMPLE 10-4:

A user-defined component definition called my_new_comp has been programmed to display the contents of certain key input parameter fields, along with the definition name, within comments provided in the component Fortran segment, namely:  Frequency with Symbol name freq, value 60.0 and units in Hz, and Voltage with Symbol name volts, value 120.0 and units in kV.  Note that both freq and volts are local variables and so the local context short form is used.

When the component is evaluated, the Symbol names (freq and volts) are given the value entered in their respective fields.  In this case, freq = 60.0 and volts = 120.0.  The user is free to insert these variables elsewhere within the component script by using the $ operator.

Something similar to the following comments could appear in either the Fortran, DSDYN, or DSOUT segments:

This feature is excellent for formatting source code comments.

Literal values can also be substituted directly into text labels in the Graphic section, by using the $ operator.  This is a convenient feature, as it allows users to change text appearance on the component graphic according to say, for example, input parameters.  

EXAMPLE 10-5:

A user has created a single-phase, two-winding transformer component and wishes to display both the primary and secondary winding voltage ratings directly on the component graphic.  The primary voltage rating input parameter Vprim is entered as 25.0 [kV] and the secondary input Vsec is set at 4.0 [kV] as shown below:

In the component Graphic section, the user adds two new text labels (positioned accordingly) and enters $Vprim and $Vsec as shown below:

When the component instance is viewed on the Circuit canvas, input parameter values for Vprim and Vsec will appear directly on the component graphic.  For this example,

Contextual Substitution of Text

Contextual substitution is a formal way of handling text substitutions from other contexts outside the definition.  Contextual substitution is enabled by inserting delimiting symbols following the $ operator.  The standard syntax is as follows:

$(<Context>:<Key>)

The substitution contains both a <Context> and item <Key> separated by a scope operator and delimited by parentheses, where:

• <Context>:  The context that is to be used to scope the item <Key>.  See below for a list of valid <Context> names.  

• <Key>:  Item key (actual substitution) that is to be placed at the substitution point.  See below for a list of valid <Key> names.

Contextual substitution may be used in text labels within the Graphic section, as well as comments in the Fortran, DSDYN, DSOUT, Branch, Model-Data, Matrix-Fill, Transformers, or T-Lines segments.  In addition, it may also be used to substitute global substitutions and various keys under their respective contexts.

The following table lists all valid context names that may be used in place of <Context> and <Key> as described above (both Context and Key names are case sensitive):

When using substitutions within the context of the component instance, there is no need to include the <Context> identifier and it hence may be excluded along with the scope operator.  In such cases the syntax is:

$(<Key>) or simply $<Key>.

EXAMPLE 10-6:

A user has created a definition and wants to display the current user on the component Graphic.  A text label is added the Graphic section, which contains a $ operator extracting the required information.

$#DIM: Substituting Port Dimension

The dimension of any connection port may be substituted as an integer directly into the component script using the $#DIM operator. The $#DIM operator may appear in Fortran, DSDYN, DSOUT and the Checks segments. This operator must appear in the following format:

$#DIM(<Node_Name>)

Where:

• <Node_Name>:  The connection port Symbol name.

An example usage of this operator is presented below:

$#Component: Substituting Component Instance ID

The instance ID number of any component instance may be substituted using the $#Component operator. The $#Component operator may appear in Fortran, DSDYN and DSOUT segments. This operator must appear in the following format:

$#Component

The primary purpose of this operator is to provide the instance id of the calling component to EMTDC for the purpose of defining a messaging source. In this way, PSCAD can provide a navigable link in the build messages pane if a message is generated by a specific component. An example usage of this operator is presented below:

% Data Substitution Prefix Operator

The % Data Substitution Prefix Operator (or simply '%') can be used to make a direct text substitution.  Data substitution is very similar to the $ Value Substitution Prefix Operator, except that it substitutes the exact contents of an input parameter as text, and may only be used to substitute input parameters.

The % operator may be used in text labels within the Graphic section, as well as within commented code in the Fortran, DSDYN, DSOUT, Branch, Model-Data, Matrix-Fill, Transformers, or T-Lines segments.

EXAMPLE 10-7:

Consider Example 10-4 above, but replace the $ operator with the % operator.  The following comments could then appear in either the Fortran, DSDYN or DSOUT segments:

EXAMPLE 10-8:

Consider Example 10-5 above, but replace the $ operator with the % operator in the new text labels.  When the component instance is now viewed on the Circuit canvas, values of the input parameters Vprim and Vsec will appear on the component graphic as follows:

{ } Braces

Braces can be used to perform mathematical, logical and formatting operations before all other definition script is considered by the compiler.  Braces can appear all over the component definition.  There are two main forms in which braces may be used:  Expression substitution and block processing.  The brace syntax is as follows:

[$]{<Expression>}

Where:

• $:  Optional.  Optional.  The $ Value Substitution Prefix Operator is not required in some instances, such as in most block processing operations.

• <Expression>:  Can be a mathematical expression, or simply a block of text.  

It is important to note that mathematical and logical operations within braces are performed prior to the insertion of code into the Fortran or Data files.  Subsequently, these operations cannot involve variables – only literals and constants (such as constant input parameters, local constants, or constants defined in the Computations segment).

Although simple examples are provided here, you can find more examples by studying the definitions of master library components.

EXAMPLE 10-9:

The following example shows how expression braces can be used within text labels:  A mathematical operation is performed on substituted values.  Say that two input parameters are entered as Symbol names A1 and A2 with values 2.0 and 3.0 respectively.  The user wants to display another value, based on these values, directly on the component graphic as follows:

Text Label = A1*A2 = 6.0

The following is entered into the text label properties dialog:

EXAMPLE 10-10:

A user has modified the function PH_CON in Example 10-3 to include phase angle conversion in both directions (i.e. degrees to radians and radians to degrees).  In the component Parameters section, a choice list with Symbol name Ptype is designed with two options as shown below:

The function PH_CON is modified to include a second argument indicating the conversion type required, based on the state of Ptype.  The additional argument is a character string, where D2R indicates degrees to radians conversion and R2D radians to degrees.  Braces are used, along with a #CASE directive and ~ Line Continuation Operator:

RT_1 and RT_2 are variable substitutions given by EMTDC:  Their names may vary.

! Comment Indicator

The exclamation point is used throughout the component definition segments to indicate that a particular line of code is a comment.  All lines of script preceded by this operator will be considered source comments for inclusion in the project Fortran or Data files.

NOTE:  Commented code that is written to the data file, requires that the Comment Indicator be in the first column from the left.

EXAMPLE 10-11:

Comments should be used to describe the user's code, as well as to provide spacers and section breaks in order to enhance readability.  The comment indicator may be used everywhere except the Branch segment.

The following example illustrates the use of comments in the Fortran or DSDYN segments in the a user component definition:

NOTE:  See the #STORAGE Directive for more details.