fr.cnes.sirius.patrius.math.linear

Class ArrayRowSymmetricMatrix

java.lang.Object

fr.cnes.sirius.patrius.math.linear.RealLinearOperator

fr.cnes.sirius.patrius.math.linear.AbstractRealMatrix

fr.cnes.sirius.patrius.math.linear.ArrayRowSymmetricMatrix

All Implemented Interfaces:

AnyMatrix, RealMatrix, SymmetricMatrix, Serializable

Direct Known Subclasses:

ArrayRowSymmetricPositiveMatrix

public class ArrayRowSymmetricMatrix
extends AbstractRealMatrix
implements SymmetricMatrix

Symmetric matrix defined by its lower triangular part.

This implementation stores the elements of the lower triangular part of a symmetric matrix. These elements are stored in a 1D array, row after row. For example, for a 3 by 3 matrix we have:
(1) = s_1,1;
(2) = s_2,1; (3) = s_2,2;
(4) = s_3,1; (5) = s_3,2; (6) = s_3,3;

The elements actually stored depends on the type of symmetry specified at construction: LOWER or UPPER implies the symmetry is enforced by keeping only the lower or upper triangular part of the matrix, while MEAN enforces the symmetry by computing the mean of the lower and upper elements. The symmetry of the provided matrix is not checked by default, meaning that the symmetry is enforced regardless of the inputs. However, such a check can be triggered by setting the default absolute or relative symmetry threshold to a non-null value, or by specifying any of these thresholds at construction.

Important:
Because only half the elements of the matrix are actually stored, setting an off-diagonal element to a new value will automatically modify the symmetric element. As a result, the symmetry of the matrix will automatically be preserved. However, note that the method setSubMatrix is not supported and will systematically throw a MathUnsupportedOperationException.

Since:

4.5 (was previously called SymmetricMatrix, which now describes the interface)

Author:

Pierre Seimandi (GMV)

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ArrayRowSymmetricMatrix.SymmetryType Enumerate to fill in a symmetric matrix only by its lower/upper part.

Constructor Summary

Constructors

Modifier	Constructor and Description
	ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType, double[][] dataIn) Builds a new ArrayRowSymmetricMatrix from the provided data, using the default symmetry thresholds.
	ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType, double[][] dataIn, Double absoluteSymmetryThreshold, Double relativeSymmetryThreshold) Builds a new ArrayRowSymmetricMatrix from the provided data, using the specified symmetry thresholds.
	ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType, RealMatrix matrix) Builds a new ArrayRowSymmetricMatrix from the provided matrix, using the default symmetry thresholds.
	ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType, RealMatrix matrix, Double absoluteSymmetryThreshold, Double relativeSymmetryThreshold) Builds a new ArrayRowSymmetricMatrix from the provided matrix, using the specified symmetry thresholds.
protected	ArrayRowSymmetricMatrix(double[] dataIn, boolean copyArray) Builds a new ArrayRowSymmetricMatrix by specifying the lower triangular part of the matrix directly.
	ArrayRowSymmetricMatrix(int n) Builds a new ArrayRowSymmetricMatrix of dimension n (filled with zero).

Method Summary

Modifier and Type	Method and Description
ArrayRowSymmetricMatrix	add(DiagonalMatrix m) Returns the result of adding the diagonal matrix m to this matrix.
RealMatrix	add(RealMatrix m) Returns the result of adding the matrix m to this matrix.
ArrayRowSymmetricMatrix	add(SymmetricMatrix m) Returns the result of adding the symmetric matrix m to this matrix.
void	addToEntry(int row, int column, double increment) Adds (in place) a given value to the specified entry of this matrix.
protected static void	checkAbsoluteThreshold(Double threshold) Ensures the provided absolute threshold is either null or a positive number (zero included).
protected static void	checkDataArray(double[] data) Checks the validity of the provided data array.
protected static void	checkMatrix(RealMatrix matrix) Ensures the provided matrix is not null and is a square matrix.
protected static void	checkRelativeThreshold(Double threshold) Ensures the provided relative threshold is either null or a positive number (zero included).
RealMatrix	concatenateDiagonally(RealMatrix m, boolean rightConcatenation, boolean lowerConcatenation) Diagonally or anti-diagonally concatenates this matrix and another matrix m.
RealMatrix	concatenateHorizontally(RealMatrix m, boolean rightConcatenation) Horizontally concatenates this matrix and another matrix m, , placing it in the left or right part of the concatenated matrix.
RealMatrix	concatenateVertically(RealMatrix m, boolean lowerConcatenation) Vertically concatenates this matrix and another matrix m, placing it in the lower or upper part of the concatenated matrix.
ArrayRowSymmetricMatrix	copy() Returns a deep copy of this matrix.
static ArrayRowSymmetricMatrix	createIdentityMatrix(int dim) Creates an identity matrix of the specified dimension.
ArrayRowSymmetricMatrix	createMatrix(int rowDimension, int columnDimension) Creates a new matrix of the same type as this matrix.
boolean	equals(Object object) Returns true if the provided object is a RealMatrix instance with the same dimensions as this matrix, whose entries are strictly equal to the entries of this matrix (no absolute or relative tolerance is taken into account when comparing the entries).
int	getColumnDimension() Returns the dimension of the domain of this operator.
RealMatrix	getColumnMatrix(int column) Gets the entries of a given column as a column matrix.
protected double[]	getDataRef() Gets a reference to the internal data array storing the lower part of the symmetric matrix.
static Double	getDefaultAbsoluteSymmetryThreshold() Gets the default absolute threshold above which off-diagonal elements are considered different.
static Double	getDefaultRelativeSymmetryThreshold() Gets the default relative threshold above which off-diagonal elements are considered different.
double	getEntry(int row, int column) Gets the entry at the specified row and column.
ArrayRowSymmetricMatrix	getInverse() Gets the inverse (or pseudo-inverse) of this matrix using the default decomposition.
ArrayRowSymmetricMatrix	getInverse(Function<RealMatrix,Decomposition> decompositionBuilder) Gets the inverse (or pseudo-inverse) of this matrix using the given decomposition algorithm.
int	getRowDimension() Returns the dimension of the codomain of this operator.
RealMatrix	getRowMatrix(int row) Gets the entries of a given row as a row matrix.
ArrayRowSymmetricMatrix	getSubMatrix(int[] indices) Extracts the submatrix corresponding to the specified indices.
RealMatrix	getSubMatrix(int[] selectedRows, int[] selectedColumns) Gets a submatrix.
ArrayRowSymmetricMatrix	getSubMatrix(int startIndex, int endIndex) Extracts the submatrix corresponding to the specified indices.
RealMatrix	getSubMatrix(int startRow, int endRow, int startColumn, int endColumn) Gets a submatrix.
int	hashCode() Computes a hash code for the matrix.
boolean	isSquare() Is this a square matrix?
boolean	isSymmetric() Is this a symmetric matrix?
boolean	isSymmetric(double relativeTolerance) Is this a symmetric matrix?
boolean	isSymmetric(double relativeTolerance, double absoluteTolerance) Is this a symmetric matrix?
RealMatrix	multiply(DiagonalMatrix m, double d) Returns the result of postmultiplying this matrix by the diagonal matrix m, then by the scalar d.
RealMatrix	multiply(RealMatrix m, boolean toTranspose, double d) Returns the result of postmultiplying this matrix by the matrix m or its transpose mT, then by the scalar d.
void	multiplyEntry(int row, int column, double factor) Multiplies (in place) the specified entry of this matrix by a given value.
ArrayRowSymmetricMatrix	power(int p) Returns the the result of multiplying this matrix with itself p times.
ArrayRowSymmetricMatrix	quadraticMultiplication(RealMatrix m) Returns the result of the quadratic multiplication M×this×MT, where M is the provided matrix.
ArrayRowSymmetricMatrix	quadraticMultiplication(RealMatrix m, boolean isTranspose) Returns the result of the quadratic multiplication M×this×MT, where M or MT is the provided matrix.
ArrayRowSymmetricMatrix	scalarAdd(double d) Returns the result of adding a scalar d to the entries of this matrix.
ArrayRowSymmetricMatrix	scalarMultiply(double d) Returns the result of multiplying the entries of this matrix by the scalar d.
static void	setDefaultAbsoluteSymmetryThreshold(Double threshold) Sets the default absolute threshold above which off-diagonal elements are considered different.
static void	setDefaultRelativeSymmetryThreshold(Double threshold) Sets the default relative threshold above which off-diagonal elements are considered different.
void	setEntry(int row, int column, double value) Sets the entry at the specified row and column to a new value.
void	setSubMatrix(double[][] subMatrix, int row, int column) Replaces part of the matrix with a given submatrix, starting at the specified row and column.
ArrayRowSymmetricMatrix	subtract(DiagonalMatrix m) Returns the result of subtracting the diagonal matrix m from this matrix.
RealMatrix	subtract(RealMatrix m) Returns the result of subtracting the matrix m from this matrix.
ArrayRowSymmetricMatrix	subtract(SymmetricMatrix m) Returns the result of subtracting the symmetric matrix m from this matrix.
ArrayRowSymmetricMatrix	transpose() Returns the transpose of this matrix.
ArrayRowSymmetricMatrix	transpose(boolean forceCopy) Returns the transpose of this matrix.

Methods inherited from class fr.cnes.sirius.patrius.math.linear.AbstractRealMatrix

checkDestinationArray, checkSquare, concatenateDiagonally, concatenateDiagonally, concatenateHorizontally, concatenateVertically, copySubMatrix, copySubMatrix, copySubMatrix, copySubMatrix, equals, getColumn, getColumnVector, getData, getData, getDefaultDecomposition, getDiagonal, getFrobeniusNorm, getMax, getMin, getNorm, getRow, getRowVector, getTrace, isAntisymmetric, isDiagonal, isInvertible, isOrthogonal, multiply, multiply, operate, operate, preMultiply, preMultiply, preMultiply, setColumn, setColumnMatrix, setColumnVector, setDefaultDecomposition, setRow, setRowMatrix, setRowVector, toString, toString, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder

Methods inherited from class fr.cnes.sirius.patrius.math.linear.RealLinearOperator

isTransposable, operateTranspose

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface fr.cnes.sirius.patrius.math.linear.SymmetricMatrix

getDiagonal

Methods inherited from interface fr.cnes.sirius.patrius.math.linear.RealMatrix

concatenateDiagonally, concatenateDiagonally, concatenateHorizontally, concatenateVertically, copySubMatrix, copySubMatrix, copySubMatrix, copySubMatrix, equals, getColumn, getColumnVector, getData, getData, getDefaultDecomposition, getFrobeniusNorm, getMax, getMin, getNorm, getRow, getRowVector, getTrace, isAntisymmetric, isDiagonal, isInvertible, isOrthogonal, multiply, multiply, operate, operate, preMultiply, preMultiply, preMultiply, setColumn, setColumnMatrix, setColumnVector, setDefaultDecomposition, setRow, setRowMatrix, setRowVector, toString, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder

Constructor Detail

ArrayRowSymmetricMatrix

public ArrayRowSymmetricMatrix(int n)

Builds a new ArrayRowSymmetricMatrix of dimension n (filled with zero).

Parameters:

n - the dimension of the matrix

ArrayRowSymmetricMatrix

public ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType,
                               double[][] dataIn)

Builds a new ArrayRowSymmetricMatrix from the provided data, using the default symmetry thresholds.

Parameters:

symmetryType - the type of symmetry enforced at construction

dataIn - the data of the matrix (must be a NxN array)

Throws:

NonSquareMatrixException - if the provided matrix is not square (unchecked)

NonSymmetricMatrixException - if the provided matrix is not symmetric (unchecked)

See Also:

getDefaultRelativeSymmetryThreshold()

ArrayRowSymmetricMatrix

public ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType,
                               double[][] dataIn,
                               Double absoluteSymmetryThreshold,
                               Double relativeSymmetryThreshold)

Builds a new ArrayRowSymmetricMatrix from the provided data, using the specified symmetry thresholds.

Parameters:

symmetryType - the type of symmetry enforced at construction

dataIn - the data of the matrix (must be a NxN array)

absoluteSymmetryThreshold - the absolute threshold above which off-diagonal elements are considered different
(if null, no check is made on the absolute difference between symmetric elements)

relativeSymmetryThreshold - the relative threshold above which off-diagonal elements are considered different
(if null, no check is made on the relative difference between symmetric elements)

Throws:

IllegalArgumentException - if one of the provided thresholds is NaN or is strictly negative (unchecked)

NonSquareMatrixException - if the provided matrix is not square (unchecked)

NonSymmetricMatrixException - if the provided matrix is not symmetric (unchecked)

ArrayRowSymmetricMatrix

public ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType,
                               RealMatrix matrix)

Builds a new ArrayRowSymmetricMatrix from the provided matrix, using the default symmetry thresholds.

Parameters:

symmetryType - the type of symmetry enforced at construction

matrix - the matrix (must NxN)

Throws:

NonSquareMatrixException - if the provided matrix is not square (unchecked)

NonSymmetricMatrixException - if the provided matrix is not symmetric (unchecked)

See Also:

getDefaultRelativeSymmetryThreshold()

ArrayRowSymmetricMatrix

public ArrayRowSymmetricMatrix(ArrayRowSymmetricMatrix.SymmetryType symmetryType,
                               RealMatrix matrix,
                               Double absoluteSymmetryThreshold,
                               Double relativeSymmetryThreshold)

Builds a new ArrayRowSymmetricMatrix from the provided matrix, using the specified symmetry thresholds.

Parameters:

symmetryType - the type of symmetry enforced at construction

matrix - the matrix (must NxN)

absoluteSymmetryThreshold - the absolute threshold above which off-diagonal elements are considered different
(if null, no check is made on the absolute difference between symmetric elements)

relativeSymmetryThreshold - the relative threshold above which off-diagonal elements are considered different
(if null, no check is made on the absolute difference between symmetric elements)

Throws:

IllegalArgumentException - if one of the provided thresholds is NaN or is strictly negative (unchecked)

NonSquareMatrixException - if the provided matrix is not square (unchecked)

NonSymmetricMatrixException - if the provided matrix is not symmetric (unchecked)

ArrayRowSymmetricMatrix

protected ArrayRowSymmetricMatrix(double[] dataIn,
                                  boolean copyArray)

Builds a new ArrayRowSymmetricMatrix by specifying the lower triangular part of the matrix directly.

Parameters:

dataIn - the array storing the lower triangular part of the matrix

copyArray - if true, copy the provided array instead

Method Detail

checkMatrix

protected static void checkMatrix(RealMatrix matrix)

Ensures the provided matrix is not null and is a square matrix.

Parameters:

matrix - the matrix to be checked

Throws:

NullArgumentException - if the provided matrix is null

NonSquareMatrixException - if the provided matrix is not square

checkDataArray

protected static void checkDataArray(double[] data)

Checks the validity of the provided data array.

To be valid, the array must not be null or empty.

Parameters:

data - the data array to be checked

Throws:

NullArgumentException - if the data array is null

NoDataException - if the data array is empty

checkAbsoluteThreshold

protected static void checkAbsoluteThreshold(Double threshold)

Ensures the provided absolute threshold is either null or a positive number (zero included).

Parameters:

threshold - the absolute threshold to check

Throws:

IllegalArgumentException - if the provided threshold is NaN or is strictly negative

checkRelativeThreshold

protected static void checkRelativeThreshold(Double threshold)

Ensures the provided relative threshold is either null or a positive number (zero included).

Parameters:

threshold - the relative threshold to check

Throws:

IllegalArgumentException - if the provided threshold is NaN or is strictly negative

getDataRef

protected double[] getDataRef()

Gets a reference to the internal data array storing the lower part of the symmetric matrix.

This method is only provided for optimization purposes.
Any modification made on the returned array will change the values of this matrix.

Returns:

a direct reference to the internal data array storing the lower part of the symmetric matrix

getRowDimension

public int getRowDimension()

Returns the dimension of the codomain of this operator.

Specified by:

getRowDimension in interface AnyMatrix

Specified by:

getRowDimension in class AbstractRealMatrix

Returns:

the number of rows of the underlying matrix

getColumnDimension

public int getColumnDimension()

Returns the dimension of the domain of this operator.

Specified by:

getColumnDimension in interface AnyMatrix

Specified by:

getColumnDimension in class AbstractRealMatrix

Returns:

the number of columns of the underlying matrix

getEntry

public double getEntry(int row,
                       int column)

Gets the entry at the specified row and column.

Row and column indices start at 0.

Specified by:

getEntry in interface RealMatrix

Specified by:

getEntry in class AbstractRealMatrix

Parameters:

row - the row index of entry to be fetched

column - the column index of entry to be fetched

Returns:

the matrix entry at the specified row and column

setEntry

public void setEntry(int row,
                     int column,
                     double value)

Sets the entry at the specified row and column to a new value.

Row and column indices start at 0.

This method automatically modify the symmetric element to ensure the symmetry of the matrix is preserved.

Specified by:

setEntry in interface RealMatrix

Specified by:

setEntry in class AbstractRealMatrix

Parameters:

row - the row index of entry to be set

column - the column index of entry to be set

value - the new value of the entry

addToEntry

public void addToEntry(int row,
                       int column,
                       double increment)

Adds (in place) a given value to the specified entry of this matrix.

Row and column indices start at 0.

Specified by:

addToEntry in interface RealMatrix

Overrides:

addToEntry in class AbstractRealMatrix

Parameters:

row - the row index of the entry to be modified

column - the column index of the entry to be modified

increment - the value to add to the matrix entry

multiplyEntry

public void multiplyEntry(int row,
                          int column,
                          double factor)

Multiplies (in place) the specified entry of this matrix by a given value.

Row and column indices start at 0.

Specified by:

multiplyEntry in interface RealMatrix

Overrides:

multiplyEntry in class AbstractRealMatrix

Parameters:

row - the row index of the entry to be modified

column - the column index of the entry to be modified

factor - the multiplication factor for the matrix entry

getRowMatrix

public RealMatrix getRowMatrix(int row)

Gets the entries of a given row as a row matrix.

Row indices start at 0.

Specified by:

getRowMatrix in interface RealMatrix

Overrides:

getRowMatrix in class AbstractRealMatrix

Parameters:

row - the index of the row to be fetched

Returns:

the extracted row matrix

getColumnMatrix

public RealMatrix getColumnMatrix(int column)

Gets the entries of a given column as a column matrix.

Column indices start at 0.

Specified by:

getColumnMatrix in interface RealMatrix

Overrides:

getColumnMatrix in class AbstractRealMatrix

Parameters:

column - the index of the column to be fetched

Returns:

the extracted column matrix

getSubMatrix

public RealMatrix getSubMatrix(int startRow,
                               int endRow,
                               int startColumn,
                               int endColumn)

Gets a submatrix.

Rows and columns are indicated counting from 0 to n-1.

The returned matrix is an ArrayRowSymmetricMatrix if the selected indices are the same for the rows and the columns, and an Array2DRowRealMatrix or a BlockRealMatrix otherwise.

Specified by:

getSubMatrix in interface RealMatrix

Overrides:

getSubMatrix in class AbstractRealMatrix

Parameters:

startRow - the initial row index

endRow - the final row index (inclusive)

startColumn - the initial column index

endColumn - the final column index (inclusive)

Returns:

the submatrix containing the data of the specified rows and columns

getSubMatrix

public RealMatrix getSubMatrix(int[] selectedRows,
                               int[] selectedColumns)

Gets a submatrix.

Rows and columns are indicated counting from 0 to n-1.

The returned matrix is an ArrayRowSymmetricMatrix if the selected indices are the same for the rows and the columns (same indices, same order), and an Array2DRowRealMatrix or a BlockRealMatrix otherwise.

Specified by:

getSubMatrix in interface RealMatrix

Overrides:

getSubMatrix in class AbstractRealMatrix

Parameters:

selectedRows - the selected row indices

selectedColumns - the selected column indices

Returns:

the submatrix containing the data in the specified rows and columns

getSubMatrix

public ArrayRowSymmetricMatrix getSubMatrix(int startIndex,
                                            int endIndex)

Extracts the submatrix corresponding to the specified indices.

This method uses the same start/end indices to select the rows and columns to be extracted. These indices must be valid indices with respect to the dimensions of the matrix (valid indices range from 0 to n-1, with n the row/column dimension of the matrix). Calling this method is equivalent to calling RealMatrix.getSubMatrix(int, int, int, int) using the same start/end indices for the rows and columns. The extracted submatrix is guaranteed to be symmetric. It will also remain positive semi-definite if the initial matrix originally is.

Usage examples:

 // Initial matrix
 matrix = [a00, a10, a20]
          [a10, a11, a21]
          [a20, a21, a22]
 
 // Submatrix extraction
 matrix.getSubMatrix(1, 2) => [a11, a21]
                              [a21, a22]
 

Specified by:

getSubMatrix in interface SymmetricMatrix

Parameters:

startIndex - the initial row/column index

endIndex - the final row/column index (inclusive)

Returns:

the extracted submatrix

getSubMatrix

public ArrayRowSymmetricMatrix getSubMatrix(int[] indices)

Extracts the submatrix corresponding to the specified indices.

This method uses a single index array to select the rows and columns to be extracted. All indices must be valid indices with respect to the dimensions of the matrix (valid indices range from 0 to n-1, with n the row/column dimension of the matrix). The provided index array is allowed to contain duplicates. Calling this method is equivalent to calling RealMatrix.getSubMatrix(int[], int[]) using the provided index array for the selected rows and columns. This method can be used to extract any submatrix and perform a symmetric reordering of its rows/columns. The extracted submatrix is guaranteed to be symmetric. It will also remain positive semi-definite if the initial matrix originally is.

Usage examples:

 // Initial matrix
 matrix = [a00, a10, a20]
          [a10, a11, a21]
          [a20, a21, a22]
 
 // Submatrix extraction
 matrix.getSubMatrix([1, 2]) => [a11, a21]
                                [a21, a22]
 
 // Rows/Columns permutation
 matrix.getSubMatrix([1, 2, 0]) => [a11, a21, a10]
                                   [a21, a22, a20]
                                   [a10, a20, a00]
 
 // Submatrix extraction (with duplicated indices)
 matrix.getSubMatrix([1, 2, 0, 1, 0]) 
      => [a11, a21, a10, a11, a10]
         [a21, a22, a20, a21, a20]
         [a10, a20, a00, a10, a00]
         [a11, a21, a10, a11, a10]
         [a10, a20, a00, a10, a00]
 

Specified by:

getSubMatrix in interface SymmetricMatrix

Parameters:

indices - the selected indices

Returns:

the extracted submatrix

setSubMatrix

public void setSubMatrix(double[][] subMatrix,
                         int row,
                         int column)

Replaces part of the matrix with a given submatrix, starting at the specified row and column. Important:
This method systematically throws a MathUnsupportedOperationException since this operation is not safe when dealing with symmetric matrices (the properties of the matrix are not guaranteed to be preserved and this method cannot determine which value should take precedence when symmetric elements are both provided).

Specified by:

setSubMatrix in interface RealMatrix

Overrides:

setSubMatrix in class AbstractRealMatrix

Parameters:

subMatrix - the array containing the submatrix replacement data

row - the row coordinate of the top, left element to be replaced

column - the column coordinate of the top, left element to be replaced

Throws:

MathUnsupportedOperationException - systematically, since this operation is not supported

Since:

4.5

scalarAdd

public ArrayRowSymmetricMatrix scalarAdd(double d)

Returns the result of adding a scalar d to the entries of this matrix.

Specified by:

scalarAdd in interface RealMatrix

Specified by:

scalarAdd in interface SymmetricMatrix

Overrides:

scalarAdd in class AbstractRealMatrix

Parameters:

d - the scalar value to be added to the entries of this matrix

Returns:

the matrix resulting from the addition this+d

scalarMultiply

public ArrayRowSymmetricMatrix scalarMultiply(double d)

Returns the result of multiplying the entries of this matrix by the scalar d.

Specified by:

scalarMultiply in interface RealMatrix

Specified by:

scalarMultiply in interface SymmetricMatrix

Overrides:

scalarMultiply in class AbstractRealMatrix

Parameters:

d - the scalar value by which to multiply the entries of this matrix by

Returns:

the matrix resulting from the product this×d

add

public RealMatrix add(RealMatrix m)

Returns the result of adding the matrix m to this matrix.

The returned matrix is, in order of priority:

• An ArrayRowSymmetricMatrix if it is a SymmetricMatrix;
• An Array2DRowRealMatrix or a BlockRealMatrix if it is any other type of RealMatrix.

Specified by:

add in interface RealMatrix

Overrides:

add in class AbstractRealMatrix

Parameters:

m - the matrix to be added

Returns:

the matrix resulting from the addition this+m

add

public ArrayRowSymmetricMatrix add(SymmetricMatrix m)

Returns the result of adding the symmetric matrix m to this matrix.

Specified by:

add in interface SymmetricMatrix

Parameters:

m - the matrix to be added

Returns:

the matrix resulting from the addition this+m

add

public ArrayRowSymmetricMatrix add(DiagonalMatrix m)

Returns the result of adding the diagonal matrix m to this matrix.

Parameters:

m - the matrix to be added

Returns:

the matrix resulting from the addition this + m

Throws:

MatrixDimensionMismatchException - if the matrix m is not the same size as this matrix

subtract

public RealMatrix subtract(RealMatrix m)

Returns the result of subtracting the matrix m from this matrix.

The returned matrix is, in order of priority:

• An ArrayRowSymmetricMatrix if it is a SymmetricMatrix;
• An Array2DRowRealMatrix or a BlockRealMatrix if it is any other type of RealMatrix.

Specified by:

subtract in interface RealMatrix

Overrides:

subtract in class AbstractRealMatrix

Parameters:

m - the matrix to be subtracted

Returns:

the matrix resulting from the subtraction this-m

subtract

public ArrayRowSymmetricMatrix subtract(SymmetricMatrix m)

Returns the result of subtracting the symmetric matrix m from this matrix.

Specified by:

subtract in interface SymmetricMatrix

Parameters:

m - the matrix to be subtracted

Returns:

the matrix resulting from the subtraction this-m

subtract

public ArrayRowSymmetricMatrix subtract(DiagonalMatrix m)

Returns the result of subtracting the diagonal matrix m from this matrix.

Parameters:

m - the matrix to be subtracted

Returns:

the matrix resulting from the subtraction this - m

Throws:

MatrixDimensionMismatchException - if the matrix m is not the same size as this matrix

multiply

public RealMatrix multiply(RealMatrix m,
                           boolean toTranspose,
                           double d)

Returns the result of postmultiplying this matrix by the matrix m or its transpose m^T, then by the scalar d.

Specified by:

multiply in interface RealMatrix

Overrides:

multiply in class AbstractRealMatrix

Parameters:

m - the matrix by which to multiply this matrix by

toTranspose - whether to compute the product this×m×d ( toTranspose=false), or the product this×m ^T×d (toTranspose=true)

d - the scalar by which to multiply the resulting matrix by

Returns:

the matrix resulting from the product this×m×d or this×m^T×d

multiply

public RealMatrix multiply(DiagonalMatrix m,
                           double d)

Returns the result of postmultiplying this matrix by the diagonal matrix m, then by the scalar d.

Overrides:

multiply in class AbstractRealMatrix

Parameters:

m - the diagonal matrix by which to multiply this matrix by

d - the scalar by which to multiply the resulting matrix by

Returns:

the matrix resulting from the product this×m×d or this×m^T×d

quadraticMultiplication

public ArrayRowSymmetricMatrix quadraticMultiplication(RealMatrix m)

Returns the result of the quadratic multiplication M×this×M^T, where M is the provided matrix.

Specified by:

quadraticMultiplication in interface SymmetricMatrix

Parameters:

m - the matrix M

Returns:

the matrix resulting from the quadratic multiplication M×this ×M^T

quadraticMultiplication

public ArrayRowSymmetricMatrix quadraticMultiplication(RealMatrix m,
                                                       boolean isTranspose)

Returns the result of the quadratic multiplication M×this×M^T, where M or M^T is the provided matrix.

Specified by:

quadraticMultiplication in interface SymmetricMatrix

Parameters:

m - the matrix M or the matrix M^T

isTranspose - if true, assumes the provided matrix is M^T, otherwise assumes it is M

Returns:

the matrix resulting from the quadratic multiplication M×this ×M^T

power

public ArrayRowSymmetricMatrix power(int p)

Returns the the result of multiplying this matrix with itself p times.

The exponent p must be positive or equal to zero.
This operation is only supported for square matrices.
Depending on the underlying storage, numerical instabilities might occur for high powers.

Specified by:

power in interface RealMatrix

Specified by:

power in interface SymmetricMatrix

Overrides:

power in class AbstractRealMatrix

Parameters:

p - the exponent p to which this matrix is to be raised

Returns:

the matrix resulting from raising this matrix to the power of p

createMatrix

public ArrayRowSymmetricMatrix createMatrix(int rowDimension,
                                            int columnDimension)

Creates a new matrix of the same type as this matrix.

The returned matrix is filled with zeros. Its size is determined by the specified row and column dimensions, which must both be strictly positive. Additional constraints on the dimensions may apply depending on the implementation (for example, symmetric matrices must be square, which implies that the row and column dimensions must be equal).

Specified by:

createMatrix in interface RealMatrix

Specified by:

createMatrix in interface SymmetricMatrix

Specified by:

createMatrix in class AbstractRealMatrix

Parameters:

rowDimension - the number of rows in the new matrix

columnDimension - the number of columns in the new matrix

Returns:

a new matrix of the same type as this matrix

createIdentityMatrix

public static ArrayRowSymmetricMatrix createIdentityMatrix(int dim)

Creates an identity matrix of the specified dimension.

Parameters:

dim - the dimension of the identity matrix

Returns:

the identity matrix built

copy

public ArrayRowSymmetricMatrix copy()

Returns a deep copy of this matrix.

Specified by:

copy in interface RealMatrix

Specified by:

copy in interface SymmetricMatrix

Specified by:

copy in class AbstractRealMatrix

Returns:

a deep copy of this matrix

transpose

public ArrayRowSymmetricMatrix transpose()

Returns the transpose of this matrix.

Specified by:

transpose in interface RealMatrix

Specified by:

transpose in interface SymmetricMatrix

Overrides:

transpose in class AbstractRealMatrix

Returns:

the transpose of this matrix

transpose

public ArrayRowSymmetricMatrix transpose(boolean forceCopy)

Returns the transpose of this matrix.

If forceCopy is true, the returned matrix is guaranteed to be a new instance, which can be modified without any risk of impacting the current instance. Otherwise, this method may simply return the current instance when the matrix is its own transpose (symmetric matrix).

Specified by:

transpose in interface RealMatrix

Specified by:

transpose in interface SymmetricMatrix

Overrides:

transpose in class AbstractRealMatrix

Parameters:

forceCopy - if true, the transpose of the matrix is systematically stored in a new matrix; otherwise the method may return the current instance when the matrix is its own transpose

Returns:

the transpose of this matrix

concatenateHorizontally

public RealMatrix concatenateHorizontally(RealMatrix m,
                                          boolean rightConcatenation)

Horizontally concatenates this matrix and another matrix m, , placing it in the left or right part of the concatenated matrix.

The way the two matrices are concatenated depends on the provided argument:
The matrix m is placed in the right part of the concatenated matrix if rightConcatenation is set to true, and in its left part if it is set to false.

Usage examples:

 this.concatenateHorizontally(m, true)  => [this, m] 
 
 this.concatenateHorizontally(m, false) => [m, this]
 

Specified by:

concatenateHorizontally in interface RealMatrix

Overrides:

concatenateHorizontally in class AbstractRealMatrix

Parameters:

m - the matrix to be concatenated with this matrix

rightConcatenation - whether the matrix m is to be placed in the right (true) or left ( false) part of the concatenated matrix

Returns:

the concatenated matrix

concatenateVertically

public RealMatrix concatenateVertically(RealMatrix m,
                                        boolean lowerConcatenation)

Vertically concatenates this matrix and another matrix m, placing it in the lower or upper part of the concatenated matrix.

The way the two matrices are concatenated depends on the provided argument:
The matrix m is placed in the lower part of the concatenated matrix if lowerConcatenation is set to true, and in its upper part if it is set to false.

Usage examples:

 this.concatenateVertically(m, true)  => [this] 
                                         [   m]
                                              
 this.concatenateVertically(m, false) => [   m]
                                         [this]
 

Specified by:

concatenateVertically in interface RealMatrix

Overrides:

concatenateVertically in class AbstractRealMatrix

Parameters:

m - the matrix to be concatenated with this matrix

lowerConcatenation - whether the matrix m is to be placed in the lower (true) or upper ( false) part of the concatenated matrix

Returns:

the concatenated matrix

concatenateDiagonally

public RealMatrix concatenateDiagonally(RealMatrix m,
                                        boolean rightConcatenation,
                                        boolean lowerConcatenation)

Diagonally or anti-diagonally concatenates this matrix and another matrix m.

The way the two matrices are concatenated depends on the provided arguments:
The matrix m is placed in the right part of the concatenated matrix if rightConcatenation is set to true, and in its left part if it is set to false. Similarly, the matrix m is placed in the lower part of the concatenated matrix if lowerConcatenation is set to true, and in its upper part if it is set to false. This matrix is then placed in the opposite part of the concatenated matrix (as an example, if the provided matrix is placed in the upper left part, this matrix will be placed in the lower right part, the remaining parts being filled with zeros).

Usage examples:

 // Diagonal concatenation
 this.concatenateDiagonally(m, true, true)   => [this, 0] 
                                                [   0, m]
                                              
 this.concatenateDiagonally(m, false, false) => [m,    0]
                                                [0, this]
                          
 // Anti-diagonal concatenation
 this.concatenateDiagonally(m, false, true)  => [0, this]
                                                [m,    0]
                                               
 this.concatenateDiagonally(m, true, false)  => [   0, m]
                                                [this, 0]
 

Specified by:

concatenateDiagonally in interface RealMatrix

Overrides:

concatenateDiagonally in class AbstractRealMatrix

Parameters:

m - the matrix to be concatenated with this matrix

rightConcatenation - whether the matrix m is to be placed in the right (true) or left ( false) part of the concatenated matrix

lowerConcatenation - whether the matrix m is to be placed in the lower (true) or upper ( false) part of the concatenated matrix

Returns:

the concatenated matrix

getInverse

public ArrayRowSymmetricMatrix getInverse()

Gets the inverse (or pseudo-inverse) of this matrix using the default decomposition.

The default decomposition builder can be changed using the setDefaultDecomposition method.

Specified by:

getInverse in interface RealMatrix

Specified by:

getInverse in interface SymmetricMatrix

Overrides:

getInverse in class AbstractRealMatrix

Returns:

the inverse matrix

See Also:

RealMatrix.getDefaultDecomposition(), RealMatrix.setDefaultDecomposition(Function)

getInverse

public ArrayRowSymmetricMatrix getInverse(Function<RealMatrix,Decomposition> decompositionBuilder)

Gets the inverse (or pseudo-inverse) of this matrix using the given decomposition algorithm.

The decomposition builder is a function capable of generating new instances of the decomposition algorithm to be used for the computation of the inverse matrix (like the QRDecomposition or the EigenDecomposition, for instance).

Specified by:

getInverse in interface RealMatrix

Specified by:

getInverse in interface SymmetricMatrix

Overrides:

getInverse in class AbstractRealMatrix

Parameters:

decompositionBuilder - the decomposition builder to use

Returns:

the inverse matrix

isSquare

public boolean isSquare()

Is this a square matrix?

Specified by:

isSquare in interface AnyMatrix

Overrides:

isSquare in class AbstractRealMatrix

Returns:

true if the matrix is square (rowDimension = columnDimension)

isSymmetric

public boolean isSymmetric()

Is this a symmetric matrix?

This method indicates if the matrix is symmetric.
To do so, the method checks that symmetric off-diagonal elements are numerically equal. Two elements are considered to have different values if their absolute and relative differences are both above the default tolerances.

This method systematically returns false for non-square matrices.

The absolute and relative tolerances both default to Precision.DOUBLE_COMPARISON_EPSILON.

Specified by:

isSymmetric in interface RealMatrix

Overrides:

isSymmetric in class AbstractRealMatrix

Returns:

true if this is a symmetric matrix, false otherwise

isSymmetric

public boolean isSymmetric(double relativeTolerance)

Is this a symmetric matrix?

This method indicates if the matrix is symmetric.
To do so, the method checks that symmetric off-diagonal elements are numerically equal. Two elements are considered to have different values if their relative difference is above the specified tolerance.

This method systematically returns false for non-square matrices.

Specified by:

isSymmetric in interface RealMatrix

Overrides:

isSymmetric in class AbstractRealMatrix

Parameters:

relativeTolerance - the relative tolerance to take into account when comparing off-diagonal elements

Returns:

true if this is a symmetric matrix, false otherwise

isSymmetric

public boolean isSymmetric(double relativeTolerance,
                           double absoluteTolerance)

Is this a symmetric matrix?

This method indicates if the matrix is symmetric.
To do so, the method checks that symmetric off-diagonal elements are numerically equal. Two elements are considered to have different values if their absolute and relative differences are both above the specified tolerances.

This method systematically returns false for non-square matrices.

Specified by:

isSymmetric in interface RealMatrix

Overrides:

isSymmetric in class AbstractRealMatrix

Parameters:

relativeTolerance - the relative tolerance to take into account when comparing off-diagonal elements

absoluteTolerance - the absolute tolerance to take into account when comparing off-diagonal elements

Returns:

true if this is a symmetric matrix, false otherwise

equals

public boolean equals(Object object)

Returns true if the provided object is a RealMatrix instance with the same dimensions as this matrix, whose entries are strictly equal to the entries of this matrix (no absolute or relative tolerance is taken into account when comparing the entries).

Overrides:

equals in class AbstractRealMatrix

Parameters:

object - the object to be tested for equality

Returns:

true if the provided object is equal to this matrix

hashCode

public int hashCode()

Computes a hash code for the matrix.

Overrides:

hashCode in class AbstractRealMatrix

Returns:

hash code for matrix

getDefaultAbsoluteSymmetryThreshold

public static Double getDefaultAbsoluteSymmetryThreshold()

Gets the default absolute threshold above which off-diagonal elements are considered different.

A null value means the symmetry is enforced without any check on the absolute difference between symmetric elements.

Returns:

the default absolute symmetry threshold (≥0 or null)

setDefaultAbsoluteSymmetryThreshold

public static void setDefaultAbsoluteSymmetryThreshold(Double threshold)

Sets the default absolute threshold above which off-diagonal elements are considered different.

A null value means the symmetry is enforced without any check on the absolute difference between symmetric elements.

Parameters:

threshold - the new default absolute symmetry threshold (≥0 or null)

Throws:

IllegalArgumentException - if the provided threshold is NaN or is strictly negative

getDefaultRelativeSymmetryThreshold

public static Double getDefaultRelativeSymmetryThreshold()

Gets the default relative threshold above which off-diagonal elements are considered different.

A null value means the symmetry is enforced without any check on the relative difference between symmetric elements.

Returns:

the default relative symmetry threshold (≥0 or null)

setDefaultRelativeSymmetryThreshold

public static void setDefaultRelativeSymmetryThreshold(Double threshold)

Sets the default relative threshold above which off-diagonal elements are considered different.

A null value means the symmetry is enforced without any check on the relative difference between symmetric elements.

Parameters:

threshold - the new default relative symmetry threshold (≥0 or null)

Throws:

IllegalArgumentException - if the provided threshold is NaN or is strictly negative