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