org.apache.commons.math3.linear

## Class BlockRealMatrix

• All Implemented Interfaces:
Serializable, AnyMatrix, RealMatrix

public class BlockRealMatrix
extends AbstractRealMatrix
implements Serializable
Cache-friendly implementation of RealMatrix using a flat arrays to store square blocks of the matrix.

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.

Since:
2.0
Serialized Form
• ### Field Summary

Fields
Modifier and Type Field and Description
static int BLOCK_SIZE
Block size.
• ### Constructor Summary

Constructors
Constructor and Description
BlockRealMatrix(double[][] rawData)
Create a new dense matrix copying entries from raw layout data.
BlockRealMatrix(int rows, int columns)
Create a new matrix with the supplied row and column dimensions.
BlockRealMatrix(int rows, int columns, double[][] blockData, boolean copyArray)
Create a new dense matrix copying entries from block layout data.
• ### Method Summary

Methods
Modifier and Type Method and Description
BlockRealMatrix add(BlockRealMatrix m)
Compute the sum of this matrix and m.
BlockRealMatrix add(RealMatrix m)
Returns the sum of this and m.
void addToEntry(int row, int column, double increment)
Adds (in place) the specified value to the specified entry of this matrix.
BlockRealMatrix copy()
Returns a (deep) copy of this.
static double[][] createBlocksLayout(int rows, int columns)
Create a data array in blocks layout.
BlockRealMatrix createMatrix(int rowDimension, int columnDimension)
Create a new RealMatrix of the same type as the instance with the supplied row and column dimensions.
double[] getColumn(int column)
Get the entries at the given column index as an array.
int getColumnDimension()
Returns the number of columns of this matrix.
BlockRealMatrix getColumnMatrix(int column)
Get the entries at the given column index as a column matrix.
RealVector getColumnVector(int column)
Get the entries at the given column index as a vector.
double[][] getData()
Returns matrix entries as a two-dimensional array.
double getEntry(int row, int column)
Get the entry in the specified row and column.
double getFrobeniusNorm()
Returns the Frobenius norm of the matrix.
double getNorm()
Returns the maximum absolute row sum norm of the matrix.
double[] getRow(int row)
Get the entries at the given row index.
int getRowDimension()
Returns the number of rows of this matrix.
BlockRealMatrix getRowMatrix(int row)
Get the entries at the given row index as a row matrix.
RealVector getRowVector(int row)
Returns the entries in row number row as a vector.
BlockRealMatrix getSubMatrix(int startRow, int endRow, int startColumn, int endColumn)
Gets a submatrix.
BlockRealMatrix multiply(BlockRealMatrix m)
Returns the result of postmultiplying this by m.
BlockRealMatrix multiply(RealMatrix m)
Returns the result of postmultiplying this by m.
void multiplyEntry(int row, int column, double factor)
Multiplies (in place) the specified entry of this matrix by the specified value.
double[] operate(double[] v)
Returns the result of multiplying this by the vector v.
double[] preMultiply(double[] v)
Returns the (row) vector result of premultiplying this by the vector v.
BlockRealMatrix scalarAdd(double d)
Returns the result of adding d to each entry of this.
RealMatrix scalarMultiply(double d)
Returns the result of multiplying each entry of this by d.
void setColumn(int column, double[] array)
Sets the specified column of this matrix to the entries of the specified array.
void setColumnMatrix(int column, RealMatrix matrix)
Sets the specified column of this matrix to the entries of the specified column matrix.
void setColumnVector(int column, RealVector vector)
Sets the specified column of this matrix to the entries of the specified vector.
void setEntry(int row, int column, double value)
Set the entry in the specified row and column.
void setRow(int row, double[] array)
Sets the specified row of this matrix to the entries of the specified array.
void setRowMatrix(int row, BlockRealMatrix matrix)
Sets the entries in row number row as a row matrix.
void setRowMatrix(int row, RealMatrix matrix)
Sets the specified row of this matrix to the entries of the specified row matrix.
void setRowVector(int row, RealVector vector)
Sets the specified row of this matrix to the entries of the specified vector.
void setSubMatrix(double[][] subMatrix, int row, int column)
Replace the submatrix starting at row, column using data in the input subMatrix array.
BlockRealMatrix subtract(BlockRealMatrix m)
Subtract m from this matrix.
BlockRealMatrix subtract(RealMatrix m)
Returns this minus m.
static double[][] toBlocksLayout(double[][] rawData)
Convert a data array from raw layout to blocks layout.
BlockRealMatrix transpose()
Returns the transpose of this matrix.
double walkInOptimizedOrder(RealMatrixChangingVisitor visitor)
Visit (and possibly change) all matrix entries using the fastest possible order.
double walkInOptimizedOrder(RealMatrixChangingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)
Visit (and possibly change) some matrix entries using the fastest possible order.
double walkInOptimizedOrder(RealMatrixPreservingVisitor visitor)
Visit (but don't change) all matrix entries using the fastest possible order.
double walkInOptimizedOrder(RealMatrixPreservingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)
Visit (but don't change) some matrix entries using the fastest possible order.
double walkInRowOrder(RealMatrixChangingVisitor visitor)
Visit (and possibly change) all matrix entries in row order.
double walkInRowOrder(RealMatrixChangingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)
Visit (and possibly change) some matrix entries in row order.
double walkInRowOrder(RealMatrixPreservingVisitor visitor)
Visit (but don't change) all matrix entries in row order.
double walkInRowOrder(RealMatrixPreservingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)
Visit (but don't change) some matrix entries in row order.
• ### Methods inherited from class org.apache.commons.math3.linear.AbstractRealMatrix

copySubMatrix, copySubMatrix, equals, getSubMatrix, getTrace, hashCode, isSquare, operate, power, preMultiply, preMultiply, toString, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder
• ### Methods inherited from class org.apache.commons.math3.linear.RealLinearOperator

isTransposable, operateTranspose
• ### Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
• ### Field Detail

• #### BLOCK_SIZE

public static final int BLOCK_SIZE
Block size.
Constant Field Values
• ### Constructor Detail

• #### BlockRealMatrix

public BlockRealMatrix(int rows,
int columns)
throws NotStrictlyPositiveException
Create a new matrix with the supplied row and column dimensions.
Parameters:
rows - the number of rows in the new matrix
columns - the number of columns in the new matrix
Throws:
NotStrictlyPositiveException - if row or column dimension is not positive.
• #### BlockRealMatrix

public BlockRealMatrix(double[][] rawData)
throws DimensionMismatchException,
NotStrictlyPositiveException
Create a new dense matrix copying entries from raw layout data.

The input array must already be in raw layout.

Calling this constructor is equivalent to call:

matrix = new BlockRealMatrix(rawData.length, rawData[0].length,
toBlocksLayout(rawData), false);

Parameters:
rawData - data for new matrix, in raw layout
Throws:
DimensionMismatchException - if the shape of blockData is inconsistent with block layout.
NotStrictlyPositiveException - if row or column dimension is not positive.
BlockRealMatrix(int, int, double[][], boolean)
• #### BlockRealMatrix

public BlockRealMatrix(int rows,
int columns,
double[][] blockData,
boolean copyArray)
throws DimensionMismatchException,
NotStrictlyPositiveException
Create a new dense matrix copying entries from block layout data.

The input array must already be in blocks layout.

Parameters:
rows - Number of rows in the new matrix.
columns - Number of columns in the new matrix.
blockData - data for new matrix
copyArray - Whether the input array will be copied or referenced.
Throws:
DimensionMismatchException - if the shape of blockData is inconsistent with block layout.
NotStrictlyPositiveException - if row or column dimension is not positive.
createBlocksLayout(int, int), toBlocksLayout(double[][]), BlockRealMatrix(double[][])