/* * 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.math3.linear; import org.apache.commons.math3.Field; import org.apache.commons.math3.FieldElement; import org.apache.commons.math3.exception.DimensionMismatchException; import org.apache.commons.math3.exception.NoDataException; import org.apache.commons.math3.exception.NotPositiveException; import org.apache.commons.math3.exception.NotStrictlyPositiveException; import org.apache.commons.math3.exception.NullArgumentException; import org.apache.commons.math3.exception.NumberIsTooSmallException; import org.apache.commons.math3.exception.OutOfRangeException; /** * Interface defining field-valued matrix with basic algebraic operations. * *
Matrix element indexing is 0-based -- e.g., Example: Row 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
* @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(FieldMatrixChangingVisitor Row 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
* @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(FieldMatrixPreservingVisitor Row 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
* @throws OutOfRangeException if the indices are not valid.
* @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
* startColumn}.
* @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(
FieldMatrixChangingVisitor Row 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
* @throws OutOfRangeException if the indices are not valid.
* @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
* startColumn}.
* @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(
FieldMatrixPreservingVisitor Column 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
* @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(FieldMatrixChangingVisitor Column 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
* @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(FieldMatrixPreservingVisitor Column 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
* @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
* startColumn}.
* @throws OutOfRangeException 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(
FieldMatrixChangingVisitor Column 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
* @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
* startColumn}.
* @throws OutOfRangeException 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(
FieldMatrixPreservingVisitor The 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
* @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(FieldMatrixChangingVisitor The 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
* @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(FieldMatrixPreservingVisitor The 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)
* @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
* startColumn}.
* @throws OutOfRangeException 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(
FieldMatrixChangingVisitor The 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)
* @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
* startColumn}.
* @throws OutOfRangeException 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(
FieldMatrixPreservingVisitorgetEntry(0, 0)
returns the element in
* the first row, first column of the matrix.
*
* @param p
times. Depending on the type
* of the field elements, T, instability for high powers might occur.
*
* @param p raise this to power p
* @return this^p
* @throws NotPositiveException if {@code p < 0}
* @throws NonSquareMatrixException if {@code this matrix} is not square
*/
FieldMatrix
* 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 OutOfRangeException if {@code subMatrix} does not fit into this matrix from element
* in {@code (row, column)}.
* @throws NoDataException if a row or column of {@code subMatrix} is empty.
* @throws DimensionMismatchException if {@code subMatrix} is not rectangular (not all rows have
* the same length).
* @throws NullArgumentException if {@code subMatrix} is {@code null}.
* @since 2.0
*/
void setSubMatrix(T[][] subMatrix, int row, int column)
throws DimensionMismatchException,
OutOfRangeException,
NoDataException,
NullArgumentException;
/**
* Get the entries in row number {@code row} as a row matrix.
*
* @param row Row to be fetched.
* @return a row matrix.
* @throws OutOfRangeException if the specified row index is invalid.
*/
FieldMatrix