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     *
045     * @version $Revision: 902214 $ $Date: 2010-01-22 13:40:28 -0500 (Fri, 22 Jan 2010) $
046     * @since 2.0
047     */
048    public interface RealVector {
049    
050        /**
051         * Acts as if it is implemented as:
052         * Entry e = null;
053         * for(Iterator<Entry> it = iterator(); it.hasNext(); e = it.next()) {
054         *   e.setValue(function.value(e.getValue()));
055         * }
056         * @param function to apply to each successive entry
057         * @return this vector
058         * @throws FunctionEvaluationException if function throws it on application to any entry
059         */
060        RealVector mapToSelf(UnivariateRealFunction function) throws FunctionEvaluationException;
061    
062        /**
063         * Acts as if implemented as:
064         * return copy().map(function);
065         * @param function to apply to each successive entry
066         * @return a new vector
067         * @throws FunctionEvaluationException if function throws it on application to any entry
068         */
069        RealVector map(UnivariateRealFunction function) throws FunctionEvaluationException;
070    
071        /** Class representing a modifiable entry in the vector. */
072        public abstract class Entry {
073    
074            /** Index of the entry. */
075            private int index;
076    
077            /** Get the value of the entry.
078             * @return value of the entry
079             */
080            public abstract double getValue();
081    
082            /** Set the value of the entry.
083             * @param value new value for the entry
084             */
085            public abstract void setValue(double value);
086    
087            /** Get the index of the entry.
088             * @return index of the entry
089             */
090            public int getIndex() {
091                return index;
092            }
093    
094            /** Set the index of the entry.
095             * @param index new index for the entry
096             */
097            public void setIndex(int index) {
098                this.index = index;
099            }
100    
101        }
102    
103        /**
104         * Generic dense iterator - starts with index == zero, and hasNext() == true until index == getDimension();
105         * @return a dense iterator
106         */
107        Iterator<Entry> iterator();
108    
109        /**
110         * Specialized implementations may choose to not iterate over all dimensions, either because those values are
111         * unset, or are equal to defaultValue(), or are small enough to be ignored for the purposes of iteration.
112         * No guarantees are made about order of iteration.
113         * In dense implementations, this method will often delegate to {@link #iterator()}
114         * @return a sparse iterator
115         */
116        Iterator<Entry> sparseIterator();
117    
118        /**
119         * Returns a (deep) copy of this.
120         * @return vector copy
121         */
122        RealVector copy();
123    
124        /**
125         * Compute the sum of this and v.
126         * @param v vector to be added
127         * @return this + v
128         * @throws IllegalArgumentException if v is not the same size as this
129         */
130        RealVector add(RealVector v)
131            throws IllegalArgumentException;
132    
133        /**
134         * Compute the sum of this and v.
135         * @param v vector to be added
136         * @return this + v
137         * @throws IllegalArgumentException if v is not the same size as this
138         */
139        RealVector add(double[] v)
140            throws IllegalArgumentException;
141    
142        /**
143         * Compute this minus v.
144         * @param v vector to be subtracted
145         * @return this + v
146         * @throws IllegalArgumentException if v is not the same size as this
147         */
148        RealVector subtract(RealVector v)
149            throws IllegalArgumentException;
150    
151        /**
152         * Compute this minus v.
153         * @param v vector to be subtracted
154         * @return this + v
155         * @throws IllegalArgumentException if v is not the same size as this
156         */
157        RealVector subtract(double[] v)
158            throws IllegalArgumentException;
159    
160        /**
161         * Map an addition operation to each entry.
162         * @param d value to be added to each entry
163         * @return this + d
164         */
165        RealVector mapAdd(double d);
166    
167        /**
168         * Map an addition operation to each entry.
169         * <p>The instance <strong>is</strong> changed by this method.</p>
170         * @param d value to be added to each entry
171         * @return for convenience, return this
172         */
173        RealVector mapAddToSelf(double d);
174    
175        /**
176         * Map a subtraction operation to each entry.
177         * @param d value to be subtracted to each entry
178         * @return this - d
179         */
180        RealVector mapSubtract(double d);
181    
182        /**
183         * Map a subtraction operation to each entry.
184         * <p>The instance <strong>is</strong> changed by this method.</p>
185         * @param d value to be subtracted to each entry
186         * @return for convenience, return this
187         */
188        RealVector mapSubtractToSelf(double d);
189    
190        /**
191         * Map a multiplication operation to each entry.
192         * @param d value to multiply all entries by
193         * @return this * d
194         */
195        RealVector mapMultiply(double d);
196    
197        /**
198         * Map a multiplication operation to each entry.
199         * <p>The instance <strong>is</strong> changed by this method.</p>
200         * @param d value to multiply all entries by
201         * @return for convenience, return this
202         */
203        RealVector mapMultiplyToSelf(double d);
204    
205        /**
206         * Map a division operation to each entry.
207         * @param d value to divide all entries by
208         * @return this / d
209         */
210        RealVector mapDivide(double d);
211    
212        /**
213         * Map a division operation to each entry.
214         * <p>The instance <strong>is</strong> changed by this method.</p>
215         * @param d value to divide all entries by
216         * @return for convenience, return this
217         */
218        RealVector mapDivideToSelf(double d);
219    
220        /**
221         * Map a power operation to each entry.
222         * @param d value to raise all entries to
223         * @return this ^ d
224         */
225        RealVector mapPow(double d);
226    
227        /**
228         * Map a power operation to each entry.
229         * <p>The instance <strong>is</strong> changed by this method.</p>
230         * @param d value to raise all entries to
231         * @return for convenience, return this
232         */
233        RealVector mapPowToSelf(double d);
234    
235        /**
236         * Map the {@link Math#exp(double)} function to each entry.
237         * @return a vector containing the result of applying the function to each entry
238         */
239        RealVector mapExp();
240    
241        /**
242         * Map the {@link Math#exp(double)} function to each entry.
243         * <p>The instance <strong>is</strong> changed by this method.</p>
244         * @return for convenience, return this
245         */
246        RealVector mapExpToSelf();
247    
248        /**
249         * Map the {@link Math#expm1(double)} function to each entry.
250         * @return a vector containing the result of applying the function to each entry
251         */
252        RealVector mapExpm1();
253    
254        /**
255         * Map the {@link Math#expm1(double)} function to each entry.
256         * <p>The instance <strong>is</strong> changed by this method.</p>
257         * @return for convenience, return this
258         */
259        RealVector mapExpm1ToSelf();
260    
261        /**
262         * Map the {@link Math#log(double)} function to each entry.
263         * @return a vector containing the result of applying the function to each entry
264         */
265        RealVector mapLog();
266    
267        /**
268         * Map the {@link Math#log(double)} function to each entry.
269         * <p>The instance <strong>is</strong> changed by this method.</p>
270         * @return for convenience, return this
271         */
272        RealVector mapLogToSelf();
273    
274        /**
275         * Map the {@link Math#log10(double)} function to each entry.
276         * @return a vector containing the result of applying the function to each entry
277         */
278        RealVector mapLog10();
279    
280        /**
281         * Map the {@link Math#log10(double)} function to each entry.
282         * <p>The instance <strong>is</strong> changed by this method.</p>
283         * @return for convenience, return this
284         */
285        RealVector mapLog10ToSelf();
286    
287        /**
288         * Map the {@link Math#log1p(double)} function to each entry.
289         * @return a vector containing the result of applying the function to each entry
290         */
291        RealVector mapLog1p();
292    
293        /**
294         * Map the {@link Math#log1p(double)} function to each entry.
295         * <p>The instance <strong>is</strong> changed by this method.</p>
296         * @return for convenience, return this
297         */
298        RealVector mapLog1pToSelf();
299    
300        /**
301         * Map the {@link Math#cosh(double)} function to each entry.
302         * @return a vector containing the result of applying the function to each entry
303         */
304        RealVector mapCosh();
305    
306        /**
307         * Map the {@link Math#cosh(double)} function to each entry.
308         * <p>The instance <strong>is</strong> changed by this method.</p>
309         * @return for convenience, return this
310         */
311        RealVector mapCoshToSelf();
312    
313        /**
314         * Map the {@link Math#sinh(double)} function to each entry.
315         * @return a vector containing the result of applying the function to each entry
316         */
317        RealVector mapSinh();
318    
319        /**
320         * Map the {@link Math#sinh(double)} function to each entry.
321         * <p>The instance <strong>is</strong> changed by this method.</p>
322         * @return for convenience, return this
323         */
324        RealVector mapSinhToSelf();
325    
326        /**
327         * Map the {@link Math#tanh(double)} function to each entry.
328         * @return a vector containing the result of applying the function to each entry
329         */
330        RealVector mapTanh();
331    
332        /**
333         * Map the {@link Math#tanh(double)} function to each entry.
334         * <p>The instance <strong>is</strong> changed by this method.</p>
335         * @return for convenience, return this
336         */
337        RealVector mapTanhToSelf();
338    
339        /**
340         * Map the {@link Math#cos(double)} function to each entry.
341         * @return a vector containing the result of applying the function to each entry
342         */
343        RealVector mapCos();
344    
345        /**
346         * Map the {@link Math#cos(double)} function to each entry.
347         * <p>The instance <strong>is</strong> changed by this method.</p>
348         * @return for convenience, return this
349         */
350        RealVector mapCosToSelf();
351    
352        /**
353         * Map the {@link Math#sin(double)} function to each entry.
354         * @return a vector containing the result of applying the function to each entry
355         */
356        RealVector mapSin();
357    
358        /**
359         * Map the {@link Math#sin(double)} function to each entry.
360         * <p>The instance <strong>is</strong> changed by this method.</p>
361         * @return for convenience, return this
362         */
363        RealVector mapSinToSelf();
364    
365        /**
366         * Map the {@link Math#tan(double)} function to each entry.
367         * @return a vector containing the result of applying the function to each entry
368         */
369        RealVector mapTan();
370    
371        /**
372         * Map the {@link Math#tan(double)} function to each entry.
373         * <p>The instance <strong>is</strong> changed by this method.</p>
374         * @return for convenience, return this
375         */
376        RealVector mapTanToSelf();
377    
378        /**
379         * Map the {@link Math#acos(double)} function to each entry.
380         * @return a vector containing the result of applying the function to each entry
381         */
382        RealVector mapAcos();
383    
384        /**
385         * Map the {@link Math#acos(double)} function to each entry.
386         * <p>The instance <strong>is</strong> changed by this method.</p>
387         * @return for convenience, return this
388         */
389        RealVector mapAcosToSelf();
390    
391        /**
392         * Map the {@link Math#asin(double)} function to each entry.
393         * @return a vector containing the result of applying the function to each entry
394         */
395        RealVector mapAsin();
396    
397        /**
398         * Map the {@link Math#asin(double)} function to each entry.
399         * <p>The instance <strong>is</strong> changed by this method.</p>
400         * @return for convenience, return this
401         */
402        RealVector mapAsinToSelf();
403    
404        /**
405         * Map the {@link Math#atan(double)} function to each entry.
406         * @return a vector containing the result of applying the function to each entry
407         */
408        RealVector mapAtan();
409    
410        /**
411         * Map the {@link Math#atan(double)} function to each entry.
412         * <p>The instance <strong>is</strong> changed by this method.</p>
413         * @return for convenience, return this
414         */
415        RealVector mapAtanToSelf();
416    
417        /**
418         * Map the 1/x function to each entry.
419         * @return a vector containing the result of applying the function to each entry
420         */
421        RealVector mapInv();
422    
423        /**
424         * Map the 1/x function to each entry.
425         * <p>The instance <strong>is</strong> changed by this method.</p>
426         * @return for convenience, return this
427         */
428        RealVector mapInvToSelf();
429    
430        /**
431         * Map the {@link Math#abs(double)} function to each entry.
432         * @return a vector containing the result of applying the function to each entry
433         */
434        RealVector mapAbs();
435    
436        /**
437         * Map the {@link Math#abs(double)} function to each entry.
438         * <p>The instance <strong>is</strong> changed by this method.</p>
439         * @return for convenience, return this
440         */
441        RealVector mapAbsToSelf();
442    
443        /**
444         * Map the {@link Math#sqrt(double)} function to each entry.
445         * @return a vector containing the result of applying the function to each entry
446         */
447        RealVector mapSqrt();
448    
449        /**
450         * Map the {@link Math#sqrt(double)} function to each entry.
451         * <p>The instance <strong>is</strong> changed by this method.</p>
452         * @return for convenience, return this
453         */
454        RealVector mapSqrtToSelf();
455    
456        /**
457         * Map the {@link Math#cbrt(double)} function to each entry.
458         * @return a vector containing the result of applying the function to each entry
459         */
460        RealVector mapCbrt();
461    
462        /**
463         * Map the {@link Math#cbrt(double)} function to each entry.
464         * <p>The instance <strong>is</strong> changed by this method.</p>
465         * @return for convenience, return this
466         */
467        RealVector mapCbrtToSelf();
468    
469        /**
470         * Map the {@link Math#ceil(double)} function to each entry.
471         * @return a vector containing the result of applying the function to each entry
472         */
473        RealVector mapCeil();
474    
475        /**
476         * Map the {@link Math#ceil(double)} function to each entry.
477         * <p>The instance <strong>is</strong> changed by this method.</p>
478         * @return for convenience, return this
479         */
480        RealVector mapCeilToSelf();
481    
482        /**
483         * Map the {@link Math#floor(double)} function to each entry.
484         * @return a vector containing the result of applying the function to each entry
485         */
486        RealVector mapFloor();
487    
488        /**
489         * Map the {@link Math#floor(double)} function to each entry.
490         * <p>The instance <strong>is</strong> changed by this method.</p>
491         * @return for convenience, return this
492         */
493        RealVector mapFloorToSelf();
494    
495        /**
496         * Map the {@link Math#rint(double)} function to each entry.
497         * @return a vector containing the result of applying the function to each entry
498         */
499        RealVector mapRint();
500    
501        /**
502         * Map the {@link Math#rint(double)} function to each entry.
503         * <p>The instance <strong>is</strong> changed by this method.</p>
504         * @return for convenience, return this
505         */
506        RealVector mapRintToSelf();
507    
508        /**
509         * Map the {@link Math#signum(double)} function to each entry.
510         * @return a vector containing the result of applying the function to each entry
511         */
512        RealVector mapSignum();
513    
514        /**
515         * Map the {@link Math#signum(double)} function to each entry.
516         * <p>The instance <strong>is</strong> changed by this method.</p>
517         * @return for convenience, return this
518         */
519        RealVector mapSignumToSelf();
520    
521        /**
522         * Map the {@link Math#ulp(double)} function to each entry.
523         * @return a vector containing the result of applying the function to each entry
524         */
525        RealVector mapUlp();
526    
527        /**
528         * Map the {@link Math#ulp(double)} function to each entry.
529         * <p>The instance <strong>is</strong> changed by this method.</p>
530         * @return for convenience, return this
531         */
532        RealVector mapUlpToSelf();
533    
534        /**
535         * Element-by-element multiplication.
536         * @param v vector by which instance elements must be multiplied
537         * @return a vector containing this[i] * v[i] for all i
538         * @throws IllegalArgumentException if v is not the same size as this
539         */
540        RealVector ebeMultiply(RealVector v) throws IllegalArgumentException;
541    
542        /**
543         * Element-by-element multiplication.
544         * @param v vector by which instance elements must be multiplied
545         * @return a vector containing this[i] * v[i] for all i
546         * @throws IllegalArgumentException if v is not the same size as this
547         */
548        RealVector ebeMultiply(double[] v) throws IllegalArgumentException;
549    
550        /**
551         * Element-by-element division.
552         * @param v vector by which instance elements must be divided
553         * @return a vector containing this[i] / v[i] for all i
554         * @throws IllegalArgumentException if v is not the same size as this
555         */
556        RealVector ebeDivide(RealVector v) throws IllegalArgumentException;
557    
558        /**
559         * Element-by-element division.
560         * @param v vector by which instance elements must be divided
561         * @return a vector containing this[i] / v[i] for all i
562         * @throws IllegalArgumentException if v is not the same size as this
563         */
564        RealVector ebeDivide(double[] v) throws IllegalArgumentException;
565    
566        /**
567         * Returns vector entries as a double array.
568         * @return double array of entries
569         */
570         double[] getData();
571    
572        /**
573         * Compute the dot product.
574         * @param v vector with which dot product should be computed
575         * @return the scalar dot product between instance and v
576         * @exception IllegalArgumentException if v is not the same size as this
577         */
578        double dotProduct(RealVector v)
579            throws IllegalArgumentException;
580    
581        /**
582         * Compute the dot product.
583         * @param v vector with which dot product should be computed
584         * @return the scalar dot product between instance and v
585         * @exception IllegalArgumentException if v is not the same size as this
586         */
587        double dotProduct(double[] v)
588            throws IllegalArgumentException;
589    
590        /**
591         * Returns the L<sub>2</sub> norm of the vector.
592         * <p>The L<sub>2</sub> norm is the root of the sum of
593         * the squared elements.</p>
594         * @return norm
595         * @see #getL1Norm()
596         * @see #getLInfNorm()
597         * @see #getDistance(RealVector)
598         */
599        double getNorm();
600    
601        /**
602         * Returns the L<sub>1</sub> norm of the vector.
603         * <p>The L<sub>1</sub> norm is the sum of the absolute
604         * values of elements.</p>
605         * @return norm
606         * @see #getNorm()
607         * @see #getLInfNorm()
608         * @see #getL1Distance(RealVector)
609         */
610        double getL1Norm();
611    
612        /**
613         * Returns the L<sub>&infin;</sub> norm of the vector.
614         * <p>The L<sub>&infin;</sub> norm is the max of the absolute
615         * values of elements.</p>
616         * @return norm
617         * @see #getNorm()
618         * @see #getL1Norm()
619         * @see #getLInfDistance(RealVector)
620         */
621        double getLInfNorm();
622    
623        /**
624         * Distance between two vectors.
625         * <p>This method computes the distance consistent with the
626         * L<sub>2</sub> norm, i.e. the square root of the sum of
627         * elements differences, or euclidian distance.</p>
628         * @param v vector to which distance is requested
629         * @return distance between two vectors.
630         * @exception IllegalArgumentException if v is not the same size as this
631         * @see #getL1Distance(RealVector)
632         * @see #getLInfDistance(RealVector)
633         * @see #getNorm()
634         */
635        double getDistance(RealVector v)
636            throws IllegalArgumentException;
637    
638        /**
639         * Distance between two vectors.
640         * <p>This method computes the distance consistent with the
641         * L<sub>2</sub> norm, i.e. the square root of the sum of
642         * elements differences, or euclidian distance.</p>
643         * @param v vector to which distance is requested
644         * @return distance between two vectors.
645         * @exception IllegalArgumentException if v is not the same size as this
646         * @see #getL1Distance(double[])
647         * @see #getLInfDistance(double[])
648         * @see #getNorm()
649         */
650        double getDistance(double[] v)
651            throws IllegalArgumentException;
652    
653        /**
654         * Distance between two vectors.
655         * <p>This method computes the distance consistent with
656         * L<sub>1</sub> norm, i.e. the sum of the absolute values of
657         * elements differences.</p>
658         * @param v vector to which distance is requested
659         * @return distance between two vectors.
660         * @exception IllegalArgumentException if v is not the same size as this
661         * @see #getDistance(RealVector)
662         * @see #getLInfDistance(RealVector)
663         * @see #getL1Norm()
664         */
665        double getL1Distance(RealVector v)
666            throws IllegalArgumentException;
667    
668        /**
669         * Distance between two vectors.
670         * <p>This method computes the distance consistent with
671         * L<sub>1</sub> norm, i.e. the sum of the absolute values of
672         * elements differences.</p>
673         * @param v vector to which distance is requested
674         * @return distance between two vectors.
675         * @exception IllegalArgumentException if v is not the same size as this
676         * @see #getDistance(double[])
677         * @see #getLInfDistance(double[])
678         * @see #getL1Norm()
679         */
680        double getL1Distance(double[] v)
681            throws IllegalArgumentException;
682    
683        /**
684         * Distance between two vectors.
685         * <p>This method computes the distance consistent with
686         * L<sub>&infin;</sub> norm, i.e. the max of the absolute values of
687         * elements differences.</p>
688         * @param v vector to which distance is requested
689         * @return distance between two vectors.
690         * @exception IllegalArgumentException if v is not the same size as this
691         * @see #getDistance(RealVector)
692         * @see #getL1Distance(RealVector)
693         * @see #getLInfNorm()
694         */
695        double getLInfDistance(RealVector v)
696            throws IllegalArgumentException;
697    
698        /**
699         * Distance between two vectors.
700         * <p>This method computes the distance consistent with
701         * L<sub>&infin;</sub> norm, i.e. the max of the absolute values of
702         * elements differences.</p>
703         * @param v vector to which distance is requested
704         * @return distance between two vectors.
705         * @exception IllegalArgumentException if v is not the same size as this
706         * @see #getDistance(double[])
707         * @see #getL1Distance(double[])
708         * @see #getLInfNorm()
709         */
710        double getLInfDistance(double[] v)
711            throws IllegalArgumentException;
712    
713        /** Creates a unit vector pointing in the direction of this vector.
714         * <p>The instance is not changed by this method.</p>
715         * @return a unit vector pointing in direction of this vector
716         * @exception ArithmeticException if the norm is null
717         */
718        RealVector unitVector();
719    
720        /** Converts this vector into a unit vector.
721         * <p>The instance itself is changed by this method.</p>
722         * @exception ArithmeticException if the norm is null
723         */
724        void unitize();
725    
726        /** Find the orthogonal projection of this vector onto another vector.
727         * @param v vector onto which instance must be projected
728         * @return projection of the instance onto v
729         * @throws IllegalArgumentException if v is not the same size as this
730         */
731        RealVector projection(RealVector v)
732            throws IllegalArgumentException;
733    
734        /** Find the orthogonal projection of this vector onto another vector.
735         * @param v vector onto which instance must be projected
736         * @return projection of the instance onto v
737         * @throws IllegalArgumentException if v is not the same size as this
738         */
739        RealVector projection(double[] v)
740            throws IllegalArgumentException;
741    
742        /**
743         * Compute the outer product.
744         * @param v vector with which outer product should be computed
745         * @return the square matrix outer product between instance and v
746         * @exception IllegalArgumentException if v is not the same size as this
747         */
748        RealMatrix outerProduct(RealVector v)
749            throws IllegalArgumentException;
750    
751        /**
752         * Compute the outer product.
753         * @param v vector with which outer product should be computed
754         * @return the square matrix outer product between instance and v
755         * @exception IllegalArgumentException if v is not the same size as this
756         */
757        RealMatrix outerProduct(double[] v)
758            throws IllegalArgumentException;
759    
760        /**
761         * Returns the entry in the specified index.
762         * <p>
763         * The index start at 0 and must be lesser than the size,
764         * otherwise a {@link MatrixIndexException} is thrown.
765         * </p>
766         * @param index  index location of entry to be fetched
767         * @return vector entry at index
768         * @throws MatrixIndexException if the index is not valid
769         * @see #setEntry(int, double)
770         */
771        double getEntry(int index)
772            throws MatrixIndexException;
773    
774        /**
775         * Set a single element.
776         * @param index element index.
777         * @param value new value for the element.
778         * @exception MatrixIndexException if the index is
779         * inconsistent with vector size
780         * @see #getEntry(int)
781         */
782        void setEntry(int index, double value)
783            throws MatrixIndexException;
784    
785        /**
786         * Returns the size of the vector.
787         * @return size
788         */
789        int getDimension();
790    
791        /**
792         * Construct a vector by appending a vector to this vector.
793         * @param v vector to append to this one.
794         * @return a new vector
795         */
796        RealVector append(RealVector v);
797    
798        /**
799         * Construct a vector by appending a double to this vector.
800         * @param d double to append.
801         * @return a new vector
802         */
803        RealVector append(double d);
804    
805        /**
806         * Construct a vector by appending a double array to this vector.
807         * @param a double array to append.
808         * @return a new vector
809         */
810        RealVector append(double[] a);
811    
812        /**
813         * Get a subvector from consecutive elements.
814         * @param index index of first element.
815         * @param n number of elements to be retrieved.
816         * @return a vector containing n elements.
817         * @exception MatrixIndexException if the index is
818         * inconsistent with vector size
819         */
820        RealVector getSubVector(int index, int n)
821            throws MatrixIndexException;
822    
823        /**
824         * Set a set of consecutive elements.
825         * @param index index of first element to be set.
826         * @param v vector containing the values to set.
827         * @exception MatrixIndexException if the index is
828         * inconsistent with vector size
829         * @see #setSubVector(int, double[])
830         */
831        void setSubVector(int index, RealVector v)
832            throws MatrixIndexException;
833    
834        /**
835         * Set a set of consecutive elements.
836         * @param index index of first element to be set.
837         * @param v vector containing the values to set.
838         * @exception MatrixIndexException if the index is
839         * inconsistent with vector size
840         * @see #setSubVector(int, RealVector)
841         */
842        void setSubVector(int index, double[] v)
843            throws MatrixIndexException;
844    
845        /**
846         * Set all elements to a single value.
847         * @param value single value to set for all elements
848         */
849        void set(double value);
850    
851        /**
852         * Convert the vector to a double array.
853         * <p>The array is independent from vector data, it's elements
854         * are copied.</p>
855         * @return array containing a copy of vector elements
856         */
857        double[] toArray();
858    
859        /**
860         * Returns true if any coordinate of this vector is NaN; false otherwise
861         * @return  true if any coordinate of this vector is NaN; false otherwise
862         */
863        boolean isNaN();
864    
865        /**
866         * Returns true if any coordinate of this vector is infinite and none are NaN;
867         * false otherwise
868         * @return  true if any coordinate of this vector is infinite and none are NaN;
869         * false otherwise
870         */
871        boolean isInfinite();
872    
873    }