# Matrix primtives

Matrix operators such as matrix addition and multiplication.

The primitives in the matrix library operate on particles that represent matrices with floating-point, fixed-point, complex, or integer entries. Most of the work is done in the underlying matrix classes, FloatMatrix, ComplexMatrix, FixMatrix, and IntMatrix. These classes are treated as ordinary particles. In MLDesigner, matrix types are indicated with thick stems, where the color of the terminal stem corresponds to the data type of the matrix elements.

The Matrix conversion primitives are documented among the conversion primitives, see Matrix conversion primitives.

## Matrix-Vector conversion

MxCom_M

Accept input matrices and create a matrix output. Each input matrix represents a decomposed sub-matrix of output matrix in row by row.

Note that for one output image, we will need a total (numRows/numRowsSubMx)(numCols/numColsSubMx) input matrices.

MxDecom_M
Decompose a portion of input matrix into a sequence of sub-matrices. The desired portion of input matrix is specified by the parameters startRow, startCol, numRows and numCols. Then output each sub-matrix with dimension numRowsSubMxnumColsSubMx in row by row. Note that for one input matrix, there will be a total of (numRows/numRowsSubMx)(numCols/numColsSubMx) output matrices.

The following conversions perform more interesting functions. They also come in four versions, one for each data type, and again we only list the floating-point version.

Pack_M
Produce a matrix with floating-point entries constructed from floating-point input particles. The inputs are put in the matrix in rasterized order, for example, for a matrix, the first row is filled from left to right using the first N input particles.
Toeplitz_M

Generate a floating-point data matrix X, with dimensions (numRows,numCols), from a stream of input particles organized as shown below:

Here numRows = and numCols=M. This Toeplitz matrix is the form of the matrix that is required by the SVD_M primitive, among others.

UnPk_M
Read a floating-point matrix and output its elements, row by row, as a stream of floating-point particles.

## Matrix operations

SmithForm
Decompose an integer matrix S into one of its Smith forms , where U, D, and V are simpler integer matrices. The Smith form decomposition for integer matrices is analogous to singular value decomposition for floating-point matrices.
SVD_M
Compute the singular-value decomposition of a Toeplitz data matrix A by decomposing A into A = , where U and V are orthogonal matrices, and represents the transpose of V. W is a diagonal matrix composed of the singular values of A, and the columns of U and V are the left and right singular vectors of A.

The following blocks are functions defined only for the ComplexMatrix data type.

Conjugate_M
Conjugate a matrix.
Hermitian_M
Perform a Hermitian transpose (conjugate transpose) on the input matrix.

The following are usual matrix operations. They are arranged row by row, with one row for each data type (floating point, complex, fixed point, and integer). We list below only the floating point data types.

Gain_M
Multiply a floating-point matrix by a static scalar gain value.
Inverse_M
Invert a square floating-point matrix.
Mpy_M
Multiply two floating-point matrices A and B to produce matrix C.
Matrix A has dimensions (numRows,).
Matrix B has dimensions (,numCols).
Matrix C has dimensions (numRows,numCols).
The user only needs to specify numRows and numCols. An error will be generated if the number of columns in A does not match the number of rows in B.
Sub_M
Subtract floating-point matrix B from A.
Transpose_M
Transpose a floating-point matrix read as a single particle.
SubMx_M
Find a sub-matrix of the input matrix.
MpyScalar_M
Multiply a floating-point matrix by a scalar gain value.

## Miscellaneous

Table_M
(3 primitives for floating-point, complex and integer) This primitive implements a lookup table indexed by an integer-valued input. The output is a matrix. The input must lie between 0 and N − 1, inclusive, where N is the number of matrices in the table. The floatTable parameter specifies the entries of matrices in the table. Note that the entries of each matrix in the table should be given in row major ordering. The first matrix in the table is indexed by a zero-valued input. An error occurs if the input value is out of bounds.
SampleMean
Find the average amplitude of the components of the input matrix.
AvgSqrErr
Find the average squared error between two input sequences of matrices.
Abs_M
Return the absolute value of each entry of the floating-point matrix.