org.ojalgo.matrix
Interface BasicMatrix

All Known Implementing Classes:

BigMatrix, ComplexMatrix, JamaMatrix, PrimitiveMatrix

public interface BasicMatrix

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

Nested Class Summary

static interface

BasicMatrix.Factory

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.
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) Deprecated. Since v27 Use round(NumberContext) instead.
boolean	equals(BasicMatrix aMtrx, NumberContext aCntxt)
void	flushCache() BasicMatrix instances are intended to be immutable.
int	getColDim()
BasicMatrix	getColumns(int[] someCols)
Scalar<?>	getCondition()
Scalar<?>	getDeterminant()
List<ComplexNumber>	getEigenvalues()
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()
Scalar<?>	getKyFanNorm(int k)
Scalar<?>	getOneNorm()
Scalar<?>	getOperatorNorm() 2-norm, max singular value
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)
List<? extends Number>	getSingularValues()
Scalar<?>	getTrace() The sum of the diagonal elements.
Scalar<?>	getTraceNorm()
Scalar<?>	getVectorInfinityNorm() Deprecated. Since v29. Use getVectorNorm(int) instead with argument Integer.MAX_VALUE.
Scalar<?>	getVectorNorm(int aDegree) Treats [this] as if it is one dimensional (a vector) and calculates the vector norm.
Scalar<?>	getVectorZeroNorm() Deprecated. Since v29. Use getVectorNorm(int) instead with argument 0.
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	isFullRank()
boolean	isHermitian()
boolean	isScalar()
boolean	isSquare() Matrices are either square, tall, fat or empty.
boolean	isSymmetric()
boolean	isTall() Matrices are either square, tall, fat or empty.
boolean	isVector()
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.
Scalar<?>	multiplyVectors(BasicMatrix aVctr) Assumes that both [this] and [aVctr] have row or column dimension, doesn't matter which, equal to 1.
BasicMatrix	negate()
BasicMatrix	round(NumberContext aCntxt)
BasicMatrix	set(int aRow, int aCol, Number aNmbr) Do not use this method to populate large dense matrices! Only use it to change a few (a small number) of elements.
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() Must be a copy that is safe to modify.
ComplexNumber	toComplexNumber(int aRow, int aCol) Extracts one element of this matrix as a ComplexNumber.
PhysicalStore<ComplexNumber>	toComplexStore() Must be a copy that is safe to modify.
List<BasicMatrix>	toListOfColumns()
List<? extends Number>	toListOfElements() It is also possible to call toBigStore(), toComplexStore() or toPrimitiveStore() and then PhysicalStore.asList().
List<BasicMatrix>	toListOfRows()
PhysicalStore<Double>	toPrimitiveStore() Must be a copy that is safe to modify.
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.

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

@Deprecated
BasicMatrix enforce(NumberContext aCntxt)

Deprecated. Since v27 Use round(NumberContext) instead.

equals

boolean equals(BasicMatrix aMtrx,
               NumberContext aCntxt)

Returns:

true if the frobenius norm of the difference between [this] and [aStore] is zero within the limits of aCntxt.

flushCache

void flushCache()

BasicMatrix instances are intended to be immutable. If they are it possible to cache (partial) calculation results. Calling this method should flush any cached calculation results.

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.

getCondition

Scalar<?> getCondition()

getDeterminant

Scalar<?> getDeterminant()

Returns:

The matrix' determinant.

getEigenvalues

List<ComplexNumber> getEigenvalues()

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

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getInfinityNorm

Scalar<?> getInfinityNorm()

Returns:

Max row sum

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getKyFanNorm

Scalar<?> getKyFanNorm(int k)

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getOneNorm

Scalar<?> getOneNorm()

Returns:

Max col sum

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getOperatorNorm

Scalar<?> getOperatorNorm()

2-norm, max singular value

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

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.

getSingularValues

List<? extends Number> getSingularValues()

getTrace

Scalar<?> getTrace()

The sum of the diagonal elements.

Returns:

The matrix' trace.

getTraceNorm

Scalar<?> getTraceNorm()

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getVectorInfinityNorm

@Deprecated
Scalar<?> getVectorInfinityNorm()

Deprecated. Since v29. Use getVectorNorm(int) instead with argument Integer.MAX_VALUE.

The largest, absolute, element value.

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getVectorNorm

Scalar<?> getVectorNorm(int aDegree)

Treats [this] as if it is one dimensional (a vector) and calculates the vector norm. The interface only requires that implementations can handle arguments 0, 1, 2 and Integer.MAX_VALUE.

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

getVectorZeroNorm

@Deprecated
Scalar<?> getVectorZeroNorm()

Deprecated. Since v29. Use getVectorNorm(int) instead with argument 0.

Returns:

The number of non-zero elements

See Also:

getFrobeniusNorm(), getInfinityNorm(), getKyFanNorm(int), getOneNorm(), getOperatorNorm(), getTraceNorm(), getVectorInfinityNorm(), getVectorNorm(int), getVectorZeroNorm()

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

isFullRank

boolean isFullRank()

Returns:

true if getRank() == min(getRowDim(),getColDim())

isHermitian

boolean isHermitian()

isScalar

boolean isScalar()

Returns:

true if this is a 1x1 matrix

isSquare

boolean isSquare()

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

Returns:

true if matrix is square

isSymmetric

boolean isSymmetric()

isTall

boolean isTall()

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

Returns:

true if matrix is tall

isVector

boolean isVector()

Returns:

true if the row or column dimensions are equal to 1.

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)

multiplyVectors

Scalar<?> multiplyVectors(BasicMatrix aVctr)

Assumes that both [this] and [aVctr] have row or column dimension, doesn't matter which, equal to 1. The two vectors must have the same number of elements.

negate

BasicMatrix negate()

Returns:

A new matrix with negated elements.

round

BasicMatrix round(NumberContext aCntxt)

set

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

Do not use this method to populate large dense matrices! Only use it to change a few (a small number) of elements.

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()

Must be a copy that is safe to modify.

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()

Must be a copy that is safe to modify.

See Also:

toBigStore(), toPrimitiveStore()

toListOfColumns

List<BasicMatrix> toListOfColumns()

toListOfElements

List<? extends Number> toListOfElements()

It is also possible to call toBigStore(), toComplexStore() or toPrimitiveStore() and then PhysicalStore.asList().

toListOfRows

List<BasicMatrix> toListOfRows()

toPrimitiveStore

PhysicalStore<Double> toPrimitiveStore()

Must be a copy that is safe to modify.

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()