Class MatrixFactory


  • public class MatrixFactory
    extends Object
    These are the utility functions to create a new matrix/vector from existing ones.
    • 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,
                                       List<Integer> rows,
                                       List<Integer> 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 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
        See Also:
        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
      • 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