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.linear.MatrixVisitorException; 21 22 23 /** 24 * Interface defining a real-valued matrix with basic algebraic operations. 25 * <p> 26 * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code> 27 * returns the element in the first row, first column of the matrix.</p> 28 * 29 * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 févr. 2011) $ 30 */ 31 public interface RealMatrix extends AnyMatrix { 32 33 /** 34 * Create a new RealMatrix of the same type as the instance with the supplied 35 * row and column dimensions. 36 * 37 * @param rowDimension the number of rows in the new matrix 38 * @param columnDimension the number of columns in the new matrix 39 * @return a new matrix of the same type as the instance 40 * @throws IllegalArgumentException if row or column dimension is not positive 41 * @since 2.0 42 */ createMatrix(final int rowDimension, final int columnDimension)43 RealMatrix createMatrix(final int rowDimension, final int columnDimension); 44 45 /** 46 * Returns a (deep) copy of this. 47 * 48 * @return matrix copy 49 */ copy()50 RealMatrix copy(); 51 52 /** 53 * Compute the sum of this and m. 54 * 55 * @param m matrix to be added 56 * @return this + m 57 * @throws IllegalArgumentException if m is not the same size as this 58 */ add(RealMatrix m)59 RealMatrix add(RealMatrix m) throws IllegalArgumentException; 60 61 /** 62 * Compute this minus m. 63 * 64 * @param m matrix to be subtracted 65 * @return this - m 66 * @throws IllegalArgumentException if m is not the same size as this 67 */ subtract(RealMatrix m)68 RealMatrix subtract(RealMatrix m) throws IllegalArgumentException; 69 70 /** 71 * Returns the result of adding d to each entry of this. 72 * 73 * @param d value to be added to each entry 74 * @return d + this 75 */ scalarAdd(double d)76 RealMatrix scalarAdd(double d); 77 78 /** 79 * Returns the result multiplying each entry of this by d. 80 * 81 * @param d value to multiply all entries by 82 * @return d * this 83 */ scalarMultiply(double d)84 RealMatrix scalarMultiply(double d); 85 86 /** 87 * Returns the result of postmultiplying this by m. 88 * 89 * @param m matrix to postmultiply by 90 * @return this * m 91 * @throws IllegalArgumentException 92 * if columnDimension(this) != rowDimension(m) 93 */ multiply(RealMatrix m)94 RealMatrix multiply(RealMatrix m) throws IllegalArgumentException; 95 96 /** 97 * Returns the result premultiplying this by <code>m</code>. 98 * @param m matrix to premultiply by 99 * @return m * this 100 * @throws IllegalArgumentException 101 * if rowDimension(this) != columnDimension(m) 102 */ preMultiply(RealMatrix m)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 */ getData()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 */ getNorm()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 */ getFrobeniusNorm()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 */ getSubMatrix(int startRow, int endRow, int startColumn, int endColumn)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 */ getSubMatrix(int[] selectedRows, int[] selectedColumns)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 */ copySubMatrix(int startRow, int endRow, int startColumn, int endColumn, double[][] destination)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 */ copySubMatrix(int[] selectedRows, int[] selectedColumns, double[][] destination)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 */ setSubMatrix(double[][] subMatrix, int row, int column)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 */ getRowMatrix(int row)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 */ setRowMatrix(int row, RealMatrix matrix)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 */ getColumnMatrix(int column)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 */ setColumnMatrix(int column, RealMatrix matrix)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 */ getRowVector(int row)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 */ setRowVector(int row, RealVector vector)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 */ getColumnVector(int column)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 */ setColumnVector(int column, RealVector vector)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 */ getRow(int row)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 */ setRow(int row, double[] array)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 */ getColumn(int column)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 */ setColumn(int column, double[] array)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 */ getEntry(int row, int column)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 */ setEntry(int row, int column, double value)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 */ addToEntry(int row, int column, double increment)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 */ multiplyEntry(int row, int column, double factor)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 */ transpose()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 inverse()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 getDeterminant()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 isSingular()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 */ getTrace()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 */ operate(double[] v)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 */ operate(RealVector v)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 */ preMultiply(double[] v)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 */ preMultiply(RealVector v)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 */ walkInRowOrder(RealMatrixChangingVisitor visitor)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 */ walkInRowOrder(RealMatrixPreservingVisitor visitor)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 */ walkInRowOrder(RealMatrixChangingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)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 */ walkInRowOrder(RealMatrixPreservingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)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 */ walkInColumnOrder(RealMatrixChangingVisitor visitor)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 */ walkInColumnOrder(RealMatrixPreservingVisitor visitor)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 */ walkInColumnOrder(RealMatrixChangingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)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 */ walkInColumnOrder(RealMatrixPreservingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)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 */ walkInOptimizedOrder(RealMatrixChangingVisitor visitor)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 */ walkInOptimizedOrder(RealMatrixPreservingVisitor visitor)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 */ walkInOptimizedOrder(RealMatrixChangingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)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 */ walkInOptimizedOrder(RealMatrixPreservingVisitor visitor, int startRow, int endRow, int startColumn, int endColumn)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 solve(double[] b)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 solve(RealMatrix b)869 RealMatrix solve(RealMatrix b) throws IllegalArgumentException, InvalidMatrixException; 870 871 } 872