org.apache.commons.math3.linear
Class RealVector

java.lang.Object
  extended by org.apache.commons.math3.linear.RealVector
Direct Known Subclasses:
ArrayRealVector, SparseRealVector

public abstract class RealVector
extends Object

Class 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 code map and mapToSelf 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 map versions create a new vector to hold the result and do not change the instance. The mapToSelf version uses the instance itself to store the results, so the instance is changed by this method. In all cases, the result vector is returned by the methods, allowing the fluent API style, like this:

   RealVector result = v.mapAddToSelf(3.4).mapToSelf(new Tan()).mapToSelf(new Power(2.3));
 

Since:
2.1
Version:
$Id: RealVector.java 1244107 2012-02-14 16:17:55Z erans $

Nested Class Summary
protected  class RealVector.Entry
          An entry in the vector.
protected  class RealVector.SparseEntryIterator
          This class should rarely be used, but is here to provide a default implementation of sparseIterator(), which is implemented by walking over the entries, skipping those whose values are the default one.
 
Constructor Summary
RealVector()
           
 
Method Summary
 RealVector add(RealVector v)
          Compute the sum of this vector and v.
 void addToEntry(int index, double increment)
          Change an entry at the specified index.
abstract  RealVector append(double d)
          Construct a new vector by appending a double to this vector.
abstract  RealVector append(RealVector v)
          Construct a new vector by appending a vector to this vector.
protected  void checkIndex(int index)
          Check if an index is valid.
protected  void checkVectorDimensions(int n)
          Check if instance dimension is equal to some expected value.
protected  void checkVectorDimensions(RealVector v)
          Check if instance and specified vectors have the same dimension.
 RealVector combine(double a, double b, RealVector y)
          Returns a new vector representing a * this + b * y, the linear combination of this and y.
 RealVector combineToSelf(double a, double b, RealVector y)
          Updates this with the linear combination of this and y.
abstract  RealVector copy()
          Returns a (deep) copy of this vector.
 double cosine(RealVector v)
          Computes the cosine of the angle between this vector and the argument.
 double dotProduct(RealVector v)
          Compute the dot product of this vector with v.
abstract  RealVector ebeDivide(RealVector v)
          Element-by-element division.
abstract  RealVector ebeMultiply(RealVector v)
          Element-by-element multiplication.
abstract  int getDimension()
          Returns the size of the vector.
 double getDistance(RealVector v)
          Distance between two vectors.
abstract  double getEntry(int index)
          Return the entry at the specified index.
 double getL1Distance(RealVector v)
          Distance between two vectors.
 double getL1Norm()
          Returns the L1 norm of the vector.
 double getLInfDistance(RealVector v)
          Distance between two vectors.
 double getLInfNorm()
          Returns the L norm of the vector.
 int getMaxIndex()
          Get the index of the maximum entry.
 double getMaxValue()
          Get the value of the maximum entry.
 int getMinIndex()
          Get the index of the minimum entry.
 double getMinValue()
          Get the value of the minimum entry.
 double getNorm()
          Returns the L2 norm of the vector.
abstract  RealVector getSubVector(int index, int n)
          Get a subvector from consecutive elements.
abstract  boolean isInfinite()
          Check whether any coordinate of this vector is infinite and none are NaN.
abstract  boolean isNaN()
          Check whether any coordinate of this vector is NaN.
 Iterator<RealVector.Entry> iterator()
          Generic dense iterator.
 RealVector map(UnivariateFunction function)
          Acts as if implemented as:
 RealVector mapAdd(double d)
          Add a value to each entry.
 RealVector mapAddToSelf(double d)
          Add a value to each entry.
 RealVector mapDivide(double d)
          Divide each entry by the argument.
 RealVector mapDivideToSelf(double d)
          Divide each entry by the argument.
 RealVector mapMultiply(double d)
          Multiply each entry by the argument.
 RealVector mapMultiplyToSelf(double d)
          Multiply each entry.
 RealVector mapSubtract(double d)
          Subtract a value from each entry.
 RealVector mapSubtractToSelf(double d)
          Subtract a value from each entry.
 RealVector mapToSelf(UnivariateFunction function)
          Acts as if it is implemented as:
 RealMatrix outerProduct(RealVector v)
          Compute the outer product.
abstract  RealVector projection(RealVector v)
          Find the orthogonal projection of this vector onto another vector.
 void set(double value)
          Set all elements to a single value.
abstract  void setEntry(int index, double value)
          Set a single element.
abstract  void setSubVector(int index, RealVector v)
          Set a sequence of consecutive elements.
 Iterator<RealVector.Entry> sparseIterator()
          Create a sparse iterator over the vector, which may omit some entries.
 RealVector subtract(RealVector v)
          Subtract v from this vector.
 double[] toArray()
          Convert the vector to an array of doubles.
 void unitize()
          Converts this vector into a unit vector.
 RealVector unitVector()
          Creates a unit vector pointing in the direction of this vector.
static RealVector unmodifiableRealVector(RealVector v)
          Returns an unmodifiable view of the specified vector.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RealVector

public RealVector()
Method Detail

getDimension

public abstract int getDimension()
Returns the size of the vector.

Returns:
the size of this vector.

getEntry

public abstract double getEntry(int index)
Return the entry at the specified index.

Parameters:
index - Index location of entry to be fetched.
Returns:
the vector entry at index.
Throws:
OutOfRangeException - if the index is not valid.
See Also:
setEntry(int, double)

setEntry

public abstract void setEntry(int index,
                              double value)
Set a single element.

Parameters:
index - element index.
value - new value for the element.
Throws:
OutOfRangeException - if the index is not valid.
See Also:
getEntry(int)

addToEntry

public void addToEntry(int index,
                       double increment)
Change an entry at the specified index.

Parameters:
index - Index location of entry to be set.
increment - Value to add to the vector entry.
Throws:
OutOfRangeException - if the index is not valid.
Since:
3.0

append

public abstract RealVector append(RealVector v)
Construct a new vector by appending a vector to this vector.

Parameters:
v - vector to append to this one.
Returns:
a new vector.

append

public abstract RealVector append(double d)
Construct a new vector by appending a double to this vector.

Parameters:
d - double to append.
Returns:
a new vector.

getSubVector

public abstract RealVector getSubVector(int index,
                                        int n)
Get a subvector from consecutive elements.

Parameters:
index - index of first element.
n - number of elements to be retrieved.
Returns:
a vector containing n elements.
Throws:
OutOfRangeException - if the index is not valid.

setSubVector

public abstract void setSubVector(int index,
                                  RealVector v)
Set a sequence of consecutive elements.

Parameters:
index - index of first element to be set.
v - vector containing the values to set.
Throws:
OutOfRangeException - if the index is not valid.

isNaN

public abstract boolean isNaN()
Check whether any coordinate of this vector is NaN.

Returns:
true if any coordinate of this vector is NaN, false otherwise.

isInfinite

public abstract boolean isInfinite()
Check whether any coordinate of this vector is infinite and none are NaN.

Returns:
true if any coordinate of this vector is infinite and none are NaN, false otherwise.

checkVectorDimensions

protected void checkVectorDimensions(RealVector v)
Check if instance and specified vectors have the same dimension.

Parameters:
v - Vector to compare instance with.
Throws:
DimensionMismatchException - if the vectors do not have the same dimension.

checkVectorDimensions

protected void checkVectorDimensions(int n)
Check if instance dimension is equal to some expected value.

Parameters:
n - Expected dimension.
Throws:
DimensionMismatchException - if the dimension is inconsistent with the vector size.

checkIndex

protected void checkIndex(int index)
Check if an index is valid.

Parameters:
index - Index to check.
Throws:
OutOfRangeException - if index is not valid.

add

public RealVector add(RealVector v)
Compute the sum of this vector and v. Returns a new vector. Does not change instance data.

Parameters:
v - Vector to be added.
Returns:
this + v.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

subtract

public RealVector subtract(RealVector v)
Subtract v from this vector. Returns a new vector. Does not change instance data.

Parameters:
v - Vector to be subtracted.
Returns:
this - v.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

mapAdd

public RealVector mapAdd(double d)
Add a value to each entry. Returns a new vector. Does not change instance data.

Parameters:
d - Value to be added to each entry.
Returns:
this + d.

mapAddToSelf

public RealVector mapAddToSelf(double d)
Add a value to each entry. The instance is changed in-place.

Parameters:
d - Value to be added to each entry.
Returns:
this.

copy

public abstract RealVector copy()
Returns a (deep) copy of this vector.

Returns:
a vector copy.

dotProduct

public double dotProduct(RealVector v)
Compute the dot product of this vector with v.

Parameters:
v - Vector with which dot product should be computed
Returns:
the scalar dot product between this instance and v.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

cosine

public double cosine(RealVector v)
Computes the cosine of the angle between this vector and the argument.

Parameters:
v - Vector.
Returns:
the cosine of the angle between this vector and v.

ebeDivide

public abstract RealVector ebeDivide(RealVector v)
Element-by-element division.

Parameters:
v - Vector by which instance elements must be divided.
Returns:
a vector containing this[i] / v[i] for all i.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

ebeMultiply

public abstract RealVector ebeMultiply(RealVector v)
Element-by-element multiplication.

Parameters:
v - Vector by which instance elements must be multiplied
Returns:
a vector containing this[i] * v[i] for all i.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

getDistance

public double getDistance(RealVector v)
Distance between two vectors.

This method computes the distance consistent with the L2 norm, i.e. the square root of the sum of element differences, or Euclidian distance.

Parameters:
v - Vector to which distance is requested.
Returns:
the distance between two vectors.
Throws:
DimensionMismatchException - if v is not the same size as this vector.
See Also:
getL1Distance(RealVector), getLInfDistance(RealVector), getNorm()

getNorm

public double getNorm()
Returns the L2 norm of the vector.

The L2 norm is the root of the sum of the squared elements.

Returns:
the norm.
See Also:
getL1Norm(), getLInfNorm(), getDistance(RealVector)

getL1Norm

public double getL1Norm()
Returns the L1 norm of the vector.

The L1 norm is the sum of the absolute values of the elements.

Returns:
the norm.
See Also:
getNorm(), getLInfNorm(), getL1Distance(RealVector)

getLInfNorm

public double getLInfNorm()
Returns the L norm of the vector.

The L norm is the max of the absolute values of the elements.

Returns:
the norm.
See Also:
getNorm(), getL1Norm(), getLInfDistance(RealVector)

getL1Distance

public double getL1Distance(RealVector v)
Distance between two vectors.

This method computes the distance consistent with L1 norm, i.e. the sum of the absolute values of the elements differences.

Parameters:
v - Vector to which distance is requested.
Returns:
the distance between two vectors.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

getLInfDistance

public double getLInfDistance(RealVector v)
Distance between two vectors.

This method computes the distance consistent with L norm, i.e. the max of the absolute values of element differences.

Parameters:
v - Vector to which distance is requested.
Returns:
the distance between two vectors.
Throws:
DimensionMismatchException - if v is not the same size as this vector.
See Also:
getDistance(RealVector), getL1Distance(RealVector), getLInfNorm()

getMinIndex

public int getMinIndex()
Get the index of the minimum entry.

Returns:
the index of the minimum entry or -1 if vector length is 0 or all entries are NaN.

getMinValue

public double getMinValue()
Get the value of the minimum entry.

Returns:
the value of the minimum entry or NaN if all entries are NaN.

getMaxIndex

public int getMaxIndex()
Get the index of the maximum entry.

Returns:
the index of the maximum entry or -1 if vector length is 0 or all entries are NaN

getMaxValue

public double getMaxValue()
Get the value of the maximum entry.

Returns:
the value of the maximum entry or NaN if all entries are NaN.

mapMultiply

public RealVector mapMultiply(double d)
Multiply each entry by the argument. Returns a new vector. Does not change instance data.

Parameters:
d - Multiplication factor.
Returns:
this * d.

mapMultiplyToSelf

public RealVector mapMultiplyToSelf(double d)
Multiply each entry. The instance is changed in-place.

Parameters:
d - Multiplication factor.
Returns:
this.

mapSubtract

public RealVector mapSubtract(double d)
Subtract a value from each entry. Returns a new vector. Does not change instance data.

Parameters:
d - Value to be subtracted.
Returns:
this - d.

mapSubtractToSelf

public RealVector mapSubtractToSelf(double d)
Subtract a value from each entry. The instance is changed in-place.

Parameters:
d - Value to be subtracted.
Returns:
this.

mapDivide

public RealVector mapDivide(double d)
Divide each entry by the argument. Returns a new vector. Does not change instance data.

Parameters:
d - Value to divide by.
Returns:
this / d.

mapDivideToSelf

public RealVector mapDivideToSelf(double d)
Divide each entry by the argument. The instance is changed in-place.

Parameters:
d - Value to divide by.
Returns:
this.

outerProduct

public RealMatrix outerProduct(RealVector v)
Compute the outer product.

Parameters:
v - Vector with which outer product should be computed.
Returns:
the matrix outer product between this instance and v.

projection

public abstract RealVector projection(RealVector v)
Find the orthogonal projection of this vector onto another vector.

Parameters:
v - vector onto which instance must be projected.
Returns:
projection of the instance onto v.
Throws:
DimensionMismatchException - if v is not the same size as this vector.

set

public void set(double value)
Set all elements to a single value.

Parameters:
value - Single value to set for all elements.

toArray

public double[] toArray()
Convert the vector to an array of doubles. The array is independent from this vector data: the elements are copied.

Returns:
an array containing a copy of the vector elements.

unitVector

public RealVector unitVector()
Creates a unit vector pointing in the direction of this vector. The instance is not changed by this method.

Returns:
a unit vector pointing in direction of this vector.
Throws:
ArithmeticException - if the norm is null.

unitize

public void unitize()
Converts this vector into a unit vector. The instance itself is changed by this method.

Throws:
MathArithmeticException - if the norm is zero.

sparseIterator

public Iterator<RealVector.Entry> sparseIterator()
Create a sparse iterator over the vector, which may omit some entries. Specialized implementations may choose to not iterate over all dimensions, either because those values are unset, or are equal to defaultValue(), or are small enough to be ignored for the purposes of iteration. No guarantees are made about order of iteration. In dense implementations, this method will often delegate to iterator().

Returns:
a sparse iterator.

iterator

public Iterator<RealVector.Entry> iterator()
Generic dense iterator. Iteration is in increasing order of the vector index.

Returns:
a dense iterator.

map

public RealVector map(UnivariateFunction function)
Acts as if implemented as:
  return copy().mapToSelf(function);
 
Returns a new vector. Does not change instance data.

Parameters:
function - Function to apply to each entry.
Returns:
a new vector.

mapToSelf

public RealVector mapToSelf(UnivariateFunction function)
Acts as if it is implemented as:
  Entry e = null;
  for(Iterator it = iterator(); it.hasNext(); e = it.next()) {
      e.setValue(function.value(e.getValue()));
  }
 
Entries of this vector are modified in-place by this method.

Parameters:
function - Function to apply to each entry.
Returns:
a reference to this vector.

combine

public RealVector combine(double a,
                          double b,
                          RealVector y)
Returns a new vector representing a * this + b * y, the linear combination of this and y. Returns a new vector. Does not change instance data.

Parameters:
a - Coefficient of this.
b - Coefficient of y.
y - Vector with which this is linearly combined.
Returns:
a vector containing a * this[i] + b * y[i] for all i.
Throws:
DimensionMismatchException - if y is not the same size as this vector.

combineToSelf

public RealVector combineToSelf(double a,
                                double b,
                                RealVector y)
Updates this with the linear combination of this and y.

Parameters:
a - Weight of this.
b - Weight of y.
y - Vector with which this is linearly combined.
Returns:
this, with components equal to a * this[i] + b * y[i] for all i.
Throws:
DimensionMismatchException - if y is not the same size as this vector.

unmodifiableRealVector

public static RealVector unmodifiableRealVector(RealVector v)
Returns an unmodifiable view of the specified vector. The returned vector has read-only access. An attempt to modify it will result in a MathUnsupportedOperationException. However, the returned vector is not immutable, since any modification of v will also change the returned view. For example, in the following piece of code
     RealVector v = new ArrayRealVector(2);
     RealVector w = RealVector.unmodifiableRealVector(v);
     v.setEntry(0, 1.2);
     v.setEntry(1, -3.4);
 
the changes will be seen in the w view of v.

Parameters:
v - Vector for which an unmodifiable view is to be returned.
Returns:
an unmodifiable view of v.


Copyright (c) 2003-2013 Apache Software Foundation