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