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