This implementation is specially designed to be cache-friendly. Square blocks are stored as small arrays and allow efficient traversal of data both in row major direction and columns major direction, one block at a time. This greatly increases performances for algorithms that use crossed directions loops like multiplication or transposition.
The size of square blocks is a static parameter. It may be tuned according to the cache size of the target computer processor. As a rule of thumbs, it should be the largest value that allows three blocks to be simultaneously cached (this is necessary for example for matrix multiplication). The default value is to use 52x52 blocks which is well suited for processors with 64k L1 cache (one block holds 2704 values or 21632 bytes). This value could be lowered to 36x36 for processors with 32k L1 cache.
The regular blocks represent BLOCK_SIZE x BLOCK_SIZE squares. Blocks
at right hand side and bottom side which may be smaller to fit matrix dimensions. The square
blocks are flattened in row major order in single dimension arrays which are therefore
BLOCK_SIZE2 elements long for regular blocks. The blocks are themselves
organized in row major order.
As an example, for a block size of 52x52, a 100x60 matrix would be stored in 4 blocks. Block 0 would be a double[2704] array holding the upper left 52x52 square, block 1 would be a double[416] array holding the upper right 52x8 rectangle, block 2 would be a double[2496] array holding the lower left 48x52 rectangle and block 3 would be a double[384] array holding the lower right 48x8 rectangle.
The layout complexity overhead versus simple mapping of matrices to java arrays is negligible for small matrices (about 1%). The gain from cache efficiency leads to up to 3-fold improvements for matrices of moderate to large size.
| Modifier and Type | Field and Description |
|---|---|
| public static final int | BLOCK_SIZE
Block size. |
| private final int | blockColumns
Number of block columns of the matrix. |
| private final int | blockRows
Number of block rows of the matrix. |
| private final double[][] | blocks
Blocks of matrix entries. |
| private final int | columns
Number of columns of the matrix. |
| private final int | rows
Number of rows of the matrix. |
| private static final long | serialVersionUID
Serializable version identifier |
| Access | Constructor and Description |
|---|---|
| public | BlockRealMatrix(final int
the number of rows in the new matrix rows, final int the number of columns in the new matrix columns)Create a new matrix with the supplied row and column dimensions. |
| public | BlockRealMatrix(final double[][]
data for new matrix, in raw layout rawData)Create a new dense matrix copying entries from raw layout data. |
| public | BlockRealMatrix(final int
Number of rows in the new matrix. rows, final int Number of columns in the new matrix. columns, final double[][] data for new matrix blockData, final boolean Whether the input array will be copied or referenced. copyArray)Create a new dense matrix copying entries from block layout data. |
| Modifier and Type | Method and Description |
|---|---|
| public BlockRealMatrix | add(final RealMatrix
matrix to be added m)Overrides org. Implements org. Returns the sum of |
| public BlockRealMatrix | Returns: this + m.Matrix to be added. m)Compute the sum of this matrix and |
| public void | addToEntry(final int
Row index of the entry to be modified. row, final int Column index of the entry to be modified. column, final double value to add to the matrix entry. increment)Overrides org. Implements org. Adds (in place) the specified value to the specified entry of
|
| private int | Returns: height (number of rows) of the blockrow index (in block sense) of the block blockRow)Get the height of a block. |
| private int | Returns: width (number of columns) of the blockcolumn index (in block sense) of the block blockColumn)Get the width of a block. |
| public BlockRealMatrix | copy()
Implements abstract org. Implements org. Returns a (deep) copy of this. |
| private void | copyBlockPart(final double[]
source block srcBlock, final int source block width ( srcWidth, final int BLOCK_SIZE or smaller)start row in the source block srcStartRow, final int end row (exclusive) in the source block srcEndRow, final int start column in the source block srcStartColumn, final int end column (exclusive) in the source block srcEndColumn, final double[] destination block dstBlock, final int destination block width ( dstWidth, final int BLOCK_SIZE or smaller)start row in the destination block dstStartRow, final int start column in the destination block dstStartColumn)Copy a part of a block into another one This method can be called only when the specified part fits in both blocks, no verification is done here. |
| public static double[][] | Returns: a new data array in blocks layout.Number of rows in the new matrix. rows, final int Number of columns in the new matrix. columns)Create a data array in blocks layout. |
| public BlockRealMatrix | createMatrix(final int
the number of rows in the new matrix rowDimension, final int the number of columns in the new matrix columnDimension)Implements abstract org. Implements org. Create a new RealMatrix of the same type as the instance with the supplied row and column dimensions. |
| public double[] | getColumn(final int
Column to be fetched. column)Overrides org. Implements org. Get the entries at the given column index as an array. |
| public int | getColumnDimension()
Implements abstract org. Implements org. Returns the number of columns of this matrix. |
| public BlockRealMatrix | getColumnMatrix(final int
Column to be fetched. column)Overrides org. Implements org. Get the entries at the given column index as a column matrix. |
| public RealVector | getColumnVector(final int
Column to be fetched. column)Overrides org. Implements org. Get the entries at the given column index as a vector. |
| public double[][] | getData()
Overrides org. Implements org. Returns matrix entries as a two-dimensional array. |
| public double | getEntry(final int
Row index of entry to be fetched. row, final int Column index of entry to be fetched. column)Implements abstract org. Implements org. Get the entry in the specified row and column. |
| public double | getFrobeniusNorm()
Overrides org. Implements org. Returns the Frobenius norm of the matrix. |
| public double | getNorm()
Overrides org. Implements org. Returns the maximum absolute row sum norm of the matrix. |
| public double[] | getRow(final int
Row to be fetched. row)Overrides org. Implements org. Get the entries at the given row index. |
| public int | getRowDimension()
Implements abstract org. Implements org. Returns the number of rows of this matrix. |
| public BlockRealMatrix | getRowMatrix(final int
Row to be fetched. row)Overrides org. Implements org. Get the entries at the given row index as a row matrix. |
| public RealVector | getRowVector(final int
Row to be fetched. row)Overrides org. Implements org. Returns the entries in row number |
| public BlockRealMatrix | getSubMatrix(final int
Initial row index startRow, final int Final row index (inclusive) endRow, final int Initial column index startColumn, final int Final column index (inclusive) endColumn)Overrides org. Implements org. Gets a submatrix. |
| public BlockRealMatrix | multiply(final RealMatrix
matrix to postmultiply by m)Overrides org. Implements org. Returns the result of postmultiplying |
| public BlockRealMatrix | Returns: this * m.Matrix to postmultiply by. m)Returns the result of postmultiplying this by |
| public void | multiplyEntry(final int
Row index of the entry to be modified. row, final int Column index of the entry to be modified. column, final double Multiplication factor for the matrix entry. factor)Overrides org. Implements org. Multiplies (in place) the specified entry of |
| public double[] | operate(final double[]
the vector to operate on v)Overrides org. Implements org. Returns the result of multiplying this by the vector |
| public double[] | preMultiply(final double[]
the row vector to premultiply by v)Overrides org. Implements org. Returns the (row) vector result of premultiplying this by the vector |
| public BlockRealMatrix | scalarAdd(final double
value to be added to each entry d)Overrides org. Implements org. Returns the result of adding |
| public RealMatrix | scalarMultiply(final double
value to multiply all entries by d)Overrides org. Implements org. Returns the result of multiplying each entry of |
| public void | setColumn(final int
Column to be set. column, final double[] Column array to be copied (must have the same number of
rows as the instance). array)Overrides org. Implements org. Sets the specified |
| public void | setColumnMatrix(final int
Column to be set. column, final RealMatrix Column matrix to be copied (must have one column and the
same number of rows as the instance). matrix)Overrides org. Implements org. Sets the specified |
| pack-priv void | setColumnMatrix(final int
the column to be set column, final BlockRealMatrix column matrix (must have one column and the same number of rows
as the instance) matrix)Sets the entries in column number |
| public void | setColumnVector(final int
Column to be set. column, final RealVector column vector to be copied (must have the same number of
rows as the instance). vector)Overrides org. Implements org. Sets the specified |
| public void | setEntry(final int
Row index of entry to be set. row, final int Column index of entry to be set. column, final double the new value of the entry. value)Implements abstract org. Implements org. Set the entry in the specified row and column. |
| public void | setRow(final int
Row to be set. row, final double[] Row matrix to be copied (must have the same number of
columns as the instance) array)Overrides org. Implements org. Sets the specified |
| public void | setRowMatrix(final int
Row to be set. row, final RealMatrix Row matrix to be copied (must have one row and the same
number of columns as the instance). matrix)Overrides org. Implements org. Sets the specified |
| public void | setRowMatrix(final int
the row to be set row, final BlockRealMatrix row matrix (must have one row and the same number of columns
as the instance) matrix)Sets the entries in row number |
| public void | setRowVector(final int
Row to be set. row, final RealVector row vector to be copied (must have the same number of
column as the instance). vector)Overrides org. Implements org. Sets the specified |
| public void | setSubMatrix(final double[][]
array containing the submatrix replacement data subMatrix, final int row coordinate of the top, left element to be replaced row, final int column coordinate of the top, left element to be replaced column)Overrides org. Implements org. Replace the submatrix starting at |
| public BlockRealMatrix | subtract(final RealMatrix
matrix to be subtracted m)Overrides org. Implements org. Returns |
| public BlockRealMatrix | Returns: this - m.Matrix to be subtracted. m)Subtract |
| public static double[][] | Returns: a new data array containing the same entries but in blocks layout.Data array in raw layout. rawData)Convert a data array from raw layout to blocks layout. |
| public BlockRealMatrix | transpose()
Overrides org. Implements org. Returns the transpose of this matrix. |
| public double | walkInOptimizedOrder(final RealMatrixChangingVisitor
visitor used to process all matrix entries visitor)Overrides org. Implements org. Visit (and possibly change) all matrix entries using the fastest possible order. |
| public double | walkInOptimizedOrder(final RealMatrixPreservingVisitor
visitor used to process all matrix entries visitor)Overrides org. Implements org. Visit (but don't change) all matrix entries using the fastest possible order. |
| public double | walkInOptimizedOrder(final RealMatrixChangingVisitor
visitor used to process all matrix entries visitor, final int Initial row index startRow, final int Final row index (inclusive) endRow, final int Initial column index startColumn, final int Final column index (inclusive) endColumn)Overrides org. Implements org. Visit (and possibly change) some matrix entries using the fastest possible order. |
| public double | walkInOptimizedOrder(final RealMatrixPreservingVisitor
visitor used to process all matrix entries visitor, final int Initial row index startRow, final int Final row index (inclusive) endRow, final int Initial column index startColumn, final int Final column index (inclusive) endColumn)Overrides org. Implements org. Visit (but don't change) some matrix entries using the fastest possible order. |
| public double | walkInRowOrder(final RealMatrixChangingVisitor
visitor used to process all matrix entries visitor)Overrides org. Implements org. Visit (and possibly change) all matrix entries in row order. |
| public double | walkInRowOrder(final RealMatrixPreservingVisitor
visitor used to process all matrix entries visitor)Overrides org. Implements org. Visit (but don't change) all matrix entries in row order. |
| public double | walkInRowOrder(final RealMatrixChangingVisitor
visitor used to process all matrix entries visitor, final int Initial row index startRow, final int Final row index (inclusive) endRow, final int Initial column index startColumn, final int Final column index endColumn)Overrides org. Implements org. Visit (and possibly change) some matrix entries in row order. |
| public double | walkInRowOrder(final RealMatrixPreservingVisitor
visitor used to process all matrix entries visitor, final int Initial row index startRow, final int Final row index (inclusive) endRow, final int Initial column index startColumn, final int Final column index endColumn)Overrides org. Implements org. Visit (but don't change) some matrix entries in row order. |