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