Matrix Class

From SysCAD Documentation
Jump to: navigation, search

Navigation: PGMs -> Classes -> Predefined Classes

Species Database Class Particle Size Definition Class Array Class StrArray Class Matrix Class Tag Select Class Plant Model Class Noise Class TimeClass

Description

The MATRIX class provides member functions, to create a dynamic matrix and manipulate its elements. It also allows one to read in a matrix from a file.

Notes:

  1. The initial length of the matrix is zero.
  2. The matrix is zero indexed, i.e. the index starts at zero. If the index is out of range (0 <= index < length) then a PGM class execution error will occur and the MATRIX operation will be ignored.
  3. If the user reads values into a matrix from a CSV file, the file may contain alphanumeric strings, but the alphanumeric strings must NOT contain any spaces.

Data Members

None

Member Functions

The example in the table below is based on the following variables and matrix declarations.

Matrix a, b, c, L, M, M1, M2
Real   d, Qty
Long   RowCount, ColCount
Bit    OK
Array  TestRow, TestCol, xA

Call

Functionality

Return Type

Parameters

Example

SetSize(Rows,Columns)

The matrix size is set to rows x columns.

Rows : the required number of rows of the matrix, is of data type LONG.

Columns : the required number of columns of the matrix, is of data type LONG.

a.SetSize(5, 3)

GetRowCount()

This returns the current number of rows of the matrix.

Long

None

RowCount = a.GetRowCount()

GetColCount()

This returns the current number of columns of the matrix.

Long

None

ColCount = a.GetColCount()

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)

SetAt(Rowindex, ColumnIndex, value)

This sets the element of the matrix, which corresponds to the given indexes to the specified value.

RowIndex : the index of the required Row entry in the matrix (Note: index starts at zero). This is of data type LONG.

ColumnIndex: the index of the required Column entry in the matrix (Note: index starts at zero). This is of data type LONG.

a.SetAt(2, 2, 2.2)

GetAt(Rowindex,ColumnIndex)

This retrieves the value of the element of the matrix, which corresponds to the given indexes.

Real

RowIndex: the index of the required Row entry in the matrix (Note: index starts at zero). This is of data type LONG.

ColumnIndex: the index of the required Column entry in the matrix (Note: index starts at zero). This is of data type LONG.

d = a.GetAt(3,1)

IncAt(Rowindex, ColumnIndex, value)

This sets the element of the matrix with the increased value.

RowIndex: the index of the required Row entry in the matrix (Note: index starts at zero). This is of data type LONG.

ColumnIndex: the index of the required Column entry in the matrix (Note: index starts at zero). This is of data type LONG.

value : the value to which the specified element, in the matrix, will be increased. This is of data type REAL.

a.IncAt(3, 2, Qty)

DecAt(Rowindex, ColumnIndex, value)

This sets the element of the matrix with the decreased value.

RowIndex: the index of the required Row entry in the matrix (Note: index starts at zero). This is of data type LONG.

ColumnIndex: the index of the required Column entry in the matrix (Note: index starts at zero). This is of data type LONG.

value : the value to which the specified element, in the matrix, will be decreased. This is of data type REAL.

a.IncAt(0, 2, Qty)

Sum()
Only available in SysCAD 9.3

This calculates the sum of all elements in the matrix.

Real

None

a.Sum()

Avg()
Only available in SysCAD 9.3

This calculates the average of all elements in the matrix.

Real

None

a.Avg()

Min()
Only available in SysCAD 9.3

This returns the minimum value of all elements in the matrix.

Real

None

a.Min()

Max()
Only available in SysCAD 9.3

This returns the maximum value of all elements in the matrix.

Real

None

a.Max()

Load(filename)

This creates a new matrix from a file.

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

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

Bit

fileName : 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 = b.Load("$Prj\Data.txt")

Save(filename)

This saves the matrix 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

fileName : 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\OutputData.txt")

CopyToClipboard()

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

Bit

None

a.CopyToClipboard()

SetAll(value)

This sets all the elements of the Matrix to the specified value.

value : the required initialising value. This is of data type REAL.

a.SetAll(0)

Scale(value)
Only available in Build 137.

All the elements of the Matrix 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 Matrix "a" will be increased by factor of 2.

Offset(value)
Only available in Build 137.

All the elements of the Matrix 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 Matrix "a" will be increased by 5.

Transpose()
Only available in Build 137.

Transposes the matrix.

M.Transpose()

Copy(Matrix)
Only available in Build 137.

All the elements of the specified Matrix are copied into the new Matrix.

Matrix: the name of the Matrix to copy from. This is an Matrix class.

PreVals.Copy(a)
- The values in Matrix "a" are copied into the Matrix "PreVals".

IsEqual(Matrix)
Only available in Build 137.

This compares the current Matrix with the specified Matrix data, if each element of the Matrix are equal, the function returns the value, True.

Bit

Matrix: the name of the Matrix to compare with. This is a Matrix class.

EqualOK = PreVals.IsEqual(a)
- The values in Matrix "PreVals" are compared to the values of the Matrix "a". Returns true if they are equal.

GetRow(Rowindex,Array)
Only available in Build 137.

This retrieves the values the specified row of the matrix, the values are stored in the specified array. It also sets the length of the array to match the number of of values in the row.

Bit

RowIndex: the index of the required Row entry in the matrix (Note: index starts at zero). This is of data type LONG.

Array: the name of the array to stored the retrieved information. This is an Array class.

a.GetRow(0,TestRow)

GetCol(Colindex,Array)
Only available in Build 137.

This retrieves the values the specified column of the matrix, the values are stored in the specified array. It also sets the length of the array to match the number of of values in the column.

Bit

ColIndex: the index of the required column entry in the matrix (Note: index starts at zero). This is of data type LONG.

Array: the name of the array to stored the retrieved information. This is an Array class.

a.GetCol(0,TestCol)

SetRow(Rowindex,Array)
Only available in Build 137.

This sets the values at the specified row in the matrix, with values from the specified array. The matrix row length must equal to the array length, otherwise it will return an error.

Bit

RowIndex: the index of the required Row entry in the matrix (Note: index starts at zero). This is of data type LONG.

Array: the name of the array that contains the values. This is an Array class.

a.SetRow(1,TestRow)

SetCol(Colindex,Array)
Only available in Build 137.

This sets the values at the specified column in the matrix, with values from the specified array. The matrix column length must equal to the array length, otherwise it will return an error.

Bit

ColIndex: the index of the required column entry in the matrix (Note: index starts at zero). This is of data type LONG.

Array: the name of the array that contains the values. This is an Array class.

a.SetCol(1,TestCol)

Add(Matrix)
Only available in Build 137.
This function performs addition between current matrix and a specified matrix. New value for each element in current matrix = value in current Matrix + specified Matrix.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix: the name of the specified Matrix. This is a Matrix class. AddOK = M.addMatrix(M1)
(each element in M = M + M1)
Sub(Matrix)
Only available in Build 137.
This function performs subtraction between current matrix and a specified matrix. New value for each element in current matrix = value in current Matrix + specified Matrix.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix: the name of the specified Matrix. This is a Matrix class. SubOK = M.SubMatrix(M1)
(each element in M = M - M1)
Mult(Matrix)
Only available in Build 137.
This function performs multiplication between current matrix and a specified matrix. New value for each element in current matrix = value in current Matrix + specified Matrix.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix: the name of the specified Matrix. This is a Matrix class. MultOK = M.MultMatrix(M1)
(each element in M = M * M1)
Div(Matrix)
Only available in Build 137.
This function performs division between current matrix and a specified matrix. New value for each element in current matrix = value in current Matrix + specified Matrix.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix: the name of the specified Matrix. This is a Matrix class. DivOK = M.DivMatrix(M1)
(each element in M = M / M1)
MultMatrix(Matrix)
Only available in Build 137.
Matrix multiplication for matrix of different size, but the number of Rows in the specified Matrix must match the number of columns of the current matrix. The resulting matrix is resized. Bit Matrix: the name of the specified Matrix. This is a Matrix class. MultMatrixOK = L.MultMatrix(M1)
- If Matrix "L" is 3x2 and Matrix "M1" is 2x4, resulting Matrix "L" is resized to 3x4.
MultArray(Array)
Only available in Build 137.
Matrix by Array multiplication, the Array is treated as a matrix with one of the dimensions equal to 1. The matrix column length must match the array length. Bit Array: the name of the specified Array. This is an Array class. MultArrayOK = L.MultArray(xA)
- the number of columns in Matrix "L" must equal to the array length of "xA"
CopyAdd(Matrix1, Matrix2)
Only available in Build 137.
This function performs addition between two matrices and stores the values in a new matrix(current matrix). Value for each element = value in specified Matrix1 + specified Matrix2.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix1: the name of the first specified Matrix. This is a Matrix class.
Matrix2: the name of the second specified Matrix. This is a Matrix class.
AddOK = M.CopyaddMatrix(M1, M2)
(each element in M = M1 + M2)
CopySub(Matrix1, Matrix2)
Only available in Build 137.
This function performs subtraction between two matrices and stores the values in a new matrix(current matrix). Value for each element = value in specified Matrix1 - specified Matrix2.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix1: the name of the first specified Matrix. This is a Matrix class.
Matrix2: the name of the second specified Matrix. This is a Matrix class.
SubOK = M.CopySubMatrix(M1, M2)
(each element in M = M1 - M2)
CopyMult(Matrix1, Matrix2)
Only available in Build 137.
This function performs multiplication between two matrices and stores the values in a new matrix(current matrix). Value for each element = value in specified Matrix1 x specified Matrix2.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix1: the name of the first specified Matrix. This is a Matrix class.
Matrix2: the name of the second specified Matrix. This is a Matrix class.
MultOK = M.CopyMultMatrix(M1, M2)
(each element in M = M1 * M2)
CopyDiv(Matrix1, Matrix2)
Only available in Build 137.
This function performs division between two matrices and stores the values in a new matrix(current matrix). Value for each element = value in specified Matrix1 / specified Matrix2.
The two Matrices must be the same size, otherwise value remains unchanged and error is returned.
Bit Matrix1: the name of the first specified Matrix. This is a Matrix class.
Matrix2: the name of the second specified Matrix. This is a Matrix class.
DivOK = M.CopyDivMatrix(M1, M2)
(each element in M = M1 / M2)
CopyMultMatrix(Matrix1, Matrix2)
Only available in Build 137.
This function performs multiplication between two matrices and stores the values in a new matrix(current matrix). The matrices can be of different size, but the number of Rows in the specified Matrix must match the number of columns of the current matrix. The resulting matrix is resized. Bit Matrix1: the name of the first specified Matrix. This is a Matrix class.
Matrix2: the name of the second specified Matrix. This is a Matrix class.
MultMatrixOK = M.CopyMultMatrix(L,M1)
- If Matrix "L" is 3x2 and Matrix "M1" is 2x4, resulting Matrix "M" is resized to 3x4.
CopyMultArray(Matrix, Array)
Only available in Build 137.
This function performs multiplication between a matrix and an array. The results are stored in a new matrix(current matrix). Matrix by Array multiplication, the Array is treated as a matrix with one of the dimensions equal to 1. The matrix column length must match the array length. Bit Matrix: the name of the first specified Matrix. This is a Matrix class.
Array: the name of the specified Array. This is an Array class.
MultArrayOK = M.CopyMultArray(L,xA)
- the number of columns in Matrix "L" must equal to the array length of "xA"

Watch

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

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

Matrix with Constant Values

The user may declare a matrix with a set of constant values. This allows the user to set up a table of look up values, without having to read them into the matrix via a CSV file. This functionality is only available in SysCAD 9.3.

The syntax is:

Matrix  LookupTable = {{a1,a2,a3,....}, {b1,b2,b3,....}, {c1,c2,c3,....}}
where a1, a2, b1, etc are real numbers.  

Notes:

  • Each group is a row, so {a1,a2,a3,....} is the first row of the Matrix.
  • If the number of elements in each row differs, the maximum number is used to set the number of colums in the Matrix. The missing elements are initialised to zero.
  • The Matrix is Read Only so data elements cannot be set, the Matrix resized, etc.

Caution

Using a GetAt within a SetAt can sometimes fail.

;For example:
a.SetAt(i, j, a.GetAt(i+1, j))  ;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, j)
a.SetAt(i, j, Tmp)

Example 1

SysCAD 9.3 Format SysCAD 9.2 Format
Matrix    TestMatrix, TestMatrix1, TestMatrix2, TestMatrix3
Matrix    Table1 = { {2, 5, 10}, {1, 3, 6} }
Real      Col1Sum@, SumV@, AverageV@, MinimumV@, MaximumV@
Long      RowCount@, ColCount@
Array     TestRowValue = {25, 30, 35}
Array     TestColValue = {5, 10}
Array     TestRow, TestCol
Bit       OK@, OK2@

Sub InitialiseSolution()
  TestMatrix.Copy(Table1)
  SumV     = TestMatrix.Sum()
  AverageV = TestMatrix.Avg()
  MinimumV = TestMatrix.Min()
  MaximumV = TestMatrix.Max() 
  TestMatrix.Scale(2)
  TestMatrix.Transpose()
  RowCount = TestMatrix.GetRowCount()
  ColCount = TestMatrix.GetColCount()
  TestMatrix1.SetSize(2,3)
  TestMatrix2.Copy(Table1)
  TestMatrix3.SetSize(2,3)
  TestMatrix2.GetRow(0, TestRow)
  TestMatrix2.GetCol(0, TestCol)
  TestMatrix1.SetRow(1, TestRowValue)
  TestMatrix1.SetCol(0, TestColValue)
  TestMatrix3.Add(TestMatrix2)
  TestMatrix3.Sub(TestMatrix2)
  TestMatrix3.Mult(TestMatrix2)
  TestMatrix3.Div(TestMatrix2)
  OK  = TestMatrix2.MultMatrix(TestMatrix)
  OK2 = TestMatrix1.MultArray(TestRowValue)
EndSub

$
Matrix    a
String    ProjectFolder, CsvFilename@
Real      d*, Col1Sum@
Long      RowCount@, ColCount@, i
Bit       SaveNow*, OK, CopyToClipboard*

if (OnInitialise)
  ProjectFolder = GetDynStrTag("PlantModel.System.PrjFolder")
  CsvFilename = strcat(ProjectFolder, "\test.csv")
  a.SetSize(5, 3)
  a.setat(2, 2, 2.2) 
  a.setat(0, 1, 0.1) 
  a.setat(4, 1, 4.1)
  d = 2^0.5
  RowCount = a.GetRowCount()
  ColCount = a.GetColCount()

elseif (OnTerminate)
  
else

  a.SetAt(1, 1, d)
  i = 0
  Col1Sum = 0.0
  while (i<RowCount)
    Col1Sum = Col1Sum + a.GetAt(i, 1)
    i = i + 1
  endWhile
  
  if (SaveNow)
    SaveNow = false
    OK = a.Save(CsvFilename)
    if (NOT OK)
        LogError(strcat("Matrix data not saved to file ", CsvFilename))
    endif  
  endif 
  
  if (CopyToClipboard)
    CopyToClipboard = false
    a.CopyToClipboard()
  endif
  
endif
$

Example 2 - Table Look up using Array and Matrix