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 */
017package org.apache.commons.math4.legacy.linear;
018
019import org.apache.commons.math4.legacy.core.Field;
020import org.apache.commons.math4.legacy.core.FieldElement;
021import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
022import org.apache.commons.math4.legacy.exception.MathArithmeticException;
023import org.apache.commons.math4.legacy.exception.NotPositiveException;
024import org.apache.commons.math4.legacy.exception.NullArgumentException;
025import org.apache.commons.math4.legacy.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 * <p>
047 * Note that as almost all operations on {@link FieldElement} throw {@link
048 * NullArgumentException} when operating on a null element, it is the responsibility
049 * of <code>FieldVector</code> implementations to make sure no null elements
050 * are inserted into the vector. This must be done in all constructors and
051 * all setters.
052 * </p>
053 *
054 * @param <T> the type of the field elements
055 * @since 2.0
056 */
057public interface FieldVector<T extends FieldElement<T>>  {
058
059    /**
060     * Get the type of field elements of the vector.
061     * @return type of field elements of the vector
062     */
063    Field<T> getField();
064
065    /**
066     * Returns a (deep) copy of this.
067     * @return vector copy
068     */
069    FieldVector<T> copy();
070
071    /**
072     * Compute the sum of {@code this} and {@code v}.
073     * @param v vector to be added
074     * @return {@code this + v}
075     * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
076     */
077    FieldVector<T> add(FieldVector<T> v) throws DimensionMismatchException;
078
079    /**
080     * Compute {@code this} minus {@code v}.
081     * @param v vector to be subtracted
082     * @return {@code this - v}
083     * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
084     */
085    FieldVector<T> subtract(FieldVector<T> v) throws DimensionMismatchException;
086
087    /**
088     * Map an addition operation to each entry.
089     * @param d value to be added to each entry
090     * @return {@code this + d}
091     * @throws NullArgumentException if {@code d} is {@code null}.
092     */
093    FieldVector<T> mapAdd(T d) throws NullArgumentException;
094
095    /**
096     * Map an addition operation to each entry.
097     * <p>The instance <strong>is</strong> changed by this method.</p>
098     * @param d value to be added to each entry
099     * @return for convenience, return {@code this}
100     * @throws NullArgumentException if {@code d} is {@code null}.
101     */
102    FieldVector<T> mapAddToSelf(T d) throws NullArgumentException;
103
104    /**
105     * Map a subtraction operation to each entry.
106     * @param d value to be subtracted to each entry
107     * @return {@code this - d}
108     * @throws NullArgumentException if {@code d} is {@code null}
109     */
110    FieldVector<T> mapSubtract(T d) throws NullArgumentException;
111
112    /**
113     * Map a subtraction operation to each entry.
114     * <p>The instance <strong>is</strong> changed by this method.</p>
115     * @param d value to be subtracted to each entry
116     * @return for convenience, return {@code this}
117     * @throws NullArgumentException if {@code d} is {@code null}
118     */
119    FieldVector<T> mapSubtractToSelf(T d) throws NullArgumentException;
120
121    /**
122     * Map a multiplication operation to each entry.
123     * @param d value to multiply all entries by
124     * @return {@code this * d}
125     * @throws NullArgumentException if {@code d} is {@code null}.
126     */
127    FieldVector<T> mapMultiply(T d) throws NullArgumentException;
128
129    /**
130     * Map a multiplication operation to each entry.
131     * <p>The instance <strong>is</strong> changed by this method.</p>
132     * @param d value to multiply all entries by
133     * @return for convenience, return {@code this}
134     * @throws NullArgumentException if {@code d} is {@code null}.
135     */
136    FieldVector<T> mapMultiplyToSelf(T d) throws NullArgumentException;
137
138    /**
139     * Map a division operation to each entry.
140     * @param d value to divide all entries by
141     * @return {@code this / d}
142     * @throws NullArgumentException if {@code d} is {@code null}.
143     * @throws MathArithmeticException if {@code d} is zero.
144     */
145    FieldVector<T> mapDivide(T d)
146        throws NullArgumentException, MathArithmeticException;
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 {@code this}
153     * @throws NullArgumentException if {@code d} is {@code null}.
154     * @throws MathArithmeticException if {@code d} is zero.
155     */
156    FieldVector<T> mapDivideToSelf(T d)
157        throws NullArgumentException, MathArithmeticException;
158
159    /**
160     * Map the 1/x function to each entry.
161     * @return a vector containing the result of applying the function to each entry.
162     * @throws MathArithmeticException if one of the entries is zero.
163     */
164    FieldVector<T> mapInv() throws MathArithmeticException;
165
166    /**
167     * Map the 1/x function to each entry.
168     * <p>The instance <strong>is</strong> changed by this method.</p>
169     * @return for convenience, return {@code this}
170     * @throws MathArithmeticException if one of the entries is zero.
171     */
172    FieldVector<T> mapInvToSelf() throws MathArithmeticException;
173
174    /**
175     * Element-by-element multiplication.
176     * @param v vector by which instance elements must be multiplied
177     * @return a vector containing {@code this[i] * v[i]} for all {@code i}
178     * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
179     */
180    FieldVector<T> ebeMultiply(FieldVector<T> v)
181        throws DimensionMismatchException;
182
183    /**
184     * Element-by-element division.
185     * @param v vector by which instance elements must be divided
186     * @return a vector containing {@code this[i] / v[i]} for all {@code i}
187     * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
188     * @throws MathArithmeticException if one entry of {@code v} is zero.
189     */
190    FieldVector<T> ebeDivide(FieldVector<T> v)
191        throws DimensionMismatchException, MathArithmeticException;
192
193    /**
194     * Compute the dot product.
195     * @param v vector with which dot product should be computed
196     * @return the scalar dot product of {@code this} and {@code v}
197     * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
198     */
199    T dotProduct(FieldVector<T> v) throws DimensionMismatchException;
200
201    /**
202     * Find the orthogonal projection of this vector onto another vector.
203     * @param v vector onto which {@code this} must be projected
204     * @return projection of {@code this} onto {@code v}
205     * @throws DimensionMismatchException if {@code v} is not the same size as {@code this}
206     * @throws MathArithmeticException if {@code v} is the null vector.
207     */
208    FieldVector<T> projection(FieldVector<T> v)
209        throws DimensionMismatchException, MathArithmeticException;
210
211    /**
212     * Compute the outer product.
213     * @param v vector with which outer product should be computed
214     * @return the matrix outer product between instance and v
215     */
216    FieldMatrix<T> outerProduct(FieldVector<T> v);
217
218    /**
219     * Returns the entry in the specified index.
220     *
221     * @param index Index location of entry to be fetched.
222     * @return the vector entry at {@code index}.
223     * @throws OutOfRangeException if the index is not valid.
224     * @see #setEntry(int, FieldElement)
225     */
226    T getEntry(int index) throws OutOfRangeException;
227
228    /**
229     * Set a single element.
230     * @param index element index.
231     * @param value new value for the element.
232     * @throws OutOfRangeException if the index is not valid.
233     * @see #getEntry(int)
234     */
235    void setEntry(int index, T value) throws OutOfRangeException;
236
237    /**
238     * Returns the size of the vector.
239     * @return size
240     */
241    int getDimension();
242
243    /**
244     * Construct a vector by appending a vector to this vector.
245     * @param v vector to append to this one.
246     * @return a new vector
247     */
248    FieldVector<T> append(FieldVector<T> v);
249
250    /**
251     * Construct a vector by appending a T to this vector.
252     * @param d T to append.
253     * @return a new vector
254     */
255    FieldVector<T> append(T d);
256
257    /**
258     * Get a subvector from consecutive elements.
259     * @param index index of first element.
260     * @param n number of elements to be retrieved.
261     * @return a vector containing n elements.
262     * @throws OutOfRangeException if the index is not valid.
263     * @throws NotPositiveException if the number of elements if not positive.
264     */
265    FieldVector<T> getSubVector(int index, int n)
266        throws OutOfRangeException, NotPositiveException;
267
268    /**
269     * Set a set of consecutive elements.
270     * @param index index of first element to be set.
271     * @param v vector containing the values to set.
272     * @throws OutOfRangeException if the index is not valid.
273     */
274    void setSubVector(int index, FieldVector<T> v) throws OutOfRangeException;
275
276    /**
277     * Set all elements to a single value.
278     * @param value single value to set for all elements
279     */
280    void set(T value);
281
282    /**
283     * Convert the vector to a T array.
284     * <p>The array is independent from vector data, it's elements
285     * are copied.</p>
286     * @return array containing a copy of vector elements
287     */
288    T[] toArray();
289}