org.apache.commons.math.linear.RealVector Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-math Show documentation
Show all versions of commons-math Show documentation
The Math project is a library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems not immediately available in the Java programming language or commons-lang.
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.math.linear;
/**
* Interface defining a real-valued vector with basic algebraic operations.
*
* vector element indexing is 0-based -- e.g., getEntry(0)
* returns the first element of the vector.
*
*
* The various mapXxx and mapXxxToSelf methods operate
* on vectors element-wise, i.e. they perform the same operation (adding a scalar,
* applying a function ...) on each element in turn. The mapXxx
* versions create a new vector to hold the result and do not change the instance.
* The mapXxxToSelf versions use the instance itself to store the
* results, so the instance is changed by these methods. In both cases, the result
* vector is returned by the methods, this allows to use the fluent API
* style, like this:
*
*
* RealVector result = v.mapAddToSelf(3.0).mapTanToSelf().mapSquareToSelf();
*
*
* @version $Revision: 778058 $ $Date: 2009-05-23 18:57:26 -0400 (Sat, 23 May 2009) $
* @since 2.0
*/
public interface RealVector {
/**
* Returns a (deep) copy of this.
* @return vector copy
*/
RealVector copy();
/**
* Compute the sum of this and v.
* @param v vector to be added
* @return this + v
* @throws IllegalArgumentException if v is not the same size as this
*/
RealVector add(RealVector v)
throws IllegalArgumentException;
/**
* Compute the sum of this and v.
* @param v vector to be added
* @return this + v
* @throws IllegalArgumentException if v is not the same size as this
*/
RealVector add(double[] v)
throws IllegalArgumentException;
/**
* Compute this minus v.
* @param v vector to be subtracted
* @return this + v
* @throws IllegalArgumentException if v is not the same size as this
*/
RealVector subtract(RealVector v)
throws IllegalArgumentException;
/**
* Compute this minus v.
* @param v vector to be subtracted
* @return this + v
* @throws IllegalArgumentException if v is not the same size as this
*/
RealVector subtract(double[] v)
throws IllegalArgumentException;
/**
* Map an addition operation to each entry.
* @param d value to be added to each entry
* @return this + d
*/
RealVector mapAdd(double d);
/**
* Map an addition operation to each entry.
* The instance is changed by this method.
* @param d value to be added to each entry
* @return for convenience, return this
*/
RealVector mapAddToSelf(double d);
/**
* Map a subtraction operation to each entry.
* @param d value to be subtracted to each entry
* @return this - d
*/
RealVector mapSubtract(double d);
/**
* Map a subtraction operation to each entry.
* The instance is changed by this method.
* @param d value to be subtracted to each entry
* @return for convenience, return this
*/
RealVector mapSubtractToSelf(double d);
/**
* Map a multiplication operation to each entry.
* @param d value to multiply all entries by
* @return this * d
*/
RealVector mapMultiply(double d);
/**
* Map a multiplication operation to each entry.
* The instance is changed by this method.
* @param d value to multiply all entries by
* @return for convenience, return this
*/
RealVector mapMultiplyToSelf(double d);
/**
* Map a division operation to each entry.
* @param d value to divide all entries by
* @return this / d
*/
RealVector mapDivide(double d);
/**
* Map a division operation to each entry.
* The instance is changed by this method.
* @param d value to divide all entries by
* @return for convenience, return this
*/
RealVector mapDivideToSelf(double d);
/**
* Map a power operation to each entry.
* @param d value to raise all entries to
* @return this ^ d
*/
RealVector mapPow(double d);
/**
* Map a power operation to each entry.
* The instance is changed by this method.
* @param d value to raise all entries to
* @return for convenience, return this
*/
RealVector mapPowToSelf(double d);
/**
* Map the {@link Math#exp(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapExp();
/**
* Map the {@link Math#exp(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapExpToSelf();
/**
* Map the {@link Math#expm1(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapExpm1();
/**
* Map the {@link Math#expm1(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapExpm1ToSelf();
/**
* Map the {@link Math#log(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapLog();
/**
* Map the {@link Math#log(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapLogToSelf();
/**
* Map the {@link Math#log10(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapLog10();
/**
* Map the {@link Math#log10(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapLog10ToSelf();
/**
* Map the {@link Math#log1p(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapLog1p();
/**
* Map the {@link Math#log1p(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapLog1pToSelf();
/**
* Map the {@link Math#cosh(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapCosh();
/**
* Map the {@link Math#cosh(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapCoshToSelf();
/**
* Map the {@link Math#sinh(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapSinh();
/**
* Map the {@link Math#sinh(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapSinhToSelf();
/**
* Map the {@link Math#tanh(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapTanh();
/**
* Map the {@link Math#tanh(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapTanhToSelf();
/**
* Map the {@link Math#cos(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapCos();
/**
* Map the {@link Math#cos(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapCosToSelf();
/**
* Map the {@link Math#sin(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapSin();
/**
* Map the {@link Math#sin(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapSinToSelf();
/**
* Map the {@link Math#tan(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapTan();
/**
* Map the {@link Math#tan(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapTanToSelf();
/**
* Map the {@link Math#acos(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapAcos();
/**
* Map the {@link Math#acos(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapAcosToSelf();
/**
* Map the {@link Math#asin(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapAsin();
/**
* Map the {@link Math#asin(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapAsinToSelf();
/**
* Map the {@link Math#atan(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapAtan();
/**
* Map the {@link Math#atan(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapAtanToSelf();
/**
* Map the 1/x function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapInv();
/**
* Map the 1/x function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapInvToSelf();
/**
* Map the {@link Math#abs(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapAbs();
/**
* Map the {@link Math#abs(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapAbsToSelf();
/**
* Map the {@link Math#sqrt(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapSqrt();
/**
* Map the {@link Math#sqrt(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapSqrtToSelf();
/**
* Map the {@link Math#cbrt(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapCbrt();
/**
* Map the {@link Math#cbrt(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapCbrtToSelf();
/**
* Map the {@link Math#ceil(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapCeil();
/**
* Map the {@link Math#ceil(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapCeilToSelf();
/**
* Map the {@link Math#floor(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapFloor();
/**
* Map the {@link Math#floor(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapFloorToSelf();
/**
* Map the {@link Math#rint(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapRint();
/**
* Map the {@link Math#rint(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapRintToSelf();
/**
* Map the {@link Math#signum(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapSignum();
/**
* Map the {@link Math#signum(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapSignumToSelf();
/**
* Map the {@link Math#ulp(double)} function to each entry.
* @return a vector containing the result of applying the function to each entry
*/
RealVector mapUlp();
/**
* Map the {@link Math#ulp(double)} function to each entry.
* The instance is changed by this method.
* @return for convenience, return this
*/
RealVector mapUlpToSelf();
/**
* Element-by-element multiplication.
* @param v vector by which instance elements must be multiplied
* @return a vector containing this[i] * v[i] for all i
* @throws IllegalArgumentException if v is not the same size as this
*/
public RealVector ebeMultiply(RealVector v)
throws IllegalArgumentException;
/**
* Element-by-element multiplication.
* @param v vector by which instance elements must be multiplied
* @return a vector containing this[i] * v[i] for all i
* @throws IllegalArgumentException if v is not the same size as this
*/
public RealVector ebeMultiply(double[] v)
throws IllegalArgumentException;
/**
* Element-by-element division.
* @param v vector by which instance elements must be divided
* @return a vector containing this[i] / v[i] for all i
* @throws IllegalArgumentException if v is not the same size as this
*/
public RealVector ebeDivide(RealVector v)
throws IllegalArgumentException;
/**
* Element-by-element division.
* @param v vector by which instance elements must be divided
* @return a vector containing this[i] / v[i] for all i
* @throws IllegalArgumentException if v is not the same size as this
*/
public RealVector ebeDivide(double[] v)
throws IllegalArgumentException;
/**
* Returns vector entries as a double array.
* @return double array of entries
*/
double[] getData();
/**
* Compute the dot product.
* @param v vector with which dot product should be computed
* @return the scalar dot product between instance and v
* @exception IllegalArgumentException if v is not the same size as this
*/
double dotProduct(RealVector v)
throws IllegalArgumentException;
/**
* Compute the dot product.
* @param v vector with which dot product should be computed
* @return the scalar dot product between instance and v
* @exception IllegalArgumentException if v is not the same size as this
*/
double dotProduct(double[] v)
throws IllegalArgumentException;
/**
* Returns the L2 norm of the vector.
* The L2 norm is the root of the sum of
* the squared elements.
* @return norm
* @see #getL1Norm()
* @see #getLInfNorm()
* @see #getDistance(RealVector)
*/
double getNorm();
/**
* Returns the L1 norm of the vector.
* The L1 norm is the sum of the absolute
* values of elements.
* @return norm
* @see #getNorm()
* @see #getLInfNorm()
* @see #getL1Distance(RealVector)
*/
double getL1Norm();
/**
* Returns the L∞ norm of the vector.
* The L∞ norm is the max of the absolute
* values of elements.
* @return norm
* @see #getNorm()
* @see #getL1Norm()
* @see #getLInfDistance(RealVector)
*/
double getLInfNorm();
/**
* Distance between two vectors.
* This method computes the distance consistent with the
* L2 norm, i.e. the square root of the sum of
* elements differences, or euclidian distance.
* @param v vector to which distance is requested
* @return distance between two vectors.
* @exception IllegalArgumentException if v is not the same size as this
* @see #getL1Distance(RealVector)
* @see #getLInfDistance(RealVector)
* @see #getNorm()
*/
double getDistance(RealVector v)
throws IllegalArgumentException;
/**
* Distance between two vectors.
* This method computes the distance consistent with the
* L2 norm, i.e. the square root of the sum of
* elements differences, or euclidian distance.
* @param v vector to which distance is requested
* @return distance between two vectors.
* @exception IllegalArgumentException if v is not the same size as this
* @see #getL1Distance(double[])
* @see #getLInfDistance(double[])
* @see #getNorm()
*/
double getDistance(double[] v)
throws IllegalArgumentException;
/**
* Distance between two vectors.
* This method computes the distance consistent with
* L1 norm, i.e. the sum of the absolute values of
* elements differences.
* @param v vector to which distance is requested
* @return distance between two vectors.
* @exception IllegalArgumentException if v is not the same size as this
* @see #getDistance(RealVector)
* @see #getLInfDistance(RealVector)
* @see #getL1Norm()
*/
double getL1Distance(RealVector v)
throws IllegalArgumentException;
/**
* Distance between two vectors.
* This method computes the distance consistent with
* L1 norm, i.e. the sum of the absolute values of
* elements differences.
* @param v vector to which distance is requested
* @return distance between two vectors.
* @exception IllegalArgumentException if v is not the same size as this
* @see #getDistance(double[])
* @see #getLInfDistance(double[])
* @see #getL1Norm()
*/
double getL1Distance(double[] v)
throws IllegalArgumentException;
/**
* Distance between two vectors.
* This method computes the distance consistent with
* L∞ norm, i.e. the max of the absolute values of
* elements differences.
* @param v vector to which distance is requested
* @return distance between two vectors.
* @exception IllegalArgumentException if v is not the same size as this
* @see #getDistance(RealVector)
* @see #getL1Distance(RealVector)
* @see #getLInfNorm()
*/
double getLInfDistance(RealVector v)
throws IllegalArgumentException;
/**
* Distance between two vectors.
* This method computes the distance consistent with
* L∞ norm, i.e. the max of the absolute values of
* elements differences.
* @param v vector to which distance is requested
* @return distance between two vectors.
* @exception IllegalArgumentException if v is not the same size as this
* @see #getDistance(double[])
* @see #getL1Distance(double[])
* @see #getLInfNorm()
*/
double getLInfDistance(double[] v)
throws IllegalArgumentException;
/** Creates a unit vector pointing in the direction of this vector.
* The instance is not changed by this method.
* @return a unit vector pointing in direction of this vector
* @exception ArithmeticException if the norm is null
*/
RealVector unitVector();
/** Converts this vector into a unit vector.
* The instance itself is changed by this method.
* @exception ArithmeticException if the norm is null
*/
void unitize();
/** Find the orthogonal projection of this vector onto another vector.
* @param v vector onto which instance must be projected
* @return projection of the instance onto v
* @throws IllegalArgumentException if v is not the same size as this
*/
RealVector projection(RealVector v)
throws IllegalArgumentException;
/** Find the orthogonal projection of this vector onto another vector.
* @param v vector onto which instance must be projected
* @return projection of the instance onto v
* @throws IllegalArgumentException if v is not the same size as this
*/
RealVector projection(double[] v)
throws IllegalArgumentException;
/**
* Compute the outer product.
* @param v vector with which outer product should be computed
* @return the square matrix outer product between instance and v
* @exception IllegalArgumentException if v is not the same size as this
*/
RealMatrix outerProduct(RealVector v)
throws IllegalArgumentException;
/**
* Compute the outer product.
* @param v vector with which outer product should be computed
* @return the square matrix outer product between instance and v
* @exception IllegalArgumentException if v is not the same size as this
*/
RealMatrix outerProduct(double[] v)
throws IllegalArgumentException;
/**
* Returns the entry in the specified index.
*
* The index start at 0 and must be lesser than the size,
* otherwise a {@link MatrixIndexException} is thrown.
*
* @param index index location of entry to be fetched
* @return vector entry at index
* @throws MatrixIndexException if the index is not valid
* @see #setEntry(int, double)
*/
double getEntry(int index)
throws MatrixIndexException;
/**
* Set a single element.
* @param index element index.
* @param value new value for the element.
* @exception MatrixIndexException if the index is
* inconsistent with vector size
* @see #getEntry(int)
*/
void setEntry(int index, double value)
throws MatrixIndexException;
/**
* Returns the size of the vector.
* @return size
*/
int getDimension();
/**
* Construct a vector by appending a vector to this vector.
* @param v vector to append to this one.
* @return a new vector
*/
RealVector append(RealVector v);
/**
* Construct a vector by appending a double to this vector.
* @param d double to append.
* @return a new vector
*/
RealVector append(double d);
/**
* Construct a vector by appending a double array to this vector.
* @param a double array to append.
* @return a new vector
*/
RealVector append(double[] a);
/**
* Get a subvector from consecutive elements.
* @param index index of first element.
* @param n number of elements to be retrieved.
* @return a vector containing n elements.
* @exception MatrixIndexException if the index is
* inconsistent with vector size
*/
RealVector getSubVector(int index, int n)
throws MatrixIndexException;
/**
* Set a set of consecutive elements.
* @param index index of first element to be set.
* @param v vector containing the values to set.
* @exception MatrixIndexException if the index is
* inconsistent with vector size
* @see #setSubVector(int, double[])
*/
void setSubVector(int index, RealVector v)
throws MatrixIndexException;
/**
* Set a set of consecutive elements.
* @param index index of first element to be set.
* @param v vector containing the values to set.
* @exception MatrixIndexException if the index is
* inconsistent with vector size
* @see #setSubVector(int, RealVector)
*/
void setSubVector(int index, double[] v)
throws MatrixIndexException;
/**
* Set all elements to a single value.
* @param value single value to set for all elements
*/
void set(double value);
/**
* Convert the vector to a double array.
* The array is independent from vector data, it's elements
* are copied.
* @return array containing a copy of vector elements
*/
double[] toArray();
/**
* Returns true if any coordinate of this vector is NaN; false otherwise
* @return true if any coordinate of this vector is NaN; false otherwise
*/
public boolean isNaN();
/**
* Returns true if any coordinate of this vector is infinite and none are NaN;
* false otherwise
* @return true if any coordinate of this vector is infinite and none are NaN;
* false otherwise
*/
public boolean isInfinite();
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy