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