TcMatrix

Description

A TwinCAT 3 library for manipulating 2D data sets of LREAL.

Features include:

• Element-wise setting, getting, summing, scaling, and power functions
• Initialization as copies, zeros, trapezoidal, and other pre-defined matrix types
• Matrix operations like multiplication, transposition, and inversion
• Vector operations for 1D matricies like dot/cross product and normalization
• Complex access operations similar to 'slicing'
• Options to use static or dynamically allocated memory
• Reading/Writing with CSV files, output to the ADS message logger

Compare to:

• CODESYS Matrix Library (docs)
• Siemens Library of General Functions (docs)

Contents

• Installation
• Usage
  • Quick Start
  • Matrix
  • DynamicMatrix
  • StaticMatrix
  • MatrixAccessor
• Examples
  • Projects

TwinCAT 3 Installation

From Binary

1. Go to the releases page and download the *.library file from the latest release, saving it to a temporary directory somewhere on the computer running TwinCAT.
2. Follow the library installation instructions from Beckhoff, using the 'Install' option and browsing for the local copy you had just downloaded.
3. After installtion, you may delete the local copy of the library that you had downloaded. Beckhoff has likely copied it to a version-specific folder in C:\TwinCAT\3.1\Components\Plc\Managed Libraries\Burks Engineering\TcMatrix\

From Source

Preconditions:

• TwinCAT 3.1.4024 XAE
• TwinCAT 3.1.4024 XAR, ideally configured with an isolated core
• Visual Studio Community or Shell, 2019 or higher
• TcUnit v1.2 or higher

Compilation:

1. Clone the repository to a computer running TwinCAT 3
2. Open the main solution file in Visual Studio
3. Within the Visual Studio TcMatrix project, right click on the TcMatrix/TcMatrix Project item and select Rebuild
   1. There should be no compile errors, although there may be warnings
4. Right click on the TcMatrix/TcMatrix Project item again and select Save as library and install
   1. The file can be saved anywhere, but a local Builds folder is always a good choice

Test:

1. Within the Visual Studio TcMatrixTest project, right click on the PLC/TcMatrixTest/TcMatrixTest Project item and select Rebuild
   1. There should be no compile errors, although there may be warnings
2. Open the SYSTEM/Real-Time item and click Read From Target, then assign all tasks to an isolated core from your system
3. In the Visual Studio toolbar (or TwinCAT file menu) click Activate Configuration
4. When prompted, agree to start the project in run mode and auto-start the boot project
5. After a few seconds the TcUnit results should be visible in the Error List window. Verify that all tests have passed.

Usage

Quick Start

Example showing vector multiplication with the identity matrix. See TcMatrixTest.FB_Array_Test.MarkdownExample1

VAR
	M : Array2DStaticMatrix; //This instance is the matrix that the code will interact with
	M_Data : ARRAY[1..3,1..3] OF LREAL; //This array will act as the memory for the matrix
	V : Array2DStaticMatrix; //This instance is the initial column vector
	V_Data : ARRAY[1..3,1..1] OF LREAL := [1, 2, 3]; //This array will act as the memory for the initial column vector, prepopulated
	Res : Array2DStaticMatrix; //This instance is the resulting column vector
	Res_Data : ARRAY[1..3,1..1] OF LREAL := [1, 2, 3]; //This array will act as the memory for the resulting column vector
	success : BOOL; //records success or failure of the matrix multiplication
	equal : BOOL; //records success if the resulting vector is equal to the first
END_VAR

M(Data := M_Data); //Connect the memory to the matrix and initialize it
V(Data := V_Data); //Connect the memory to the initial column vector and initialize it (retaining declared values)
Res(Data := Res_Data); //Connect the memory to the resulting column vector and initialize it

M.FillTrapezoidal(Diagonal := 1, UpperRight := 0, LowerLeft := 0); //Transforms the matrix from all zeros into the identity matrix
success := Matrix_Product(M,V,Res); //perform the matrix multiplication
equal := V.IsEqual(Res); //the result of the multiplication should be equal to the initial value because of the identity matrix

Base Matrix Class

This abstract FB is the basis for all other matrix FBs. It represents a 2D array of LREAL elements. It provides dozens of methods and properties useful for manipulating itself, calculating values, and comparing to other matricies. Critically, this base class does not actually contain any mechanism for storing the values of the matrix (that is the responsibility of the specific inheriting sub-class).

---

NOTE

Because Matrix is an abstract FB it cannot be assigned (:=) directly. Instead, each Matrix is always passed in and out of a function AS REFERENCE. This also allows interactions with inhereted sub-classes of Matrix more easily.

---

Below are some (but not all) of the functions and methods within the base Matrix FB. All functions and methods are documented within the library and can be explored within TwinCAT.

Element Access

Fundamentally the matrix is just a 2D array of LREAL data. These simple methods and functions form the backbone of the entire class.

• Rows : returns the number of rows in the matrix
• Cols : Returns the number of columns in the matrix
• Size(dim) : Returns the length of the matrix in the specified dimension (0=rows, 1=cols)
• GetRC(R,C) : Returns the value of the element at the specified (0-indexed) position within the matrix
• SetRC(R,C,Val) : Sets the value of the element at the specified (0-indexed) position within the matrix
• IsEmpty : Returns TRUE if Rows=0 OR Cols=0
• IsSquare : Returns TRUE if Rows=Cols and the matrix is not empty
• IsVector : Returns TRUE if Rows=1 OR Cols=1 and the matrix is not empty

Every Matrix is considered as a 1D array of LREAL data types under the hood. This 1D view of data can be particularly useful when considering the matrix as a vector, but not caring whether it is a row vector or column vector.

• Length : The length of the 1D array (equal to Rows x Cols)
• GetI(I) : Returns the value of the element at the specified (0-based) position in the 1D array
• SetI(I,Val) : Sets the value of the element at the specified (0-based) position in the 1D array

Initializers

• Clear() : Sets the value of every element to 0.0
• CopyFrom(Matrix) : Only if the supplied matrix is exactly the same size as this matrix, copy all elements to this matrix
• FillFrom(Matrix) : Copy every element from the supplied matrix which exists in both this amtrix and the supplied matrix
• FillTrapezoidal(D,UR,LL) : Copy one value into the main diagonal of this matrix, copy another value into all elements to the upper-right of the main diagonal, and copy another value into all elements to the lower-left of the main diagonal

Modifiers

• ElementSum(Matrix) : Sets each element of this matrix to the value of its sum with the corresponding element in the supplied matrix
• ElementDifference(Matrix) : Sets each element of this matrix (as subtrahend) to the value of its difference with the corresponding element in the supplied matrix (as minuend)
• ElementProduct(Matrix) : Sets each element of this matrix to the value of its product with the corresponding element in the supplied matrix
• Scale(Scalar) : Sets each element of this matrix to the value of its product with the specified scalar
• Power(Exponent) : Sets each element of this matrix to the value of itsself raised to the supplied exponent
• TransposeSquare() : (Works on square matricies only) Swaps each element at (R,C) with a corresponding element at (C,R)
• InvertSquare(Tolerance) : Transforms this matrix into its inverse, if possible. The supplied Tolerance is used as a limit for any number used as a denominator (1E-12 is a good value to use).
• SortByColAsc(C) : Sorts the matrix by swapping entire rows around until the specified column is in ascending order. The relative position of equal rows will remain unchanged so as to allow tiered sorting.

Comparators

• IsEqualSize : Returns TRUE if this matrix is the same size (Rows and Cols) as the supplied matrix
• IsEqual : Returns TRUE if IsEqualSize is true AND every element in this matrix is equal to its corresponding element in the supplied matrix
• IsNearlyEqual(Tolerance) : Returns TRUE if IsEqualSize AND every element in this matrix is equal (within the specified tolerance) to its corresponding element in the supplied matrix

Calculators

• Sum : A property that returns the sum of every element in the matrix
• MaxVal : A property that returns the maximum value contained in the matrix
• MinVal : A property that returns the minimum value contained in the matrix
• Average : A property that returns the average of all values contained in the matrix
• GetDeterminate() : Calculates the determinate of the matrix if it is square
• __GetVectorMagnit