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