/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.math.linear; import org.apache.commons.math.Field; import org.apache.commons.math.FieldElement; import org.apache.commons.math.linear.MatrixVisitorException; /** * Interface defining field-valued matrix with basic algebraic operations. *
* Matrix element indexing is 0-based -- e.g., getEntry(0, 0)
* returns the element in the first row, first column of the matrix.
m
.
* @param m matrix to premultiply by
* @return m * this
* @throws IllegalArgumentException
* if rowDimension(this) != columnDimension(m)
*/
FieldMatrixrow, column
using data in
* the input subMatrix
array. Indexes are 0-based.
*
* Example:
* Starting with
* 1 2 3 4 * 5 6 7 8 * 9 0 1 2 ** and
subMatrix = {{3, 4} {5,6}}
, invoking
* setSubMatrix(subMatrix,1,1))
will result in * 1 2 3 4 * 5 3 4 8 * 9 5 6 2 ** * @param subMatrix array containing the submatrix replacement data * @param row row coordinate of the top, left element to be replaced * @param column column coordinate of the top, left element to be replaced * @throws MatrixIndexException if subMatrix does not fit into this * matrix from element in (row, column) * @throws IllegalArgumentException if
subMatrix
is not rectangular
* (not all rows have the same length) or empty
* @throws NullPointerException if subMatrix
is null
* @since 2.0
*/
void setSubMatrix(T[][] subMatrix, int row, int column)
throws MatrixIndexException;
/**
* Returns the entries in row number row
* as a row matrix. Row indices start at 0.
*
* @param row the row to be fetched
* @return row matrix
* @throws MatrixIndexException if the specified row index is invalid
*/
FieldMatrixrow
* as a row matrix. Row indices start at 0.
*
* @param row the row to be set
* @param matrix row matrix (must have one row and the same number of columns
* as the instance)
* @throws MatrixIndexException if the specified row index is invalid
* @throws InvalidMatrixException if the matrix dimensions do not match one
* instance row
*/
void setRowMatrix(int row, FieldMatrixcolumn
* as a column matrix. Column indices start at 0.
*
* @param column the column to be fetched
* @return column matrix
* @throws MatrixIndexException if the specified column index is invalid
*/
FieldMatrixcolumn
* as a column matrix. Column indices start at 0.
*
* @param column the column to be set
* @param matrix column matrix (must have one column and the same number of rows
* as the instance)
* @throws MatrixIndexException if the specified column index is invalid
* @throws InvalidMatrixException if the matrix dimensions do not match one
* instance column
*/
void setColumnMatrix(int column, FieldMatrixrow
* as a vector. Row indices start at 0.
*
* @param row the row to be fetched
* @return row vector
* @throws MatrixIndexException if the specified row index is invalid
*/
FieldVectorrow
* as a vector. Row indices start at 0.
*
* @param row the row to be set
* @param vector row vector (must have the same number of columns
* as the instance)
* @throws MatrixIndexException if the specified row index is invalid
* @throws InvalidMatrixException if the vector dimension does not match one
* instance row
*/
void setRowVector(int row, FieldVectorcolumn
* as a vector. Column indices start at 0.
*
* @param column the column to be fetched
* @return column vector
* @throws MatrixIndexException if the specified column index is invalid
*/
FieldVectorcolumn
* as a vector. Column indices start at 0.
*
* @param column the column to be set
* @param vector column vector (must have the same number of rows as the instance)
* @throws MatrixIndexException if the specified column index is invalid
* @throws InvalidMatrixException if the vector dimension does not match one
* instance column
*/
void setColumnVector(int column, FieldVectorrow
as an array.
*
* Row indices start at 0. A MatrixIndexException
is thrown
* unless 0 <= row < rowDimension.
row
* as a row matrix. Row indices start at 0.
*
* @param row the row to be set
* @param array row matrix (must have the same number of columns as the instance)
* @throws MatrixIndexException if the specified row index is invalid
* @throws InvalidMatrixException if the array size does not match one
* instance row
*/
void setRow(int row, T[] array)
throws MatrixIndexException, InvalidMatrixException;
/**
* Returns the entries in column number col
as an array.
*
* Column indices start at 0. A MatrixIndexException
is thrown
* unless 0 <= column < columnDimension.
column
* as a column matrix. Column indices start at 0.
*
* @param column the column to be set
* @param array column array (must have the same number of rows as the instance)
* @throws MatrixIndexException if the specified column index is invalid
* @throws InvalidMatrixException if the array size does not match one
* instance column
*/
void setColumn(int column, T[] array)
throws MatrixIndexException, InvalidMatrixException;
/**
* Returns the entry in the specified row and column.
* * Row and column indices start at 0 and must satisfy *
0 <= row < rowDimension
0 <= column < columnDimension
MatrixIndexException
is thrown.
*
* @param row row location of entry to be fetched
* @param column column location of entry to be fetched
* @return matrix entry in row,column
* @throws MatrixIndexException if the row or column index is not valid
*/
T getEntry(int row, int column) throws MatrixIndexException;
/**
* Set the entry in the specified row and column.
* * Row and column indices start at 0 and must satisfy *
0 <= row < rowDimension
0 <= column < columnDimension
MatrixIndexException
is thrown.
*
* @param row row location of entry to be set
* @param column column location of entry to be set
* @param value matrix entry to be set in row,column
* @throws MatrixIndexException if the row or column index is not valid
* @since 2.0
*/
void setEntry(int row, int column, T value) throws MatrixIndexException;
/**
* Change an entry in the specified row and column.
* * Row and column indices start at 0 and must satisfy *
0 <= row < rowDimension
0 <= column < columnDimension
MatrixIndexException
is thrown.
*
* @param row row location of entry to be set
* @param column column location of entry to be set
* @param increment value to add to the current matrix entry in row,column
* @throws MatrixIndexException if the row or column index is not valid
* @since 2.0
*/
void addToEntry(int row, int column, T increment) throws MatrixIndexException;
/**
* Change an entry in the specified row and column.
* * Row and column indices start at 0 and must satisfy *
0 <= row < rowDimension
0 <= column < columnDimension
MatrixIndexException
is thrown.
*
* @param row row location of entry to be set
* @param column column location of entry to be set
* @param factor multiplication factor for the current matrix entry in row,column
* @throws MatrixIndexException if the row or column index is not valid
* @since 2.0
*/
void multiplyEntry(int row, int column, T factor) throws MatrixIndexException;
/**
* Returns the transpose of this matrix.
*
* @return transpose matrix
*/
FieldMatrixv
.
*
* @param v the vector to operate on
* @return this*v
* @throws IllegalArgumentException if columnDimension != v.size()
*/
T[] operate(T[] v) throws IllegalArgumentException;
/**
* Returns the result of multiplying this by the vector v
.
*
* @param v the vector to operate on
* @return this*v
* @throws IllegalArgumentException if columnDimension != v.size()
*/
FieldVectorv
.
*
* @param v the row vector to premultiply by
* @return v*this
* @throws IllegalArgumentException if rowDimension != v.size()
*/
T[] preMultiply(T[] v) throws IllegalArgumentException;
/**
* Returns the (row) vector result of premultiplying this by the vector v
.
*
* @param v the row vector to premultiply by
* @return v*this
* @throws IllegalArgumentException if rowDimension != v.size()
*/
FieldVectorRow order starts at upper left and iterating through all elements * of a row from left to right before going to the leftmost element * of the next row.
* @param visitor visitor used to process all matrix entries * @exception MatrixVisitorException if the visitor cannot process an entry * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end * of the walk */ T walkInRowOrder(FieldMatrixChangingVisitorRow order starts at upper left and iterating through all elements * of a row from left to right before going to the leftmost element * of the next row.
* @param visitor visitor used to process all matrix entries * @exception MatrixVisitorException if the visitor cannot process an entry * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end * of the walk */ T walkInRowOrder(FieldMatrixPreservingVisitorRow order starts at upper left and iterating through all elements * of a row from left to right before going to the leftmost element * of the next row.
* @param visitor visitor used to process all matrix entries * @param startRow Initial row index * @param endRow Final row index (inclusive) * @param startColumn Initial column index * @param endColumn Final column index * @exception MatrixVisitorException if the visitor cannot process an entry * @exception MatrixIndexException if the indices are not valid * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end * of the walk */ T walkInRowOrder(FieldMatrixChangingVisitorRow order starts at upper left and iterating through all elements * of a row from left to right before going to the leftmost element * of the next row.
* @param visitor visitor used to process all matrix entries * @param startRow Initial row index * @param endRow Final row index (inclusive) * @param startColumn Initial column index * @param endColumn Final column index * @exception MatrixVisitorException if the visitor cannot process an entry * @exception MatrixIndexException if the indices are not valid * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end * of the walk */ T walkInRowOrder(FieldMatrixPreservingVisitorColumn order starts at upper left and iterating through all elements * of a column from top to bottom before going to the topmost element * of the next column.
* @param visitor visitor used to process all matrix entries * @exception MatrixVisitorException if the visitor cannot process an entry * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end * of the walk */ T walkInColumnOrder(FieldMatrixChangingVisitorColumn order starts at upper left and iterating through all elements * of a column from top to bottom before going to the topmost element * of the next column.
* @param visitor visitor used to process all matrix entries * @exception MatrixVisitorException if the visitor cannot process an entry * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end * of the walk */ T walkInColumnOrder(FieldMatrixPreservingVisitorColumn order starts at upper left and iterating through all elements * of a column from top to bottom before going to the topmost element * of the next column.
* @param visitor visitor used to process all matrix entries * @param startRow Initial row index * @param endRow Final row index (inclusive) * @param startColumn Initial column index * @param endColumn Final column index * @exception MatrixVisitorException if the visitor cannot process an entry * @exception MatrixIndexException if the indices are not valid * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end * of the walk */ T walkInColumnOrder(FieldMatrixChangingVisitorColumn order starts at upper left and iterating through all elements * of a column from top to bottom before going to the topmost element * of the next column.
* @param visitor visitor used to process all matrix entries * @param startRow Initial row index * @param endRow Final row index (inclusive) * @param startColumn Initial column index * @param endColumn Final column index * @exception MatrixVisitorException if the visitor cannot process an entry * @exception MatrixIndexException if the indices are not valid * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end * of the walk */ T walkInColumnOrder(FieldMatrixPreservingVisitorThe fastest walking order depends on the exact matrix class. It may be * different from traditional row or column orders.
* @param visitor visitor used to process all matrix entries * @exception MatrixVisitorException if the visitor cannot process an entry * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end * of the walk */ T walkInOptimizedOrder(FieldMatrixChangingVisitorThe fastest walking order depends on the exact matrix class. It may be * different from traditional row or column orders.
* @param visitor visitor used to process all matrix entries * @exception MatrixVisitorException if the visitor cannot process an entry * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end * of the walk */ T walkInOptimizedOrder(FieldMatrixPreservingVisitorThe fastest walking order depends on the exact matrix class. It may be * different from traditional row or column orders.
* @param visitor visitor used to process all matrix entries * @param startRow Initial row index * @param endRow Final row index (inclusive) * @param startColumn Initial column index * @param endColumn Final column index (inclusive) * @exception MatrixVisitorException if the visitor cannot process an entry * @exception MatrixIndexException if the indices are not valid * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end * of the walk */ T walkInOptimizedOrder(FieldMatrixChangingVisitorThe fastest walking order depends on the exact matrix class. It may be * different from traditional row or column orders.
* @param visitor visitor used to process all matrix entries * @param startRow Initial row index * @param endRow Final row index (inclusive) * @param startColumn Initial column index * @param endColumn Final column index (inclusive) * @exception MatrixVisitorException if the visitor cannot process an entry * @exception MatrixIndexException if the indices are not valid * @see #walkInRowOrder(FieldMatrixChangingVisitor) * @see #walkInRowOrder(FieldMatrixPreservingVisitor) * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixChangingVisitor) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor) * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int) * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor) * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor) * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int) * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end * of the walk */ T walkInOptimizedOrder(FieldMatrixPreservingVisitor