    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.commons.math3.linear;
    019
    020    import org.apache.commons.math3.exception.DimensionMismatchException;
    021    import org.apache.commons.math3.exception.NoDataException;
    022    import org.apache.commons.math3.exception.NotPositiveException;
    023    import org.apache.commons.math3.exception.NotStrictlyPositiveException;
    024    import org.apache.commons.math3.exception.NullArgumentException;
    025    import org.apache.commons.math3.exception.NumberIsTooSmallException;
    026    import org.apache.commons.math3.exception.OutOfRangeException;
    027
    028    /**
    029     * Interface defining a real-valued matrix with basic algebraic operations.
    030     * <p>
    031     * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
    032     * returns the element in the first row, first column of the matrix.</p>
    033     *
    034     * @version $Id: RealMatrix.java 1416643 2012-12-03 19:37:14Z tn $
    035     */
    036    public interface RealMatrix extends AnyMatrix {
    037
    038        /**
    039         * Create a new RealMatrix of the same type as the instance with the
    040         * supplied
    041         * row and column dimensions.
    042         *
    043         * @param rowDimension the number of rows in the new matrix
    044         * @param columnDimension the number of columns in the new matrix
    045         * @return a new matrix of the same type as the instance
    046         * @throws NotStrictlyPositiveException if row or column dimension is not
    047         * positive.
    048         * @since 2.0
    049         */
    050        RealMatrix createMatrix(int rowDimension, int columnDimension)
    051            throws NotStrictlyPositiveException;
    052
    053        /**
    054         * Returns a (deep) copy of this.
    055         *
    056         * @return matrix copy
    057         */
    058        RealMatrix copy();
    059
    060        /**
    061         * Returns the sum of {@code this} and {@code m}.
    062         *
    063         * @param m matrix to be added
    064         * @return {@code this + m}
    065         * @throws MatrixDimensionMismatchException if {@code m} is not the same
    066         * size as {@code this}.
    067         */
    068        RealMatrix add(RealMatrix m)
    069            throws MatrixDimensionMismatchException;
    070
    071        /**
    072         * Returns {@code this} minus {@code m}.
    073         *
    074         * @param m matrix to be subtracted
    075         * @return {@code this - m}
    076         * @throws MatrixDimensionMismatchException if {@code m} is not the same
    077         * size as {@code this}.
    078         */
    079        RealMatrix subtract(RealMatrix m)
    080            throws MatrixDimensionMismatchException;
    081
    082        /**
    083         * Returns the result of adding {@code d} to each entry of {@code this}.
    084         *
    085         * @param d value to be added to each entry
    086         * @return {@code d + this}
    087         */
    088        RealMatrix scalarAdd(double d);
    089
    090        /**
    091         * Returns the result of multiplying each entry of {@code this} by
    092         * {@code d}.
    093         *
    094         * @param d value to multiply all entries by
    095         * @return {@code d * this}
    096         */
    097        RealMatrix scalarMultiply(double d);
    098
    099        /**
    100         * Returns the result of postmultiplying {@code this} by {@code m}.
    101         *
    102         * @param m matrix to postmultiply by
    103         * @return {@code this * m}
    104         * @throws DimensionMismatchException if
    105         * {@code columnDimension(this) != rowDimension(m)}
    106         */
    107        RealMatrix multiply(RealMatrix m)
    108            throws DimensionMismatchException;
    109
    110        /**
    111         * Returns the result of premultiplying {@code this} by {@code m}.
    112         *
    113         * @param m matrix to premultiply by
    114         * @return {@code m * this}
    115         * @throws DimensionMismatchException if
    116         * {@code rowDimension(this) != columnDimension(m)}
    117         */
    118        RealMatrix preMultiply(RealMatrix m)
    119            throws DimensionMismatchException;
    120
    121        /**
    122         * Returns the result of multiplying {@code this} with itself {@code p}
    123         * times. Depending on the underlying storage, instability for high powers
    124         * might occur.
    125         *
    126         * @param p raise {@code this} to power {@code p}
    127         * @return {@code this^p}
    128         * @throws NotPositiveException if {@code p < 0}
    129         * @throws NonSquareMatrixException if the matrix is not square
    130         */
    131        RealMatrix power(final int p)
    132            throws NotPositiveException, NonSquareMatrixException;
    133
    134        /**
    135         * Returns matrix entries as a two-dimensional array.
    136         *
    137         * @return 2-dimensional array of entries
    138         */
    139        double[][] getData();
    140
    141        /**
    142         * Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
    143         * maximum absolute row sum norm</a> of the matrix.
    144         *
    145         * @return norm
    146         */
    147        double getNorm();
    148
    149        /**
    150         * Returns the <a href="http://mathworld.wolfram.com/FrobeniusNorm.html">
    151         * Frobenius norm</a> of the matrix.
    152         *
    153         * @return norm
    154         */
    155        double getFrobeniusNorm();
    156
    157        /**
    158         * Gets a submatrix. Rows and columns are indicated
    159         * counting from 0 to n-1.
    160         *
    161         * @param startRow Initial row index
    162         * @param endRow Final row index (inclusive)
    163         * @param startColumn Initial column index
    164         * @param endColumn Final column index (inclusive)
    165         * @return The subMatrix containing the data of the
    166         * specified rows and columns.
    167         * @throws OutOfRangeException if the indices are not valid.
    168         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    169         * {@code endColumn < startColumn}.
    170         */
    171        RealMatrix getSubMatrix(int startRow, int endRow, int startColumn,
    172                                int endColumn)
    173            throws OutOfRangeException, NumberIsTooSmallException;
    174
    175        /**
    176         * Gets a submatrix. Rows and columns are indicated counting from 0 to n-1.
    177         *
    178         * @param selectedRows Array of row indices.
    179         * @param selectedColumns Array of column indices.
    180         * @return The subMatrix containing the data in the specified rows and
    181         * columns
    182         * @throws NullArgumentException if the row or column selections are
    183         * {@code null}
    184         * @throws NoDataException if the row or column selections are empty (zero
    185         * length).
    186         * @throws OutOfRangeException if the indices are not valid.
    187         */
    188        RealMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
    189            throws NullArgumentException, NoDataException, OutOfRangeException;
    190
    191        /**
    192         * Copy a submatrix. Rows and columns are indicated counting from 0 to n-1.
    193         *
    194         * @param startRow Initial row index
    195         * @param endRow Final row index (inclusive)
    196         * @param startColumn Initial column index
    197         * @param endColumn Final column index (inclusive)
    198         * @param destination The arrays where the submatrix data should be copied
    199         * (if larger than rows/columns counts, only the upper-left part will be
    200         * used)
    201         * @throws OutOfRangeException if the indices are not valid.
    202         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    203         * {@code endColumn < startColumn}.
    204         * @throws MatrixDimensionMismatchException if the destination array is too
    205         * small.
    206         */
    207        void copySubMatrix(int startRow, int endRow, int startColumn,
    208                           int endColumn, double[][] destination)
    209            throws OutOfRangeException, NumberIsTooSmallException,
    210            MatrixDimensionMismatchException;
    211
    212        /**
    213         * Copy a submatrix. Rows and columns are indicated counting from 0 to n-1.
    214         *
    215         * @param selectedRows Array of row indices.
    216         * @param selectedColumns Array of column indices.
    217         * @param destination The arrays where the submatrix data should be copied
    218         * (if larger than rows/columns counts, only the upper-left part will be
    219         * used)
    220         * @throws NullArgumentException if the row or column selections are
    221         * {@code null}
    222         * @throws NoDataException if the row or column selections are empty (zero
    223         * length).
    224         * @throws OutOfRangeException if the indices are not valid.
    225         * @throws MatrixDimensionMismatchException if the destination array is too
    226         * small.
    227         */
    228        void copySubMatrix(int[] selectedRows, int[] selectedColumns,
    229                           double[][] destination)
    230            throws OutOfRangeException, NullArgumentException, NoDataException,
    231            MatrixDimensionMismatchException;
    232
    233       /**
    234        * Replace the submatrix starting at {@code row, column} using data in the
    235        * input {@code subMatrix} array. Indexes are 0-based.
    236        * <p>
    237        * Example:<br>
    238        * Starting with <pre>
    239        * 1  2  3  4
    240        * 5  6  7  8
    241        * 9  0  1  2
    242        * </pre>
    243        * and <code>subMatrix = {{3, 4} {5,6}}</code>, invoking
    244        * {@code setSubMatrix(subMatrix,1,1))} will result in <pre>
    245        * 1  2  3  4
    246        * 5  3  4  8
    247        * 9  5  6  2
    248        * </pre></p>
    249        *
    250        * @param subMatrix  array containing the submatrix replacement data
    251        * @param row  row coordinate of the top, left element to be replaced
    252        * @param column  column coordinate of the top, left element to be replaced
    253        * @throws NoDataException if {@code subMatrix} is empty.
    254        * @throws OutOfRangeException if {@code subMatrix} does not fit into
    255        * this matrix from element in {@code (row, column)}.
    256        * @throws DimensionMismatchException if {@code subMatrix} is not rectangular
    257        * (not all rows have the same length) or empty.
    258        * @throws NullArgumentException if {@code subMatrix} is {@code null}.
    259        * @since 2.0
    260        */
    261        void setSubMatrix(double[][] subMatrix, int row, int column)
    262            throws NoDataException, OutOfRangeException,
    263            DimensionMismatchException, NullArgumentException;
    264
    265       /**
    266        * Get the entries at the given row index as a row matrix.  Row indices start
    267        * at 0.
    268        *
    269        * @param row Row to be fetched.
    270        * @return row Matrix.
    271        * @throws OutOfRangeException if the specified row index is invalid.
    272        */
    273       RealMatrix getRowMatrix(int row) throws OutOfRangeException;
    274
    275        /**
    276         * Sets the specified {@code row} of {@code this} matrix to the entries of
    277         * the specified row {@code matrix}. Row indices start at 0.
    278         *
    279         * @param row Row to be set.
    280         * @param matrix Row matrix to be copied (must have one row and the same
    281         * number of columns as the instance).
    282         * @throws OutOfRangeException if the specified row index is invalid.
    283         * @throws MatrixDimensionMismatchException if the row dimension of the
    284         * {@code matrix} is not {@code 1}, or the column dimensions of {@code this}
    285         * and {@code matrix} do not match.
    286         */
    287        void setRowMatrix(int row, RealMatrix matrix)
    288            throws OutOfRangeException, MatrixDimensionMismatchException;
    289
    290        /**
    291         * Get the entries at the given column index as a column matrix. Column
    292         * indices start at 0.
    293         *
    294         * @param column Column to be fetched.
    295         * @return column Matrix.
    296         * @throws OutOfRangeException if the specified column index is invalid.
    297         */
    298        RealMatrix getColumnMatrix(int column)
    299            throws OutOfRangeException;
    300
    301        /**
    302         * Sets the specified {@code column} of {@code this} matrix to the entries
    303         * of the specified column {@code matrix}. Column indices start at 0.
    304         *
    305         * @param column Column to be set.
    306         * @param matrix Column matrix to be copied (must have one column and the
    307         * same number of rows as the instance).
    308         * @throws OutOfRangeException if the specified column index is invalid.
    309         * @throws MatrixDimensionMismatchException if the column dimension of the
    310         * {@code matrix} is not {@code 1}, or the row dimensions of {@code this}
    311         * and {@code matrix} do not match.
    312         */
    313        void setColumnMatrix(int column, RealMatrix matrix)
    314            throws OutOfRangeException, MatrixDimensionMismatchException;
    315
    316        /**
    317         * Returns the entries in row number {@code row} as a vector. Row indices
    318         * start at 0.
    319         *
    320         * @param row Row to be fetched.
    321         * @return a row vector.
    322         * @throws OutOfRangeException if the specified row index is invalid.
    323         */
    324        RealVector getRowVector(int row)
    325            throws OutOfRangeException;
    326
    327        /**
    328         * Sets the specified {@code row} of {@code this} matrix to the entries of
    329         * the specified {@code vector}. Row indices start at 0.
    330         *
    331         * @param row Row to be set.
    332         * @param vector row vector to be copied (must have the same number of
    333         * column as the instance).
    334         * @throws OutOfRangeException if the specified row index is invalid.
    335         * @throws MatrixDimensionMismatchException if the {@code vector} dimension
    336         * does not match the column dimension of {@code this} matrix.
    337         */
    338        void setRowVector(int row, RealVector vector)
    339            throws OutOfRangeException, MatrixDimensionMismatchException;
    340
    341        /**
    342         * Get the entries at the given column index as a vector. Column indices
    343         * start at 0.
    344         *
    345         * @param column Column to be fetched.
    346         * @return a column vector.
    347         * @throws OutOfRangeException if the specified column index is invalid
    348         */
    349        RealVector getColumnVector(int column)
    350            throws OutOfRangeException;
    351
    352        /**
    353         * Sets the specified {@code column} of {@code this} matrix to the entries
    354         * of the specified {@code vector}. Column indices start at 0.
    355         *
    356         * @param column Column to be set.
    357         * @param vector column vector to be copied (must have the same number of
    358         * rows as the instance).
    359         * @throws OutOfRangeException if the specified column index is invalid.
    360         * @throws MatrixDimensionMismatchException if the {@code vector} dimension
    361         * does not match the row dimension of {@code this} matrix.
    362         */
    363        void setColumnVector(int column, RealVector vector)
    364            throws OutOfRangeException, MatrixDimensionMismatchException;
    365
    366        /**
    367         * Get the entries at the given row index. Row indices start at 0.
    368         *
    369         * @param row Row to be fetched.
    370         * @return the array of entries in the row.
    371         * @throws OutOfRangeException if the specified row index is not valid.
    372         */
    373        double[] getRow(int row) throws OutOfRangeException;
    374
    375        /**
    376         * Sets the specified {@code row} of {@code this} matrix to the entries
    377         * of the specified {@code array}. Row indices start at 0.
    378         *
    379         * @param row Row to be set.
    380         * @param array Row matrix to be copied (must have the same number of
    381         * columns as the instance)
    382         * @throws OutOfRangeException if the specified row index is invalid.
    383         * @throws MatrixDimensionMismatchException if the {@code array} length does
    384         * not match the column dimension of {@code this} matrix.
    385         */
    386        void setRow(int row, double[] array)
    387            throws OutOfRangeException, MatrixDimensionMismatchException;
    388
    389        /**
    390         * Get the entries at the given column index as an array. Column indices
    391         * start at 0.
    392         *
    393         * @param column Column to be fetched.
    394         * @return the array of entries in the column.
    395         * @throws OutOfRangeException if the specified column index is not valid.
    396         */
    397        double[] getColumn(int column) throws OutOfRangeException;
    398
    399        /**
    400         * Sets the specified {@code column} of {@code this} matrix to the entries
    401         * of the specified {@code array}. Column indices start at 0.
    402         *
    403         * @param column Column to be set.
    404         * @param array Column array to be copied (must have the same number of
    405         * rows as the instance).
    406         * @throws OutOfRangeException if the specified column index is invalid.
    407         * @throws MatrixDimensionMismatchException if the {@code array} length does
    408         * not match the row dimension of {@code this} matrix.
    409         */
    410        void setColumn(int column, double[] array)
    411            throws OutOfRangeException, MatrixDimensionMismatchException;
    412
    413        /**
    414         * Get the entry in the specified row and column. Row and column indices
    415         * start at 0.
    416         *
    417         * @param row Row index of entry to be fetched.
    418         * @param column Column index of entry to be fetched.
    419         * @return the matrix entry at {@code (row, column)}.
    420         * @throws OutOfRangeException if the row or column index is not valid.
    421         */
    422        double getEntry(int row, int column) throws OutOfRangeException;
    423
    424        /**
    425         * Set the entry in the specified row and column. Row and column indices
    426         * start at 0.
    427         *
    428         * @param row Row index of entry to be set.
    429         * @param column Column index of entry to be set.
    430         * @param value the new value of the entry.
    431         * @throws OutOfRangeException if the row or column index is not valid
    432         * @since 2.0
    433         */
    434        void setEntry(int row, int column, double value) throws OutOfRangeException;
    435
    436        /**
    437         * Adds (in place) the specified value to the specified entry of
    438         * {@code this} matrix. Row and column indices start at 0.
    439         *
    440         * @param row Row index of the entry to be modified.
    441         * @param column Column index of the entry to be modified.
    442         * @param increment value to add to the matrix entry.
    443         * @throws OutOfRangeException if the row or column index is not valid.
    444         * @since 2.0
    445         */
    446        void addToEntry(int row, int column, double increment) throws OutOfRangeException;
    447
    448        /**
    449         * Multiplies (in place) the specified entry of {@code this} matrix by the
    450         * specified value. Row and column indices start at 0.
    451         *
    452         * @param row Row index of the entry to be modified.
    453         * @param column Column index of the entry to be modified.
    454         * @param factor Multiplication factor for the matrix entry.
    455         * @throws OutOfRangeException if the row or column index is not valid.
    456         * @since 2.0
    457         */
    458        void multiplyEntry(int row, int column, double factor) throws OutOfRangeException;
    459
    460        /**
    461         * Returns the transpose of this matrix.
    462         *
    463         * @return transpose matrix
    464         */
    465        RealMatrix transpose();
    466
    467        /**
    468         * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
    469         * trace</a> of the matrix (the sum of the elements on the main diagonal).
    470         *
    471         * @return the trace.
    472         * @throws NonSquareMatrixException if the matrix is not square.
    473         */
    474        double getTrace() throws NonSquareMatrixException;
    475
    476        /**
    477         * Returns the result of multiplying this by the vector {@code v}.
    478         *
    479         * @param v the vector to operate on
    480         * @return {@code this * v}
    481         * @throws DimensionMismatchException if the length of {@code v} does not
    482         * match the column dimension of {@code this}.
    483         */
    484        double[] operate(double[] v) throws DimensionMismatchException;
    485
    486        /**
    487         * Returns the result of multiplying this by the vector {@code v}.
    488         *
    489         * @param v the vector to operate on
    490         * @return {@code this * v}
    491         * @throws DimensionMismatchException if the dimension of {@code v} does not
    492         * match the column dimension of {@code this}.
    493         */
    494        RealVector operate(RealVector v) throws DimensionMismatchException;
    495
    496        /**
    497         * Returns the (row) vector result of premultiplying this by the vector {@code v}.
    498         *
    499         * @param v the row vector to premultiply by
    500         * @return {@code v * this}
    501         * @throws DimensionMismatchException if the length of {@code v} does not
    502         * match the row dimension of {@code this}.
    503         */
    504        double[] preMultiply(double[] v) throws DimensionMismatchException;
    505
    506        /**
    507         * Returns the (row) vector result of premultiplying this by the vector {@code v}.
    508         *
    509         * @param v the row vector to premultiply by
    510         * @return {@code v * this}
    511         * @throws DimensionMismatchException if the dimension of {@code v} does not
    512         * match the row dimension of {@code this}.
    513         */
    514        RealVector preMultiply(RealVector v) throws DimensionMismatchException;
    515
    516        /**
    517         * Visit (and possibly change) all matrix entries in row order.
    518         * <p>Row order starts at upper left and iterating through all elements
    519         * of a row from left to right before going to the leftmost element
    520         * of the next row.</p>
    521         * @param visitor visitor used to process all matrix entries
    522         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    523         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    524         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    525         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    526         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    527         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    528         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    529         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    530         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    531         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    532         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    533         * @return the value returned by {@link RealMatrixChangingVisitor#end()} at the end
    534         * of the walk
    535         */
    536        double walkInRowOrder(RealMatrixChangingVisitor visitor);
    537
    538        /**
    539         * Visit (but don't change) all matrix entries in row order.
    540         * <p>Row order starts at upper left and iterating through all elements
    541         * of a row from left to right before going to the leftmost element
    542         * of the next row.</p>
    543         * @param visitor visitor used to process all matrix entries
    544         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    545         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    546         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    547         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    548         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    549         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    550         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    551         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    552         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    553         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    554         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    555         * @return the value returned by {@link RealMatrixPreservingVisitor#end()} at the end
    556         * of the walk
    557         */
    558        double walkInRowOrder(RealMatrixPreservingVisitor visitor);
    559
    560        /**
    561         * Visit (and possibly change) some matrix entries in row order.
    562         * <p>Row order starts at upper left and iterating through all elements
    563         * of a row from left to right before going to the leftmost element
    564         * of the next row.</p>
    565         * @param visitor visitor used to process all matrix entries
    566         * @param startRow Initial row index
    567         * @param endRow Final row index (inclusive)
    568         * @param startColumn Initial column index
    569         * @param endColumn Final column index
    570         * @throws OutOfRangeException if the indices are not valid.
    571         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    572         * {@code endColumn < startColumn}.
    573         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    574         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    575         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    576         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    577         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    578         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    579         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    580         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    581         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    582         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    583         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    584         * @return the value returned by {@link RealMatrixChangingVisitor#end()} at the end
    585         * of the walk
    586         */
    587        double walkInRowOrder(RealMatrixChangingVisitor visitor, int startRow,
    588            int endRow, int startColumn, int endColumn)
    589            throws OutOfRangeException, NumberIsTooSmallException;
    590
    591        /**
    592         * Visit (but don't change) some matrix entries in row order.
    593         * <p>Row order starts at upper left and iterating through all elements
    594         * of a row from left to right before going to the leftmost element
    595         * of the next row.</p>
    596         * @param visitor visitor used to process all matrix entries
    597         * @param startRow Initial row index
    598         * @param endRow Final row index (inclusive)
    599         * @param startColumn Initial column index
    600         * @param endColumn Final column index
    601         * @throws OutOfRangeException if the indices are not valid.
    602         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    603         * {@code endColumn < startColumn}.
    604         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    605         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    606         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    607         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    608         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    609         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    610         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    611         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    612         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    613         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    614         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    615         * @return the value returned by {@link RealMatrixPreservingVisitor#end()} at the end
    616         * of the walk
    617         */
    618        double walkInRowOrder(RealMatrixPreservingVisitor visitor, int startRow,
    619            int endRow, int startColumn, int endColumn)
    620            throws OutOfRangeException, NumberIsTooSmallException;
    621
    622        /**
    623         * Visit (and possibly change) all matrix entries in column order.
    624         * <p>Column order starts at upper left and iterating through all elements
    625         * of a column from top to bottom before going to the topmost element
    626         * of the next column.</p>
    627         * @param visitor visitor used to process all matrix entries
    628         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    629         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    630         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    631         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    632         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    633         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    634         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    635         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    636         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    637         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    638         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    639         * @return the value returned by {@link RealMatrixChangingVisitor#end()} at the end
    640         * of the walk
    641         */
    642        double walkInColumnOrder(RealMatrixChangingVisitor visitor);
    643
    644        /**
    645         * Visit (but don't change) all matrix entries in column order.
    646         * <p>Column order starts at upper left and iterating through all elements
    647         * of a column from top to bottom before going to the topmost element
    648         * of the next column.</p>
    649         * @param visitor visitor used to process all matrix entries
    650         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    651         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    652         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    653         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    654         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    655         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    656         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    657         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    658         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    659         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    660         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    661         * @return the value returned by {@link RealMatrixPreservingVisitor#end()} at the end
    662         * of the walk
    663         */
    664        double walkInColumnOrder(RealMatrixPreservingVisitor visitor);
    665
    666        /**
    667         * Visit (and possibly change) some matrix entries in column order.
    668         * <p>Column order starts at upper left and iterating through all elements
    669         * of a column from top to bottom before going to the topmost element
    670         * of the next column.</p>
    671         * @param visitor visitor used to process all matrix entries
    672         * @param startRow Initial row index
    673         * @param endRow Final row index (inclusive)
    674         * @param startColumn Initial column index
    675         * @param endColumn Final column index
    676         * @throws OutOfRangeException if the indices are not valid.
    677         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    678         * {@code endColumn < startColumn}.
    679         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    680         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    681         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    682         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    683         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    684         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    685         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    686         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    687         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    688         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    689         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    690         * @return the value returned by {@link RealMatrixChangingVisitor#end()} at the end
    691         * of the walk
    692         */
    693        double walkInColumnOrder(RealMatrixChangingVisitor visitor, int startRow,
    694            int endRow, int startColumn, int endColumn)
    695            throws OutOfRangeException, NumberIsTooSmallException;
    696
    697        /**
    698         * Visit (but don't change) some matrix entries in column order.
    699         * <p>Column order starts at upper left and iterating through all elements
    700         * of a column from top to bottom before going to the topmost element
    701         * of the next column.</p>
    702         * @param visitor visitor used to process all matrix entries
    703         * @param startRow Initial row index
    704         * @param endRow Final row index (inclusive)
    705         * @param startColumn Initial column index
    706         * @param endColumn Final column index
    707         * @throws OutOfRangeException if the indices are not valid.
    708         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    709         * {@code endColumn < startColumn}.
    710         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    711         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    712         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    713         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    714         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    715         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    716         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    717         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    718         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    719         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    720         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    721         * @return the value returned by {@link RealMatrixPreservingVisitor#end()} at the end
    722         * of the walk
    723         */
    724        double walkInColumnOrder(RealMatrixPreservingVisitor visitor, int startRow,
    725            int endRow, int startColumn, int endColumn)
    726            throws OutOfRangeException, NumberIsTooSmallException;
    727
    728        /**
    729         * Visit (and possibly change) all matrix entries using the fastest possible order.
    730         * <p>The fastest walking order depends on the exact matrix class. It may be
    731         * different from traditional row or column orders.</p>
    732         * @param visitor visitor used to process all matrix entries
    733         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    734         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    735         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    736         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    737         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    738         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    739         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    740         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    741         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    742         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    743         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    744         * @return the value returned by {@link RealMatrixChangingVisitor#end()} at the end
    745         * of the walk
    746         */
    747        double walkInOptimizedOrder(RealMatrixChangingVisitor visitor);
    748
    749        /**
    750         * Visit (but don't change) all matrix entries using the fastest possible order.
    751         * <p>The fastest walking order depends on the exact matrix class. It may be
    752         * different from traditional row or column orders.</p>
    753         * @param visitor visitor used to process all matrix entries
    754         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    755         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    756         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    757         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    758         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    759         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    760         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    761         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    762         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    763         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    764         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    765         * @return the value returned by {@link RealMatrixPreservingVisitor#end()} at the end
    766         * of the walk
    767         */
    768        double walkInOptimizedOrder(RealMatrixPreservingVisitor visitor);
    769
    770        /**
    771         * Visit (and possibly change) some matrix entries using the fastest possible order.
    772         * <p>The fastest walking order depends on the exact matrix class. It may be
    773         * different from traditional row or column orders.</p>
    774         * @param visitor visitor used to process all matrix entries
    775         * @param startRow Initial row index
    776         * @param endRow Final row index (inclusive)
    777         * @param startColumn Initial column index
    778         * @param endColumn Final column index (inclusive)
    779         * @throws OutOfRangeException if the indices are not valid.
    780         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    781         * {@code endColumn < startColumn}.
    782         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    783         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    784         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    785         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    786         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    787         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    788         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    789         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    790         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    791         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    792         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor, int, int, int, int)
    793         * @return the value returned by {@link RealMatrixChangingVisitor#end()} at the end
    794         * of the walk
    795         */
    796        double walkInOptimizedOrder(RealMatrixChangingVisitor visitor,
    797            int startRow, int endRow, int startColumn, int endColumn)
    798            throws OutOfRangeException, NumberIsTooSmallException;
    799
    800        /**
    801         * Visit (but don't change) some matrix entries using the fastest possible order.
    802         * <p>The fastest walking order depends on the exact matrix class. It may be
    803         * different from traditional row or column orders.</p>
    804         * @param visitor visitor used to process all matrix entries
    805         * @param startRow Initial row index
    806         * @param endRow Final row index (inclusive)
    807         * @param startColumn Initial column index
    808         * @param endColumn Final column index (inclusive)
    809         * @throws OutOfRangeException if the indices are not valid.
    810         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    811         * {@code endColumn < startColumn}.
    812         * @see #walkInRowOrder(RealMatrixChangingVisitor)
    813         * @see #walkInRowOrder(RealMatrixPreservingVisitor)
    814         * @see #walkInRowOrder(RealMatrixChangingVisitor, int, int, int, int)
    815         * @see #walkInRowOrder(RealMatrixPreservingVisitor, int, int, int, int)
    816         * @see #walkInColumnOrder(RealMatrixChangingVisitor)
    817         * @see #walkInColumnOrder(RealMatrixPreservingVisitor)
    818         * @see #walkInColumnOrder(RealMatrixChangingVisitor, int, int, int, int)
    819         * @see #walkInColumnOrder(RealMatrixPreservingVisitor, int, int, int, int)
    820         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor)
    821         * @see #walkInOptimizedOrder(RealMatrixPreservingVisitor)
    822         * @see #walkInOptimizedOrder(RealMatrixChangingVisitor, int, int, int, int)
    823         * @return the value returned by {@link RealMatrixPreservingVisitor#end()} at the end
    824         * of the walk
    825         */
    826        double walkInOptimizedOrder(RealMatrixPreservingVisitor visitor,
    827            int startRow, int endRow, int startColumn, int endColumn)
    828            throws OutOfRangeException, NumberIsTooSmallException;
    829    }