    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 org.apache.commons.math.Field;
    020    import org.apache.commons.math.FieldElement;
    021
    022    /**
    023     * Interface defining a field-valued vector with basic algebraic operations.
    024     * <p>
    025     * vector element indexing is 0-based -- e.g., <code>getEntry(0)</code>
    026     * returns the first element of the vector.
    027     * </p>
    028     * <p>
    029     * The various <code>mapXxx</code> and <code>mapXxxToSelf</code> methods operate
    030     * on vectors element-wise, i.e. they perform the same operation (adding a scalar,
    031     * applying a function ...) on each element in turn. The <code>mapXxx</code>
    032     * versions create a new vector to hold the result and do not change the instance.
    033     * The <code>mapXxxToSelf</code> versions use the instance itself to store the
    034     * results, so the instance is changed by these methods. In both cases, the result
    035     * vector is returned by the methods, this allows to use the <i>fluent API</i>
    036     * style, like this:
    037     * </p>
    038     * <pre>
    039     *   RealVector result = v.mapAddToSelf(3.0).mapTanToSelf().mapSquareToSelf();
    040     * </pre>
    041     *
    042     * @param <T> the type of the field elements
    043     * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $
    044     * @since 2.0
    045     */
    046    public interface FieldVector<T extends FieldElement<T>>  {
    047
    048        /**
    049         * Get the type of field elements of the vector.
    050         * @return type of field elements of the vector
    051         */
    052        Field<T> getField();
    053
    054        /**
    055         * Returns a (deep) copy of this.
    056         * @return vector copy
    057         */
    058        FieldVector<T> copy();
    059
    060        /**
    061         * Compute the sum of this and v.
    062         * @param v vector to be added
    063         * @return this + v
    064         * @throws IllegalArgumentException if v is not the same size as this
    065         */
    066        FieldVector<T> add(FieldVector<T> v)
    067            throws IllegalArgumentException;
    068
    069        /**
    070         * Compute the sum of this and v.
    071         * @param v vector to be added
    072         * @return this + v
    073         * @throws IllegalArgumentException if v is not the same size as this
    074         */
    075        FieldVector<T> add(T[] v)
    076            throws IllegalArgumentException;
    077
    078        /**
    079         * Compute this minus v.
    080         * @param v vector to be subtracted
    081         * @return this + v
    082         * @throws IllegalArgumentException if v is not the same size as this
    083         */
    084        FieldVector<T> subtract(FieldVector<T> v)
    085            throws IllegalArgumentException;
    086
    087        /**
    088         * Compute this minus v.
    089         * @param v vector to be subtracted
    090         * @return this + v
    091         * @throws IllegalArgumentException if v is not the same size as this
    092         */
    093        FieldVector<T> subtract(T[] v)
    094            throws IllegalArgumentException;
    095
    096        /**
    097         * Map an addition operation to each entry.
    098         * @param d value to be added to each entry
    099         * @return this + d
    100         */
    101        FieldVector<T> mapAdd(T d);
    102
    103        /**
    104         * Map an addition operation to each entry.
    105         * <p>The instance <strong>is</strong> changed by this method.</p>
    106         * @param d value to be added to each entry
    107         * @return for convenience, return this
    108         */
    109        FieldVector<T> mapAddToSelf(T d);
    110
    111        /**
    112         * Map a subtraction operation to each entry.
    113         * @param d value to be subtracted to each entry
    114         * @return this - d
    115         */
    116        FieldVector<T> mapSubtract(T d);
    117
    118        /**
    119         * Map a subtraction operation to each entry.
    120         * <p>The instance <strong>is</strong> changed by this method.</p>
    121         * @param d value to be subtracted to each entry
    122         * @return for convenience, return this
    123         */
    124        FieldVector<T> mapSubtractToSelf(T d);
    125
    126        /**
    127         * Map a multiplication operation to each entry.
    128         * @param d value to multiply all entries by
    129         * @return this * d
    130         */
    131        FieldVector<T> mapMultiply(T d);
    132
    133        /**
    134         * Map a multiplication operation to each entry.
    135         * <p>The instance <strong>is</strong> changed by this method.</p>
    136         * @param d value to multiply all entries by
    137         * @return for convenience, return this
    138         */
    139        FieldVector<T> mapMultiplyToSelf(T d);
    140
    141        /**
    142         * Map a division operation to each entry.
    143         * @param d value to divide all entries by
    144         * @return this / d
    145         */
    146        FieldVector<T> mapDivide(T d);
    147
    148        /**
    149         * Map a division operation to each entry.
    150         * <p>The instance <strong>is</strong> changed by this method.</p>
    151         * @param d value to divide all entries by
    152         * @return for convenience, return this
    153         */
    154        FieldVector<T> mapDivideToSelf(T d);
    155
    156        /**
    157         * Map the 1/x function to each entry.
    158         * @return a vector containing the result of applying the function to each entry
    159         */
    160        FieldVector<T> mapInv();
    161
    162        /**
    163         * Map the 1/x function to each entry.
    164         * <p>The instance <strong>is</strong> changed by this method.</p>
    165         * @return for convenience, return this
    166         */
    167        FieldVector<T> mapInvToSelf();
    168
    169        /**
    170         * Element-by-element multiplication.
    171         * @param v vector by which instance elements must be multiplied
    172         * @return a vector containing this[i] * v[i] for all i
    173         * @throws IllegalArgumentException if v is not the same size as this
    174         */
    175        FieldVector<T> ebeMultiply(FieldVector<T> v) throws IllegalArgumentException;
    176
    177        /**
    178         * Element-by-element multiplication.
    179         * @param v vector by which instance elements must be multiplied
    180         * @return a vector containing this[i] * v[i] for all i
    181         * @throws IllegalArgumentException if v is not the same size as this
    182         */
    183        FieldVector<T> ebeMultiply(T[] v) throws IllegalArgumentException;
    184
    185        /**
    186         * Element-by-element division.
    187         * @param v vector by which instance elements must be divided
    188         * @return a vector containing this[i] / v[i] for all i
    189         * @throws IllegalArgumentException if v is not the same size as this
    190         */
    191        FieldVector<T> ebeDivide(FieldVector<T> v) throws IllegalArgumentException;
    192
    193        /**
    194         * Element-by-element division.
    195         * @param v vector by which instance elements must be divided
    196         * @return a vector containing this[i] / v[i] for all i
    197         * @throws IllegalArgumentException if v is not the same size as this
    198         */
    199        FieldVector<T> ebeDivide(T[] v) throws IllegalArgumentException;
    200
    201        /**
    202         * Returns vector entries as a T array.
    203         * @return T array of entries
    204         */
    205         T[] getData();
    206
    207        /**
    208         * Compute the dot product.
    209         * @param v vector with which dot product should be computed
    210         * @return the scalar dot product between instance and v
    211         * @exception IllegalArgumentException if v is not the same size as this
    212         */
    213        T dotProduct(FieldVector<T> v)
    214            throws IllegalArgumentException;
    215
    216        /**
    217         * Compute the dot product.
    218         * @param v vector with which dot product should be computed
    219         * @return the scalar dot product between instance and v
    220         * @exception IllegalArgumentException if v is not the same size as this
    221         */
    222        T dotProduct(T[] v)
    223            throws IllegalArgumentException;
    224
    225        /** Find the orthogonal projection of this vector onto another vector.
    226         * @param v vector onto which instance must be projected
    227         * @return projection of the instance onto v
    228         * @throws IllegalArgumentException if v is not the same size as this
    229         */
    230        FieldVector<T> projection(FieldVector<T> v)
    231            throws IllegalArgumentException;
    232
    233        /** Find the orthogonal projection of this vector onto another vector.
    234         * @param v vector onto which instance must be projected
    235         * @return projection of the instance onto v
    236         * @throws IllegalArgumentException if v is not the same size as this
    237         */
    238        FieldVector<T> projection(T[] v)
    239            throws IllegalArgumentException;
    240
    241        /**
    242         * Compute the outer product.
    243         * @param v vector with which outer product should be computed
    244         * @return the square matrix outer product between instance and v
    245         * @exception IllegalArgumentException if v is not the same size as this
    246         */
    247        FieldMatrix<T> outerProduct(FieldVector<T> v)
    248            throws IllegalArgumentException;
    249
    250        /**
    251         * Compute the outer product.
    252         * @param v vector with which outer product should be computed
    253         * @return the square matrix outer product between instance and v
    254         * @exception IllegalArgumentException if v is not the same size as this
    255         */
    256        FieldMatrix<T> outerProduct(T[] v)
    257            throws IllegalArgumentException;
    258
    259        /**
    260         * Returns the entry in the specified index.
    261         * <p>
    262         * The index start at 0 and must be lesser than the size,
    263         * otherwise a {@link MatrixIndexException} is thrown.
    264         * </p>
    265         * @param index  index location of entry to be fetched
    266         * @return vector entry at index
    267         * @throws MatrixIndexException if the index is not valid
    268         * @see #setEntry(int, FieldElement)
    269         */
    270        T getEntry(int index)
    271            throws MatrixIndexException;
    272
    273        /**
    274         * Set a single element.
    275         * @param index element index.
    276         * @param value new value for the element.
    277         * @exception MatrixIndexException if the index is
    278         * inconsistent with vector size
    279         * @see #getEntry(int)
    280         */
    281        void setEntry(int index, T value)
    282            throws MatrixIndexException;
    283
    284        /**
    285         * Returns the size of the vector.
    286         * @return size
    287         */
    288        int getDimension();
    289
    290        /**
    291         * Construct a vector by appending a vector to this vector.
    292         * @param v vector to append to this one.
    293         * @return a new vector
    294         */
    295        FieldVector<T> append(FieldVector<T> v);
    296
    297        /**
    298         * Construct a vector by appending a T to this vector.
    299         * @param d T to append.
    300         * @return a new vector
    301         */
    302        FieldVector<T> append(T d);
    303
    304        /**
    305         * Construct a vector by appending a T array to this vector.
    306         * @param a T array to append.
    307         * @return a new vector
    308         */
    309        FieldVector<T> append(T[] a);
    310
    311        /**
    312         * Get a subvector from consecutive elements.
    313         * @param index index of first element.
    314         * @param n number of elements to be retrieved.
    315         * @return a vector containing n elements.
    316         * @exception MatrixIndexException if the index is
    317         * inconsistent with vector size
    318         */
    319        FieldVector<T> getSubVector(int index, int n)
    320            throws MatrixIndexException;
    321
    322        /**
    323         * Set a set of consecutive elements.
    324         * @param index index of first element to be set.
    325         * @param v vector containing the values to set.
    326         * @exception MatrixIndexException if the index is
    327         * inconsistent with vector size
    328         * @see #setSubVector(int, FieldElement[])
    329         */
    330        void setSubVector(int index, FieldVector<T> v)
    331            throws MatrixIndexException;
    332
    333        /**
    334         * Set a set of consecutive elements.
    335         * @param index index of first element to be set.
    336         * @param v vector containing the values to set.
    337         * @exception MatrixIndexException if the index is
    338         * inconsistent with vector size
    339         * @see #setSubVector(int, FieldVector)
    340         */
    341        void setSubVector(int index, T[] v)
    342            throws MatrixIndexException;
    343
    344        /**
    345         * Set all elements to a single value.
    346         * @param value single value to set for all elements
    347         */
    348        void set(T value);
    349
    350        /**
    351         * Convert the vector to a T array.
    352         * <p>The array is independent from vector data, it's elements
    353         * are copied.</p>
    354         * @return array containing a copy of vector elements
    355         */
    356        T[] toArray();
    357
    358    }