View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.linear;
19  
20  
21  /**
22   * Interface defining a real-valued matrix with basic algebraic operations.
23   * <p>
24   * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
25   * returns the element in the first row, first column of the matrix.</p>
26   * 
27   * @version $Revision: 799906 $ $Date: 2009-08-01 15:01:59 -0400 (Sat, 01 Aug 2009) $
28   */
29  public interface RealMatrix extends AnyMatrix {
30  
31      /**
32       * Create a new RealMatrix of the same type as the instance with the supplied
33       * row and column dimensions.
34       *
35       * @param rowDimension  the number of rows in the new matrix
36       * @param columnDimension  the number of columns in the new matrix
37       * @return a new matrix of the same type as the instance
38       * @throws IllegalArgumentException if row or column dimension is not positive
39       * @since 2.0
40       */
41      RealMatrix createMatrix(final int rowDimension, final int columnDimension);
42  
43      /**
44       * Returns a (deep) copy of this.
45       *
46       * @return matrix copy
47       */
48      RealMatrix copy();
49  
50      /**
51       * Compute the sum of this and m.
52       *
53       * @param m    matrix to be added
54       * @return     this + m
55       * @throws  IllegalArgumentException if m is not the same size as this
56       */
57      RealMatrix add(RealMatrix m) throws IllegalArgumentException;
58  
59      /**
60       * Compute this minus m.
61       *
62       * @param m    matrix to be subtracted
63       * @return     this - m
64       * @throws  IllegalArgumentException if m is not the same size as this
65       */
66      RealMatrix subtract(RealMatrix m) throws IllegalArgumentException;
67  
68       /**
69       * Returns the result of adding d to each entry of this.
70       *
71       * @param d    value to be added to each entry
72       * @return     d + this
73       */
74      RealMatrix scalarAdd(double d);
75  
76      /**
77       * Returns the result multiplying each entry of this by d.
78       *
79       * @param d    value to multiply all entries by
80       * @return     d * this
81       */
82      RealMatrix scalarMultiply(double d);
83  
84      /**
85       * Returns the result of postmultiplying this by m.
86       *
87       * @param m    matrix to postmultiply by
88       * @return     this * m
89       * @throws     IllegalArgumentException
90       *             if columnDimension(this) != rowDimension(m)
91       */
92      RealMatrix multiply(RealMatrix m) throws IllegalArgumentException;
93  
94      /**
95       * Returns the result premultiplying this by <code>m</code>.
96       * @param m    matrix to premultiply by
97       * @return     m * this
98       * @throws     IllegalArgumentException
99       *             if rowDimension(this) != columnDimension(m)
100      */
101     public 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 }