1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17package org.apache.commons.math.linear;
18
19import org.apache.commons.math.Field;
20import org.apache.commons.math.FieldElement;
21
22/**
23 * Interface defining a field-valued vector with basic algebraic operations.
24 * <p>
25 * vector element indexing is 0-based -- e.g., <code>getEntry(0)</code>
26 * returns the first element of the vector.
27 * </p>
28 * <p>
29 * The various <code>mapXxx</code> and <code>mapXxxToSelf</code> methods operate
30 * on vectors element-wise, i.e. they perform the same operation (adding a scalar,
31 * applying a function ...) on each element in turn. The <code>mapXxx</code>
32 * versions create a new vector to hold the result and do not change the instance.
33 * The <code>mapXxxToSelf</code> versions use the instance itself to store the
34 * results, so the instance is changed by these methods. In both cases, the result
35 * vector is returned by the methods, this allows to use the <i>fluent API</i>
36 * style, like this:
37 * </p>
38 * <pre>
39 *   RealVector result = v.mapAddToSelf(3.0).mapTanToSelf().mapSquareToSelf();
40 * </pre>
41 *
42 * @param <T> the type of the field elements
43 * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $
44 * @since 2.0
45 */
46public interface FieldVector<T extends FieldElement<T>>  {
47
48    /**
49     * Get the type of field elements of the vector.
50     * @return type of field elements of the vector
51     */
52    Field<T> getField();
53
54    /**
55     * Returns a (deep) copy of this.
56     * @return vector copy
57     */
58    FieldVector<T> copy();
59
60    /**
61     * Compute the sum of this and v.
62     * @param v vector to be added
63     * @return this + v
64     * @throws IllegalArgumentException if v is not the same size as this
65     */
66    FieldVector<T> add(FieldVector<T> v)
67        throws IllegalArgumentException;
68
69    /**
70     * Compute the sum of this and v.
71     * @param v vector to be added
72     * @return this + v
73     * @throws IllegalArgumentException if v is not the same size as this
74     */
75    FieldVector<T> add(T[] v)
76        throws IllegalArgumentException;
77
78    /**
79     * Compute this minus v.
80     * @param v vector to be subtracted
81     * @return this + v
82     * @throws IllegalArgumentException if v is not the same size as this
83     */
84    FieldVector<T> subtract(FieldVector<T> v)
85        throws IllegalArgumentException;
86
87    /**
88     * Compute this minus v.
89     * @param v vector to be subtracted
90     * @return this + v
91     * @throws IllegalArgumentException if v is not the same size as this
92     */
93    FieldVector<T> subtract(T[] v)
94        throws IllegalArgumentException;
95
96    /**
97     * Map an addition operation to each entry.
98     * @param d value to be added to each entry
99     * @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}
359