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 }