org.apache.commons.math.linear

Class MatrixUtils

java.lang.Object

org.apache.commons.math.linear.MatrixUtils

public class MatrixUtils
extends java.lang.Object

A collection of static methods that operate on or return matrices.

Method Summary

Modifier and Type	Method and Description
static Array2DRowRealMatrix	bigFractionMatrixToRealMatrix(FieldMatrix<BigFraction> m) Convert a FieldMatrix/BigFraction matrix to a RealMatrix.
static void	checkAdditionCompatible(AnyMatrix left, AnyMatrix right) Check if matrices are addition compatible
static void	checkColumnIndex(AnyMatrix m, int column) Check if a column index is valid.
static void	checkMultiplicationCompatible(AnyMatrix left, AnyMatrix right) Check if matrices are multiplication compatible
static void	checkRowIndex(AnyMatrix m, int row) Check if a row index is valid.
static void	checkSubMatrixIndex(AnyMatrix m, int[] selectedRows, int[] selectedColumns) Check if submatrix ranges indices are valid.
static void	checkSubMatrixIndex(AnyMatrix m, int startRow, int endRow, int startColumn, int endColumn) Check if submatrix ranges indices are valid.
static void	checkSubtractionCompatible(AnyMatrix left, AnyMatrix right) Check if matrices are subtraction compatible
static BigMatrix	createBigIdentityMatrix(int dimension) Deprecated. since 2.0, replaced by createFieldIdentityMatrix(Field, int)
static BigMatrix	createBigMatrix(java.math.BigDecimal[][] data) Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])
static BigMatrix	createBigMatrix(java.math.BigDecimal[][] data, boolean copyArray) Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])
static BigMatrix	createBigMatrix(double[][] data) Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])
static BigMatrix	createBigMatrix(java.lang.String[][] data) Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])
static BigMatrix	createColumnBigMatrix(java.math.BigDecimal[] columnData) Deprecated. since 2.0 replaced by createColumnFieldMatrix(FieldElement[])
static BigMatrix	createColumnBigMatrix(double[] columnData) Deprecated. since 2.0 replaced by createColumnFieldMatrix(FieldElement[])
static BigMatrix	createColumnBigMatrix(java.lang.String[] columnData) Deprecated. since 2.0 replaced by createColumnFieldMatrix(FieldElement[])
static <T extends FieldElement<T>> FieldMatrix<T>	createColumnFieldMatrix(T[] columnData) Creates a column FieldMatrix using the data from the input array.
static RealMatrix	createColumnRealMatrix(double[] columnData) Creates a column RealMatrix using the data from the input array.
static <T extends FieldElement<T>> FieldMatrix<T>	createFieldDiagonalMatrix(T[] diagonal) Returns a diagonal matrix with specified elements.
static <T extends FieldElement<T>> FieldMatrix<T>	createFieldIdentityMatrix(Field<T> field, int dimension) Returns dimension x dimension identity matrix.
static <T extends FieldElement<T>> FieldMatrix<T>	createFieldMatrix(Field<T> field, int rows, int columns) Returns a FieldMatrix with specified dimensions.
static <T extends FieldElement<T>> FieldMatrix<T>	createFieldMatrix(T[][] data) Returns a FieldMatrix whose entries are the the values in the the input array.
static <T extends FieldElement<T>> FieldVector<T>	createFieldVector(T[] data) Creates a FieldVector using the data from the input array.
static RealMatrix	createRealDiagonalMatrix(double[] diagonal) Returns a diagonal matrix with specified elements.
static RealMatrix	createRealIdentityMatrix(int dimension) Returns dimension x dimension identity matrix.
static RealMatrix	createRealMatrix(double[][] data) Returns a RealMatrix whose entries are the the values in the the input array.
static RealMatrix	createRealMatrix(int rows, int columns) Returns a RealMatrix with specified dimensions.
static RealVector	createRealVector(double[] data) Creates a RealVector using the data from the input array.
static BigMatrix	createRowBigMatrix(java.math.BigDecimal[] rowData) Deprecated. since 2.0 replaced by createRowFieldMatrix(FieldElement[])
static BigMatrix	createRowBigMatrix(double[] rowData) Deprecated. since 2.0 replaced by createRowFieldMatrix(FieldElement[])
static BigMatrix	createRowBigMatrix(java.lang.String[] rowData) Deprecated. since 2.0 replaced by createRowFieldMatrix(FieldElement[])
static <T extends FieldElement<T>> FieldMatrix<T>	createRowFieldMatrix(T[] rowData) Creates a row FieldMatrix using the data from the input array.
static RealMatrix	createRowRealMatrix(double[] rowData) Creates a row RealMatrix using the data from the input array.
static void	deserializeRealMatrix(java.lang.Object instance, java.lang.String fieldName, java.io.ObjectInputStream ois) Deserialize a RealMatrix field in a class.
static void	deserializeRealVector(java.lang.Object instance, java.lang.String fieldName, java.io.ObjectInputStream ois) Deserialize a RealVector field in a class.
static Array2DRowRealMatrix	fractionMatrixToRealMatrix(FieldMatrix<Fraction> m) Convert a FieldMatrix/Fraction matrix to a RealMatrix.
static void	serializeRealMatrix(RealMatrix matrix, java.io.ObjectOutputStream oos) Serialize a RealMatrix.
static void	serializeRealVector(RealVector vector, java.io.ObjectOutputStream oos) Serialize a RealVector.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createRealMatrix

public static RealMatrix createRealMatrix(int rows,
                                          int columns)

Returns a RealMatrix with specified dimensions.

The type of matrix returned depends on the dimension. Below 2¹² elements (i.e. 4096 elements or 64×64 for a square matrix) which can be stored in a 32kB array, a Array2DRowRealMatrix instance is built. Above this threshold a BlockRealMatrix instance is built.

The matrix elements are all set to 0.0.

Parameters:

rows - number of rows of the matrix

columns - number of columns of the matrix

Returns:

RealMatrix with specified dimensions

See Also:

createRealMatrix(double[][])

createFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldMatrix(Field<T> field,
                                                                           int rows,
                                                                           int columns)

Returns a FieldMatrix with specified dimensions.

The type of matrix returned depends on the dimension. Below 2¹² elements (i.e. 4096 elements or 64×64 for a square matrix), a FieldMatrix instance is built. Above this threshold a BlockFieldMatrix instance is built.

The matrix elements are all set to field.getZero().

Type Parameters:

T - the type of the field elements

Parameters:

field - field to which the matrix elements belong

rows - number of rows of the matrix

columns - number of columns of the matrix

Returns:

FieldMatrix with specified dimensions

Since:

2.0

See Also:

createFieldMatrix(FieldElement[][])

createRealMatrix

public static RealMatrix createRealMatrix(double[][] data)

Returns a RealMatrix whose entries are the the values in the the input array.

The type of matrix returned depends on the dimension. Below 2¹² elements (i.e. 4096 elements or 64×64 for a square matrix) which can be stored in a 32kB array, a Array2DRowRealMatrix instance is built. Above this threshold a BlockRealMatrix instance is built.

The input array is copied, not referenced.

Parameters:

data - input array

Returns:

RealMatrix containing the values of the array

Throws:

java.lang.IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

java.lang.NullPointerException - if either data or data[0] is null

See Also:

createRealMatrix(int, int)

createFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldMatrix(T[][] data)

Returns a FieldMatrix whose entries are the the values in the the input array.

The type of matrix returned depends on the dimension. Below 2¹² elements (i.e. 4096 elements or 64×64 for a square matrix), a FieldMatrix instance is built. Above this threshold a BlockFieldMatrix instance is built.

The input array is copied, not referenced.

Type Parameters:

T - the type of the field elements

Parameters:

data - input array

Returns:

RealMatrix containing the values of the array

Throws:

java.lang.IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

java.lang.NullPointerException - if either data or data[0] is null

Since:

2.0

See Also:

createFieldMatrix(Field, int, int)

createRealIdentityMatrix

public static RealMatrix createRealIdentityMatrix(int dimension)

Returns dimension x dimension identity matrix.

Parameters:

dimension - dimension of identity matrix to generate

Returns:

identity matrix

Throws:

java.lang.IllegalArgumentException - if dimension is not positive

Since:

1.1

createFieldIdentityMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldIdentityMatrix(Field<T> field,
                                                                                   int dimension)

Returns dimension x dimension identity matrix.

Type Parameters:

T - the type of the field elements

Parameters:

field - field to which the elements belong

dimension - dimension of identity matrix to generate

Returns:

identity matrix

Throws:

java.lang.IllegalArgumentException - if dimension is not positive

Since:

2.0

createBigIdentityMatrix

@Deprecated
public static BigMatrix createBigIdentityMatrix(int dimension)

Deprecated. since 2.0, replaced by createFieldIdentityMatrix(Field, int)

Returns dimension x dimension identity matrix.

Parameters:

dimension - dimension of identity matrix to generate

Returns:

identity matrix

Throws:

java.lang.IllegalArgumentException - if dimension is not positive

Since:

1.1

createRealDiagonalMatrix

public static RealMatrix createRealDiagonalMatrix(double[] diagonal)

Returns a diagonal matrix with specified elements.

Parameters:

diagonal - diagonal elements of the matrix (the array elements will be copied)

Returns:

diagonal matrix

Since:

2.0

createFieldDiagonalMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldDiagonalMatrix(T[] diagonal)

Returns a diagonal matrix with specified elements.

Type Parameters:

T - the type of the field elements

Parameters:

diagonal - diagonal elements of the matrix (the array elements will be copied)

Returns:

diagonal matrix

Since:

2.0

createBigMatrix

@Deprecated
public static BigMatrix createBigMatrix(double[][] data)

Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])

Returns a BigMatrix whose entries are the the values in the the input array. The input array is copied, not referenced.

Parameters:

data - input array

Returns:

RealMatrix containing the values of the array

Throws:

java.lang.IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

java.lang.NullPointerException - if data is null

createBigMatrix

@Deprecated
public static BigMatrix createBigMatrix(java.math.BigDecimal[][] data)

Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])

Returns a BigMatrix whose entries are the the values in the the input array. The input array is copied, not referenced.

Parameters:

data - input array

Returns:

RealMatrix containing the values of the array

Throws:

java.lang.IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

java.lang.NullPointerException - if data is null

createBigMatrix

@Deprecated
public static BigMatrix createBigMatrix(java.math.BigDecimal[][] data,
                                                    boolean copyArray)

Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])

Returns a BigMatrix whose entries are the the values in the the input array.

If an array is built specially in order to be embedded in a BigMatrix and not used directly, the copyArray may be set to false

Parameters:

data - data for new matrix

copyArray - if true, the input array will be copied, otherwise it will be referenced

Returns:

BigMatrix containing the values of the array

Throws:

java.lang.IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

java.lang.NullPointerException - if data is null

See Also:

createRealMatrix(double[][])

createBigMatrix

@Deprecated
public static BigMatrix createBigMatrix(java.lang.String[][] data)

Deprecated. since 2.0 replaced by createFieldMatrix(FieldElement[][])

Returns a BigMatrix whose entries are the the values in the the input array. The input array is copied, not referenced.

Parameters:

data - input array

Returns:

RealMatrix containing the values of the array

Throws:

java.lang.IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

java.lang.NullPointerException - if data is null

createRealVector

public static RealVector createRealVector(double[] data)

Creates a RealVector using the data from the input array.

Parameters:

data - the input data

Returns:

a data.length RealVector

Throws:

java.lang.IllegalArgumentException - if data is empty

java.lang.NullPointerException - if datais null

createFieldVector

public static <T extends FieldElement<T>> FieldVector<T> createFieldVector(T[] data)

Creates a FieldVector using the data from the input array.

Type Parameters:

T - the type of the field elements

Parameters:

data - the input data

Returns:

a data.length FieldVector

Throws:

java.lang.IllegalArgumentException - if data is empty

java.lang.NullPointerException - if datais null

createRowRealMatrix

public static RealMatrix createRowRealMatrix(double[] rowData)

Creates a row RealMatrix using the data from the input array.

Parameters:

rowData - the input row data

Returns:

a 1 x rowData.length RealMatrix

Throws:

java.lang.IllegalArgumentException - if rowData is empty

java.lang.NullPointerException - if rowDatais null

createRowFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createRowFieldMatrix(T[] rowData)

Creates a row FieldMatrix using the data from the input array.

Type Parameters:

T - the type of the field elements

Parameters:

rowData - the input row data

Returns:

a 1 x rowData.length FieldMatrix

Throws:

java.lang.IllegalArgumentException - if rowData is empty

java.lang.NullPointerException - if rowDatais null

createRowBigMatrix

@Deprecated
public static BigMatrix createRowBigMatrix(double[] rowData)

Deprecated. since 2.0 replaced by createRowFieldMatrix(FieldElement[])

Creates a row BigMatrix using the data from the input array.

Parameters:

rowData - the input row data

Returns:

a 1 x rowData.length BigMatrix

Throws:

java.lang.IllegalArgumentException - if rowData is empty

java.lang.NullPointerException - if rowDatais null

createRowBigMatrix

@Deprecated
public static BigMatrix createRowBigMatrix(java.math.BigDecimal[] rowData)

Deprecated. since 2.0 replaced by createRowFieldMatrix(FieldElement[])

Creates a row BigMatrix using the data from the input array.

Parameters:

rowData - the input row data

Returns:

a 1 x rowData.length BigMatrix

Throws:

java.lang.IllegalArgumentException - if rowData is empty

java.lang.NullPointerException - if rowDatais null

createRowBigMatrix

@Deprecated
public static BigMatrix createRowBigMatrix(java.lang.String[] rowData)

Deprecated. since 2.0 replaced by createRowFieldMatrix(FieldElement[])

Creates a row BigMatrix using the data from the input array.

Parameters:

rowData - the input row data

Returns:

a 1 x rowData.length BigMatrix

Throws:

java.lang.IllegalArgumentException - if rowData is empty

java.lang.NullPointerException - if rowDatais null

createColumnRealMatrix

public static RealMatrix createColumnRealMatrix(double[] columnData)

Creates a column RealMatrix using the data from the input array.

Parameters:

columnData - the input column data

Returns:

a columnData x 1 RealMatrix

Throws:

java.lang.IllegalArgumentException - if columnData is empty

java.lang.NullPointerException - if columnDatais null

createColumnFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createColumnFieldMatrix(T[] columnData)

Creates a column FieldMatrix using the data from the input array.

Type Parameters:

T - the type of the field elements

Parameters:

columnData - the input column data

Returns:

a columnData x 1 FieldMatrix

Throws:

java.lang.IllegalArgumentException - if columnData is empty

java.lang.NullPointerException - if columnDatais null

createColumnBigMatrix

@Deprecated
public static BigMatrix createColumnBigMatrix(double[] columnData)

Deprecated. since 2.0 replaced by createColumnFieldMatrix(FieldElement[])

Creates a column BigMatrix using the data from the input array.

Parameters:

columnData - the input column data

Returns:

a columnData x 1 BigMatrix

Throws:

java.lang.IllegalArgumentException - if columnData is empty

java.lang.NullPointerException - if columnDatais null

createColumnBigMatrix

@Deprecated
public static BigMatrix createColumnBigMatrix(java.math.BigDecimal[] columnData)

Deprecated. since 2.0 replaced by createColumnFieldMatrix(FieldElement[])

Creates a column BigMatrix using the data from the input array.

Parameters:

columnData - the input column data

Returns:

a columnData x 1 BigMatrix

Throws:

java.lang.IllegalArgumentException - if columnData is empty

java.lang.NullPointerException - if columnDatais null

createColumnBigMatrix

@Deprecated
public static BigMatrix createColumnBigMatrix(java.lang.String[] columnData)

Deprecated. since 2.0 replaced by createColumnFieldMatrix(FieldElement[])

Creates a column BigMatrix using the data from the input array.

Parameters:

columnData - the input column data

Returns:

a columnData x 1 BigMatrix

Throws:

java.lang.IllegalArgumentException - if columnData is empty

java.lang.NullPointerException - if columnDatais null

checkRowIndex

public static void checkRowIndex(AnyMatrix m,
                                 int row)

Check if a row index is valid.

Parameters:

m - matrix containing the submatrix

row - row index to check

Throws:

MatrixIndexException - if index is not valid

checkColumnIndex

public static void checkColumnIndex(AnyMatrix m,
                                    int column)
                             throws MatrixIndexException

Check if a column index is valid.

Parameters:

m - matrix containing the submatrix

column - column index to check

Throws:

MatrixIndexException - if index is not valid

checkSubMatrixIndex

public static void checkSubMatrixIndex(AnyMatrix m,
                                       int startRow,
                                       int endRow,
                                       int startColumn,
                                       int endColumn)

Check if submatrix ranges indices are valid. Rows and columns are indicated counting from 0 to n-1.

Parameters:

m - matrix containing the submatrix

startRow - Initial row index

endRow - Final row index

startColumn - Initial column index

endColumn - Final column index

Throws:

MatrixIndexException - if the indices are not valid

checkSubMatrixIndex

public static void checkSubMatrixIndex(AnyMatrix m,
                                       int[] selectedRows,
                                       int[] selectedColumns)
                                throws MatrixIndexException

Check if submatrix ranges indices are valid. Rows and columns are indicated counting from 0 to n-1.

Parameters:

m - matrix containing the submatrix

selectedRows - Array of row indices.

selectedColumns - Array of column indices.

Throws:

MatrixIndexException - if row or column selections are not valid

checkAdditionCompatible

public static void checkAdditionCompatible(AnyMatrix left,
                                           AnyMatrix right)
                                    throws java.lang.IllegalArgumentException

Check if matrices are addition compatible

Parameters:

left - left hand side matrix

right - right hand side matrix

Throws:

java.lang.IllegalArgumentException - if matrices are not addition compatible

checkSubtractionCompatible

public static void checkSubtractionCompatible(AnyMatrix left,
                                              AnyMatrix right)
                                       throws java.lang.IllegalArgumentException

Check if matrices are subtraction compatible

Parameters:

left - left hand side matrix

right - right hand side matrix

Throws:

java.lang.IllegalArgumentException - if matrices are not subtraction compatible

checkMultiplicationCompatible

public static void checkMultiplicationCompatible(AnyMatrix left,
                                                 AnyMatrix right)
                                          throws java.lang.IllegalArgumentException

Check if matrices are multiplication compatible

Parameters:

left - left hand side matrix

right - right hand side matrix

Throws:

java.lang.IllegalArgumentException - if matrices are not multiplication compatible

fractionMatrixToRealMatrix

public static Array2DRowRealMatrix fractionMatrixToRealMatrix(FieldMatrix<Fraction> m)

Convert a FieldMatrix/Fraction matrix to a RealMatrix.

Parameters:

m - matrix to convert

Returns:

converted matrix

bigFractionMatrixToRealMatrix

public static Array2DRowRealMatrix bigFractionMatrixToRealMatrix(FieldMatrix<BigFraction> m)

Convert a FieldMatrix/BigFraction matrix to a RealMatrix.

Parameters:

m - matrix to convert

Returns:

converted matrix

serializeRealVector

public static void serializeRealVector(RealVector vector,
                                       java.io.ObjectOutputStream oos)
                                throws java.io.IOException

Serialize a RealVector.

This method is intended to be called from within a private writeObject method (after a call to oos.defaultWriteObject()) in a class that has a RealVector field, which should be declared transient. This way, the default handling does not serialize the vector (the RealVector interface is not serializable by default) but this method does serialize it specifically.

The following example shows how a simple class with a name and a real vector should be written:

 public class NamedVector implements Serializable {

     private final String name;
     private final transient RealVector coefficients;

     // omitted constructors, getters ...

     private void writeObject(ObjectOutputStream oos) throws IOException {
         oos.defaultWriteObject();  // takes care of name field
         MatrixUtils.serializeRealVector(coefficients, oos);
     }

     private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException {
         ois.defaultReadObject();  // takes care of name field
         MatrixUtils.deserializeRealVector(this, "coefficients", ois);
     }

 }
 

Parameters:

vector - real vector to serialize

oos - stream where the real vector should be written

Throws:

java.io.IOException - if object cannot be written to stream

See Also:

deserializeRealVector(Object, String, ObjectInputStream)

deserializeRealVector

public static void deserializeRealVector(java.lang.Object instance,
                                         java.lang.String fieldName,
                                         java.io.ObjectInputStream ois)
                                  throws java.lang.ClassNotFoundException,
                                         java.io.IOException

Deserialize a RealVector field in a class.

This method is intended to be called from within a private readObject method (after a call to ois.defaultReadObject()) in a class that has a RealVector field, which should be declared transient. This way, the default handling does not deserialize the vector (the RealVector interface is not serializable by default) but this method does deserialize it specifically.

Parameters:

instance - instance in which the field must be set up

fieldName - name of the field within the class (may be private and final)

ois - stream from which the real vector should be read

Throws:

java.lang.ClassNotFoundException - if a class in the stream cannot be found

java.io.IOException - if object cannot be read from the stream

See Also:

serializeRealVector(RealVector, ObjectOutputStream)

serializeRealMatrix

public static void serializeRealMatrix(RealMatrix matrix,
                                       java.io.ObjectOutputStream oos)
                                throws java.io.IOException

Serialize a RealMatrix.

This method is intended to be called from within a private writeObject method (after a call to oos.defaultWriteObject()) in a class that has a RealMatrix field, which should be declared transient. This way, the default handling does not serialize the matrix (the RealMatrix interface is not serializable by default) but this method does serialize it specifically.

The following example shows how a simple class with a name and a real matrix should be written:

 public class NamedMatrix implements Serializable {

     private final String name;
     private final transient RealMatrix coefficients;

     // omitted constructors, getters ...

     private void writeObject(ObjectOutputStream oos) throws IOException {
         oos.defaultWriteObject();  // takes care of name field
         MatrixUtils.serializeRealMatrix(coefficients, oos);
     }

     private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException {
         ois.defaultReadObject();  // takes care of name field
         MatrixUtils.deserializeRealMatrix(this, "coefficients", ois);
     }

 }
 

Parameters:

matrix - real matrix to serialize

oos - stream where the real matrix should be written

Throws:

java.io.IOException - if object cannot be written to stream

See Also:

deserializeRealMatrix(Object, String, ObjectInputStream)

deserializeRealMatrix

public static void deserializeRealMatrix(java.lang.Object instance,
                                         java.lang.String fieldName,
                                         java.io.ObjectInputStream ois)
                                  throws java.lang.ClassNotFoundException,
                                         java.io.IOException

Deserialize a RealMatrix field in a class.

This method is intended to be called from within a private readObject method (after a call to ois.defaultReadObject()) in a class that has a RealMatrix field, which should be declared transient. This way, the default handling does not deserialize the matrix (the RealMatrix interface is not serializable by default) but this method does deserialize it specifically.

Parameters:

instance - instance in which the field must be set up

fieldName - name of the field within the class (may be private and final)

ois - stream from which the real matrix should be read

Throws:

java.lang.ClassNotFoundException - if a class in the stream cannot be found

java.io.IOException - if object cannot be read from the stream

See Also:

serializeRealMatrix(RealMatrix, ObjectOutputStream)