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