Matrix Class
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 

Contents
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:
 The initial length of the matrix is zero.
 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.
 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() 
This calculates the sum of all elements in the matrix. 
Real 
None 
a.Sum() 
Avg() 
This calculates the average of all elements in the matrix. 
Real 
None 
a.Avg() 
Min() 
This returns the minimum value of all elements in the matrix. 
Real 
None 
a.Min() 
Max() 
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.
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.

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 
value : the required scaling factor. This is of data type REAL. 
a.Scale(2)  
Offset(value) Only available in Build 137. 
All the elements of the Matrix are offset by the specified value 
value : the required offset value. This is of data type REAL. 
a.Offset(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)  
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) 
GetRow(Rowindex,Array) 
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) 
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) 
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) 
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
 9.3 Syntax: Table lookup using Array and Matrix
 9.2 Syntax: Table lookup using Array and Matrix 9.2