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 $Id: FieldVector.java 1178171 2011-10-02 10:10:50Z luc $
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 this minus v.
071 * @param v vector to be subtracted
072 * @return this + v
073 * @throws IllegalArgumentException if v is not the same size as this
074 */
075 FieldVector<T> subtract(FieldVector<T> v)
076 throws IllegalArgumentException;
077
078 /**
079 * Map an addition operation to each entry.
080 * @param d value to be added to each entry
081 * @return this + d
082 */
083 FieldVector<T> mapAdd(T d);
084
085 /**
086 * Map an addition operation to each entry.
087 * <p>The instance <strong>is</strong> changed by this method.</p>
088 * @param d value to be added to each entry
089 * @return for convenience, return this
090 */
091 FieldVector<T> mapAddToSelf(T d);
092
093 /**
094 * Map a subtraction operation to each entry.
095 * @param d value to be subtracted to each entry
096 * @return this - d
097 */
098 FieldVector<T> mapSubtract(T d);
099
100 /**
101 * Map a subtraction operation to each entry.
102 * <p>The instance <strong>is</strong> changed by this method.</p>
103 * @param d value to be subtracted to each entry
104 * @return for convenience, return this
105 */
106 FieldVector<T> mapSubtractToSelf(T d);
107
108 /**
109 * Map a multiplication operation to each entry.
110 * @param d value to multiply all entries by
111 * @return this * d
112 */
113 FieldVector<T> mapMultiply(T d);
114
115 /**
116 * Map a multiplication operation to each entry.
117 * <p>The instance <strong>is</strong> changed by this method.</p>
118 * @param d value to multiply all entries by
119 * @return for convenience, return this
120 */
121 FieldVector<T> mapMultiplyToSelf(T d);
122
123 /**
124 * Map a division operation to each entry.
125 * @param d value to divide all entries by
126 * @return this / d
127 */
128 FieldVector<T> mapDivide(T d);
129
130 /**
131 * Map a division operation to each entry.
132 * <p>The instance <strong>is</strong> changed by this method.</p>
133 * @param d value to divide all entries by
134 * @return for convenience, return this
135 */
136 FieldVector<T> mapDivideToSelf(T d);
137
138 /**
139 * Map the 1/x function to each entry.
140 * @return a vector containing the result of applying the function to each entry
141 */
142 FieldVector<T> mapInv();
143
144 /**
145 * Map the 1/x function to each entry.
146 * <p>The instance <strong>is</strong> changed by this method.</p>
147 * @return for convenience, return this
148 */
149 FieldVector<T> mapInvToSelf();
150
151 /**
152 * Element-by-element multiplication.
153 * @param v vector by which instance elements must be multiplied
154 * @return a vector containing this[i] * v[i] for all i
155 * @throws IllegalArgumentException if v is not the same size as this
156 */
157 FieldVector<T> ebeMultiply(FieldVector<T> v) throws IllegalArgumentException;
158
159 /**
160 * Element-by-element division.
161 * @param v vector by which instance elements must be divided
162 * @return a vector containing this[i] / v[i] for all i
163 * @throws IllegalArgumentException if v is not the same size as this
164 */
165 FieldVector<T> ebeDivide(FieldVector<T> v) throws IllegalArgumentException;
166
167 /**
168 * Returns vector entries as a T array.
169 * @return T array of entries
170 */
171 T[] getData();
172
173 /**
174 * Compute the dot product.
175 * @param v vector with which dot product should be computed
176 * @return the scalar dot product between instance and v
177 * @exception IllegalArgumentException if v is not the same size as this
178 */
179 T dotProduct(FieldVector<T> v)
180 throws IllegalArgumentException;
181
182 /** Find the orthogonal projection of this vector onto another vector.
183 * @param v vector onto which instance must be projected
184 * @return projection of the instance onto v
185 * @throws IllegalArgumentException if v is not the same size as this
186 */
187 FieldVector<T> projection(FieldVector<T> v)
188 throws IllegalArgumentException;
189
190 /**
191 * Compute the outer product.
192 * @param v vector with which outer product should be computed
193 * @return the matrix outer product between instance and v
194 */
195 FieldMatrix<T> outerProduct(FieldVector<T> v);
196
197 /**
198 * Returns the entry in the specified index.
199 *
200 * @param index Index location of entry to be fetched.
201 * @return the vector entry at {@code index}.
202 * @throws org.apache.commons.math.exception.OutOfRangeException if the
203 * index is not valid.
204 * @see #setEntry(int, FieldElement)
205 */
206 T getEntry(int index);
207
208 /**
209 * Set a single element.
210 * @param index element index.
211 * @param value new value for the element.
212 * @throws org.apache.commons.math.exception.OutOfRangeException
213 * if the index is inconsistent with vector size.
214 * @see #getEntry(int)
215 */
216 void setEntry(int index, T value);
217
218 /**
219 * Returns the size of the vector.
220 * @return size
221 */
222 int getDimension();
223
224 /**
225 * Construct a vector by appending a vector to this vector.
226 * @param v vector to append to this one.
227 * @return a new vector
228 */
229 FieldVector<T> append(FieldVector<T> v);
230
231 /**
232 * Construct a vector by appending a T to this vector.
233 * @param d T to append.
234 * @return a new vector
235 */
236 FieldVector<T> append(T d);
237
238 /**
239 * Get a subvector from consecutive elements.
240 * @param index index of first element.
241 * @param n number of elements to be retrieved.
242 * @return a vector containing n elements.
243 * @throws org.apache.commons.math.exception.OutOfRangeException
244 * if the index is inconsistent with vector size.
245 */
246 FieldVector<T> getSubVector(int index, int n);
247
248 /**
249 * Set a set of consecutive elements.
250 * @param index index of first element to be set.
251 * @param v vector containing the values to set.
252 * @throws org.apache.commons.math.exception.OutOfRangeException
253 * if the index is inconsistent with vector size.
254 */
255 void setSubVector(int index, FieldVector<T> v);
256
257 /**
258 * Set all elements to a single value.
259 * @param value single value to set for all elements
260 */
261 void set(T value);
262
263 /**
264 * Convert the vector to a T array.
265 * <p>The array is independent from vector data, it's elements
266 * are copied.</p>
267 * @return array containing a copy of vector elements
268 */
269 T[] toArray();
270
271 }