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