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: 780674 $ $Date: 2009-06-01 11:10:55 -0400 (Mon, 01 Jun 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        public FieldVector<T> ebeMultiply(FieldVector<T> v)
176            throws IllegalArgumentException;
177    
178        /**
179         * Element-by-element multiplication.
180         * @param v vector by which instance elements must be multiplied
181         * @return a vector containing this[i] * v[i] for all i
182         * @throws IllegalArgumentException if v is not the same size as this
183         */
184        public FieldVector<T> ebeMultiply(T[] v)
185            throws IllegalArgumentException;
186    
187        /**
188         * Element-by-element division.
189         * @param v vector by which instance elements must be divided
190         * @return a vector containing this[i] / v[i] for all i
191         * @throws IllegalArgumentException if v is not the same size as this
192         */
193        public FieldVector<T> ebeDivide(FieldVector<T> v)
194            throws IllegalArgumentException;
195    
196        /**
197         * Element-by-element division.
198         * @param v vector by which instance elements must be divided
199         * @return a vector containing this[i] / v[i] for all i
200         * @throws IllegalArgumentException if v is not the same size as this
201         */
202        public FieldVector<T> ebeDivide(T[] v)
203            throws IllegalArgumentException;
204    
205        /**
206         * Returns vector entries as a T array.
207         * @return T array of entries
208         */
209         T[] getData();
210    
211        /**
212         * Compute the dot product.
213         * @param v vector with which dot product should be computed
214         * @return the scalar dot product between instance and v
215         * @exception IllegalArgumentException if v is not the same size as this
216         */
217        T dotProduct(FieldVector<T> v)
218            throws IllegalArgumentException;
219    
220        /**
221         * Compute the dot product.
222         * @param v vector with which dot product should be computed
223         * @return the scalar dot product between instance and v
224         * @exception IllegalArgumentException if v is not the same size as this
225         */
226        T dotProduct(T[] v)
227            throws IllegalArgumentException;
228    
229        /** Find the orthogonal projection of this vector onto another vector.
230         * @param v vector onto which instance must be projected
231         * @return projection of the instance onto v
232         * @throws IllegalArgumentException if v is not the same size as this
233         */
234        FieldVector<T> projection(FieldVector<T> v)
235            throws IllegalArgumentException;
236    
237        /** Find the orthogonal projection of this vector onto another vector.
238         * @param v vector onto which instance must be projected
239         * @return projection of the instance onto v
240         * @throws IllegalArgumentException if v is not the same size as this
241         */
242        FieldVector<T> projection(T[] v)
243            throws IllegalArgumentException;
244    
245        /**
246         * Compute the outer product.
247         * @param v vector with which outer product should be computed
248         * @return the square matrix outer product between instance and v
249         * @exception IllegalArgumentException if v is not the same size as this
250         */
251        FieldMatrix<T> outerProduct(FieldVector<T> v)
252            throws IllegalArgumentException;
253    
254        /**
255         * Compute the outer product.
256         * @param v vector with which outer product should be computed
257         * @return the square matrix outer product between instance and v
258         * @exception IllegalArgumentException if v is not the same size as this
259         */
260        FieldMatrix<T> outerProduct(T[] v)
261            throws IllegalArgumentException;
262    
263        /**
264         * Returns the entry in the specified index.
265         * <p>
266         * The index start at 0 and must be lesser than the size,
267         * otherwise a {@link MatrixIndexException} is thrown.
268         * </p>
269         * @param index  index location of entry to be fetched
270         * @return vector entry at index
271         * @throws MatrixIndexException if the index is not valid
272         * @see #setEntry(int, FieldElement)
273         */
274        T getEntry(int index)
275            throws MatrixIndexException;
276    
277        /**
278         * Set a single element.
279         * @param index element index.
280         * @param value new value for the element.
281         * @exception MatrixIndexException if the index is
282         * inconsistent with vector size
283         * @see #getEntry(int)
284         */
285        void setEntry(int index, T value)
286            throws MatrixIndexException;
287    
288        /**
289         * Returns the size of the vector.
290         * @return size
291         */
292        int getDimension();
293    
294        /**
295         * Construct a vector by appending a vector to this vector.
296         * @param v vector to append to this one.
297         * @return a new vector
298         */
299        FieldVector<T> append(FieldVector<T> v);
300    
301        /**
302         * Construct a vector by appending a T to this vector.
303         * @param d T to append.
304         * @return a new vector
305         */
306        FieldVector<T> append(T d);
307    
308        /**
309         * Construct a vector by appending a T array to this vector.
310         * @param a T array to append.
311         * @return a new vector
312         */
313        FieldVector<T> append(T[] a);
314    
315        /**
316         * Get a subvector from consecutive elements.
317         * @param index index of first element.
318         * @param n number of elements to be retrieved.
319         * @return a vector containing n elements.
320         * @exception MatrixIndexException if the index is
321         * inconsistent with vector size
322         */
323        FieldVector<T> getSubVector(int index, int n)
324            throws MatrixIndexException;
325    
326        /**
327         * Set a set of consecutive elements.
328         * @param index index of first element to be set.
329         * @param v vector containing the values to set.
330         * @exception MatrixIndexException if the index is
331         * inconsistent with vector size
332         * @see #setSubVector(int, FieldElement[])
333         */
334        void setSubVector(int index, FieldVector<T> v)
335            throws MatrixIndexException;
336    
337        /**
338         * Set a set of consecutive elements.
339         * @param index index of first element to be set.
340         * @param v vector containing the values to set.
341         * @exception MatrixIndexException if the index is
342         * inconsistent with vector size
343         * @see #setSubVector(int, FieldVector)
344         */
345        void setSubVector(int index, T[] v)
346            throws MatrixIndexException;
347    
348        /**
349         * Set all elements to a single value.
350         * @param value single value to set for all elements
351         */
352        void set(T value);
353    
354        /**
355         * Convert the vector to a T array.
356         * <p>The array is independent from vector data, it's elements
357         * are copied.</p>
358         * @return array containing a copy of vector elements
359         */
360        T[] toArray();
361    
362    }