Namespace PlcDocu.TcMatrix

Classes

DynamicMatrix

The DynamicMatrix class uses the FB_DynMem_Manager2 to dynamically allocate as much memory as required for the given operation. This amazing flexibility comes at the cost of some restrictions on use in order to avoid memory leaks.

warning

Using the assignment operator (:=) to copy a DynamicMatrix will result in the new matrix retaining a pointer to the data of the old matrix! For this reason, the pragma {attribute 'no_assign'} is used to block assignment at compile-time, but inheriting sub-classes will need to include this pragma themselves. Note that using DynamicMatrix as the return value of a function is essentially an assignment operation and will also not work. Therefore, it is recommended to always pass DynamicMatrix objects in and out of functions using the REFERENCE TO keyword. To alleviate the pain of these assignment rules there are a ton of 'Resultant' helper functions available to use which initialize a new DynamicMatrix as the result of some operation on other matrix objects.

The DynamicMatrix FB will automatically free its memory when an instance of the class is created, or goes out of scope. This prevents memory leaks and page faults, but it also prevents you from instantiating a DynamicMatrix inside of a function and then passing a REFERENCE TO it back up the call chain. Another consequnce is that a DynamicMatrix cannot be retained after power-loss. A DynamicMatrix within a GVL will free its memory when the program terminates.

ExternalStaticMatrix

This simple concrete derivative of the StaticMatrix class uses an external ARRAY OF LREAL as the memory source for the matrix data. It is accessed in row-major order based on the logic in the GetI and SetI functions. It is most useful when someone doesn't trust dynamically allocated memory, but also doesn't want to make multiple size-specific custom derived FBs just to set up a single complex matrix operation.

Init(R,C,pD)
: Must be called in order to setup the matrix (it will be empty until this method is called).
warning

It is the callers responsibility to ensure that the pointer provided to the initializer is valid: - The length of the data structure pointed to (probably an array of LREAL) is at least as long as Rows x Cols - The scope of the data structure pointed to is the same as the scope of the corresponding ExternalStaticMatrix (probably declared adjacent to eachother as a VAR or GVL) Additionally, direct assignment (:=) should not be used with this type of matrix because a second copy of the Matrix, but with a pointer to the original's data source, would be created. For this reason, the pragma {attribute 'no_assign'} is used to block assignment at compile-time. Keep in mind that returning a value from a function is also a form of assignment and is not allowed.

Matrix

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).

info

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.

MatrixAccessor

Matrix accessors are a way of interacting with the data of a parent Matrix through a special lens, without copying the data into a new Matrix and then back again. This type of Matrix works by creating a function that converts the I-based indexing of the accessor matrix into the I-based indexing of the parent matrix, then using it to intercept calls to GetI and SetI. Concrete Matrix Accessor Classes can be easily created from the parent MatrixAccessor abstract class by implementing the This2Parent method in order to define the index conversion.

note

Note that matrix accessor allow both read and write access to the parent matrix!

warning

Matrix Accessors inherently store a pointer (BY REFERENCE) to their parent matrix. If the parent matrix goes out of scope (through function return) or is moved (through an online change) then the Matrix Accessor will no longer work. Therefore, they are best used quickly then destroyed, all within the scope of a single F or FB.

MatrixCsvReader

ShrunkMatrixAccessor

MatrixAccessor Allows access to the parent matrix as if the Shrink(Object, Object) function had been called

StaticMatrix

This type of matrix has the number of rows and columns set during initialization and then they cannot be changed. Derived class must:

  • Declare a VAR array of LREAL named Data_
  • Call Init_ in FB_init, pointing to the local arrays, with Rows and Cols such that Rows*Cols <= Length(Data_) This simple abstract class sets the rules for all static memory matricies by creating a protected Init_(R,C) method that must be called to set the initial size of the matrix. It also implements the required Rows and Cols properties to return the values that were set during initialization.
warning

It is the callers responsibility to ensure that the pointer provided to the initializer is valid: - The length of the data structure pointed to (probably an array of LREAL) is at least as long as Rows x Cols - The scope of the data structure pointed to is the same as the scope of the corresponding ExternalStaticMatrix (probably declared adjacent to eachother as a VAR or GVL) Additionally, direct assignment (:=) should not be used with this type of matrix because a second copy of the Matrix, but with a pointer to the original's data source, would be created. For this reason, the pragma {attribute 'no_assign'} is used to block assignment at compile-time. Keep in mind that returning a value from a function is also a form of assignment and is not allowed.

SubMatrixAccessor

MatrixAccessor Allows access to a rectangular subset of the parent matrix as if it were a standalone matrix

TransposeMatrixAccessor

MatrixAccessor Allows access to the elements of the parent matrix as if it were transposed