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.math3.linear;
018
019 import org.apache.commons.math3.Field;
020 import org.apache.commons.math3.FieldElement;
021 import org.apache.commons.math3.exception.DimensionMismatchException;
022 import org.apache.commons.math3.exception.MathArithmeticException;
023 import org.apache.commons.math3.exception.NotPositiveException;
024 import org.apache.commons.math3.exception.NullArgumentException;
025 import org.apache.commons.math3.exception.OutOfRangeException;
026
027 /**
028 * Interface defining a field-valued vector with basic algebraic operations.
029 * <p>
030 * vector element indexing is 0-based -- e.g., <code>getEntry(0)</code>
031 * returns the first element of the vector.
032 * </p>
033 * <p>
034 * The various <code>mapXxx</code> and <code>mapXxxToSelf</code> methods operate
035 * on vectors element-wise, i.e. they perform the same operation (adding a scalar,
036 * applying a function ...) on each element in turn. The <code>mapXxx</code>
037 * versions create a new vector to hold the result and do not change the instance.
038 * The <code>mapXxxToSelf</code> versions use the instance itself to store the
039 * results, so the instance is changed by these methods. In both cases, the result
040 * vector is returned by the methods, this allows to use the <i>fluent API</i>
041 * style, like this:
042 * </p>
043 * <pre>
044 * RealVector result = v.mapAddToSelf(3.0).mapTanToSelf().mapSquareToSelf();
045 * </pre>
046 *
047 * @param <T> the type of the field elements
048 * @version $Id: FieldVector.java 1416643 2012-12-03 19:37:14Z tn $
049 * @since 2.0
050 */
051 public interface FieldVector<T extends FieldElement<T>> {
052
053 /**
054 * Get the type of field elements of the vector.
055 * @return type of field elements of the vector
056 */
057 Field<T> getField();
058
059 /**
060 * Returns a (deep) copy of this.
061 * @return vector copy
062 */
063 FieldVector<T> copy();
064
065 /**
066 * Compute the sum of {@code this} and {@code v}.
067 * @param v vector to be added
068 * @return {@code this + v}
069 * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
070 */
071 FieldVector<T> add(FieldVector<T> v) throws DimensionMismatchException;
072
073 /**
074 * Compute {@code this} minus {@code v}.
075 * @param v vector to be subtracted
076 * @return {@code this - v}
077 * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
078 */
079 FieldVector<T> subtract(FieldVector<T> v) throws DimensionMismatchException;
080
081 /**
082 * Map an addition operation to each entry.
083 * @param d value to be added to each entry
084 * @return {@code this + d}
085 * @throws NullArgumentException if {@code d} is {@code null}.
086 */
087 FieldVector<T> mapAdd(T d) throws NullArgumentException;
088
089 /**
090 * Map an addition operation to each entry.
091 * <p>The instance <strong>is</strong> changed by this method.</p>
092 * @param d value to be added to each entry
093 * @return for convenience, return {@code this}
094 * @throws NullArgumentException if {@code d} is {@code null}.
095 */
096 FieldVector<T> mapAddToSelf(T d) throws NullArgumentException;
097
098 /**
099 * Map a subtraction operation to each entry.
100 * @param d value to be subtracted to each entry
101 * @return {@code this - d}
102 * @throws NullArgumentException if {@code d} is {@code null}
103 */
104 FieldVector<T> mapSubtract(T d) throws NullArgumentException;
105
106 /**
107 * Map a subtraction operation to each entry.
108 * <p>The instance <strong>is</strong> changed by this method.</p>
109 * @param d value to be subtracted to each entry
110 * @return for convenience, return {@code this}
111 * @throws NullArgumentException if {@code d} is {@code null}
112 */
113 FieldVector<T> mapSubtractToSelf(T d) throws NullArgumentException;
114
115 /**
116 * Map a multiplication operation to each entry.
117 * @param d value to multiply all entries by
118 * @return {@code this * d}
119 * @throws NullArgumentException if {@code d} is {@code null}.
120 */
121 FieldVector<T> mapMultiply(T d) throws NullArgumentException;
122
123 /**
124 * Map a multiplication operation to each entry.
125 * <p>The instance <strong>is</strong> changed by this method.</p>
126 * @param d value to multiply all entries by
127 * @return for convenience, return {@code this}
128 * @throws NullArgumentException if {@code d} is {@code null}.
129 */
130 FieldVector<T> mapMultiplyToSelf(T d) throws NullArgumentException;
131
132 /**
133 * Map a division operation to each entry.
134 * @param d value to divide all entries by
135 * @return {@code this / d}
136 * @throws NullArgumentException if {@code d} is {@code null}.
137 * @throws MathArithmeticException if {@code d} is zero.
138 */
139 FieldVector<T> mapDivide(T d)
140 throws NullArgumentException, MathArithmeticException;
141
142 /**
143 * Map a division operation to each entry.
144 * <p>The instance <strong>is</strong> changed by this method.</p>
145 * @param d value to divide all entries by
146 * @return for convenience, return {@code this}
147 * @throws NullArgumentException if {@code d} is {@code null}.
148 * @throws MathArithmeticException if {@code d} is zero.
149 */
150 FieldVector<T> mapDivideToSelf(T d)
151 throws NullArgumentException, MathArithmeticException;
152
153 /**
154 * Map the 1/x function to each entry.
155 * @return a vector containing the result of applying the function to each entry.
156 * @throws MathArithmeticException if one of the entries is zero.
157 */
158 FieldVector<T> mapInv() throws MathArithmeticException;
159
160 /**
161 * Map the 1/x function to each entry.
162 * <p>The instance <strong>is</strong> changed by this method.</p>
163 * @return for convenience, return {@code this}
164 * @throws MathArithmeticException if one of the entries is zero.
165 */
166 FieldVector<T> mapInvToSelf() throws MathArithmeticException;
167
168 /**
169 * Element-by-element multiplication.
170 * @param v vector by which instance elements must be multiplied
171 * @return a vector containing {@code this[i] * v[i]} for all {@code i}
172 * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
173 */
174 FieldVector<T> ebeMultiply(FieldVector<T> v)
175 throws DimensionMismatchException;
176
177 /**
178 * Element-by-element division.
179 * @param v vector by which instance elements must be divided
180 * @return a vector containing {@code this[i] / v[i]} for all {@code i}
181 * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
182 * @throws MathArithmeticException if one entry of {@code v} is zero.
183 */
184 FieldVector<T> ebeDivide(FieldVector<T> v)
185 throws DimensionMismatchException, MathArithmeticException;
186
187 /**
188 * Returns vector entries as a T array.
189 * @return T array of entries
190 * @deprecated as of 3.1, to be removed in 4.0. Please use the {@link #toArray()} method instead.
191 */
192 @Deprecated
193 T[] getData();
194
195 /**
196 * Compute the dot product.
197 * @param v vector with which dot product should be computed
198 * @return the scalar dot product of {@code this} and {@code v}
199 * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
200 */
201 T dotProduct(FieldVector<T> v) throws DimensionMismatchException;
202
203 /**
204 * Find the orthogonal projection of this vector onto another vector.
205 * @param v vector onto which {@code this} must be projected
206 * @return projection of {@code this} onto {@code v}
207 * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
208 * @throws MathArithmeticException if {@code v} is the null vector.
209 */
210 FieldVector<T> projection(FieldVector<T> v)
211 throws DimensionMismatchException, MathArithmeticException;
212
213 /**
214 * Compute the outer product.
215 * @param v vector with which outer product should be computed
216 * @return the matrix outer product between instance and v
217 */
218 FieldMatrix<T> outerProduct(FieldVector<T> v);
219
220 /**
221 * Returns the entry in the specified index.
222 *
223 * @param index Index location of entry to be fetched.
224 * @return the vector entry at {@code index}.
225 * @throws OutOfRangeException if the index is not valid.
226 * @see #setEntry(int, FieldElement)
227 */
228 T getEntry(int index) throws OutOfRangeException;
229
230 /**
231 * Set a single element.
232 * @param index element index.
233 * @param value new value for the element.
234 * @throws OutOfRangeException if the index is not valid.
235 * @see #getEntry(int)
236 */
237 void setEntry(int index, T value) throws OutOfRangeException;
238
239 /**
240 * Returns the size of the vector.
241 * @return size
242 */
243 int getDimension();
244
245 /**
246 * Construct a vector by appending a vector to this vector.
247 * @param v vector to append to this one.
248 * @return a new vector
249 */
250 FieldVector<T> append(FieldVector<T> v);
251
252 /**
253 * Construct a vector by appending a T to this vector.
254 * @param d T to append.
255 * @return a new vector
256 */
257 FieldVector<T> append(T d);
258
259 /**
260 * Get a subvector from consecutive elements.
261 * @param index index of first element.
262 * @param n number of elements to be retrieved.
263 * @return a vector containing n elements.
264 * @throws OutOfRangeException if the index is not valid.
265 * @throws NotPositiveException if the number of elements if not positive.
266 */
267 FieldVector<T> getSubVector(int index, int n)
268 throws OutOfRangeException, NotPositiveException;
269
270 /**
271 * Set a set of consecutive elements.
272 * @param index index of first element to be set.
273 * @param v vector containing the values to set.
274 * @throws OutOfRangeException if the index is not valid.
275 */
276 void setSubVector(int index, FieldVector<T> v) throws OutOfRangeException;
277
278 /**
279 * Set all elements to a single value.
280 * @param value single value to set for all elements
281 */
282 void set(T value);
283
284 /**
285 * Convert the vector to a T array.
286 * <p>The array is independent from vector data, it's elements
287 * are copied.</p>
288 * @return array containing a copy of vector elements
289 */
290 T[] toArray();
291
292 }