path: root/src/main/java/org/apache/commons/math3/linear/FieldMatrix.java

/*
 * 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.
 *
 * <p>Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code> returns the element in
 * the first row, first column of the matrix.
 *
 * @param <T> the type of the field elements
 */
public interface FieldMatrix<T extends FieldElement<T>> extends AnyMatrix {
    /**
     * Get the type of field elements of the matrix.
     *
     * @return the type of field elements of the matrix.
     */
    Field<T> getField();

    /**
     * Create a new FieldMatrix<T> of the same type as the instance with the supplied row and column
     * dimensions.
     *
     * @param rowDimension the number of rows in the new matrix
     * @param columnDimension the number of columns in the new matrix
     * @return a new matrix of the same type as the instance
     * @throws NotStrictlyPositiveException if row or column dimension is not positive.
     * @since 2.0
     */
    FieldMatrix<T> createMatrix(final int rowDimension, final int columnDimension)
            throws NotStrictlyPositiveException;

    /**
     * Make a (deep) copy of this.
     *
     * @return a copy of this matrix.
     */
    FieldMatrix<T> copy();

    /**
     * Compute the sum of this and m.
     *
     * @param m Matrix to be added.
     * @return {@code this} + {@code m}.
     * @throws MatrixDimensionMismatchException if {@code m} is not the same size as {@code this}
     *     matrix.
     */
    FieldMatrix<T> add(FieldMatrix<T> m) throws MatrixDimensionMismatchException;

    /**
     * Subtract {@code m} from this matrix.
     *
     * @param m Matrix to be subtracted.
     * @return {@code this} - {@code m}.
     * @throws MatrixDimensionMismatchException if {@code m} is not the same size as {@code this}
     *     matrix.
     */
    FieldMatrix<T> subtract(FieldMatrix<T> m) throws MatrixDimensionMismatchException;

    /**
     * Increment each entry of this matrix.
     *
     * @param d Value to be added to each entry.
     * @return {@code d} + {@code this}.
     */
    FieldMatrix<T> scalarAdd(T d);

    /**
     * Multiply each entry by {@code d}.
     *
     * @param d Value to multiply all entries by.
     * @return {@code d} * {@code this}.
     */
    FieldMatrix<T> scalarMultiply(T d);

    /**
     * Postmultiply this matrix by {@code m}.
     *
     * @param m Matrix to postmultiply by.
     * @return {@code this} * {@code m}.
     * @throws DimensionMismatchException if the number of columns of {@code this} matrix is not
     *     equal to the number of rows of matrix {@code m}.
     */
    FieldMatrix<T> multiply(FieldMatrix<T> m) throws DimensionMismatchException;

    /**
     * Premultiply this matrix by {@code m}.
     *
     * @param m Matrix to premultiply by.
     * @return {@code m} * {@code this}.
     * @throws DimensionMismatchException if the number of columns of {@code m} differs from the
     *     number of rows of {@code this} matrix.
     */
    FieldMatrix<T> preMultiply(FieldMatrix<T> m) throws DimensionMismatchException;

    /**
     * Returns the result multiplying this with itself <code>p</code> 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<T> power(final int p) throws NonSquareMatrixException, NotPositiveException;

    /**
     * Returns matrix entries as a two-dimensional array.
     *
     * @return a 2-dimensional array of entries.
     */
    T[][] getData();

    /**
     * Get a submatrix. Rows and columns are indicated counting from 0 to n - 1.
     *
     * @param startRow Initial row index
     * @param endRow Final row index (inclusive)
     * @param startColumn Initial column index
     * @param endColumn Final column index (inclusive)
     * @return the matrix containing the data of the specified rows and columns.
     * @throws NumberIsTooSmallException is {@code endRow < startRow} of {@code endColumn <
     *     startColumn}.
     * @throws OutOfRangeException if the indices are not valid.
     */
    FieldMatrix<T> getSubMatrix(int startRow, int endRow, int startColumn, int endColumn)
            throws NumberIsTooSmallException, OutOfRangeException;

    /**
     * Get a submatrix. Rows and columns are indicated counting from 0 to n - 1.
     *
     * @param selectedRows Array of row indices.
     * @param selectedColumns Array of column indices.
     * @return the matrix containing the data in the specified rows and columns.
     * @throws NoDataException if {@code selectedRows} or {@code selectedColumns} is empty
     * @throws NullArgumentException if {@code selectedRows} or {@code selectedColumns} is {@code
     *     null}.
     * @throws OutOfRangeException if row or column selections are not valid.
     */
    FieldMatrix<T> getSubMatrix(int[] selectedRows, int[] selectedColumns)
            throws NoDataException, NullArgumentException, OutOfRangeException;

    /**
     * Copy a submatrix. Rows and columns are 0-based. The designated submatrix is copied into the
     * top left portion of the destination array.
     *
     * @param startRow Initial row index.
     * @param endRow Final row index (inclusive).
     * @param startColumn Initial column index.
     * @param endColumn Final column index (inclusive).
     * @param destination The array where the submatrix data should be copied (if larger than
     *     rows/columns counts, only the upper-left part will be modified).
     * @throws MatrixDimensionMismatchException if the dimensions of {@code destination} are not
     *     large enough to hold the submatrix.
     * @throws NumberIsTooSmallException if {@code endRow < startRow} or {@code endColumn <
     *     startColumn}.
     * @throws OutOfRangeException if the indices are not valid.
     */
    void copySubMatrix(int startRow, int endRow, int startColumn, int endColumn, T[][] destination)
            throws MatrixDimensionMismatchException, NumberIsTooSmallException, OutOfRangeException;

    /**
     * Copy a submatrix. Rows and columns are indicated counting from 0 to n - 1.
     *
     * @param selectedRows Array of row indices.
     * @param selectedColumns Array of column indices.
     * @param destination Arrays where the submatrix data should be copied (if larger than
     *     rows/columns counts, only the upper-left part will be used)
     * @throws MatrixDimensionMismatchException if the dimensions of {@code destination} do not
     *     match those of {@code this}.
     * @throws NoDataException if {@code selectedRows} or {@code selectedColumns} is empty
     * @throws NullArgumentException if {@code selectedRows} or {@code selectedColumns} is {@code
     *     null}.
     * @throws OutOfRangeException if the indices are not valid.
     */
    void copySubMatrix(int[] selectedRows, int[] selectedColumns, T[][] destination)
            throws MatrixDimensionMismatchException,
                    NoDataException,
                    NullArgumentException,
                    OutOfRangeException;

    /**
     * Replace the submatrix starting at {@code (row, column)} using data in the input {@code
     * subMatrix} array. Indexes are 0-based.
     *
     * <p>Example:<br>
     * Starting with
     *
     * <pre>
     * 1  2  3  4
     * 5  6  7  8
     * 9  0  1  2
     * </pre>
     *
     * and <code>subMatrix = {{3, 4} {5,6}}</code>, invoking <code>setSubMatrix(subMatrix,1,1))
     * </code> will result in
     *
     * <pre>
     * 1  2  3  4
     * 5  3  4  8
     * 9  5  6  2
     * </pre>
     *
     * @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<T> getRowMatrix(int row) throws OutOfRangeException;

    /**
     * Set the entries in row number {@code row} as a row matrix.
     *
     * @param row Row to be set.
     * @param matrix Row matrix (must have one row and the same number of columns as the instance).
     * @throws OutOfRangeException if the specified row index is invalid.
     * @throws MatrixDimensionMismatchException if the matrix dimensions do not match one instance
     *     row.
     */
    void setRowMatrix(int row, FieldMatrix<T> matrix)
            throws MatrixDimensionMismatchException, OutOfRangeException;

    /**
     * Get the entries in column number {@code column} as a column matrix.
     *
     * @param column Column to be fetched.
     * @return a column matrix.
     * @throws OutOfRangeException if the specified column index is invalid.
     */
    FieldMatrix<T> getColumnMatrix(int column) throws OutOfRangeException;

    /**
     * Set the entries in column number {@code column} as a column matrix.
     *
     * @param column Column to be set.
     * @param matrix column matrix (must have one column and the same number of rows as the
     *     instance).
     * @throws OutOfRangeException if the specified column index is invalid.
     * @throws MatrixDimensionMismatchException if the matrix dimensions do not match one instance
     *     column.
     */
    void setColumnMatrix(int column, FieldMatrix<T> matrix)
            throws MatrixDimensionMismatchException, OutOfRangeException;

    /**
     * Get the entries in row number {@code row} as a vector.
     *
     * @param row Row to be fetched
     * @return a row vector.
     * @throws OutOfRangeException if the specified row index is invalid.
     */
    FieldVector<T> getRowVector(int row) throws OutOfRangeException;

    /**
     * Set the entries in row number {@code row} as a vector.
     *
     * @param row Row to be set.
     * @param vector row vector (must have the same number of columns as the instance).
     * @throws OutOfRangeException if the specified row index is invalid.
     * @throws MatrixDimensionMismatchException if the vector dimension does not match one instance
     *     row.
     */
    void setRowVector(int row, FieldVector<T> vector)
            throws MatrixDimensionMismatchException, OutOfRangeException;

    /**
     * Returns the entries in column number {@code column} as a vector.
     *
     * @param column Column to be fetched.
     * @return a column vector.
     * @throws OutOfRangeException if the specified column index is invalid.
     */
    FieldVector<T> getColumnVector(int column) throws OutOfRangeException;

    /**
     * Set the entries in column number {@code column} as a vector.
     *
     * @param column Column to be set.
     * @param vector Column vector (must have the same number of rows as the instance).
     * @throws OutOfRangeException if the specified column index is invalid.
     * @throws MatrixDimensionMismatchException if the vector dimension does not match one instance
     *     column.
     */
    void setColumnVector(int column, FieldVector<T> vector)
            throws MatrixDimensionMismatchException, OutOfRangeException;

    /**
     * Get the entries in row number {@code row} as an array.
     *
     * @param row Row to be fetched.
     * @return array of entries in the row.
     * @throws OutOfRangeException if the specified row index is not valid.
     */
    T[] getRow(int row) throws OutOfRangeException;

    /**
     * Set the entries in row number {@code row} as a row matrix.
     *
     * @param row Row to be set.
     * @param array Row matrix (must have the same number of columns as the instance).
     * @throws OutOfRangeException if the specified row index is invalid.
     * @throws MatrixDimensionMismatchException if the array size does not match one instance row.
     */
    void setRow(int row, T[] array) throws MatrixDimensionMismatchException, OutOfRangeException;

    /**
     * Get the entries in column number {@code col} as an array.
     *
     * @param column the column to be fetched
     * @return array of entries in the column
     * @throws OutOfRangeException if the specified column index is not valid.
     */
    T[] getColumn(int column) throws OutOfRangeException;

    /**
     * Set the entries in column number {@code column} as a column matrix.
     *
     * @param column the column to be set
     * @param array column array (must have the same number of rows as the instance)
     * @throws OutOfRangeException if the specified column index is invalid.
     * @throws MatrixDimensionMismatchException if the array size does not match one instance
     *     column.
     */
    void setColumn(int column, T[] array)
            throws MatrixDimensionMismatchException, OutOfRangeException;

    /**
     * Returns the entry in the specified row and column.
     *
     * @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 OutOfRangeException if the row or column index is not valid.
     */
    T getEntry(int row, int column) throws OutOfRangeException;

    /**
     * Set the entry in the specified row and column.
     *
     * @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 OutOfRangeException if the row or column index is not valid.
     * @since 2.0
     */
    void setEntry(int row, int column, T value) throws OutOfRangeException;

    /**
     * Change an entry in the specified row and column.
     *
     * @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 {@code (row, column)}.
     * @throws OutOfRangeException if the row or column index is not valid.
     * @since 2.0
     */
    void addToEntry(int row, int column, T increment) throws OutOfRangeException;

    /**
     * Change an entry in the specified row and column.
     *
     * @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 {@code (row,column)}
     * @throws OutOfRangeException if the row or column index is not valid.
     * @since 2.0
     */
    void multiplyEntry(int row, int column, T factor) throws OutOfRangeException;

    /**
     * Returns the transpose of this matrix.
     *
     * @return transpose matrix
     */
    FieldMatrix<T> transpose();

    /**
     * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">trace</a> of the matrix
     * (the sum of the elements on the main diagonal).
     *
     * @return trace
     * @throws NonSquareMatrixException if the matrix is not square.
     */
    T getTrace() throws NonSquareMatrixException;

    /**
     * Returns the result of multiplying this by the vector {@code v}.
     *
     * @param v the vector to operate on
     * @return {@code this * v}
     * @throws DimensionMismatchException if the number of columns of {@code this} matrix is not
     *     equal to the size of the vector {@code v}.
     */
    T[] operate(T[] v) throws DimensionMismatchException;

    /**
     * Returns the result of multiplying this by the vector {@code v}.
     *
     * @param v the vector to operate on
     * @return {@code this * v}
     * @throws DimensionMismatchException if the number of columns of {@code this} matrix is not
     *     equal to the size of the vector {@code v}.
     */
    FieldVector<T> operate(FieldVector<T> v) throws DimensionMismatchException;

    /**
     * Returns the (row) vector result of premultiplying this by the vector {@code v}.
     *
     * @param v the row vector to premultiply by
     * @return {@code v * this}
     * @throws DimensionMismatchException if the number of rows of {@code this} matrix is not equal
     *     to the size of the vector {@code v}
     */
    T[] preMultiply(T[] v) throws DimensionMismatchException;

    /**
     * Returns the (row) vector result of premultiplying this by the vector {@code v}.
     *
     * @param v the row vector to premultiply by
     * @return {@code v * this}
     * @throws DimensionMismatchException if the number of rows of {@code this} matrix is not equal
     *     to the size of the vector {@code v}
     */
    FieldVector<T> preMultiply(FieldVector<T> v) throws DimensionMismatchException;

    /**
     * Visit (and possibly change) all matrix entries in row order.
     *
     * <p>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<T> visitor);

    /**
     * Visit (but don't change) all matrix entries in row order.
     *
     * <p>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<T> visitor);

    /**
     * Visit (and possibly change) some matrix entries in row order.
     *
     * <p>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<T> visitor,
            int startRow,
            int endRow,
            int startColumn,
            int endColumn)
            throws OutOfRangeException, NumberIsTooSmallException;

    /**
     * Visit (but don't change) some matrix entries in row order.
     *
     * <p>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<T> visitor,
            int startRow,
            int endRow,
            int startColumn,
            int endColumn)
            throws OutOfRangeException, NumberIsTooSmallException;

    /**
     * Visit (and possibly change) all matrix entries in column order.
     *
     * <p>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<T> visitor);

    /**
     * Visit (but don't change) all matrix entries in column order.
     *
     * <p>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<T> visitor);

    /**
     * Visit (and possibly change) some matrix entries in column order.
     *
     * <p>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<T> visitor,
            int startRow,
            int endRow,
            int startColumn,
            int endColumn)
            throws NumberIsTooSmallException, OutOfRangeException;

    /**
     * Visit (but don't change) some matrix entries in column order.
     *
     * <p>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<T> visitor,
            int startRow,
            int endRow,
            int startColumn,
            int endColumn)
            throws NumberIsTooSmallException, OutOfRangeException;

    /**
     * Visit (and possibly change) all matrix entries using the fastest possible order.
     *
     * <p>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<T> visitor);

    /**
     * Visit (but don't change) all matrix entries using the fastest possible order.
     *
     * <p>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<T> visitor);

    /**
     * Visit (and possibly change) some matrix entries using the fastest possible order.
     *
     * <p>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<T> visitor,
            int startRow,
            int endRow,
            int startColumn,
            int endColumn)
            throws NumberIsTooSmallException, OutOfRangeException;

    /**
     * Visit (but don't change) some matrix entries using the fastest possible order.
     *
     * <p>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(
            FieldMatrixPreservingVisitor<T> visitor,
            int startRow,
            int endRow,
            int startColumn,
            int endColumn)
            throws NumberIsTooSmallException, OutOfRangeException;
}