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