Module Input Parameters
Import Connection Components on Canvas
Module Definitions and Instances
A Practical Example of Multiple Module Instances in Use
Important Design Considerations
Runtime Configuration in EMTDC
Since its introduction in PSCAD V3, the module (also known as a sub-page or page module) has been a useful tool in enhancing the organization and navigation of projects. Modules are themselves components, but possess a canvas of their own, and thereby add a third dimension to an otherwise flat environment. Their inception was in response to the growing size of simulation drawings in PSCAD V2, where a two-dimensional drawing canvas proved cumbersome when dealing with larger projects.
The original modules however lacked an important attribute of their standard component counterparts: The ability to be instantiated (i.e. two or more instances based on the same definition). This was primarily due to complications in the mapping of data signals, such as plotted curves and meter outputs. In addition to this, a module definition could potentially be part of other module definitions, and there was again a difficulty in tracking multiply-instanced modules of this kind. Essentially, the architecture of the software was, at the time, not optimized for this sort of thing and as a result, the ability to instantiate a module was restricted to a single instance for simplicity, thereby making the definition and single instance one in the same.
The absence of the ability to multiply-instance modules remained throughout the life of both the V3 and V4 releases, but was finally remedied in PSCAD X4. This was made possible by a complete rework of the PSCAD program architecture towards a more data-centralized model. This new architecture greatly simplified the mapping and bookkeeping involved in allowing effective use of multiple instance modules. A module may now be copied and pasted easily just like any other component, even if it contains many module components within it!
The capabilities of this feature may not be immediately obvious, but if not properly utilized it can be dangerously powerful. For example, if a module containing say 100 Output Channel components is instantiated, 100 new signals would be added for every instance. This can quickly overwhelm the memory capacity of your workstation, and/or greatly affect simulation speed. This becomes even more apparent if the module being copied contains other modules that contain more Output Channels. This section is designed to ensure that projects with multiple instance modules are designed properly from the very beginning, thereby avoiding problems like that described above.
With the establishment of multiple instance module capabilities in PSCAD, it was also a prudent time to introduce parameter functionality as well. As veteran users know, module components did not support parameters in the past, and relied purely on port connections to transfer data signals into and out of the canvas. Parameter dialogs can now be designed for module components in the exact same manner as they are for standard components, and every instance of a module component may possess unique parameter values.
When it comes to porting parameter values onto or from the canvas, they are treated in exactly the same way as port connections – that is, each parameter requires a matching Import or Export component on the canvas. The name of the Import or Export component must match the Symbol name of the corresponding parameter.
|
|
Module Input Parameters |
Import Connection Components on Canvas |
For more details on designing component parameter dialogs, see The Parameters Section.
Modules and standard components are now more alike than ever: They both may possess input parameters, they both have graphics; in fact they are indiscernible from each other unless their definition is edited. The only major difference between them is that module components possess a canvas, whereas the standard components contain a section for scripting.
|
Schematic |
Graphic |
Parameters |
Script |
Standard Component |
û |
ü |
ü |
ü |
Module Component |
ü |
ü |
ü |
û |
Similarities between Modules and Components
The table above hints that module components simply offer an alternative way in which to build a model: With a module component, the design is accomplished graphically via a circuit schematic, as opposed to using script and code. In fact, modules must utilize standard or user-defined components in their design – components that are pieced together to form the circuit model.
Since the concept of modules and project hierarchy was introduced, the root or top-level canvas has always been what is referred to as the Main page. Anyone who has used PSCAD in the past has constructed a circuit starting from the Main canvas. Main is itself a module component and its canvas is part of its definition. Therefore, any modifications made to Main modify its definition, which in turn affects any instances of it. Of course, Main only ever has one instance, as it is the top-level module, and it, along with its definition, are included for you automatically whenever a new project is created.
The Schematic canvas is an integral part of a module component definition, and so changes made to this canvas are changes made to the definition. If a component is added to the module canvas (or deleted from it), its location moved, or even if its input parameter values are modified, the module definition is affected. This is because the components, wires and other objects combine to define what the module is meant to represent or model. By extension then, all module component instances, based on this definition, will be affected by changes to the definition. For more seasoned users, this concept may be a bit difficult to grasp at first, as in the past, module components were never allowed to possess more than one instance. Because of this fact, modules were always unique (one definition, one instance) —not so any more.
|
Multiple Instances Based on a Single Module Definition |
With standard, non-module components, it is easy to differentiate between the components definition and instance environments; its definition is composed purely of script and code, parameters and graphics, and of course does not include a canvas. In other words, it is obvious that you are inside the definition environment when you edit the definition of a standard component. This is not true when dealing with module components. A module component utilizes a canvas to represent its definition, but at the same time, that canvas is used as part of the hierarchy of the greater circuit, meaning that one or more instances of that module component may appear in the project, all of which are used in a unique context.
Every component, graph, control panel, etc. that is placed on a module canvas, becomes part of that module's definition. If a plot panel is resized, or a new graph is added to the panel, it modifies the definition. Changing graph settings, curve colours, zoom settings all affect the definition. The same goes for control panels, meters and online controls. If a Slider component interface for example is adjusted (say from 0.12 to 0.23), it affects the definition and therefore all of the module instances based on it. This is because the Slider component interface is defined or sourced directly on the module canvas.
It is important to distinguish between the settings of plotting and control tools, and the actual signals themselves. The signals being displayed on graphs or meters may not necessarily be defined purely as part of the module definition. If a signal is sourced from within a module, say for example a breaker control signal, and is not influenced in any way by signal values external to the module, then the signal value will be identical in all module instances based on that definition. However, if the signal value is based or influenced by an external signal, such as an imported parameter, then the signal value may change depending on the module instance (or context), and in such cases may be considered an instance-based signal. This means that although the curve colour or thickness of a curve is a definition-based setting —and will be identical in every instance— the actual data signal values are unique from one module instance to another. This allows us to visualize the concept of a definition canvas and instance context, as a base layer canvas, with a transparent overlay representing the context of each module instance.
|
Module Definition Canvas with Data Values in Two Unique Instance Contexts |
The image below shows the subtle differences between data signal values in two, separate instances of a module – both are based on the same definition. Notice that the graph and curve settings are identical (i.e. colour, glyphs, etc.), but their values are slightly different. This is because the data signals plotted are sourced from outside the module canvas, and are ported in through an input parameter or port connection.
|
Same Graph from Two Separate Module Instances Based on the Same Definition |
Before continuing on, it would be prudent to pause and look at a practical situation where multiple module instances could be put to good use. Consider a three-phase bridge unit that is to be used in the construction of a monopolar HVDC system. The system will utilize four bridge units in total, where each unit is identical and comes from the same manufacturer.
|
Monopolar HVDC System with Four Converter Bridge Units |
Since the converter bridges are all identical, it makes sense that a bridge unit only be defined once, and used multiple times. This helps to alleviate maintenance headaches and to ensure that changes made to one unit are applied to all. Veteran PSCAD users will understand that this concept has been utilized since the beginnings of the application; up until recently however, this has been accomplished only through the use of standard (non-module) components. In fact, the master library already includes a bridge component called 6 Pulse Bridge. This component may be instantiated many times when constructing systems like that shown above.
|
|
6 Pulse Bridge Component Graphic |
6 Pulse Bridge Equivalent Circuit |
Standard components however are limited in flexibility, in that if they are to be combined with other components to form another single device, they must be reprogrammed into a single unit (i.e. combining two bridge units in series to form a 12-pulse converter for example). Reprogramming these models can prove cumbersome depending on the complexity of the model. With module components however, the reprogramming is performed for you by the application; the user is left to simply construct a circuit graphically.
Let us conceptually build a three-phase bridge from scratch, using only module components: The most elemental (i.e. indivisible) component of the converter is the individual thyristor valves (ignoring the snubber circuits). This is where we should start the design. In practice, thyristor valves are combined in series to form a valve group. The valve group will be our first module component, where the canvas of the valve group definition consists of a string of series-connected, non-module thyristor components. The module component will also require a graphic to represent the string of thyristors when the component is placed on the canvas of its parent module.
|
|
Valve Group Module Component Graphic |
Valve Group Module Component Canvas |
A 6-pulse bridge will consist of a total of six valve groups, each group representing a switching device: This is our second module component. The 6-pulse module component canvas will include six instances of the valve group module component. These are of course connected to form the bridge.
|
|
6-Pulse Bridge Module Component Graphic |
6-Pulse Bridge Module Component Canvas |
So far, we have constructed a 6-pulse bridge module definition, which contains instances of another module definition (called Valve Group) within it:
Module Definitions List:
Valve Group
6-Pulse Bridge
Module Instance Hierarchy:
6-Pulse Bridge
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
In the instance hierarchy above, the numbers indicate the instance number of the module (where the first instance is 0).
Our monopolar HVDC system is to contain four instances of the 6-pulse bridge we just constructed. If we assume that this system is constructed on the Main canvas, and that there are no other module components other than those above, then the project module hierarchy will be:
Module Definitions List:
Valve Group
6-Pulse Bridge
Main
Module Instance Hierarchy:
Main
6-Pulse Bridge
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
6-Pulse Bridge
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
6-Pulse Bridge
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
6-Pulse Bridge
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
Valve Group
The ability to instantiate module definitions fits perfectly into how a typical structured program is created. PSCAD is a structured code generator (presently Fortran that may include C), which combines components and modules in a project to construct and build an executable program. The project itself can be compared to a coded program in its entirety, where regular components represent snippets of inline code and modules represent subroutines.
PSCAD Object |
Code Equivalent |
Project |
Program |
Module Definition |
Subroutine |
Module Instance |
Subroutine Call |
Non-Module Component |
Inline Code |
Port Connections/Input Parameters |
Subroutine Arguments |
Analogies Between PSCAD Project Structure and Programming Structure
When a project is built, a separate Fortran (*.f) file containing a subroutine definition is created for every unique module definition used in the project. Any instance of said module definition will appear as a call within the subroutine of its parent module (i.e. the canvas on which the module instance is placed). For example, say a module definition called A is created and an instance of it is placed on the Main canvas.
|
|
Module A Definition Fortran File |
Call to Subroutine from Main Module |
When the project is built, a separate Fortran file called A.f is created to represent the definition of A. The code within it (i.e. the inline code) is constructed using the non-module components placed on the canvas of A. An instance of A exists within the canvas of Main, so therefore it contributes to defining the subroutine for Main – in other words, the instance of A is part of the definition of Main. Conceptually then, this project contains two module definitions, where an instance of module A is set within the canvas of Main.
In the above example, there are two module definitions (one for Main and one for A). What would happen then if A was instantiated again so that there are two instances of it on the Main canvas? Well a new definition is not required; only an additional call statement to A within the Main subroutine is needed.
|
|
Main Definition Fortran File |
Two Instances of A on the Main Canvas |
Now let’s complicate things a bit: Say there are two instances of another module called B placed on the canvas of module A. Since the instances of B are situated within A, then B becomes part of the definition of A – that is, calls to B will appear in the subroutine of A.
|
|
|
Module B Definition Fortran File |
Module A Definition Fortran File with Calls to B |
Module Main Definition Fortran File with Calls to A |
Notice above that the addition of module B to the project does not affect the definition of Main. This is because B is part of the definition of A, which appears only as an instance (or call statement) in Main. Conceptually:
You may have noticed above that module B is called four times in the above project, although there are only two instances of B. This is because the two instances of B help to define A, and A is called twice from Main. This does not mean that there are four instances of B, but each of the two instances of B is called twice. This concept is aptly referred to as a Call.
|
Instances |
Calls |
Main |
1 |
1 |
A |
2 |
2 |
B |
2 |
4 |
Instance and Call Numbers for the Given Example
It is important to understand this concept in order understand fully how multiple instance modules work, and how signal values are mapped and accessed within PSCAD and EMTDC.
Up until now, we have not mentioned the arguments shown in both the SUBROUTINE and CALL statements above. Subroutine arguments exist whenever the module definition possesses either input parameters or port connections. In fact, this is yet another coding analogy: Input parameters and port connections are a means to transfer data defined external to the module, for use inside the module. This is exactly what subroutine arguments are used for when coding.
Say for example that our module A above has two connection ports X and Y. The connection ports are defined as part of the module definition, and are therefore also part of the subroutine file definition. Although the ports are named X and Y in the definition, the actual signal connected to the port can be any other pre-defined signal; be it a literal value or another variable signal.
|
|
Module A Definition Fortran File |
Two Instances of A Called From the Main Canvas |
Notice above that input arguments in each call statement for A can be literal numbers or signal values. Each argument defined in the SUBROUTINE statement is represented by an Import or Export component on the module canvas.
For more details on defining input parameters and port connections, see the chapter entitled Component Design in this manual.
Up until now, we have discussed multiple instance modules in a conceptual manner. In practice however, there are certain important things to consider when designing your system, so as to ensure maximum compile and simulation efficiency. It is essential to consider where signals are sourced. That is, whether a signal should be definition or instance-based. Also, Output Channel placement is a concern.
When designing and utilizing a system containing multiple instance modules, it is very important to study and determine how to deal with system parameters that may differ between instances. For example, if a module definition were to contain a transformer component and the MVA of this transformer is to vary from instance to instance of the module, then the source of the MVA value must be defined external to the module definition; otherwise all instances of the module will be forced to have the same transformer MVA value. Let’s have a look at this example in PSCAD:
|
|
Module Definition Canvas with Transformer Component |
Transformer Component Parameter Dialog |
Here, a module definition contains a simple circuit with a transformer component. The transformer possesses an input parameter called Transformer MVA, which will accept a signal constant for its value. This signal is defined externally and imported as a signal called mva, which is entered directly as the transformer parameter. Although the import tag component, the transformer component and the signal itself are all part of the module definition, the value of the signal may be different for each module instance.
In this case, the signal mva is defined as an input parameter of the module itself. So if the module is instantiated many times, the mva parameter can possess a different value for each instance.
See The Parameters Section in the chapter called Component Design in this manual for more details on the proper design of module parameters, specifically the definitions of Literal, Constant and Variable type parameters, and how they pertain to multiple instance modules.
Output channels and controls can be dangerous when using multiple instance modules. This is because an output channel component creates a signal for monitoring by EMTDC wherever it is placed, thereby reserving memory used and affecting simulation speed.
If an output channel is placed within a low-level module, say for example the Valve Group module discussed above, the volume of signals that single output channel creates can quickly balloon. Notice that when the Valve Group modules parent module (6 Pulse Bridge) is copied, the Valve Group module is called six additional times for each 6 Pulse Bridge instance. This means that if the 6 Pulse Bridge is copied multiple times, then the single output channel is multiplied six-fold.
It is best to avoid placing an output channel component at this level. A better option would be to export the signal to be monitored as far up the module hierarchy as possible. This way the signal is available at an upper level, where the user can decide to monitor it if the need arises. The image below illustrates this concept: Instead of attaching an Output Channel to the signal inside the module canvas, the signal is exported to the parent canvas, where it can be monitored as desired.
|
Multiple-Instanced Module Component with Signal Exported Through a Port Connection |
In order to ensure full support of multiple-instance modules, EMTDC also had to go through some modifications. The major change to EMTDC involves the initialization of component parameters when they appear on a multiply-instanced module canvas. As a result of this, all relevant master library components have been modified to support this new structure. The same process must be applied to user-defined components, before they can fully support use on a multiple-instance canvas.
Please see the following sections in the PSCAD and EMTDC manuals for more details on this:
Changes to EMTDC Program Structure: EMTDC Manual | Program Structure | The EMTDC Solution Process and System Dynamics.
New Input Parameter Constant Type: PSCAD Manual | Component Design | Parameters Section | Input Fields | Input Field Data Types.
The #BEGIN Directive: PSCAD Manual | Definition Script | Script Directives | #BEGIN/#ENDBEGIN.
