gov.sandia.cognition.math.matrix
Interface Vector

All Superinterfaces:
Cloneable, CloneableSerializable, Iterable<VectorEntry>, Ring<Vector>, Serializable, Vectorizable, VectorSpace<Vector,VectorEntry>
All Known Subinterfaces:
Vector1D, Vector2D, Vector3D
All Known Implementing Classes:
AbstractMTJVector, AbstractVector, DenseVector, SparseVector, Vector1, Vector2, Vector3

@CodeReviews(reviews={@CodeReview(reviewer="Kevin R. Dixon",date="2008-02-26",changesNeeded=false,comments={"Minor changes to formatting.","Otherwise, looks good."}),@CodeReview(reviewer="Jonathan McClain",date="2006-05-17",changesNeeded=false,comments="Looks fine.")})
public interface Vector
extends VectorSpace<Vector,VectorEntry>, Vectorizable

The Vector interface defines the operations that are expected on a mathematical vector. The Vector can be thought of as a collection of doubles of fixed size (the dimensionality) that supports array-like indexing into the Vector. The Vector is defined as an interface because there is more than one way to implement a Vector, in particular if you want to make use of sparseness, which occurs when most of the elements of a Vector are zero so that they are not represented.

Since:
1.0
Author:
Kevin R. Dixon

Nested Class Summary
 
Nested classes/interfaces inherited from interface gov.sandia.cognition.math.matrix.VectorSpace
VectorSpace.Entry
 
Method Summary
 void assertDimensionalityEquals(int otherDimensionality)
          Asserts that the dimensionality of this vector equals the given dimensionality.
 void assertSameDimensionality(Vector other)
          Asserts that this vector has the same dimensionality as the given vector.
 boolean checkSameDimensionality(Vector other)
          Determines if this and other have the same number of dimensions (size)
 Vector clone()
          Returns a smart copy of this, such that changing the values of the return class will not effect this
 Vector dotDivide(Vector other)
          Element-wise division of this by other.
 void dotDivideEquals(Vector other)
          Inline element-wise division of this by other.
 int getDimensionality()
          Returns the number of elements in the Vector
 double getElement(int index)
          Gets the zero-based indexed element from the Vector
 boolean isSparse()
          Returns true if this vector has a potentially sparse underlying structure.
 Matrix outerProduct(Vector other)
          Computes the outer matrix product between the two vectors
 void setElement(int index, double value)
          Sets the zero-based indexed element in the Vector from the specified value
 Vector stack(Vector other)
          Stacks "other" below "this" and returns the stacked Vector
 Vector subVector(int minIndex, int maxIndex)
          Gets a subvector of "this", specified by the inclusive indices
 Vector times(Matrix matrix)
          Premultiplies the matrix by the vector "this"
 double[] toArray()
          Converts this vector to a new array of doubles, in the same order as they are in the vector.
 String toString()
           
 String toString(NumberFormat format)
          Converts the vector to a String, using the given formatter.
 String toString(NumberFormat format, String delimiter)
          Converts the vector to a String, using the given formatter and delimiter.
 Vector transform(UnivariateScalarFunction function)
          Applies the given function to each of the elements of this vector and returns a new vector with the result.
 void transformEquals(UnivariateScalarFunction function)
          Applies the given function to each of the elements of this vector and sets them to the result.
 Vector transformNonZeros(UnivariateScalarFunction function)
          Applies the given function to each of the non-zero elements of this vector and returns a new vector with the result.
 void transformNonZerosEquals(UnivariateScalarFunction function)
          Applies the given function to each of the non-zero elements of this vector and sets them to the result.
 
Methods inherited from interface gov.sandia.cognition.math.matrix.VectorSpace
angle, cosine, dotProduct, euclideanDistance, euclideanDistanceSquared, isUnitVector, isUnitVector, norm, norm1, norm2, norm2Squared, normInfinity, sum, unitVector, unitVectorEquals
 
Methods inherited from interface gov.sandia.cognition.math.Ring
dotTimes, dotTimesEquals, equals, equals, isZero, isZero, minus, minusEquals, negative, negativeEquals, plus, plusEquals, scale, scaledMinus, scaledMinusEquals, scaledPlus, scaledPlusEquals, scaleEquals, zero
 
Methods inherited from interface java.lang.Iterable
iterator
 
Methods inherited from interface gov.sandia.cognition.math.matrix.Vectorizable
convertFromVector, convertToVector
 

Method Detail

clone

Vector clone()
Description copied from interface: Ring
Returns a smart copy of this, such that changing the values of the return class will not effect this

Specified by:
clone in interface CloneableSerializable
Specified by:
clone in interface Ring<Vector>
Specified by:
clone in interface Vectorizable
Returns:
smart copy of this

getDimensionality

int getDimensionality()
Returns the number of elements in the Vector

Returns:
number of elements in the Vector

getElement

double getElement(int index)
Gets the zero-based indexed element from the Vector

Parameters:
index - zero-based index
Returns:
zero-based indexed element in the Vector

setElement

void setElement(int index,
                double value)
Sets the zero-based indexed element in the Vector from the specified value

Parameters:
index - zero-based index
value - value to set the element in the Vector

outerProduct

Matrix outerProduct(Vector other)
Computes the outer matrix product between the two vectors

Parameters:
other - post-multiplied Vector with which to compute the outer product
Returns:
Outer matrix product, which will have dimensions (this.getDimensionality x other.getDimensionality) and WILL BE singular

times

Vector times(Matrix matrix)
Premultiplies the matrix by the vector "this"

Parameters:
matrix - Matrix to premultiply by "this", must have the same number of rows as the dimensionality of "this"
Returns:
Vector of dimension equal to the number of columns of "matrix"

dotDivide

Vector dotDivide(Vector other)
Element-wise division of this by other. Note that if other has zero elements the result will contain NaN values.

Parameters:
other - The other ring whose elements will divide into this one.
Returns:
A new ring of equal size whose elements are equal to the corresponding element in this divided by the element in other.

dotDivideEquals

void dotDivideEquals(Vector other)
Inline element-wise division of this by other. Note that if other has zero elements this will contain NaN values.

Parameters:
other - The other vector whose elements will divide into this one.

checkSameDimensionality

boolean checkSameDimensionality(Vector other)
Determines if this and other have the same number of dimensions (size)

Parameters:
other - vector to compare to
Returns:
true iff this.getDimensionality() == other.getDimensionality(), false otherwise

assertSameDimensionality

void assertSameDimensionality(Vector other)
Asserts that this vector has the same dimensionality as the given vector. If this assertion fails, a DimensionalityMismatchException is thrown.

Parameters:
other - The other vector to compare to.

assertDimensionalityEquals

void assertDimensionalityEquals(int otherDimensionality)
Asserts that the dimensionality of this vector equals the given dimensionality. If this assertion fails, a DimensionalityMismatchException is thrown.

Parameters:
otherDimensionality - The dimensionality of the.

stack

Vector stack(Vector other)
Stacks "other" below "this" and returns the stacked Vector

Parameters:
other - Vector to stack below "this"
Returns:
stacked Vector

subVector

Vector subVector(int minIndex,
                 int maxIndex)
Gets a subvector of "this", specified by the inclusive indices

Parameters:
minIndex - minimum index to get (inclusive)
maxIndex - maximum index to get (inclusive)
Returns:
vector of dimension (maxIndex-minIndex+1)

transform

Vector transform(UnivariateScalarFunction function)
Applies the given function to each of the elements of this vector and returns a new vector with the result. Note that this is a dense operation where zero elements will be passed to the function.

Parameters:
function - The function from double to double to apply.
Returns:
A new vector whose elements represent the result of applying the function to corresponding element in this vector.

transformEquals

void transformEquals(UnivariateScalarFunction function)
Applies the given function to each of the elements of this vector and sets them to the result.

Parameters:
function - The function from double to double to apply.

transformNonZeros

Vector transformNonZeros(UnivariateScalarFunction function)
Applies the given function to each of the non-zero elements of this vector and returns a new vector with the result.

Parameters:
function - The function from double to double to apply to the non-zero elements.
Returns:
A new vector whose elements represent the result of applying the function to the corresponding element in this vector, except for zeros, which are exactly the same as in this vector.

transformNonZerosEquals

void transformNonZerosEquals(UnivariateScalarFunction function)
Applies the given function to each of the non-zero elements of this vector and sets them to the result.

Parameters:
function - The function from double to double to apply to the non-zero elements.

isSparse

boolean isSparse()
Returns true if this vector has a potentially sparse underlying structure. This can indicate that it is faster to only process the non-zero elements rather than to do dense operations on it. Of course, even with a sparse structure, there may be no zero elements or conversely even with a non-sparse (dense) structure there may be many zero elements.

Returns:
True if the vector has a potentially sparse structure. Otherwise, false.

toArray

double[] toArray()
Converts this vector to a new array of doubles, in the same order as they are in the vector. The returned will be safe in that no references are maintained by this vector.

Returns:
The vector as a dense array of doubles. Its length will be equal to the dimensionality of the vector.

toString

String toString()
Overrides:
toString in class Object

toString

String toString(NumberFormat format)
Converts the vector to a String, using the given formatter.

Parameters:
format - The number format to use.
Returns:
The string representation of the vector.

toString

String toString(NumberFormat format,
                String delimiter)
Converts the vector to a String, using the given formatter and delimiter.

Parameters:
format - The number format to use.
delimiter - The delimiter to use.
Returns:
The string representation of the vector.