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 */
17package org.apache.commons.math.linear;
18
19import java.util.Iterator;
20
21import org.apache.commons.math.FunctionEvaluationException;
22import 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 févr. 2011) $
52 * @since 2.0
53 */
54public 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>&infin;</sub> norm of the vector.
752     * <p>The L<sub>&infin;</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>&infin;</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>&infin;</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