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 }