# SuanShu, a Java numerical and statistical library

com.numericalmethod.suanshu.algebra.linear.matrix.doubles.operation

## Class MatrixFactory

• java.lang.Object
• com.numericalmethod.suanshu.algebra.linear.matrix.doubles.operation.MatrixFactory

• public class MatrixFactory
extends Object
These are the utility functions to create a new matrix/vector from existing ones.
• ### Method Summary

All Methods
Modifier and Type Method and Description
static Matrix cbind(List<Vector> vectors)
Combines a list of vectors by columns.
static Matrix cbind(Matrix... matrices)
Combines an array of matrices by columns.
static SparseMatrix cbind(SparseMatrix... matrices)
Combines an array of sparse matrices by columns.
static SparseMatrix cbind(SparseVector... vectors)
Combines an array of sparse vectors by columns and returns a CSR sparse matrix.
static Matrix cbind(Vector... vectors)
Combines an array of vectors by columns.
static Matrix columns(Matrix A, int[] cols)
Constructs a sub-matrix from the columns of a matrix.
static Matrix columns(Matrix A, int begin, int end)
Constructs a sub-matrix from the columns of a matrix.
static DiagonalMatrix diagonalMatrix(Matrix A)
Gets the diagonal of a matrix.
static Matrix foreach(Matrix A, UnivariateRealFunction f)
Constructs a new matrix in which each entry is the result of applying a function to the corresponding entry of a matrix.
static Matrix foreachColumn(Matrix matrix, RealVectorFunction f)
Constructs a new matrix in which each column is the result of applying a real vector function on each column vector of an input matrix.
static Matrix foreachRow(Matrix A, RealVectorFunction f)
Constructs a new matrix in which each row is the result of applying a real vector function on each row vector of an input matrix.
static Matrix identity(int nRows, int nCols)
Constructs a new identity matrix.
static Matrix minorMatrix(Matrix X, int row, int col)
Gets the minor matrix of a given matrix, by removing a specified row and a specified column.
static Matrix ones(int nRows, int nCols)
Constructs a matrix of 1's.
static Matrix ones(int nRows, int nCols, double s)
Constructs a matrix of the same scalar, e.g.,1.
static CSRSparseMatrix randomCSRSparseMatrix(int nRows, int nCols, int nNonZero, RandomLongGenerator uniform)
Constructs a random CSRSparseMatrix.
static DenseMatrix randomDenseMatrix(int nRows, int nCols, RandomNumberGenerator rng)
Constructs a random DenseMatrix.
static DOKSparseMatrix randomDOKSparseMatrix(int nRows, int nCols, int nNonZero, RandomLongGenerator uniform)
Constructs a random DOKSparseMatrix.
static LILSparseMatrix randomLILSparseMatrix(int nRows, int nCols, int nNonZero, RandomLongGenerator uniform)
Constructs a random LILSparseMatrix.
static LowerTriangularMatrix randomLowerTriangularMatrix(int dim, RandomNumberGenerator rng)
Constructs a random LowerTriangularMatrix.
static Matrix randomPositiveDefiniteMatrix(int dim, RandomNumberGenerator rng)
Constructs a random symmetric, positive definite matrix.
static SymmetricMatrix randomSymmetricMatrix(int dim, RandomNumberGenerator rng)
Constructs a random SymmetricMatrix.
static UpperTriangularMatrix randomUpperTriangularMatrix(int dim, RandomNumberGenerator rng)
Constructs a random UpperTriangularMatrix.
static Matrix rbind(List<Vector> vectors)
Combines a list of array of vectors by rows.
static Matrix rbind(Matrix... matrices)
Combines an array of matrices by rows.
static SparseMatrix rbind(SparseMatrix... matrices)
Combines an array of sparse matrices by rows.
static SparseMatrix rbind(SparseVector... vectors)
Combines an array of sparse vectors by rows and returns a sparse matrix.
static Matrix rbind(Vector... vectors)
Combines an array of vectors by rows.
static Matrix replaceInPlace(Matrix original, int rowFrom, int rowTo, int colFrom, int colTo, Matrix replacement)
Replaces a sub-matrix of a matrix with a smaller matrix.
static Matrix rows(Matrix A, int[] rows)
Construct a sub-matrix from the rows of a matrix.
static Matrix rows(Matrix A, int begin, int end)
Constructs a sub-matrix from the rows of a matrix.
static Matrix subMatrix(Matrix A, int[] rows, int[] cols)
Constructs a sub-matrix from the intersections of rows and columns of a matrix.
static Matrix subMatrix(Matrix A, int rowFrom, int rowTo, int colFrom, int colTo)
Constructs a sub-matrix from the four corners of a matrix.
static SparseMatrix subMatrix(SparseMatrix A, int[] rows, int[] cols)
Constructs a sub-matrix from the intersections of rows and columns of a sparse matrix.
static SparseMatrix subMatrix(SparseMatrix A, int rowFrom, int rowTo, int colFrom, int colTo)
Constructs a sub-matrix from the four corners of a sparse matrix.
• ### Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
• ### Method Detail

• #### identity

public static Matrix identity(int nRows,
int nCols)
Constructs a new identity matrix.
Parameters:
nRows - the number of rows
nCols - the number of columns
Returns:
the new identity matrix
• #### ones

public static Matrix ones(int nRows,
int nCols,
double s)
Constructs a matrix of the same scalar, e.g.,1.
Parameters:
nRows - the number of rows
nCols - the number of columns
s - the scale to fill the matrix
Returns:
a matrix of the same scalar
• #### ones

public static Matrix ones(int nRows,
int nCols)
Constructs a matrix of 1's.
Parameters:
nRows - the number of rows
nCols - the number of columns
Returns:
a matrix of 1's
• #### replaceInPlace

public static Matrix replaceInPlace(Matrix original,
int rowFrom,
int rowTo,
int colFrom,
int colTo,
Matrix replacement)
Replaces a sub-matrix of a matrix with a smaller matrix. This method is best NOT to apply to SymmetricMatrix because this method does not ensure the symmetry property after replacement.

Note that The original matrix is modified afterward (for performance reason in case of a big matrix). No new Matrix instance is constructed.

Parameters:
original - the matrix whose entries are to be replaced
rowFrom - the beginning row index
rowTo - the ending row index
colFrom - the beginning column index
colTo - the ending column index
replacement - the matrix to be inserted into the original matrix
Returns:
the modified matrix
• #### foreach

public static Matrix foreach(Matrix A,
UnivariateRealFunction f)
Constructs a new matrix in which each entry is the result of applying a function to the corresponding entry of a matrix. The type of the output matrix is always the same as the type of the input matrix. However, sparsity may not preserved under this operation.
Parameters:
A - a matrix
f - the function to be applied to each entry of a matrix
Returns:
$$[f(A[i,j])], \forall i, j$$
• #### foreachRow

public static Matrix foreachRow(Matrix A,
RealVectorFunction f)
Constructs a new matrix in which each row is the result of applying a real vector function on each row vector of an input matrix.
Parameters:
A - the input matrix
f - the real vector function
Returns:
$$[f(A[i,])], \forall i$$
• #### foreachColumn

public static Matrix foreachColumn(Matrix matrix,
RealVectorFunction f)
Constructs a new matrix in which each column is the result of applying a real vector function on each column vector of an input matrix.
Parameters:
matrix - the input matrix
f - the real vector function
Returns:
$$[f(A[,j])], \forall j$$
• #### cbind

public static Matrix cbind(Vector... vectors)
Combines an array of vectors by columns. The vectors must have the same length.
Parameters:
vectors - an array of vectors, e.g., v1, v2, v3, ...
Returns:
[v1 v2 v3 ...]
• #### cbind

public static SparseMatrix cbind(SparseVector... vectors)
Combines an array of sparse vectors by columns and returns a CSR sparse matrix. The vectors must have the same length.
Parameters:
vectors - an array of vectors, e.g., v1, v2, v3, ...
Returns:
[v1 v2 v3 ...]
• #### cbind

public static Matrix cbind(List<Vector> vectors)
Combines a list of vectors by columns. The vectors must have the same length.
Parameters:
vectors - a list of vectors, e.g., v1, v2, v3, ...
Returns:
[v1 v2 v3 ...]
• #### cbind

public static Matrix cbind(Matrix... matrices)
Combines an array of matrices by columns. The matrices must have the same number of rows.
Parameters:
matrices - an array of matrices, e.g., A1, A2, A3, ...
Returns:
[A1 A2 A3 ...]
• #### cbind

public static SparseMatrix cbind(SparseMatrix... matrices)
Combines an array of sparse matrices by columns. The matrices must have the same number of rows. If all the matrices have the same type, then returns the combined matrix of that type; otherwise, returns a CSR sparse matrix.
Parameters:
matrices - an array of matrices, e.g., A1, A2, A3, ...
Returns:
[A1 A2 A3 ...]
• #### rbind

public static Matrix rbind(Vector... vectors)
Combines an array of vectors by rows. The vectors must have the same length. If the vectors are all sparse, it will returns a sparse matrix.
Parameters:
vectors - an array of vector, e.g., v1, v2, v3, ...
Returns:
$\begin{bmatrix} v_1\\ v_2\\ v_3\\ ... \end{bmatrix}$
Throws:
IllegalArgumentException - if the vectors form a jagged array
• #### rbind

public static SparseMatrix rbind(SparseVector... vectors)
Combines an array of sparse vectors by rows and returns a sparse matrix. The vectors must have the same length.
Parameters:
vectors - an array of vector, e.g., v1, v2, v3, ...
Returns:
$\begin{bmatrix} v_1\\ v_2\\ v_3\\ ... \end{bmatrix}$
Throws:
IllegalArgumentException - if the vectors form a jagged array
• #### rbind

public static Matrix rbind(List<Vector> vectors)
Combines a list of array of vectors by rows. The vectors must have the same length.
Parameters:
vectors - a list of vector, e.g., v1, v2, v3, ...
Returns:
$\begin{bmatrix} v_1\\ v_2\\ v_3\\ ... \end{bmatrix}$
Throws:
IllegalArgumentException - if the vectors form a jagged array
• #### rbind

public static Matrix rbind(Matrix... matrices)
Combines an array of matrices by rows. The matrices must have the same number of columns.
Parameters:
matrices - an array of matrices, e.g., A1, A2, A3, ...
Returns:
$\begin{bmatrix} A_1\\ A_2\\ A_3\\ ... \end{bmatrix}$
• #### rbind

public static SparseMatrix rbind(SparseMatrix... matrices)
Combines an array of sparse matrices by rows. The matrices must have the same number of columns. If all the matrices have the same type, then returns a sparse matrix of that type; otherwise, returns CSR sparse matrix.
Parameters:
matrices - an array of matrices, e.g., A1, A2, A3, ...
Returns:
$\begin{bmatrix} A_1\\ A_2\\ A_3\\ ... \end{bmatrix}$
• #### subMatrix

public static Matrix subMatrix(Matrix A,
int rowFrom,
int rowTo,
int colFrom,
int colTo)
Constructs a sub-matrix from the four corners of a matrix.
Parameters:
A - a matrix
rowFrom - the beginning row index
rowTo - the ending row index
colFrom - the beginning column index
colTo - the ending column index
Returns:
A[rowFrom:rowTo, colFrom:colTo]
• #### subMatrix

public static SparseMatrix subMatrix(SparseMatrix A,
int rowFrom,
int rowTo,
int colFrom,
int colTo)
Constructs a sub-matrix from the four corners of a sparse matrix.
Parameters:
A - a sparse matrix
rowFrom - the beginning row index
rowTo - the ending row index
colFrom - the beginning column index
colTo - the ending column index
Returns:
A[rowFrom:rowTo, colFrom:colTo]
• #### subMatrix

public static Matrix subMatrix(Matrix A,
int[] rows,
int[] cols)
Constructs a sub-matrix from the intersections of rows and columns of a matrix.
Parameters:
A - a matrix
rows - the rows to be extracted
cols - the columns to be extracted
Returns:
A[rows, cols]
• #### subMatrix

public static SparseMatrix subMatrix(SparseMatrix A,
int[] rows,
int[] cols)
Constructs a sub-matrix from the intersections of rows and columns of a sparse matrix.
Parameters:
A - a sparse matrix
rows - the rows to be extracted
cols - the columns to be extracted
Returns:
A[rows, cols]
• #### rows

public static Matrix rows(Matrix A,
int[] rows)
Construct a sub-matrix from the rows of a matrix.
Parameters:
A - a matrix
rows - the rows to be extracted
Returns:
A[rows, *]
• #### rows

public static Matrix rows(Matrix A,
int begin,
int end)
Constructs a sub-matrix from the rows of a matrix.
Parameters:
A - a matrix
begin - the beginning row index (counting from 1)
end - the ending row index (counting from 1)
Returns:
A[begin:end, *]
• #### columns

public static Matrix columns(Matrix A,
int[] cols)
Constructs a sub-matrix from the columns of a matrix.
Parameters:
A - a matrix
cols - the columns to be extracted
Returns:
A[*, cols]
• #### columns

public static Matrix columns(Matrix A,
int begin,
int end)
Constructs a sub-matrix from the columns of a matrix.
Parameters:
A - a matrix
begin - the beginning column index (counting from 1)
end - the ending column index (counting from 1)
Returns:
A[*, begin:end]
• #### diagonalMatrix

public static DiagonalMatrix diagonalMatrix(Matrix A)
Gets the diagonal of a matrix.
Parameters:
A - a matrix
Returns:
a diagonal matrix whose diagonal entries are Ai,i, zeros elsewhere
Throws:
IllegalArgumentException - if A is not square
• #### minorMatrix

public static Matrix minorMatrix(Matrix X,
int row,
int col)
Gets the minor matrix of a given matrix, by removing a specified row and a specified column.
Parameters:
X - the matrix
row - the index of the row to be removed
col - the index of the column to be removed
Returns:
the minor matrix
Wikipedia: Minor (linear algebra)
• #### randomDenseMatrix

public static DenseMatrix randomDenseMatrix(int nRows,
int nCols,
RandomNumberGenerator rng)
Constructs a random DenseMatrix.
Parameters:
nRows - the number of rows
nCols - the number of columns
rng - a random number generator
Returns:
a random DenseMatrix
• #### randomSymmetricMatrix

public static SymmetricMatrix randomSymmetricMatrix(int dim,
RandomNumberGenerator rng)
Constructs a random SymmetricMatrix.
Parameters:
dim - the matrix dimension
rng - a random number generator
Returns:
a random SymmetricMatrix
• #### randomLowerTriangularMatrix

public static LowerTriangularMatrix randomLowerTriangularMatrix(int dim,
RandomNumberGenerator rng)
Constructs a random LowerTriangularMatrix.
Parameters:
dim - the matrix dimension
rng - a random number generator
Returns:
a random SymmetricMatrix
• #### randomUpperTriangularMatrix

public static UpperTriangularMatrix randomUpperTriangularMatrix(int dim,
RandomNumberGenerator rng)
Constructs a random UpperTriangularMatrix.
Parameters:
dim - the matrix dimension
rng - a random number generator
Returns:
a random UpperTriangularMatrix
• #### randomDOKSparseMatrix

public static DOKSparseMatrix randomDOKSparseMatrix(int nRows,
int nCols,
int nNonZero,
RandomLongGenerator uniform)
Constructs a random DOKSparseMatrix.
Parameters:
nRows - the number of rows
nCols - the number of columns
nNonZero - the number of non-zero elements
uniform - a uniform random number generator
Returns:
a random DOKSparseMatrix
• #### randomLILSparseMatrix

public static LILSparseMatrix randomLILSparseMatrix(int nRows,
int nCols,
int nNonZero,
RandomLongGenerator uniform)
Constructs a random LILSparseMatrix.
Parameters:
nRows - the number of rows
nCols - the number of columns
nNonZero - the number of non-zero elements
uniform - a uniform random number generator
Returns:
a random LILSparseMatrix
• #### randomCSRSparseMatrix

public static CSRSparseMatrix randomCSRSparseMatrix(int nRows,
int nCols,
int nNonZero,
RandomLongGenerator uniform)
Constructs a random CSRSparseMatrix.
Parameters:
nRows - the number of rows
nCols - the number of columns
nNonZero - the number of non-zero elements
uniform - a uniform random number generator
Returns:
a random CSRSparseMatrix
• #### randomPositiveDefiniteMatrix

public static Matrix randomPositiveDefiniteMatrix(int dim,
RandomNumberGenerator rng)
Constructs a random symmetric, positive definite matrix.
Parameters:
dim - the matrix dimension
rng - a random number generator
Returns:
a random symmetric, positive definite matrix