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 }