org.ojalgo.matrix
Interface BasicMatrix

All Superinterfaces:

Serializable

All Known Implementing Classes:

BigMatrix, ComplexMatrix, JamaMatrix, PrimitiveMatrix

public interface BasicMatrix
extends Serializable

This interface declares a set of high level methods for linear algebra. Only the most basic set of matrix functionality is defined here. Various matrix decompositions may be used to do some of the more advanced tasks.

A vector is a matrix with column (or perhaps row) dimension 1.

Author:

apete

See Also:

LU, Cholesky, QR, Eigenvalue, SingularValue, MatrixStore

Method Summary

BasicMatrix	add(BasicMatrix aMtrx) Adds the elements of aMtrx to the elements of this matrix.
BasicMatrix	add(Number aNmbr) Adds aNmbr to the elements of this.
Scalar<? extends Number>	calculateDeterminant() Deprecated. Since Version 24. Use getDeterminant() instead
Scalar<? extends Number>	calculateFrobeniusNorm() Deprecated. Since Version 24. Use getFrobeniusNorm() instead
int	calculateRank() Deprecated. Since Version 24. Use getRank() instead
Scalar<? extends Number>	calculateTrace() Deprecated. Since Version 24. Use getTrace() instead
Scalar<? extends Number>	calculateVectorNorm(int aDegree) Deprecated. Since Version 24. Use getVectorNorm(int) instead
Scalar<? extends Number>	calculateVectorProduct(BasicMatrix aVctr) Deprecated. Since Version 24. Use getVectorProduct(BasicMatrix) instead
BasicMatrix	conjugate() For real matrices conjugate() and transpose() are identical.
BasicMatrix	divide(Number aNmbr) Divides the elements of this with aNmbr.
BasicMatrix	divideElements(BasicMatrix aMtrx) Divides the elements of this with the elements of aMtrx.
double	doubleValue(int aRow, int aCol) Extracts one element of this matrix as a double.
BasicMatrix	enforce(NumberContext aCntxt)
boolean	equals(BasicMatrix aMtrx, NumberContext aCntxt)
int	getColDim()
BasicMatrix	getColumns(int[] someCols)
Scalar<?>	getDeterminant()
Scalar<?>	getFrobeniusNorm() The Frobenius norm is the square root of the sum of the squares of each element, or the square root of the sum of the square of the singular values.
Scalar<?>	getInfinityNorm() The largest, absolute, element value.
Scalar<? extends Number>	getLargestElement() Deprecated. Since Version 24. Use getInfinityNorm() instead
int	getRank() The rank of a matrix is the maximum number of linearly independent rows or columns it contains.
int	getRowDim()
BasicMatrix	getRows(int[] someRows)
Scalar<?>	getTrace() The sum of the diagonal elements.
Scalar<?>	getVectorNorm(int aDegree) Treats [this] as if it is one dimensional (a vector) and calculates the vector norm.
Scalar<?>	getVectorProduct(BasicMatrix aVctr) Treats [this] and [aVctr] as if they are one dimensional (vectors) and calculates the vector (dot) product.
Scalar<?>	getZeroNorm()
BasicMatrix	invert() About inverting matrices:
boolean	isEmpty() Matrices are either square, tall, fat or empty.
boolean	isFat() Matrices are either square, tall, fat or empty.
boolean	isSquare() Matrices are either square, tall, fat or empty.
boolean	isTall() Matrices are either square, tall, fat or empty.
BasicMatrix	mergeColumns(BasicMatrix aMtrx) [aMtrx] is appended to the bottom of [this].
BasicMatrix	mergeRows(BasicMatrix aMtrx) [aMtrx] is appended to the right side of [this].
BasicMatrix	multiply(Number aNmbr) Multiplies the elements of this matrix with aNmbr.
BasicMatrix	multiplyElements(BasicMatrix aMtrx) Multiplies the elements of this matrix with the elements of aMtrx.
BasicMatrix	multiplyLeft(BasicMatrix aMtrx) Matrix multiplication: [aMtrx][this] The column dimension of the left matrix must equal the row dimension of the right matrix.
BasicMatrix	multiplyRight(BasicMatrix aMtrx) Matrix multiplication: [this][aMtrx] The column dimension of the left matrix must equal the row dimension of the right matrix.
BasicMatrix	negate()
BasicMatrix	set(int aRow, int aCol, Number aNmbr)
int	size()
BasicMatrix	solve(BasicMatrix aRHS) This method solves a system of linear equations: [this][X]=[aRHS].
BasicMatrix	subtract(BasicMatrix aMtrx) Subtracts the elements of aMtrx from the elements of this matrix.
BasicMatrix	subtract(Number aNmbr) Subtracts aNmbr from the elements of this matrix.
BigDecimal	toBigDecimal(int aRow, int aCol) Extracts one element of this matrix as a BigDecimal.
PhysicalStore<BigDecimal>	toBigStore()
ComplexNumber	toComplexNumber(int aRow, int aCol) Extracts one element of this matrix as a ComplexNumber.
PhysicalStore<ComplexNumber>	toComplexStore()
List<BasicMatrix>	toListOfColumns()
List<BigDecimal>	toListOfElements()
List<BasicMatrix>	toListOfRows()
PhysicalStore<Double>	toPrimitiveStore()
Scalar<?>	toScalar(int aRow, int aCol) Extracts one element of this matrix as a Scalar.
String	toString(int aRow, int aCol)
BasicMatrix	transpose() Transposes this matrix.

Method Detail

add

BasicMatrix add(BasicMatrix aMtrx)

Adds the elements of aMtrx to the elements of this matrix. The matrices must have equal dimensions.

Parameters:

aMtrx - What to add.

Returns:

A new matrix whos elements are the sum of this' and aMtrx'.

add

BasicMatrix add(Number aNmbr)

Adds aNmbr to the elements of this.

Parameters:

aNmbr - What to add

Returns:

A new matrix whos elements are the sum of this' elements and aNmbr.

calculateDeterminant

@Deprecated
Scalar<? extends Number> calculateDeterminant()

Deprecated. Since Version 24. Use getDeterminant() instead

Returns:

The matrix' determinant.

calculateFrobeniusNorm

@Deprecated
Scalar<? extends Number> calculateFrobeniusNorm()

Deprecated. Since Version 24. Use getFrobeniusNorm() instead

The Frobenius norm is the square root of the sum of the squares of each element, or the square root of the sum of the square of the singular values.

Returns:

The matrix' Frobenius norm

calculateRank

@Deprecated
int calculateRank()

Deprecated. Since Version 24. Use getRank() instead

The rank of a matrix is the maximum number of linearly independent rows or columns it contains. It is also equal to the number of nonzero singular values of the matrix.

Returns:

The matrix' rank.

calculateTrace

@Deprecated
Scalar<? extends Number> calculateTrace()

Deprecated. Since Version 24. Use getTrace() instead

The sum of the diagonal elements.

Returns:

The matrix' trace.

calculateVectorNorm

@Deprecated
Scalar<? extends Number> calculateVectorNorm(int aDegree)

Deprecated. Since Version 24. Use getVectorNorm(int) instead

Treats [this] as if it is one dimensional (a vector) and calculates the vector norm.

See Also:

toListOfRows(), toListOfColumns(), toListOfElements()

calculateVectorProduct

@Deprecated
Scalar<? extends Number> calculateVectorProduct(BasicMatrix aVctr)

Deprecated. Since Version 24. Use getVectorProduct(BasicMatrix) instead

Treats [this] and [aVctr] as if they are one dimensional (vectors) and calculates the vector (dot) product. The two vectors must have the same number of elements.

conjugate

BasicMatrix conjugate()

For real matrices conjugate() and transpose() are identical. For complex matrices they're not.

Returns:

The conjugate transpose of this.

See Also:

transpose()

divide

BasicMatrix divide(Number aNmbr)

Divides the elements of this with aNmbr.

Parameters:

aNmbr - The denominator.

Returns:

A new matrix whos elements are the elements of this divided with aNmbr.

divideElements

BasicMatrix divideElements(BasicMatrix aMtrx)

Divides the elements of this with the elements of aMtrx. The matrices must have equal dimensions.

Parameters:

aMtrx - The denominator elements.

Returns:

A new matrix whos elements are the elements of this divided with the elements of aMtrx.

doubleValue

double doubleValue(int aRow,
                   int aCol)

Extracts one element of this matrix as a double.

Parameters:

aRow - A row index.

aCol - A column index.

Returns:

One matrix element

enforce

BasicMatrix enforce(NumberContext aCntxt)

equals

boolean equals(BasicMatrix aMtrx,
               NumberContext aCntxt)

getColDim

int getColDim()

Returns:

The number of columns.

getColumns

BasicMatrix getColumns(int[] someCols)

Parameters:

someCols - An ordered array of column indeces.

Returns:

A matrix with a subset of, reordered, columns.

getDeterminant

Scalar<?> getDeterminant()

Returns:

The matrix' determinant.

getFrobeniusNorm

Scalar<?> getFrobeniusNorm()

The Frobenius norm is the square root of the sum of the squares of each element, or the square root of the sum of the square of the singular values.

Returns:

The matrix' Frobenius norm

getInfinityNorm

Scalar<?> getInfinityNorm()

The largest, absolute, element value.

getLargestElement

@Deprecated
Scalar<? extends Number> getLargestElement()

Deprecated. Since Version 24. Use getInfinityNorm() instead

The largest, absolute, element value. For complex matrices the modulus should be compared and returned.

getRank

int getRank()

The rank of a matrix is the maximum number of linearly independent rows or columns it contains. It is also equal to the number of nonzero singular values of the matrix.

Returns:

The matrix' rank.

getRowDim

int getRowDim()

Returns:

The number of rows.

getRows

BasicMatrix getRows(int[] someRows)

Parameters:

someRows - An ordered array of row indeces.

Returns:

A matrix with a subset of, reordered, rows.

getTrace

Scalar<?> getTrace()

The sum of the diagonal elements.

Returns:

The matrix' trace.

getVectorNorm

Scalar<?> getVectorNorm(int aDegree)

Treats [this] as if it is one dimensional (a vector) and calculates the vector norm.

See Also:

toListOfRows(), toListOfColumns(), toListOfElements()

getVectorProduct

Scalar<?> getVectorProduct(BasicMatrix aVctr)

Treats [this] and [aVctr] as if they are one dimensional (vectors) and calculates the vector (dot) product. The two vectors must have the same number of elements.

getZeroNorm

Scalar<?> getZeroNorm()

Returns:

The matrix' zero-norm

invert

BasicMatrix invert()

About inverting matrices:

• "right inverse": [this][right inverse]=[I]. You may calculate it using solve(BasicMatrix).
• "left inverse": [left inverse][this]=[I]. You may calculate it using solve(BasicMatrix) and transposing.
• "generalised inverse": [this][generalised inverse][this]=[this]. Note that if [this] is singular or non-square, then [generalised inverse] is not unique.
• "pseudoinverse": The generalised inverse (there are typically/possibly many) with the smallest frobenius norm is called the pseudoinverse. You may calculate it using the QR or SingularValue decompositions.
• "inverse":
  • If [left inverse]=[right inverse] then it is also [inverse].
  • If [this] is square and has full rank then the [generalised inverse] is unique, with the [pseudoinverse] given, and equal to [inverse].

Returns:

The "best possible" inverse....

isEmpty

boolean isEmpty()

Matrices are either square, tall, fat or empty. m <= 0 or n <= 0

Returns:

true if matrix is empty

isFat

boolean isFat()

Matrices are either square, tall, fat or empty. 1 <= m < n

Returns:

true if matrix is fat

isSquare

boolean isSquare()

Matrices are either square, tall, fat or empty. m = n <> 0

Returns:

true if matrix is square

isTall

boolean isTall()

Matrices are either square, tall, fat or empty. m > n >= 1

Returns:

true if matrix is tall

mergeColumns

BasicMatrix mergeColumns(BasicMatrix aMtrx)

[aMtrx] is appended to the bottom of [this]. The two matrices must have the same number of columns.

Parameters:

aMtrx - The matrix to merge.

Returns:

A new matrix with more rows.

mergeRows

BasicMatrix mergeRows(BasicMatrix aMtrx)

[aMtrx] is appended to the right side of [this]. The two matrices must have the same number of rows.

Parameters:

aMtrx - The matrix to merge.

Returns:

A new matrix with more columns.

multiply

BasicMatrix multiply(Number aNmbr)

Multiplies the elements of this matrix with aNmbr.

Parameters:

aNmbr - What to multiply with.

Returns:

A new matrix whos elements are the elements of this multiplied with aNmbr.

multiplyElements

BasicMatrix multiplyElements(BasicMatrix aMtrx)

Multiplies the elements of this matrix with the elements of aMtrx. The matrices must have equal dimensions.

Parameters:

aMtrx - The elements to multiply by.

Returns:

A new matrix whos elements are the elements of this multiplied with the elements of aMtrx.

multiplyLeft

BasicMatrix multiplyLeft(BasicMatrix aMtrx)

Matrix multiplication: [aMtrx][this]
The column dimension of the left matrix must equal the row dimension of the right matrix.

Parameters:

aMtrx - The left matrix.

Returns:

The product.

See Also:

multiplyRight(BasicMatrix)

multiplyRight

BasicMatrix multiplyRight(BasicMatrix aMtrx)

Matrix multiplication: [this][aMtrx]
The column dimension of the left matrix must equal the row dimension of the right matrix.

Parameters:

aMtrx - The right matrix.

Returns:

The product.

See Also:

multiplyLeft(BasicMatrix)

negate

BasicMatrix negate()

Returns:

A new matrix with negated elements.

set

BasicMatrix set(int aRow,
                int aCol,
                Number aNmbr)

size

int size()

Returns:

The number of elements.

solve

BasicMatrix solve(BasicMatrix aRHS)

This method solves a system of linear equations: [this][X]=[aRHS]. A combination of columns in [this] should produce a column in [aRHS]. It is ok for [aRHS] to have more than 1 column.

• If the problem is over-qualified an approximate solution is returned.
• If the problem is under-qualified one possible solution is returned.

Remember that: [X][this]=[aRHS] is equivalent to [this]^T[X]^T=[aRHS]^T

Parameters:

aRHS - The right hand side of the equation.

Returns:

The solution, [X].

subtract

BasicMatrix subtract(BasicMatrix aMtrx)

Subtracts the elements of aMtrx from the elements of this matrix. The matrices must have equal dimensions.

Parameters:

aMtrx - What to subtract.

Returns:

A new matrix whos elements are the difference of this' and aMtrx'.

subtract

BasicMatrix subtract(Number aNmbr)

Subtracts aNmbr from the elements of this matrix.

Parameters:

aNmbr - What to subtract.

Returns:

A new matrix whos elements are the differences between this' elements and aNmbr.

toBigDecimal

BigDecimal toBigDecimal(int aRow,
                        int aCol)

Extracts one element of this matrix as a BigDecimal.

Parameters:

aRow - A row index.

aCol - A column index.

Returns:

One matrix element

toBigStore

PhysicalStore<BigDecimal> toBigStore()

See Also:

toComplexStore(), toPrimitiveStore()

toComplexNumber

ComplexNumber toComplexNumber(int aRow,
                              int aCol)

Extracts one element of this matrix as a ComplexNumber.

Parameters:

aRow - A row index.

aCol - A column index.

Returns:

One matrix element

toComplexStore

PhysicalStore<ComplexNumber> toComplexStore()

See Also:

toBigStore(), toPrimitiveStore()

toListOfColumns

List<BasicMatrix> toListOfColumns()

toListOfElements

List<BigDecimal> toListOfElements()

toListOfRows

List<BasicMatrix> toListOfRows()

toPrimitiveStore

PhysicalStore<Double> toPrimitiveStore()

See Also:

toBigStore(), toComplexStore()

toScalar

Scalar<?> toScalar(int aRow,
                   int aCol)

Extracts one element of this matrix as a Scalar.

Parameters:

aRow - A row index.

aCol - A column index.

Returns:

One matrix element

toString

String toString(int aRow,
                int aCol)

transpose

BasicMatrix transpose()

Transposes this matrix. For complex matrices conjugate() and transpose() are NOT EQUAL.

Returns:

A matrix that is the transpose of this matrix.

See Also:

conjugate()