    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>&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    }