Array Class

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: PGMs ➔ Classes ➔ Array Class

Global Pre-Defined Class Instances SysCAD Pre-Defined Classes
Sp Database
SDB Class 		Particle Size Defn
PSD Class 		Plant Model
PM Class 		Array
Class 		StrArray
Class 		Matrix
Class 		TagSelect
Class 		Time
Class 		Noise
Class

Latest SysCAD Version: 25 October 2024 - SysCAD 9.3 Build 139.36522

Related Links: Defining a Class, Example PGM Files

Description

The ARRAY class provides member functions to create a dynamic array and manipulate its elements.

  • The user may read in an array from a file. The file may be either a CSV file, created using Excel, or a TXT file, created using a test editor such as Notepad++.
  • The user may set constant values into an array when it is declared.

Notes:

  1. The initial length of the array is zero.
  2. The array is zero indexed, i.e. the index of the first element in the array is zero, and NOT 1. Therefore, the final element in an array of length n will have an index = n-1.
  3. If the index is out of range (0 <= index < length) then a runtime "PGM class execution error" will occur and the ARRAY operation will be ignored.
  4. The Array class allows user to Get / Set numeric values only. Please see StrArray Class for getting/setting String values.

Data Members

None

Member Functions

The examples in the table below is based on the following variables and array declarations. 

STRING   ArrayFileName
REAL     e, DotProduct
LONG     d
BIT      OK@, EqualOK@, SortOK@, AddOK@, SubOK@, MultOK@, DivOK@
ARRAY    a, b, c, NewA, A1, A2, PreVals, z ;declares array instances
Call Functionality Return Type Parameters Example
SetLen(length) Sets the size of the array to length length : the required length of the array, is of data type INTEGER a.SetLen(5)
GetLen() The function returns the length of the array. integer None d = a.GetLen()
SetSize(length)
Available from Build 139.30807.		 Sets the size of the array to length. SetSize() function is an equivalent alternative to SetLen() length : the required size of the array, is of data type INTEGER a.SetSize(5)
Size()
Available from Build 139.30807.		 The function returns the length of the array. Size() function is an equivalent alternative to GetLen(). integer None d = a.Size()
SetAt(index, value) This sets the element of the array, which corresponds to the given index to the specified value. index: the index of the required entry in the array (Note: index starts at zero). This is of data type, INTEGER.
value : the value to which the specified element, in the array, will be set. This is of data type, REAL.		 a.SetAt(0, 3)
OR:
a[0] = 3
GetAt(index) This retrieves the value (type real) of the element from the array, which corresponds to the given index. Real index : the index of the required entry in the array (Note: index starts at zero). This is of data type INTEGER. e = a.GetAt(0)
or:
e = a[0]
IncAt(Index, value) This increases the element of the array by the specified value. index : the index of the required entry in the array (Note: index starts at zero). This is of data type INTEGER.
value : the value to which the specified element, in the array, will be increased. This is of data type REAL.		 "a.IncAt(3, 10)" is equivalent to:
temp = a.GetAt(3)
a.SetAt(3, temp + 10)
DecAt(Index, value) This decreases the element of the array by the specified value. index : the index of the required entry in the array (Note: index starts at zero). This is of data type INTEGER.
value : the value to which the specified element, in the array, will be decreased. This is of data type REAL.		 "a.DecAt(3, 5)" is equivalent to:
temp = a.GetAt(3)
a.SetAt(3, temp - 5)"
Sum() This calculates the sum of all elements in the array. Real None e = a.Sum()
Avg() This calculates the average of all elements in the array. Real None e = a.Avg()
Min() This returns the minimum value of all elements in the array. Real None e = a.Min()
MinIndex() This returns the index of the minimum value in the array. If multiple entries of equal minimum value, the first index is returned. Return value is -1 for empty array. integer None d = a.MinIndex()
Max() This returns the maximum value of all elements in the array. Real None e = a.Max()
MaxIndex() This returns the index of the maximum value in the array. If multiple entries of equal maximum value, the first index is returned. Return value is -1 for empty array. integer None d = a.MaxIndex()
Norm()
Available from Build 139.30807.		 This normalises the contents of the array such that the sum is 1. Equivalent to a.OpDiv(a.Sum()). None a.Norm()
Reverse()
Available from Build 139.30807.		 This reverses the sequence of all elements in the array. None a.Reverse()
Sort(Ascending/Descending) This re-arranges all elements in the array in ascending / descending order. 0: Descending order,
1: Ascending order		 a.Sort(1)
IsSorted(Ascending/Descending) This checks if the array is sorted in ascending / descending order. Returns True if array is sorted in the specified order. Bit 0: Descending order,
1: Ascending order		 SortOK = a.IsSorted(1)

Load(arrayfilename)

This creates a new array from a file.

  • The first element on each line, of the specified file, is read in as an element of the array, until either an empty line or end-of-file character is reached.
  • The function returns the value, True if the file was read or, False if the file was not read.

Note: if any elements exist in the array, prior to calling Load, these elements will be overridden.

Bit

arrayfileName : either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.

ArrayFileName = "c:\SysCAD\array.csv"
OK = b.Load(ArrayFileName)
or
OK = c.Load("$Prj\data.txt")

Save(arrayfilename)

This saves the array data to a comma separated text file.

  • If the specified file exists it is overwritten.
  • The function returns, True if the file was saved or, False if the file was not saved.
  • This could fail for any file access reason, for example: invalid folder, invalid filename, file access error, file already open in another application, etc.

Bit

arrayfileName : either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.

OK = a.Save("$Prj\data_output.txt")

CopyToClipboard()

This saves the array data to the clipboard. The function returns the value, True.

Bit

None

OK = a.CopyToClipboard()

SetAll(value) This sets all the elements of the array to the specified value. value : the required initialising value. This is of data type REAL. a.SetAll(0)
Scale(value) All the elements of the array are scaled by the specified value
(New value = original value * Scale).		 value : the required scaling factor. This is of data type REAL. a.Scale(2)
- Each value of the Array "a" will be increased by factor of 2.
Offset(value) All the elements of the array are offset by the specified value
(New value = original value + Offset).		 value : the required offset value. This is of data type REAL. a.Offset(5)
- Each value of the Array "a" will be increased by 5.
Copy(Array) All the elements of the specified array are copied into the new array. Array: the name of the array to copy from. This is an ARRAY class. PreVals.Copy(a)
- The values in Array "a" are copied into the Array "PreVals".
Append(Array)
Available from Build 139.30807.		 All the elements of the specified array are added to the end of the existing array. The new length of the array will be the sum of the original length plus the length of the specified array. Array: the name of the array to append. This is an ARRAY class. PreVals.Append(a)
- The values in Array "a" are appended to the end of the Array "PreVals".
AppendItem(value)
Available from Build 139.30874.		 Increase the length of the array by one with the supplied value. value: the value to which the last element in the array will be set. a.AppendItem(42)
InsertAt(index, value)
Available from Build 139.32112.		 Increase the length of the array by one inserting the supplied value at the specified index. index: the zero based index in array where the value must be inserted. Index data type is INTEGER and must be in range for Array length.
value: the value to be set at the new inserted element in the array.		 a.InsertAt(0, 42)
- Inserts 42 at start of array.
RemoveAt(index, count)
Available from Build 139.32112.		 Decrease the length of the array by removing count (or less) values starting at the specified index. index: the zero based index in array where values must be deleted. Index data type is INTEGER and must be in range for Array length.
count: the number of elements to be removed. The value of count may be large, exceeding the current array length in which case all elements from the specified index are removed. Count data type is INTEGER.		 a.RemoveAt(5, 1)
- Removes one element at index 5.
IsEqual(Array) This compares the current array with the specified array data, if each element of the array are equal, the function returns the value, True. Bit Array: the name of the array to compare with. This is an ARRAY class. EqualOK = PreVals.IsEqual(a)
- The values in array "PreVals" are compared to the values of the Array "a". Returns true if they are equal.
Add(Array) This function performs addition between current array and a specified array. New value for each element in current array = value in current array + specified array.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array: the name of the specified array. This is an ARRAY class. AddOK = NewA.add(A1)
(each element in NewA = NewA + A1)
Sub(Array) This function performs subtraction between current array and a specified array. New value for each element in current array = value in current array - specified array.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array: the name of the specified array. This is an ARRAY class. SubOK = NewA.Sub(A1)
(each element in NewA = NewA - A1)
Mult(Array) This function performs multiplication between current array and a specified array. New value for each element in current array = value in current array x specified array.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array: the name of the specified array. This is an ARRAY class. MultOK = NewA.Mult(A1)
(each element in NewA = NewA * A1)
Div(Array) This function performs division between current array and a specified array. New value for each element in current array = value in current array / specified array.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array: the name of the specified array. This is an ARRAY class. DivOK = NewA.Div(A1)
(each element in NewA = NewA / A1)
CopyAdd(Array1, Array2) This function performs addition between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 + array2.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array1: the name of the first specified array. This is an ARRAY class.
Array2: the name of the second specified array. This is an ARRAY class.		 AddOK = NewA.CopyAdd(A1, A2)
(each element in NewA = A1 + A2)
CopySub(Array1, Array2) This function performs subtraction between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 - array2.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array1: the name of the first specified array. This is an ARRAY class.
Array2: the name of the second specified array. This is an ARRAY class.		 AddOK = NewA.CopySub(A1, A2)
(each element in NewA = A1 - A2)
CopyMult(Array1, Array2) This function performs multiplication between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 x array2.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array1: the name of the first specified array. This is an ARRAY class.
Array2: the name of the second specified array. This is an ARRAY class.		 AddOK = NewA.CopyMult(A1, A2)
(each element in NewA = A1 * A2)
CopyDiv(Array1, Array2) This function performs division between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 / array2.
The two arrays must have the same length, otherwise value remains unchanged and error is returned.		 Bit Array1: the name of the first specified array. This is an ARRAY class.
Array2: the name of the second specified array. This is an ARRAY class.		 AddOK = NewA.CopyDiv(A1, A2)
(each element in NewA = A1 / A2)
Inner(Array) This returns the Sum of Element i (Current Array * Specified Array). The two arrays must have the same length, otherwise error is returned. REAL Array: the name of the second array. This is an ARRAY class. DotProduct = a.Inner(PreVals)
CircConv(Array)
Available from Build 139.30613.		 This function performs circular convolution calculation between the current array and a specified array. New value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The values in the current array will be replaced with the new value.
The two arrays are expected to have the same length.		 Bit Array: the name of the specified array. This is an ARRAY class. AddOK = NewA.CirConv(A1)
(each element in NewA = circular convolution of NewA and A1)
CopyCircConv(Array1, Array2)
Available from Build 139.30613.		 This function performs circular convolution calculation between two arrays and stores the values in a new array (current array). Value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted.
The two arrays are expected to have the same length.		 Bit Array1: the name of the first specified array. This is an ARRAY class.
Array2: the name of the second specified array. This is an ARRAY class.		 AddOK = NewA.CopyCirConv(A1, A2)
(each element in NewA = circular convolution of A1 and A2)
SetFromStr(Str s, Str Separ)
Available from Build 139.35544.		 This function enables the unpacking of a string into an array, converting each element into a number. It internally utilises the StrToFlt function.
The array’s length is determined by the number of items derived from unpacking the string.		 REAL s is the string that requires unpacking.
Separ is the separator used within the string ‘s’ to define the divisions.		 x.SetFromStr("35,4,30", ",") will unpack the three numbers into the array ‘x’, resulting in x[0]=35, x[1]=4, and x[2]=30.
CopyToStr(Str Separ)
Available from Build 139.35544.		 This function enables the consolidation of a ‘Array’ into a single string. STRING Separ denotes the delimiter used within the string ‘s’ to demarcate its segments. x.CopyToStr(",") will combine the elements of the 'Array' named 'x' into the string "35,4,30".

Watch

To make the array variables visible in the access window the Watch command can be used.

  • Individual elements in the array can be made visible - e.g. "Watch A[2]" or "Watch A@[2]".
  • A range of array elements can be made visible - e.g. "Watch A[All,5]" which would show the first 5 elements of the array.
  • If the "@" symbol is included, then the array elements will be read only fields in the access window.

Array with Constant Values

The user may declare an array with a set of constant values. This allows the user to set up an array with known values for direct use. It can be a useful alternative to reading values from a CSV file. Once defined, the contents or size of this constant Array cannot be changed. Where a number is not specified for an entry, 0 is assumed. The contents of the array are not saved as they are defined in the code. From Build 139.32217, the list can include system constants (for example NAN or PI), or user defined constants. From Build 139.32325 the const keyword should be used, otherwise a load warning (or error) is given.

The syntax is: 

const ARRAY a = {n1,n2,n3,....} ;Syntax from Build 139.32325
ARRAY a = {n1,n2,n3,....} ;Syntax before Build 139.32325
;where n1, n2 etc. are real numbers or constants.
;Example
const Array SomePrimes = {2,3,5,7,11,13,17,19,23,29,31,37,41,43,47,53,59,61,67,71}

Caution

Using a GetAt within a SetAt can sometimes fail. This may be for expressions with multiple array references. 

;For example:
a.SetAt(i, a.GetAt(i+1))  ;This can sometimes fail

;The solution is to use a temporary variable to first retrieve the GetAt value and then call SetAt as follows:
Real   Tmp
Tmp = a.GetAt(i+1)
a.SetAt(i, Tmp)

Example

STRING      ArrayFileName
REAL        d, e, f, Total@, Average@, Minimum@, Maximum@, DotProduct@
BIT         OK@, CopyOK@, SortOK@, AddOK@, SubOK@
ARRAY       a                           ;declares array instance.
ARRAY       b{e}, c{e}                  ;declares array instances that are excluded from save (for efficiency).
const ARRAY x = {60,35,25,62,105}       ;declares an array z with constant values.
;ARRAY      x = {60,35,25,62,105}       ;Old syntax before Build 139.32325
ARRAY       y, y1, y2 
const ARRAY y3 = {20,35,45,62,105,150}  ;declares an array y3 with constant values.
const ARRAY z = {20,35,45,62,105}       ;declares an array z with constant values.

Sub InitialiseSolution()
  ArrayFileName = "c:\SysCAD\array.csv"
  OK = b.Load(ArrayFileName)
  OK = c.Load("$Prj\data.txt")
  a.SetLen(5)                  ;sets the array length
  y.copy(x)                    ;array x is copied into array y, returns {60,35,25,62,105}
  CopyOK = y.isEqual(x)        ;compares array y with array x, returns true
  y.sort(1)                    ;sorts array y in ascending order, returns {25,35,60,62,105}
  SortOK = y.IsSorted(1)       ;checks if array y is sorted in ascending order, returns true
  y1.copy(y)                   ;copies y, returns {25,35,60,62,105}
  y1.scale(2)                  ;multiplies each element by scaling factor of 2, returns {50, 70, 120, 124, 210}
  y2.copy(y)                   ;copies y, returns {25,35,60,62,105}
  y2.offset(5)                 ;adds each element by offset factor of 5, returns {30, 40, 65, 67, 110}
  AddOK = y.add(y2)            ;Adds each element of y to elements of y2, y now becomes {55, 75, 125, 129, 215}, returns true 
  SubOK = y1.sub(y3)           ;returns false since array length of y1 does not equal to y3. Array y1 unchanged.
  DotProduct = y.inner(y2)     ;sum of each element y_i * y2_i, returns 45068
EndSub

;Logic   
d = a.GetLen()               ;gets the array length
a.SetAll(2.2/2)              ;sets all elements
a.IncAt(0, 7.0)              ;increments the first element
a[d-1] = 3.3                 ;sets last element 
e = a[0]                     ;gets first element
f = z[3]                     ;gets the fourth element of array z, so f = 62
Total = z.Sum()              ;gets the sum of all the values in array z, Total = 267
Average = z.Avg()            ;gets the average of all the values in array z, Average = 53.4
Minimum = z.Min()            ;gets the minimum of all the values in array z, Minimum = 20
Maximum = z.Max()            ;gets the maximum of all the values in array z, Maximum = 105
$

See also Example PGM - Species Check. Also this Optimisation Example shows using these Array tools in a real example for plant tuning calculating an objective funtion.

Retrieved from "https://help.syscad.net/index.php?title=Array_Class&oldid=80219"