orbital.math
Interface Matrix

All Superinterfaces:

Arithmetic, Normed, Tensor

public interface Matrix
extends Tensor

Represents a matrix of any dimension n×m.

R^n×m = { M=(m_i,j) ¦ m_i,j∈R} ≅ Rⁿ ⊗_R R^m where

M = (mi,j) =	[	m0,0 ,	m0,1 ,	m0,2 ,	…,	m0,m-1	]
		m1,0 ,	m1,1 ,	m1,2 ,	…,	m1,m-1
		⋮				⋮
		mn-1,0,	mn-1,1,	mn-1,2,	…,	mn-1,m-1

If the dimension is height×width then the matrix has height rows and width columns.

The components m_i,j∈R are any arithmetic objects. If R is a true ring with 1, the square matrices (R^n×n,+,·,∙) form a unital, associative R-algebra with the laws of composition + and ∙ and the law of action ·. But it is non-commutative and has zero divisors for n≥2. The general matrices (R^n×m,+,·) form an R-module, at least, with the law of composition + and the law of action ·. If R is a field, the matrices even form an R-vector space.

If you intend to use mutable arithmetic elements, note the discussion of mutations per reference vs. explicit cloning in Tensor.set(int[],Arithmetic) which generally holds for all operations that set component values.

Also note that some few methods will change its instance and explicitly return this to allow chaining of structural changes, whilst arithmetic methods will leave a matrix unchanged but return a modified version. Refer to the documentation of the individual methods for details.

Author:

André Platzer

See Also:

ValueFactory.tensor(Arithmetic[][]), ValueFactory.valueOf(Arithmetic[][]), ValueFactory.valueOf(double[][])

Invariants:

super ∧ rank()==2

Structure:

extends Tensor

Field Summary

Fields inherited from interface orbital.math.Arithmetic

numerical

Method Summary

Matrix	add(Matrix B) Adds two matrices returning a matrix.
Matrix	conjugate() Returns this matrix conjugate transposed. .⊹:Rn×m→Rm×n; M↦M⊹:=tM = (ti,j) with ti,j = mj,i.
Arithmetic	det() Returns the determinant of the matrix representation.
java.awt.Dimension	dimension() Returns the dimension of the matrix.
Arithmetic	get(int i, int j) Returns the component value at a position (i|j).
Vector	getColumn(int c) Returns the column vector view of a column.
java.util.ListIterator	getColumns() Returns an iterator over the column vectors.
Vector	getDiagonal() Returns the main-diagonal-vector of this square matrix.
Vector	getRow(int r) Returns the row vector view of a row.
java.util.ListIterator	getRows() Returns an iterator over the row vectors.
Matrix	insertColumns(int index, Matrix cols) Insert columns into this matrix.
Matrix	insertColumns(Matrix cols) Append columns to this matrix.
Matrix	insertRows(int index, Matrix rows) Insert rows into this matrix.
Matrix	insertRows(Matrix rows) Append rows to this matrix.
int	isDefinite() Checks how definite this square matrix is.
boolean	isInvertible() Checks whether this square matrix is regular.
boolean	isRegular() Deprecated. Since Orbital1.1 use isInvertible() instead.
boolean	isSquare() Checks whether this matrix is a square matrix of size n×n.
boolean	isSymmetric() Checks whether this square matrix is symmetric.
java.util.ListIterator	iterator() Returns an iterator over all components (row-wise).
int	linearRank() (linear) rank of this matrix.
Matrix	multiply(Matrix B) Multiplies two matrices returning a matrix.
Matrix	multiply(Scalar s) Multiplies a matrix with a scalar returning a matrix.
Vector	multiply(Vector B) Multiplies a matrix with a vector returning a vector.
Real	norm() Returns a norm ||.|| of this arithmetic object. Returns the sub-multiplicative Frobenius norm of this matrix.
Real	norm(double p) Returns the norm || ||p of this matrix.
Matrix	pseudoInverse() Returns the pseudo inverse matrix A+.
Matrix	removeColumn(int c) Remove a column from this matrix.
Matrix	removeRow(int r) Remove a row from this matrix.
Matrix	scale(Scalar s) Multiplies a matrix with a scalar returning a matrix.
void	set(int i, int j, Arithmetic mij) Sets a component value at a position (i|j).
void	setColumn(int c, Vector col) Sets the column vector at a column.
void	setRow(int r, Vector row) Sets the row vector at a row.
Matrix	subMatrix(int i1, int i2, int j1, int j2) Get a sub-matrix view ranging (i1:i2,j1:j2) inclusive.
Matrix	subtract(Matrix B) Subtracts two matrices returning a matrix.
Arithmetic[][]	toArray() Returns an array containing all the elements in this matrix.
Arithmetic	trace() Returns the trace of the matrix representation.
Matrix	transpose() Returns this matrix transposed.

Methods inherited from interface orbital.math.Tensor

add, clone, dimensions, entries, get, indices, multiply, rank, set, setSubTensor, subTensor, subTensor, subTensorTransposed, subtract, tensor

Methods inherited from interface orbital.math.Arithmetic

add, divide, equals, inverse, isOne, isZero, minus, multiply, one, power, scale, subtract, toString, valueFactory, zero

Method Detail

dimension

java.awt.Dimension dimension()

Returns the dimension of the matrix.

get

Arithmetic get(int i,
               int j)

Returns the component value at a position (i|j).

Of course, this method only has a meaning for free modules like vector spaces.

Parameters:

i - the row of the value to get.

j - the column of the value to get.

Returns:

m_i,j.

set

void set(int i,
         int j,
         Arithmetic mij)
         throws java.lang.UnsupportedOperationException

Sets a component value at a position (i|j).

Of course, this method only has a meaning for free modules like vector spaces.

Parameters:

i - the row of the value to set.

j - the column of the value to set.

mij - the value to set for the element m_i,j at position (i|j)

Throws:

java.lang.UnsupportedOperationException - if this matrix is constant and does not allow this operation.

getColumns

java.util.ListIterator getColumns()

Returns an iterator over the column vectors.

getRows

java.util.ListIterator getRows()

Returns an iterator over the row vectors.

iterator

java.util.ListIterator iterator()

Returns an iterator over all components (row-wise).

If you cannot avoid it, call transpose().iterator() to get an iterator over all components, column by column.

Specified by:

iterator in interface Tensor

Returns:

an iterator that iterates over {m_0,0,…,m_0,m-1, m_1,0,…,m_1,m-1,…, m_n-1,0,…,m_n-1,m-1}.

getColumn

Vector getColumn(int c)

Returns the column vector view of a column.

The returned vector is a structurally unmodifiable view.

For M_i,j, bindSecond(c).

Returns:

a vector view of the specified column M_(0:n-1,c:c) in this matrix.

See Also:

Functionals.bindSecond(orbital.logic.functor.BinaryFunction, Object)

setColumn

void setColumn(int c,
               Vector col)
               throws java.lang.UnsupportedOperationException

Sets the column vector at a column.

Throws:

java.lang.UnsupportedOperationException

Preconditions:

col.dimension() == dimension().height

getRow

Vector getRow(int r)

Returns the row vector view of a row.

The returned vector is a structurally unmodifiable view.

For M_i,j bindFirst(r).

Returns:

a vector view of the specified row M_(r:r,0:m-1) in this matrix.

See Also:

Functionals.bindFirst(orbital.logic.functor.BinaryFunction, Object)

setRow

void setRow(int r,
            Vector row)
            throws java.lang.UnsupportedOperationException

Sets the row vector at a row.

Throws:

java.lang.UnsupportedOperationException

Preconditions:

row.dimension() == dimension().width

subMatrix

Matrix subMatrix(int i1,
                 int i2,
                 int j1,
                 int j2)

Get a sub-matrix view ranging (i1:i2,j1:j2) inclusive. That is Moeler notation.

The returned matrix is a structurally unmodifiable view.

Parameters:

i1 - the top-most row index of the sub matrix view to get.

i2 - the bottom-most row index of the sub matrix view to get.

j1 - the left-most column index of the sub matrix view to get.

j2 - the right-most column index of the sub matrix view to get.

Returns:

a matrix view of the specified part of this matrix.

M(i1:i2,j1:j2) = (mi,j)i∈{i1,…,i2},j∈{j1,…,j2} =	[	mi1,j1,	…,	mi1,j2	]
		⋮		⋮
		mi2,j1,	…,	mi2,j2

Preconditions:

i1≤i2 && j1≤j2 && valid(i1, j1) && valid(i2, j2)

getDiagonal

Vector getDiagonal()

Returns the main-diagonal-vector of this square matrix. The vector that consists of m_i,i.

Preconditions:

isSquare()

isSquare

boolean isSquare()

Checks whether this matrix is a square matrix of size n×n.

Preconditions:

true

Postconditions:

RES == (dimension().width == dimension().height)

isSymmetric

boolean isSymmetric()
                    throws java.lang.ArithmeticException

Checks whether this square matrix is symmetric. Symmetric matrices are those that satisfy M^T = M alias m_i,j=m_j,i ∀i,j∈N.

In R^n×m, symmetric is the same as self-adjoint.

Throws:

java.lang.ArithmeticException - if this is not a square matrix since only square matrices can be symmetric.

Preconditions:

isSquare()

Postconditions:

RES.equals(transpose().equals(this))

isInvertible

boolean isInvertible()
                     throws java.lang.ArithmeticException

Checks whether this square matrix is regular. Invertible matrices are also called regular, which are those with invertible determinant.

Returns:

true if this matrix is invertible and false if it is singular (linear rank<n).

Throws:

java.lang.ArithmeticException - if this is not a square matrix since only square matrices can be regular.

Preconditions:

isSquare()

Postconditions:

RES ⇔ det()∈R^×

isRegular

boolean isRegular()
                  throws java.lang.ArithmeticException

Deprecated. Since Orbital1.1 use isInvertible() instead.

Throws:

java.lang.ArithmeticException

isDefinite

int isDefinite()
               throws java.lang.ArithmeticException

Checks how definite this square matrix is.

f.ex. a symmetric matrix is positive definite iff every main minor is > 0. i.e. ∀i∈{0,…,n-1} det A(0:i,0:i) > 0. This means that every square submatrix that includes the element a_0,0 has a strictly positive determinant.

C.f. Sylvester-normal form of quadratic forms.

Returns:

• d>0 if this matrix is positive definite, i.e. ∀x∈V∖{0} ⟨x,A∙x⟩ > 0.
• d≥0 if this matrix is positive semi-definite, i.e. ∀x∈V ⟨x,A∙x⟩ ≥ 0.
• d=0 if this matrix is indefinite, i.e. ∃x∈V ⟨x,A∙x⟩ >0 ∧ ∃y∈V ⟨y,A∙y⟩ <0.
• d≤0 if this matrix is negative semi-definite, i.e. ∀x∈V ⟨x,A∙x⟩ ≤ 0.
• d<0 if this matrix is negative definite, i.e. ∀x∈V∖{0} ⟨x,A∙x⟩ < 0.

Throws:

java.lang.ArithmeticException - if this is not a square matrix since only square matrices can be symmetric.

Preconditions:

isSquare() ∧ isSymmetric()?

linearRank

int linearRank()

(linear) rank of this matrix. i.e. the maximum number of column vectors (or row vectors) that are linear independent.

Returns:

(linear) rank M := dim_K(im(M)).

See Also:

Tensor.rank()

norm

Real norm(double p)

Returns the norm || ||_p of this matrix.

||.||:C^n×m→[0,∞) is a matrix norm or consistent if it is a (vector) norm and

• ∀x∈C^n×m,y∈C^m×l ||x⋅y|| ≤ ||x||⋅||y|| (sub multiplicative)

||.|| is compatible or conform with the vector norms ||.||_Cⁿ, ||.||_C^m if

• ∀A∈C^n×m, x∈C^m ||A∙x||_Cⁿ ≤ ||A||⋅||x||_C^m

||.|| is induced by the vector norms ||.||_Cⁿ, ||.||_C^m if

• ∀A∈C^n×m, x∈C^m ||A|| = max {||A∙x||_Cⁿ / ||x||_C^m ¦ x≠0} = max {||A∙x||_Cⁿ ¦ ||x||_C^m=1}

which is a measure for how much A stretches vectors. Induced norms are compatible with the corresponding vector norm. Further, induced norms are sub-multiplicative if the same norm is used on Cⁿ and C^m (and n=m).

This method should at least implement the following induced p-norms

• ||A||₁ = max {∑_i=1ⁿ|a_ij| ¦ 1≤j≤m} is the norm of column sums.
• ||A||_∞ = max {∑_j=1^m|a_ij| ¦ 1≤i≤n} is the norm of row sums.
• ||A||₂ = sqrt max Eigenvalues(A^*∙A) is the spectral norm. (optional operation)

Preconditions:

p>=1

norm

Real norm()

Returns a norm ||.|| of this arithmetic object. Returns the sub-multiplicative Frobenius norm of this matrix. ||A|| = √(∑_i=1ⁿ∑_j=1^m |a_ij|²) = tr(AA^*)

Note that the Frobenius norm is not a p-norm. It is a norm got by identifying matrices with vectors.

Specified by:

norm in interface Normed

Returns:

the norm of this object, or perhaps Double.NaN if it is symbolic and really does not have a numeric norm or a useful symbolic norm.

trace

Arithmetic trace()
                 throws java.lang.ArithmeticException

Returns the trace of the matrix representation.

The trace is invariant to conjugation (similar matrices): Tr (T^-1∙A∙T) = Tr A.

Returns:

sum of the main-diagonal-vectors components.

Throws:

java.lang.ArithmeticException - if this is not a square matrix, since only square matrix have a trace.

Preconditions:

isSquare()

det

Arithmetic det()
               throws java.lang.ArithmeticException

Returns the determinant of the matrix representation. The determinant is useful to determine if a matrix is invertible. The determinant is the universal alternating map R^n×n≅(Rⁿ)ⁿ→Λⁿ(Rⁿ)≅R of the exterior product Λⁿ(Rⁿ). It is denoted as |M| := det M.

det:R^n×n→R exists and is uniquely defined by

(ml)

det

[

a0

]

=

α·det

[

a0

]

+

β·det

[

a0

]

⋮

⋮

⋮

αai + βbi

ai

bi

⋮

⋮

⋮

an-1

an-1

an-1

"multi-linear" (linear in each row)

( )

rank M < n ⇔ det(M)=0

"≈alternating"

(1)

det(I) = 1

⇒ Properties

( )

det	[	a0	]	=	-det	[	a0	]
		⋮					⋮
		ai					aj
		⋮					⋮
		aj					ai
		⋮					⋮
		an-1					an-1

"skew symmetric"

( )

det(M^T) = det(M)

"invariant to transposition"

( )

det(M∙N) = det(M)⋅det(N)

( )

M∈(R^n×n)^× ⇔ det(M)∈R^×
⇒ det(M^-1) = det(M)^-1

( )

det	[	a0	]	=	det	[	a0	]
		⋮					⋮
		ai + ∑k≠i λkak					aj
		⋮					⋮
		an-1					an-1

"invariant to EOP"

( )

det	[	a0	]	= ∑σ∈Sn sign σ ⋅ a1σ(1) ⋅ …⋅ anσ(n)
		⋮
		ai
		⋮
		an

"determinant formula of Leibniz"

The determinant is invariant to conjugation (similar matrices): det (T^-1∙A∙T) = det A. A matrix is invertible if and only if its determinant is invertible. However, if the determinant is approximately zero then inverse transform operations might not carry enough numerical precision to produce meaningful results.

(det A)' = ∑_i=0^n-1 det (a₀…a_i'…a_n-1) where a_i = (a_0,i,…,a_n-1,i)^t is the i-th column of A.

Returns:

det A = |A|

Throws:

java.lang.ArithmeticException - if this is not a square matrix, since determinant is only defined for square matrices.

Preconditions:

isSquare()

Postconditions:

det() multilinear && (rank() < dimension().width ⇔ det() = 0) && IDENTITY(n).det() = 1

add

Matrix add(Matrix B)

Adds two matrices returning a matrix.

Preconditions:

dimension().equals(B.dimension())

Postconditions:

RES.dimension().equals(dimension()) && RES.get(i, j) == get(i,j) + B.get(i,j)

Attributes:

associative, neutral (O), inverse (-A), commutative

subtract

Matrix subtract(Matrix B)

Subtracts two matrices returning a matrix.

Preconditions:

dimension().equals(B.dimension())

Postconditions:

RES.dimension().equals(dimension()) && RES.get(i, j) == get(i,j) - B.get(i,j)

Attributes:

associative

multiply

Matrix multiply(Matrix B)

Multiplies two matrices returning a matrix. If A∈R^n×m and B∈R^m×l the resulting matrix A∙B∈R^n×l. This is the ring multiplication of matrices, and an inner product.

Returns:

the n×l matrix A∙B.

Preconditions:

dimension().width == B.dimension().height

Postconditions:

RES.dimension().height == dimension().height && RES.dimension().width == B.dimension().width && RES.get(i, j) == getRow(i) ⋅ B.getColumn(j)

Attributes:

associative, neutral (I)

scale

Matrix scale(Scalar s)

Multiplies a matrix with a scalar returning a matrix. This is the scalar multiplication.

Returns:

s·A

Preconditions:

true

Postconditions:

RES.dimension().equals(dimension()) && RES.get(i, j) == s ⋅ get(i,j)

multiply

Matrix multiply(Scalar s)

Multiplies a matrix with a scalar returning a matrix.

See Also:

scale(Scalar)

multiply

Vector multiply(Vector B)

Multiplies a matrix with a vector returning a vector. If A∈R^n×m and v∈R^m is a column vector of dimension m, the resulting column vector A∙v∈Rⁿ has dimension n. This is an inner product.

Returns:

the n-dimensional column vector A∙v.

Preconditions:

dimension().width == B.dimension()

Postconditions:

RES.dimension() == dimension().height && RES.get(i) == getRow(i) ⋅ B

transpose

Matrix transpose()

Returns this matrix transposed.
^t·:R^n×m→R^m×n; M↦^tM:=M^T:=(t_i,j) with t_i,j = m_j,i.

• ^t(A+B) = ^tA + ^tB
• ^t(λ·A) = λ·^tA
• ^t(A∙C) = ^tC∙^tA
• ^t(^tA) = A

∀A,B∈R^n×m,C∈R^m×l ∀λ∈R

Returns:

the m×n matrix ^tM=(t_i,j) with elements t_i,j = m_j,i.

See Also:

conjugate()

Postconditions:

RES.get(j,i) == get(i,j) && RES.dimension().width == dimension().height && RES.dimension().height == dimension().width

conjugate

Matrix conjugate()

Returns this matrix conjugate transposed.
.^⊹:R^n×m→R^m×n; M↦M^⊹:=^tM = (t_i,j) with t_i,j = m_j,i.

• (A+B)^⊹ = A^⊹ + B^⊹
• (λ·A)^⊹ = λ·A^⊹ = λ^*∙A^⊹
• (A∙C)^⊹ = C^⊹∙A^⊹
• (A^⊹)^⊹ = A
• .^⊹ = .^T on R^n×m

∀A,B∈R^n×m,C∈R^m×l ∀λ∈R.

Relative to a finite orthonormal basis .^⊹ is the adjoint operator.

Returns:

the m×n matrix M^⊹=^tM.

See Also:

Complex.conjugate(), transpose()

Postconditions:

RES.get(j,i) == get(i,j).conjugate() RES.dimension().width == dimension().height && RES.dimension().height == dimension().width

pseudoInverse

Matrix pseudoInverse()

Returns the pseudo inverse matrix A⁺.

The pseudo inverse of A∈R^n×m is the matrix A⁺∈R^m×n that satisfies

• ∀x∈Rⁿ A⁺∙x∈NullSpace(A)^┴
• ∀x∈Rⁿ ||x - A∙A⁺∙x|| minimal

It is uniquely characterized by the Penrose axioms

1. (A⁺∙A)^T = A⁺∙A
2. (A∙A⁺)^T = A∙A⁺
3. A⁺∙A∙A⁺ = A⁺
4. A∙A⁺∙A = A

Let A = D⋅A into a diagonal matrix U,A⁺ = D^-1⋅A⋅A⁺ - I is minimal)

Returns:

the pseudo inverse A⁺∈R^m×n of this matrix A∈R^n×m.

Preconditions:

true

Postconditions:

RES.dimension().equals(transpose().dimension()) && RES.multiply(this).transpose().equals(RES.multiply(this)) && this.multiply(RES).transpose().equals(this.multiply(RES)) && RES.multiply(this).multiply(RES).equals(RES) && this.multiply(RES).multiply(this).equals(this)

insertColumns

Matrix insertColumns(int index,
                     Matrix cols)

Insert columns into this matrix.

Parameters:

cols - a n×l matrix containing l columns to be added at the end.

Returns:

this.

Preconditions:

dimension().height == cols.dimension().height

Postconditions:

RES == this && RES.dimension().height == OLD(dimension().height) && RES.dimension().width == OLD(dimension().width) + cols.dimension().width

insertRows

Matrix insertRows(int index,
                  Matrix rows)

Insert rows into this matrix.

Parameters:

rows - a x×m matrix containing x rows to be added at the end.

Returns:

this.

Preconditions:

dimension().width == rows.dimension().width

Postconditions:

RES == this && RES.dimension().width == OLD(dimension().width) && RES.dimension().height == OLD(dimension().height) + rows.dimension().height

insertColumns

Matrix insertColumns(Matrix cols)

Append columns to this matrix.

Parameters:

cols - a n×x matrix containing x columns to be added at the end.

Returns:

this.

Preconditions:

dimension().height == cols.dimension().height

Postconditions:

RES == this && RES.dimension().height == OLD(dimension().height) && RES.dimension().width == OLD(dimension().width) + cols.dimension().width

insertRows

Matrix insertRows(Matrix rows)

Append rows to this matrix.

Parameters:

rows - a x×m matrix containing x rows to be added at the end.

Returns:

this.

Preconditions:

dimension().width == rows.dimension().width

Postconditions:

RES == this && RES.dimension().width == OLD(dimension().width) && RES.dimension().height == OLD(dimension().height) + rows.dimension().height

removeColumn

Matrix removeColumn(int c)

Remove a column from this matrix.

Returns:

this.

Preconditions:

c∈[0, dimension().width)

Postconditions:

RES == this && RES.dimension().height == OLD(dimension().height) && RES.dimension().width == OLD(dimension().width) - 1

removeRow

Matrix removeRow(int r)

Remove a row from this matrix.

Returns:

this.

Preconditions:

r∈[0, dimension().height)

Postconditions:

RES == this && RES.dimension().width == OLD(dimension().width) && RES.dimension().height == OLD(dimension().height) - 1

toArray

Arithmetic[][] toArray()

Returns an array containing all the elements in this matrix. The first index in this array specifies the row, the second is for column.

See Also:

Object.clone()

Postconditions:

RES[i][j] == get(i, j) && RES != RES