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 package org.apache.commons.math.linear; 18 19 import java.util.Iterator; 20 21 import org.apache.commons.math.FunctionEvaluationException; 22 import org.apache.commons.math.analysis.UnivariateRealFunction; 23 24 25 /** 26 * Interface defining a real-valued vector with basic algebraic operations. 27 * <p> 28 * vector element indexing is 0-based -- e.g., <code>getEntry(0)</code> 29 * returns the first element of the vector. 30 * </p> 31 * <p> 32 * The various <code>mapXxx</code> and <code>mapXxxToSelf</code> methods operate 33 * on vectors element-wise, i.e. they perform the same operation (adding a scalar, 34 * applying a function ...) on each element in turn. The <code>mapXxx</code> 35 * versions create a new vector to hold the result and do not change the instance. 36 * The <code>mapXxxToSelf</code> versions use the instance itself to store the 37 * results, so the instance is changed by these methods. In both cases, the result 38 * vector is returned by the methods, this allows to use the <i>fluent API</i> 39 * style, like this: 40 * </p> 41 * <pre> 42 * RealVector result = v.mapAddToSelf(3.0).mapTanToSelf().mapSquareToSelf(); 43 * </pre> 44 * <p> 45 * Remark on the deprecated {@code mapXxx} and {@code mapXxxToSelf} methods: In 46 * Commons-Math v3.0, the same functionality will be achieved by directly using the 47 * {@link #map(UnivariateRealFunction)} and {@link #mapToSelf(UnivariateRealFunction)} 48 * together with new function objects (not available in v2.2). 49 * </p> 50 * 51 * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 fvr. 2011) $ 52 * @since 2.0 53 */ 54 public interface RealVector { 55 /** 56 * Acts as if it is implemented as: 57 * <pre> 58 * Entry e = null; 59 * for(Iterator<Entry> it = iterator(); it.hasNext(); e = it.next()) { 60 * e.setValue(function.value(e.getValue())); 61 * } 62 * </pre> 63 * 64 * @param function Function to apply to each entry. 65 * @return this vector. 66 * @throws FunctionEvaluationException if the function throws it. 67 */ 68 RealVector mapToSelf(UnivariateRealFunction function) throws FunctionEvaluationException; 69 70 /** 71 * Acts as if implemented as: 72 * <pre> 73 * return copy().map(function); 74 * </pre> 75 * 76 * @param function Function to apply to each entry. 77 * @return a new vector. 78 * @throws FunctionEvaluationException if the function throws it. 79 */ 80 RealVector map(UnivariateRealFunction function) throws FunctionEvaluationException; 81 82 /** Class representing a modifiable entry in the vector. */ 83 public abstract class Entry { 84 /** Index of the entry. */ 85 private int index; 86 87 /** 88 * Get the value of the entry. 89 * 90 * @return the value of the entry. 91 */ 92 public abstract double getValue(); 93 /** 94 * Set the value of the entry. 95 * 96 * @param value New value for the entry. 97 */ 98 public abstract void setValue(double value); 99 /** 100 * Get the index of the entry. 101 * 102 * @return the index of the entry. 103 */ 104 public int getIndex() { 105 return index; 106 } 107 /** 108 * Set the index of the entry. 109 * 110 * @param index New index for the entry. 111 */ 112 public void setIndex(int index) { 113 this.index = index; 114 } 115 } 116 117 /** 118 * Generic dense iterator. 119 * It iterates in increasing order of the vector index. 120 * 121 * @return a dense iterator 122 */ 123 Iterator<Entry> iterator(); 124 125 /** 126 * Specialized implementations may choose to not iterate over all 127 * dimensions, either because those values are unset, or are equal 128 * to defaultValue(), or are small enough to be ignored for the 129 * purposes of iteration. 130 * No guarantees are made about order of iteration. 131 * In dense implementations, this method will often delegate to 132 * {@link #iterator()}. 133 * 134 * @return a sparse iterator 135 */ 136 Iterator<Entry> sparseIterator(); 137 138 /** 139 * Returns a (deep) copy of this vector. 140 * 141 * @return a vector copy. 142 */ 143 RealVector copy(); 144 145 /** 146 * Compute the sum of this vector and {@code v}. 147 * 148 * @param v Vector to be added. 149 * @return {@code this} + {@code v}. 150 * @throws org.apache.commons.math.exception.DimensionMismatchException 151 * if {@code v} is not the same size as this vector. 152 */ 153 RealVector add(RealVector v); 154 155 /** 156 * Compute the sum of this vector and {@code v}. 157 * 158 * @param v Vector to be added. 159 * @return {@code this} + {@code v}. 160 * @throws org.apache.commons.math.exception.DimensionMismatchException 161 * if {@code v} is not the same size as this vector. 162 */ 163 RealVector add(double[] v); 164 165 166 /** 167 * Subtract {@code v} from this vector. 168 * 169 * @param v Vector to be subtracted. 170 * @return {@code this} - {@code v}. 171 * @throws org.apache.commons.math.exception.DimensionMismatchException 172 * if {@code v} is not the same size as this vector. 173 */ 174 RealVector subtract(RealVector v); 175 176 /** 177 * Subtract {@code v} from this vector. 178 * 179 * @param v Vector to be subtracted. 180 * @return {@code this} - {@code v}. 181 * @throws org.apache.commons.math.exception.DimensionMismatchException 182 * if {@code v} is not the same size as this vector. 183 */ 184 RealVector subtract(double[] v); 185 186 /** 187 * Add a value to each entry. 188 * 189 * @param d Value to be added to each entry. 190 * @return {@code this} + {@code d}. 191 */ 192 RealVector mapAdd(double d); 193 194 /** 195 * Add a value to each entry. 196 * The instance is changed in-place. 197 * 198 * @param d Value to be added to each entry. 199 * @return {@code this}. 200 */ 201 RealVector mapAddToSelf(double d); 202 203 /** 204 * Subtract a value from each entry. 205 * 206 * @param d Value to be subtracted. 207 * @return {@code this} - {@code d}. 208 */ 209 RealVector mapSubtract(double d); 210 211 /** 212 * Subtract a value from each entry. 213 * The instance is changed in-place. 214 * 215 * @param d Value to be subtracted. 216 * @return {@code this}. 217 */ 218 RealVector mapSubtractToSelf(double d); 219 220 /** 221 * Multiply each entry. 222 * 223 * @param d Multiplication factor. 224 * @return {@code this} * {@code d}. 225 */ 226 RealVector mapMultiply(double d); 227 228 /** 229 * Multiply each entry. 230 * The instance is changed in-place. 231 * 232 * @param d Multiplication factor. 233 * @return {@code this}. 234 */ 235 RealVector mapMultiplyToSelf(double d); 236 237 /** 238 * Divide each entry. 239 * 240 * @param d Value to divide by. 241 * @return {@code this} / {@code d}. 242 */ 243 RealVector mapDivide(double d); 244 245 /** 246 * Divide each entry. 247 * The instance is changed in-place. 248 * 249 * @param d Value to divide by. 250 * @return {@code this}. 251 */ 252 RealVector mapDivideToSelf(double d); 253 254 /** 255 * Map a power operation to each entry. 256 * 257 * @param d Operator value. 258 * @return a mapped copy of the vector. 259 * @deprecated in 2.2 (to be removed in 3.0). 260 */ 261 @Deprecated 262 RealVector mapPow(double d); 263 264 /** 265 * Map a power operation to each entry. 266 * The instance is changed in-place. 267 * 268 * @param d Operator value. 269 * @return the mapped vector. 270 * @deprecated in 2.2 (to be removed in 3.0). 271 */ 272 @Deprecated 273 RealVector mapPowToSelf(double d); 274 275 /** 276 * Map the {@link Math#exp(double)} function to each entry. 277 * 278 * @return a mapped copy of the vector. 279 * @deprecated in 2.2 (to be removed in 3.0). 280 */ 281 @Deprecated 282 RealVector mapExp(); 283 284 /** 285 * Map {@link Math#exp(double)} operation to each entry. 286 * The instance is changed in-place. 287 * 288 * @return the mapped vector. 289 * @deprecated in 2.2 (to be removed in 3.0). 290 */ 291 @Deprecated 292 RealVector mapExpToSelf(); 293 294 /** 295 * Map the {@link Math#expm1(double)} function to each entry. 296 * @return a vector containing the result of applying the function to each entry 297 * @deprecated in 2.2 (to be removed in 3.0). 298 */ 299 @Deprecated 300 RealVector mapExpm1(); 301 302 /** 303 * Map the {@link Math#expm1(double)} function to each entry. 304 * <p>The instance <strong>is</strong> changed by this method.</p> 305 * @return for convenience, return this 306 * @deprecated in 2.2 (to be removed in 3.0). 307 */ 308 @Deprecated 309 RealVector mapExpm1ToSelf(); 310 311 /** 312 * Map the {@link Math#log(double)} function to each entry. 313 * @return a vector containing the result of applying the function to each entry 314 * @deprecated in 2.2 (to be removed in 3.0). 315 */ 316 @Deprecated 317 RealVector mapLog(); 318 319 /** 320 * Map the {@link Math#log(double)} function to each entry. 321 * <p>The instance <strong>is</strong> changed by this method.</p> 322 * @return for convenience, return this 323 * @deprecated in 2.2 (to be removed in 3.0). 324 */ 325 @Deprecated 326 RealVector mapLogToSelf(); 327 328 /** 329 * Map the {@link Math#log10(double)} function to each entry. 330 * @return a vector containing the result of applying the function to each entry 331 * @deprecated in 2.2 (to be removed in 3.0). 332 */ 333 @Deprecated 334 RealVector mapLog10(); 335 336 /** 337 * Map the {@link Math#log10(double)} function to each entry. 338 * <p>The instance <strong>is</strong> changed by this method.</p> 339 * @return for convenience, return this 340 * @deprecated in 2.2 (to be removed in 3.0). 341 */ 342 @Deprecated 343 RealVector mapLog10ToSelf(); 344 345 /** 346 * Map the {@link Math#log1p(double)} function to each entry. 347 * @return a vector containing the result of applying the function to each entry 348 * @deprecated in 2.2 (to be removed in 3.0). 349 */ 350 @Deprecated 351 RealVector mapLog1p(); 352 353 /** 354 * Map the {@link Math#log1p(double)} function to each entry. 355 * <p>The instance <strong>is</strong> changed by this method.</p> 356 * @return for convenience, return this 357 * @deprecated in 2.2 (to be removed in 3.0). 358 */ 359 @Deprecated 360 RealVector mapLog1pToSelf(); 361 362 /** 363 * Map the {@link Math#cosh(double)} function to each entry. 364 * @return a vector containing the result of applying the function to each entry 365 * @deprecated in 2.2 (to be removed in 3.0). 366 */ 367 @Deprecated 368 RealVector mapCosh(); 369 370 /** 371 * Map the {@link Math#cosh(double)} function to each entry. 372 * <p>The instance <strong>is</strong> changed by this method.</p> 373 * @return for convenience, return this 374 * @deprecated in 2.2 (to be removed in 3.0). 375 */ 376 @Deprecated 377 RealVector mapCoshToSelf(); 378 379 /** 380 * Map the {@link Math#sinh(double)} function to each entry. 381 * @return a vector containing the result of applying the function to each entry 382 * @deprecated in 2.2 (to be removed in 3.0). 383 */ 384 @Deprecated 385 RealVector mapSinh(); 386 387 /** 388 * Map the {@link Math#sinh(double)} function to each entry. 389 * <p>The instance <strong>is</strong> changed by this method.</p> 390 * @return for convenience, return this 391 * @deprecated in 2.2 (to be removed in 3.0). 392 */ 393 @Deprecated 394 RealVector mapSinhToSelf(); 395 396 /** 397 * Map the {@link Math#tanh(double)} function to each entry. 398 * @return a vector containing the result of applying the function to each entry 399 * @deprecated in 2.2 (to be removed in 3.0). 400 */ 401 @Deprecated 402 RealVector mapTanh(); 403 404 /** 405 * Map the {@link Math#tanh(double)} function to each entry. 406 * <p>The instance <strong>is</strong> changed by this method.</p> 407 * @return for convenience, return this 408 * @deprecated in 2.2 (to be removed in 3.0). 409 */ 410 @Deprecated 411 RealVector mapTanhToSelf(); 412 413 /** 414 * Map the {@link Math#cos(double)} function to each entry. 415 * @return a vector containing the result of applying the function to each entry 416 * @deprecated in 2.2 (to be removed in 3.0). 417 */ 418 @Deprecated 419 RealVector mapCos(); 420 421 /** 422 * Map the {@link Math#cos(double)} function to each entry. 423 * <p>The instance <strong>is</strong> changed by this method.</p> 424 * @return for convenience, return this 425 * @deprecated in 2.2 (to be removed in 3.0). 426 */ 427 @Deprecated 428 RealVector mapCosToSelf(); 429 430 /** 431 * Map the {@link Math#sin(double)} function to each entry. 432 * @return a vector containing the result of applying the function to each entry 433 * @deprecated in 2.2 (to be removed in 3.0). 434 */ 435 @Deprecated 436 RealVector mapSin(); 437 438 /** 439 * Map the {@link Math#sin(double)} function to each entry. 440 * <p>The instance <strong>is</strong> changed by this method.</p> 441 * @return for convenience, return this 442 * @deprecated in 2.2 (to be removed in 3.0). 443 */ 444 @Deprecated 445 RealVector mapSinToSelf(); 446 447 /** 448 * Map the {@link Math#tan(double)} function to each entry. 449 * @return a vector containing the result of applying the function to each entry 450 * @deprecated in 2.2 (to be removed in 3.0). 451 */ 452 @Deprecated 453 RealVector mapTan(); 454 455 /** 456 * Map the {@link Math#tan(double)} function to each entry. 457 * <p>The instance <strong>is</strong> changed by this method.</p> 458 * @return for convenience, return this 459 * @deprecated in 2.2 (to be removed in 3.0). 460 */ 461 @Deprecated 462 RealVector mapTanToSelf(); 463 464 /** 465 * Map the {@link Math#acos(double)} function to each entry. 466 * @return a vector containing the result of applying the function to each entry 467 * @deprecated in 2.2 (to be removed in 3.0). 468 */ 469 @Deprecated 470 RealVector mapAcos(); 471 472 /** 473 * Map the {@link Math#acos(double)} function to each entry. 474 * <p>The instance <strong>is</strong> changed by this method.</p> 475 * @return for convenience, return this 476 * @deprecated in 2.2 (to be removed in 3.0). 477 */ 478 @Deprecated 479 RealVector mapAcosToSelf(); 480 481 /** 482 * Map the {@link Math#asin(double)} function to each entry. 483 * @return a vector containing the result of applying the function to each entry 484 * @deprecated in 2.2 (to be removed in 3.0). 485 */ 486 @Deprecated 487 RealVector mapAsin(); 488 489 /** 490 * Map the {@link Math#asin(double)} function to each entry. 491 * <p>The instance <strong>is</strong> changed by this method.</p> 492 * @return for convenience, return this 493 * @deprecated in 2.2 (to be removed in 3.0). 494 */ 495 @Deprecated 496 RealVector mapAsinToSelf(); 497 498 /** 499 * Map the {@link Math#atan(double)} function to each entry. 500 * @return a vector containing the result of applying the function to each entry 501 * @deprecated in 2.2 (to be removed in 3.0). 502 */ 503 @Deprecated 504 RealVector mapAtan(); 505 506 /** 507 * Map the {@link Math#atan(double)} function to each entry. 508 * <p>The instance <strong>is</strong> changed by this method.</p> 509 * @return for convenience, return this 510 * @deprecated in 2.2 (to be removed in 3.0). 511 */ 512 @Deprecated 513 RealVector mapAtanToSelf(); 514 515 /** 516 * Map the 1/x function to each entry. 517 * @return a vector containing the result of applying the function to each entry 518 * @deprecated in 2.2 (to be removed in 3.0). 519 */ 520 @Deprecated 521 RealVector mapInv(); 522 523 /** 524 * Map the 1/x function to each entry. 525 * <p>The instance <strong>is</strong> changed by this method.</p> 526 * @return for convenience, return this 527 * @deprecated in 2.2 (to be removed in 3.0). 528 */ 529 @Deprecated 530 RealVector mapInvToSelf(); 531 532 /** 533 * Map the {@link Math#abs(double)} function to each entry. 534 * @return a vector containing the result of applying the function to each entry 535 * @deprecated in 2.2 (to be removed in 3.0). 536 */ 537 @Deprecated 538 RealVector mapAbs(); 539 540 /** 541 * Map the {@link Math#abs(double)} function to each entry. 542 * <p>The instance <strong>is</strong> changed by this method.</p> 543 * @return for convenience, return this 544 * @deprecated in 2.2 (to be removed in 3.0). 545 */ 546 @Deprecated 547 RealVector mapAbsToSelf(); 548 549 /** 550 * Map the {@link Math#sqrt(double)} function to each entry. 551 * @return a vector containing the result of applying the function to each entry 552 * @deprecated in 2.2 (to be removed in 3.0). 553 */ 554 @Deprecated 555 RealVector mapSqrt(); 556 557 /** 558 * Map the {@link Math#sqrt(double)} function to each entry. 559 * <p>The instance <strong>is</strong> changed by this method.</p> 560 * @return for convenience, return this 561 * @deprecated in 2.2 (to be removed in 3.0). 562 */ 563 @Deprecated 564 RealVector mapSqrtToSelf(); 565 566 /** 567 * Map the {@link Math#cbrt(double)} function to each entry. 568 * @return a vector containing the result of applying the function to each entry 569 * @deprecated in 2.2 (to be removed in 3.0). 570 */ 571 @Deprecated 572 RealVector mapCbrt(); 573 574 /** 575 * Map the {@link Math#cbrt(double)} function to each entry. 576 * <p>The instance <strong>is</strong> changed by this method.</p> 577 * @return for convenience, return this 578 * @deprecated in 2.2 (to be removed in 3.0). 579 */ 580 @Deprecated 581 RealVector mapCbrtToSelf(); 582 583 /** 584 * Map the {@link Math#ceil(double)} function to each entry. 585 * @return a vector containing the result of applying the function to each entry 586 * @deprecated in 2.2 (to be removed in 3.0). 587 */ 588 @Deprecated 589 RealVector mapCeil(); 590 591 /** 592 * Map the {@link Math#ceil(double)} function to each entry. 593 * <p>The instance <strong>is</strong> changed by this method.</p> 594 * @return for convenience, return this 595 * @deprecated in 2.2 (to be removed in 3.0). 596 */ 597 @Deprecated 598 RealVector mapCeilToSelf(); 599 600 /** 601 * Map the {@link Math#floor(double)} function to each entry. 602 * @return a vector containing the result of applying the function to each entry 603 * @deprecated in 2.2 (to be removed in 3.0). 604 */ 605 @Deprecated 606 RealVector mapFloor(); 607 608 /** 609 * Map the {@link Math#floor(double)} function to each entry. 610 * <p>The instance <strong>is</strong> changed by this method.</p> 611 * @return for convenience, return this 612 * @deprecated in 2.2 (to be removed in 3.0). 613 */ 614 @Deprecated 615 RealVector mapFloorToSelf(); 616 617 /** 618 * Map the {@link Math#rint(double)} function to each entry. 619 * @return a vector containing the result of applying the function to each entry 620 * @deprecated in 2.2 (to be removed in 3.0). 621 */ 622 @Deprecated 623 RealVector mapRint(); 624 625 /** 626 * Map the {@link Math#rint(double)} function to each entry. 627 * <p>The instance <strong>is</strong> changed by this method.</p> 628 * @return for convenience, return this 629 * @deprecated in 2.2 (to be removed in 3.0). 630 */ 631 @Deprecated 632 RealVector mapRintToSelf(); 633 634 /** 635 * Map the {@link Math#signum(double)} function to each entry. 636 * @return a vector containing the result of applying the function to each entry 637 * @deprecated in 2.2 (to be removed in 3.0). 638 */ 639 @Deprecated 640 RealVector mapSignum(); 641 642 /** 643 * Map the {@link Math#signum(double)} function to each entry. 644 * <p>The instance <strong>is</strong> changed by this method.</p> 645 * @return for convenience, return this 646 * @deprecated in 2.2 (to be removed in 3.0). 647 */ 648 @Deprecated 649 RealVector mapSignumToSelf(); 650 651 /** 652 * Map the {@link Math#ulp(double)} function to each entry. 653 * @return a vector containing the result of applying the function to each entry 654 * @deprecated in 2.2 (to be removed in 3.0). 655 */ 656 @Deprecated 657 RealVector mapUlp(); 658 659 /** 660 * Map the {@link Math#ulp(double)} function to each entry. 661 * <p>The instance <strong>is</strong> changed by this method.</p> 662 * @return for convenience, return this 663 * @deprecated in 2.2 (to be removed in 3.0). 664 */ 665 @Deprecated 666 RealVector mapUlpToSelf(); 667 668 /** 669 * Element-by-element multiplication. 670 * @param v vector by which instance elements must be multiplied 671 * @return a vector containing this[i] * v[i] for all i 672 * @throws org.apache.commons.math.exception.DimensionMismatchException 673 * if {@code v} is not the same size as this vector. 674 */ 675 RealVector ebeMultiply(RealVector v); 676 677 /** 678 * Element-by-element multiplication. 679 * @param v vector by which instance elements must be multiplied 680 * @return a vector containing this[i] * v[i] for all i 681 * @throws org.apache.commons.math.exception.DimensionMismatchException 682 * if {@code v} is not the same size as this vector. 683 */ 684 RealVector ebeMultiply(double[] v); 685 686 /** 687 * Element-by-element division. 688 * @param v vector by which instance elements must be divided 689 * @return a vector containing this[i] / v[i] for all i 690 * @throws org.apache.commons.math.exception.DimensionMismatchException 691 * if {@code v} is not the same size as this vector. 692 */ 693 RealVector ebeDivide(RealVector v); 694 695 /** 696 * Element-by-element division. 697 * @param v vector by which instance elements must be divided 698 * @return a vector containing this[i] / v[i] for all i 699 * @throws org.apache.commons.math.exception.DimensionMismatchException 700 * if {@code v} is not the same size as this vector. 701 */ 702 RealVector ebeDivide(double[] v); 703 704 /** 705 * Returns vector entries as a double array. 706 * @return double array of entries 707 */ 708 double[] getData(); 709 710 /** 711 * Compute the dot product. 712 * @param v vector with which dot product should be computed 713 * @return the scalar dot product between instance and v 714 * @throws org.apache.commons.math.exception.DimensionMismatchException 715 * if {@code v} is not the same size as this vector. 716 */ 717 double dotProduct(RealVector v); 718 719 /** 720 * Compute the dot product. 721 * @param v vector with which dot product should be computed 722 * @return the scalar dot product between instance and v 723 * @throws org.apache.commons.math.exception.DimensionMismatchException 724 * if {@code v} is not the same size as this vector. 725 */ 726 double dotProduct(double[] v); 727 728 /** 729 * Returns the L<sub>2</sub> norm of the vector. 730 * <p>The L<sub>2</sub> norm is the root of the sum of 731 * the squared elements.</p> 732 * @return norm 733 * @see #getL1Norm() 734 * @see #getLInfNorm() 735 * @see #getDistance(RealVector) 736 */ 737 double getNorm(); 738 739 /** 740 * Returns the L<sub>1</sub> norm of the vector. 741 * <p>The L<sub>1</sub> norm is the sum of the absolute 742 * values of elements.</p> 743 * @return norm 744 * @see #getNorm() 745 * @see #getLInfNorm() 746 * @see #getL1Distance(RealVector) 747 */ 748 double getL1Norm(); 749 750 /** 751 * Returns the L<sub>∞</sub> norm of the vector. 752 * <p>The L<sub>∞</sub> norm is the max of the absolute 753 * values of elements.</p> 754 * @return norm 755 * @see #getNorm() 756 * @see #getL1Norm() 757 * @see #getLInfDistance(RealVector) 758 */ 759 double getLInfNorm(); 760 761 /** 762 * Distance between two vectors. 763 * <p>This method computes the distance consistent with the 764 * L<sub>2</sub> norm, i.e. the square root of the sum of 765 * elements differences, or euclidian distance.</p> 766 * @param v vector to which distance is requested 767 * @return distance between two vectors. 768 * @throws org.apache.commons.math.exception.DimensionMismatchException 769 * if {@code v} is not the same size as this vector. 770 * @see #getL1Distance(RealVector) 771 * @see #getLInfDistance(RealVector) 772 * @see #getNorm() 773 */ 774 double getDistance(RealVector v); 775 776 /** 777 * Distance between two vectors. 778 * <p>This method computes the distance consistent with the 779 * L<sub>2</sub> norm, i.e. the square root of the sum of 780 * elements differences, or euclidian distance.</p> 781 * @param v vector to which distance is requested 782 * @return distance between two vectors. 783 * @throws org.apache.commons.math.exception.DimensionMismatchException 784 * if {@code v} is not the same size as this vector. 785 * @see #getL1Distance(double[]) 786 * @see #getLInfDistance(double[]) 787 * @see #getNorm() 788 */ 789 double getDistance(double[] v); 790 791 /** 792 * Distance between two vectors. 793 * <p>This method computes the distance consistent with 794 * L<sub>1</sub> norm, i.e. the sum of the absolute values of 795 * elements differences.</p> 796 * @param v vector to which distance is requested 797 * @return distance between two vectors. 798 * @throws org.apache.commons.math.exception.DimensionMismatchException 799 * if {@code v} is not the same size as this vector. 800 * @see #getDistance(RealVector) 801 * @see #getLInfDistance(RealVector) 802 * @see #getL1Norm() 803 */ 804 double getL1Distance(RealVector v); 805 806 /** 807 * Distance between two vectors. 808 * <p>This method computes the distance consistent with 809 * L<sub>1</sub> norm, i.e. the sum of the absolute values of 810 * elements differences.</p> 811 * @param v vector to which distance is requested 812 * @return distance between two vectors. 813 * @throws org.apache.commons.math.exception.DimensionMismatchException 814 * if {@code v} is not the same size as this vector. 815 * @see #getDistance(double[]) 816 * @see #getLInfDistance(double[]) 817 * @see #getL1Norm() 818 */ 819 double getL1Distance(double[] v); 820 821 /** 822 * Distance between two vectors. 823 * <p>This method computes the distance consistent with 824 * L<sub>∞</sub> norm, i.e. the max of the absolute values of 825 * elements differences.</p> 826 * @param v vector to which distance is requested 827 * @return distance between two vectors. 828 * @throws org.apache.commons.math.exception.DimensionMismatchException 829 * if {@code v} is not the same size as this vector. 830 * @see #getDistance(RealVector) 831 * @see #getL1Distance(RealVector) 832 * @see #getLInfNorm() 833 */ 834 double getLInfDistance(RealVector v); 835 836 /** 837 * Distance between two vectors. 838 * <p>This method computes the distance consistent with 839 * L<sub>∞</sub> norm, i.e. the max of the absolute values of 840 * elements differences.</p> 841 * @param v vector to which distance is requested 842 * @return distance between two vectors. 843 * @throws org.apache.commons.math.exception.DimensionMismatchException 844 * if {@code v} is not the same size as this vector. 845 * @see #getDistance(double[]) 846 * @see #getL1Distance(double[]) 847 * @see #getLInfNorm() 848 */ 849 double getLInfDistance(double[] v); 850 851 /** Creates a unit vector pointing in the direction of this vector. 852 * <p>The instance is not changed by this method.</p> 853 * @return a unit vector pointing in direction of this vector 854 * @exception ArithmeticException if the norm is null 855 */ 856 RealVector unitVector(); 857 858 /** Converts this vector into a unit vector. 859 * <p>The instance itself is changed by this method.</p> 860 * @throws ArithmeticException 861 * if the norm is zero. 862 */ 863 void unitize(); 864 865 /** Find the orthogonal projection of this vector onto another vector. 866 * @param v vector onto which instance must be projected 867 * @return projection of the instance onto v 868 * @throws org.apache.commons.math.exception.DimensionMismatchException 869 * if {@code v} is not the same size as this vector. 870 */ 871 RealVector projection(RealVector v); 872 873 /** Find the orthogonal projection of this vector onto another vector. 874 * @param v vector onto which instance must be projected 875 * @return projection of the instance onto v 876 * @throws org.apache.commons.math.exception.DimensionMismatchException 877 * if {@code v} is not the same size as this vector. 878 */ 879 RealVector projection(double[] v); 880 881 /** 882 * Compute the outer product. 883 * @param v vector with which outer product should be computed 884 * @return the square matrix outer product between instance and v 885 * @throws org.apache.commons.math.exception.DimensionMismatchException 886 * if {@code v} is not the same size as this vector. 887 */ 888 RealMatrix outerProduct(RealVector v); 889 890 /** 891 * Compute the outer product. 892 * @param v vector with which outer product should be computed 893 * @return the square matrix outer product between instance and v 894 * @throws org.apache.commons.math.exception.DimensionMismatchException 895 * if {@code v} is not the same size as this vector. 896 */ 897 RealMatrix outerProduct(double[] v); 898 899 /** 900 * Returns the entry in the specified index. 901 * 902 * @param index Index location of entry to be fetched. 903 * @return the vector entry at {@code index}. 904 * @throws org.apache.commons.math.exception.OutOfRangeException 905 * if the index is not valid. 906 * @see #setEntry(int, double) 907 */ 908 double getEntry(int index); 909 910 /** 911 * Set a single element. 912 * @param index element index. 913 * @param value new value for the element. 914 * @throws org.apache.commons.math.exception.OutOfRangeException 915 * if the index is not valid. 916 * @see #getEntry(int) 917 */ 918 void setEntry(int index, double value); 919 920 /** 921 * Returns the size of the vector. 922 * @return size 923 */ 924 int getDimension(); 925 926 /** 927 * Construct a vector by appending a vector to this vector. 928 * @param v vector to append to this one. 929 * @return a new vector 930 */ 931 RealVector append(RealVector v); 932 933 /** 934 * Construct a vector by appending a double to this vector. 935 * @param d double to append. 936 * @return a new vector 937 */ 938 RealVector append(double d); 939 940 /** 941 * Construct a vector by appending a double array to this vector. 942 * @param a double array to append. 943 * @return a new vector 944 */ 945 RealVector append(double[] a); 946 947 /** 948 * Get a subvector from consecutive elements. 949 * @param index index of first element. 950 * @param n number of elements to be retrieved. 951 * @return a vector containing n elements. 952 * @throws org.apache.commons.math.exception.OutOfRangeException 953 * if the index is not valid. 954 */ 955 RealVector getSubVector(int index, int n); 956 957 /** 958 * Set a set of consecutive elements. 959 * @param index index of first element to be set. 960 * @param v vector containing the values to set. 961 * @throws org.apache.commons.math.exception.OutOfRangeException 962 * if the index is not valid. 963 * @see #setSubVector(int, double[]) 964 */ 965 void setSubVector(int index, RealVector v); 966 967 /** 968 * Set a set of consecutive elements. 969 * @param index index of first element to be set. 970 * @param v vector containing the values to set. 971 * @throws org.apache.commons.math.exception.OutOfRangeException 972 * if the index is not valid. 973 * @see #setSubVector(int, RealVector) 974 */ 975 void setSubVector(int index, double[] v); 976 977 /** 978 * Set all elements to a single value. 979 * @param value single value to set for all elements 980 */ 981 void set(double value); 982 983 /** 984 * Convert the vector to a double array. 985 * <p>The array is independent from vector data, it's elements 986 * are copied.</p> 987 * @return array containing a copy of vector elements 988 */ 989 double[] toArray(); 990 991 /** 992 * Check whether any coordinate of this vector is {@code NaN}. 993 * @return {@code true} if any coordinate of this vector is {@code NaN}, 994 * {@code false} otherwise. 995 */ 996 boolean isNaN(); 997 998 /** 999 * Check whether any coordinate of this vector is infinite and none are {@code NaN}. 1000 * 1001 * @return {@code true} if any coordinate of this vector is infinite and 1002 * none are {@code NaN}, {@code false} otherwise. 1003 */ 1004 boolean isInfinite(); 1005 } 1006