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 package org.apache.commons.math.linear;
018
019 import java.util.Iterator;
020
021 import org.apache.commons.math.FunctionEvaluationException;
022 import org.apache.commons.math.analysis.UnivariateRealFunction;
023
024
025 /**
026 * Interface defining a real-valued vector with basic algebraic operations.
027 * <p>
028 * vector element indexing is 0-based -- e.g., <code>getEntry(0)</code>
029 * returns the first element of the vector.
030 * </p>
031 * <p>
032 * The various <code>mapXxx</code> and <code>mapXxxToSelf</code> methods operate
033 * on vectors element-wise, i.e. they perform the same operation (adding a scalar,
034 * applying a function ...) on each element in turn. The <code>mapXxx</code>
035 * versions create a new vector to hold the result and do not change the instance.
036 * The <code>mapXxxToSelf</code> versions use the instance itself to store the
037 * results, so the instance is changed by these methods. In both cases, the result
038 * vector is returned by the methods, this allows to use the <i>fluent API</i>
039 * style, like this:
040 * </p>
041 * <pre>
042 * RealVector result = v.mapAddToSelf(3.0).mapTanToSelf().mapSquareToSelf();
043 * </pre>
044 * <p>
045 * Remark on the deprecated {@code mapXxx} and {@code mapXxxToSelf} methods: In
046 * Commons-Math v3.0, the same functionality will be achieved by directly using the
047 * {@link #map(UnivariateRealFunction)} and {@link #mapToSelf(UnivariateRealFunction)}
048 * together with new function objects (not available in v2.2).
049 * </p>
050 *
051 * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 f??vr. 2011) $
052 * @since 2.0
053 */
054 public interface RealVector {
055 /**
056 * Acts as if it is implemented as:
057 * <pre>
058 * Entry e = null;
059 * for(Iterator<Entry> it = iterator(); it.hasNext(); e = it.next()) {
060 * e.setValue(function.value(e.getValue()));
061 * }
062 * </pre>
063 *
064 * @param function Function to apply to each entry.
065 * @return this vector.
066 * @throws FunctionEvaluationException if the function throws it.
067 */
068 RealVector mapToSelf(UnivariateRealFunction function) throws FunctionEvaluationException;
069
070 /**
071 * Acts as if implemented as:
072 * <pre>
073 * return copy().map(function);
074 * </pre>
075 *
076 * @param function Function to apply to each entry.
077 * @return a new vector.
078 * @throws FunctionEvaluationException if the function throws it.
079 */
080 RealVector map(UnivariateRealFunction function) throws FunctionEvaluationException;
081
082 /** Class representing a modifiable entry in the vector. */
083 public abstract class Entry {
084 /** Index of the entry. */
085 private int index;
086
087 /**
088 * Get the value of the entry.
089 *
090 * @return the value of the entry.
091 */
092 public abstract double getValue();
093 /**
094 * Set the value of the entry.
095 *
096 * @param value New value for the entry.
097 */
098 public abstract void setValue(double value);
099 /**
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 }