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 }