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