View Javadoc

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   */
17  package org.apache.commons.math.linear;
18  
19  import org.apache.commons.math.Field;
20  import 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: 780674 $ $Date: 2009-06-01 11:10:55 -0400 (Mon, 01 Jun 2009) $
44   * @since 2.0
45   */
46  public 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     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 }