Vectors, maps and matrices can be created and manipulated in one of four types:
• IntVec: a vector of decimal numbers (of type double)
• IntDplvector: a vector of objects, sets, integers, strings or decimal numbers
• IntMat: a matrix of decimal numbers (of type double)
• IntDplmap: a vector of objects, sets, integers, strings or decimal numbers mapped to key values
4.2.1 Vectors
There are two types of vectors that can be used in PowerFactory :IntVec and IntDplvector.
IntVec is used to describe arrays of decimal numbers. IntDplvector is a more general purpose vector that can describe an array / container of objects, sets, strings or numbers:
The other key differences between the two vector types are as follows:
• IntVec objects can be edited manually in the data manager, whereas IntDplvecotr objects can only be manipulated within a DPL script.
• The first item in IntVec objects is at index “1”, while in IntDplvector objects, it is at index “0”
• IntDplVector objects have no resizing functionality, and the vector size grows (or shrinks) organically with item insertions and removals.
• IntDplVector objects have a reverse lookup feature, i.e. one can find the index number of a vector item
• IntDplVector objects are sortable.
Note that the values in an IntDplvector must have the same type. The first value inserted into the IntDplvector determines the type. For example, if you insert an object, then all other values in the vector must also be of type object.
The functions and usage of IntVec and IntDplVector objects are shown in the table below:
Function IntVec IntDplVector
Initialise a vector Init(n)
Example: Vec.Init(5) Initialises a vector with 5 items and sets all item values to “0”
Clear()
Example: DplVec.Clear() Empties the vector of all items.
The size of the vector is null / 0.
4 Advanced DPL Scripting
Function IntVec IntDplVector
Get value at index “i” Get (i)
Example: x = Vec.Get(1)
Get the value of the first item and put it into variable x.
Get (i)
Example: x = Vec.Get(0) Get the value of the first item and put it into variable x.
Set value at index “i” Set (i, value)
Example: Vec.Set(3, 2.5)
Sets the value “2.5” into the vector at index “3”
Insert (i, item) Example:
Vec.Insert(1,oBus) Puts the object “oBus” into the vector at index “1”
Resize vector to size “n” Resize (n) Example:
Vec.Resize(3) Resizes the vector to 3 items. All additional items are set to '0'.
N/A
Get number of items in vector Size()
Example: x = Vec.Size()
Gets the number of items in the vector and puts it into variable x.
Size()
Example: x = Vec.Size() Gets the number of items in the vector and puts it into variable x.
Add item to the end of a vector N/A Insert (item)
Example: DplVec.Clear() Adds the object “oBus” to the end of the vector. This
increases the size of the vector by 1.
Remove item at index “i” N/A Remove (i)
Example: Vec.Remove(3) Removes the item at index 3.
This reduces the size of the vector by 1.
4 Advanced DPL Scripting
Function IntVec IntDplVector
Find the index of item “x” in the vector (reverse lookup)
N/A IndexOf (x)
Example: i = Vec.IndexOf(x)
Returns the index of item “x”
and puts it into (integer) variable i. The function returns “-1” if no match is found.
Sort items in vector N/A Sort (order, attribute)
Example: a) Vec.Sort(1) Sorts a vector (e.g. of numbers) in ascending order
Example: b)
Vec.Sort(0,'uknom') Sorts a vector (e.g. of terminal objects) in descending order according to their nominal voltages (uknom).
Refer to the DPL reference in the PowerFactory manual for more details.
4.2.2 Maps
DPL map objects (IntDplmap) are so-called associative arrays, which are essentially arrays of key - value pairs. For example, consider the DPL map shown below:
In the example above, there are five key-value pairs, e.g. “12, oBus1”, “8, oGen2”, etc. Thus for the key-value pair “9, oGen3”, the key “9” corresponds to the value “oGen3”. We can say that we’ve mapped the key “9” to the object “oGen3”.
In DPL map objects, the keys can be represented by numbers, strings, objects or sets. In the example above, all of the keys are shown as integer numbers, while their corresponding paired values are objects. Note that the keys and values must have homogenous types. The first key-value pair inserted into the map determines the types for the keys and key-values. For example, if you insert an object key and a set value, then all other keys-value pairs must be of type object and set.
4 Advanced DPL Scripting
The functions and usage of DPL map objects are shown in the table below:
Function IntDplmap
Initialise a DPL map Clear()
Example: Map.Clear()
Empties the DPL map of all items. The size of the map is null / 0.
Get value associated with key “x”
GetValue (x)
Example: oVal = Map.GetValue(x)
Gets the value associated with the key “x” and puts it into the object variable “oVal”.
Get number of key-value pairs in DPL map
Size()
Example: i = Map.Size()
Gets the number of key-value pairs and puts it into variable “i”
Add or modify a key-value pair
Insert (key, value)
Example: Map.Insert(x, oBus)
Adds a new key-value pair “x, oBus” if the key “x” does not already exist. Otherwise, it sets the value “oBus” to the existing key “x”.
Remove a key-value pair Remove (key)
Example: Map.Remove(x)
Removes the key-value pair with key “x”. This will reduce the size of the DPL map by 1.
Check if key “x” exists in the DPL map
Contains()
Example: iBool = Map.Contains(x)
Checks if the map contains the key “x” and returns the result to variable “iBool” (returns “1” of the key exists in the map, and “0”
otherwise) Get the first key-value
pair in the DPL map
First (key, value)
Example: iBool = Map.First(x, oVal)
Gets the first key-value pair in the DPL map and puts the key into variable “x” and value into variable “oVal”. Returns the status of the operation into variable “iBool” (returns “0”: if the operation is successful, and “1” if there is an error, e.g. if the DPL map is empty)
4 Advanced DPL Scripting
Function IntDplmap
Get the next key=value pair in the DPL map
Next (key, value)
Example: iBool = Map.Next(x, oVal)
Gets the next key-value pair in the DPL map (relative to the last pair) and puts the key into variable “x” and value into variable
“oVal”. Returns the status of the operation into variable “iBool”
(returns “0”: if the operation is successful, and “1” if there is an error, e.g. there are no more key-value pairs)
4.2.3 Matrices
Matrix objects (IntMat) are two dimensional matrices of decimal numbers. The functions and usage of matrix objects are shown in the table below:
Function IntMat
Initialise a matrix Init (rows, columns, init val) Example: Mat.Init(3,4,2)
Initialises a 3 x 4 matrix and initialises all elements to the value
“2”
Get the rows and columns of a matrix
NRow() / NCol()
Example: iRow = Mat.NRow()
Gets the number of rows in the matrix and puts it in variable
“iRow”
Resize a matrix Resize (rows, columns, init val) Example: Mat.Resize(5,5)
Resizes to a 5 x 5 matrix. As init val is not set, all additional elements are initialised to 0.
Get the value at row “x”
and column “y”
Get (x, y)
Example: dVal = Mat.Get(2,3)
Gets the value stored in the 2nd row and 3rd column and puts it into the variable “dVal”
Set the value at row “x”
and column “y”
Set (x, y, value)
Example: Mat.Set(3,2,10)
Sets the value in the 3rd row and 2nd column to 10.
Read the labels of rows and columns in a matrix
RowLbl (row) / ColLbl (column)
Example: sLabel = Mat.RowLbl(1)
Gets the label of the 1st row and puts it into the (string) variable
“sLabel”
4 Advanced DPL Scripting
Function IntMat
Set the labels of rows and columns in a matrix
RowLbl (label, row) / ColLbl (label, column)
Example: Mat.ColLbl('busbars', 2) Sets the label of the 2nd column to “busbars”
Multiply two matrices Multiply (Mat A, Mat B)
Example: iBool = Mat.Multiply(A, B)
Multiplies the matrices A and B, and stores the result into itself (i.e. matrix “Mat”). Returns the status of the operation into variable “iBool” (returns “0”: if the operation is successful, and
“1” if there is an error, e.g. multiplication not possible and matrix
“Mat” is left unchanged) Invert a matrix Invert()
Example: iBool = Mat.Invert()
Inverts the matrix and then stores the result into itself (i.e. matrix
“Mat”). Returns the status of the operation into variable “iBool”
(returns “0”: if the operation is successful, and “1” if there is an error, e.g. inversion not possible and matrix “Mat” is left unchanged)
Sorts the matrix alphanumerically according to column “2”.
Returns the status of the operation into variable “iBool” (returns
“0”: if the operation is successful, and “1” if there is an error, e.g.
column doesn’t exist)