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