maspack.matrix
Interface Vector

All Superinterfaces:
Clonable, java.lang.Cloneable
All Known Implementing Classes:
CubaturePoint3d, MaterialPoint, MeshIntersectionPoint, Point2d, Point3d, Quaternion, SparseVectorNd, SpatialVector, Twist, Vector2d, Vector3d, Vector4d, VectorBase, VectorNd, VoidVector, Wrench

public interface Vector
extends Clonable

General interface for vectors. It provides methods for setting and getting the elements of a vector, and to do various non-modifying queries such as finding out its size, computing it's norms, or comparing it with other vectors. There is also a method setSize for resizing, which can be used unless the vector size is fixed (which can be determined using isFixedSize).

This base class does not publicly support vector operations such as addition or scaling. The reason for this is that specific implementations may have a specialized structure which could be compromised by arbitrary operations. For instance, an implementation that represents only unit vectors, should not allow an add operation.

Of course, it is possible to corrupt any special implementation structure using the set methods provided in this base class, but it was felt that not including such routines would be overly restrictive. It is therefore up to the user to safeguard implementation integrity against misuse of the set methods.

Note that indices for vector elements are zero-based, so that the range of valid indices for a vector of length n is [0, ... , n-1].


Method Summary
 double dot(Vector v1)
          Returns the dot product of this vector and v1.
 boolean epsilonEquals(Vector v1, double eps)
          Returns true if the elements of this vector equal those of vector v1within a prescribed tolerance epsilon.
 boolean equals(Vector v1)
          Returns true if the elements of this vector exactly equal those of vector v1.
 void get(double[] values)
          Copies the elements of this vector into an array of doubles.
 double get(int i)
          Gets a single element of this vector.
 void get(Vector v1)
          Copies the elements of this vector into another vector object.
 double infinityNorm()
          Returns the infinity norm of this vector.
 boolean isFixedSize()
          Returns true if this vector is of fixed size.
 double maxElement()
          Returns the maximum element value.
 double minElement()
          Returns the minimum element value.
 double norm()
          Returns the 2 norm of this vector.
 double normSquared()
          Returns the square of the 2 norm of this vector.
 double oneNorm()
          Returns the 1 norm of this vector.
 void scan(ReaderTokenizer rtok)
          Sets the contents of this vector to values read from a ReaderTokenizer.
 void set(double[] values)
          Sets the elements of this vector from an array of doubles.
 void set(int i, double value)
          Sets a single element of this vector.
 void set(Matrix M)
          Sets the values of this vector to those of a matrix object.
 void set(Vector v)
          Sets the values of this vector to those of another vector.
 void setSize(int n)
          Sets the size of this vector.
 int size()
          Returns the number of elements in this vector.
 java.lang.String toString(NumberFormat fmt)
          Returns a String representation of this vector, in which each element is formatted using a C printf style format as decribed by the parameter NumberFormat.
 void write(java.io.PrintWriter pw, NumberFormat fmt)
          Writes the contents of this vector to a PrintWriter.
 void write(java.io.PrintWriter pw, NumberFormat fmt, boolean withBrackets)
          Writes the contents of this vector to a PrintWriter.
 
Methods inherited from interface maspack.util.Clonable
clone
 

Method Detail

size

int size()
Returns the number of elements in this vector.

Returns:
number of elements

get

double get(int i)
Gets a single element of this vector.

Parameters:
i - element index
Returns:
element value

get

void get(double[] values)
Copies the elements of this vector into an array of doubles.

Parameters:
values - array into which values are copied

get

void get(Vector v1)
         throws ImproperSizeException
Copies the elements of this vector into another vector object.

Parameters:
v1 - vector object into which values are copied
Throws:
ImproperSizeExcept - ImproperSizeException

set

void set(int i,
         double value)
Sets a single element of this vector.

Parameters:
i - element index
value - element value

set

void set(double[] values)
Sets the elements of this vector from an array of doubles.

Parameters:
values - array from which values are copied

set

void set(Vector v)
Sets the values of this vector to those of another vector.

Parameters:
v - vector from which values are copied
Throws:
ImproperSizeException - vectors have different sizes and this vector cannot be resized accordingly.

set

void set(Matrix M)
Sets the values of this vector to those of a matrix object. The matrix must have either one column or one row; in the latter case, an attempt will be made to declare this vector a column vector, and if this fails, then an ImproperSizeException will be raised.

Parameters:
M - matrix from which values are copied
Throws:
ImproperSizeException - if this vector cannot be sized to match the dimensions of the matrix.

isFixedSize

boolean isFixedSize()
Returns true if this vector is of fixed size. If this vector is not of fixed size, then it can be resized dynamically, either explicitly using setSize, or implicitly when used as a result for various vector operations.

Returns:
true if this vector is of fixed size
See Also:
setSize(int)

setSize

void setSize(int n)
             throws java.lang.UnsupportedOperationException
Sets the size of this vector. This operation is only supported if isFixedSize returns false.

Parameters:
n - new size
Throws:
java.lang.UnsupportedOperationException - if this operation is not supported
See Also:
isFixedSize()

norm

double norm()
Returns the 2 norm of this vector. This is the square root of the sum of the squares of the elements.

Returns:
vector 2 norm

normSquared

double normSquared()
Returns the square of the 2 norm of this vector. This is the sum of the squares of the elements.

Returns:
square of the 2 norm

oneNorm

double oneNorm()
Returns the 1 norm of this vector. This is the sum of the absolute values of the elements.

Returns:
vector 1 norm

infinityNorm

double infinityNorm()
Returns the infinity norm of this vector. This is the maximum absolute value over all elements.

Returns:
vector infinity norm

maxElement

double maxElement()
Returns the maximum element value.

Returns:
maximal element

minElement

double minElement()
Returns the minimum element value.

Returns:
minimal element

dot

double dot(Vector v1)
Returns the dot product of this vector and v1.

Parameters:
v1 - right-hand vector
Returns:
dot product
Throws:
ImproperSizeException - if this vector and v1 have different sizes

epsilonEquals

boolean epsilonEquals(Vector v1,
                      double eps)
Returns true if the elements of this vector equal those of vector v1within a prescribed tolerance epsilon. If the vectors have different sizes, false is returned.

Parameters:
v1 - vector to compare with
eps - comparison tolerance
Returns:
false if the vectors are not equal within the specified tolerance, or have different sizes

equals

boolean equals(Vector v1)
Returns true if the elements of this vector exactly equal those of vector v1. If the vectors have different sizes, false is returned.

Parameters:
v1 - vector to compare with
Returns:
false if the vectors are not equal or have different sizes

write

void write(java.io.PrintWriter pw,
           NumberFormat fmt)
           throws java.io.IOException
Writes the contents of this vector to a PrintWriter. Element values are separated by spaces, and each element is formatted using a C printf style as decribed by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this vector to
fmt - numeric format
Throws:
java.io.IOException

write

void write(java.io.PrintWriter pw,
           NumberFormat fmt,
           boolean withBrackets)
           throws java.io.IOException
Writes the contents of this vector to a PrintWriter. Element values are separated by spaces, and optionally surrounded by square brackets [ ] if withBrackets is set true. Each element is formatted using a C printf style as decribed by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this vector to
fmt - numeric format
withBrackets - if true, causes the output to be surrounded by square brackets.
Throws:
java.io.IOException

scan

void scan(ReaderTokenizer rtok)
          throws java.io.IOException
Sets the contents of this vector to values read from a ReaderTokenizer. The input should consist of a sequence of numbers, separated by white space and optionally surrounded by square brackets [ ].

If the input is not surrounded by square brackets, then the number of values should equal the current size of this vector.

If the input is surrounded by square brackets, then all values up to the closing bracket are read, and the resulting number of values should either equal the current size of this vector, or this vector should be resizeable to fit the input. For example,

 [ 1.2 4 5 3.1 ]
 
defines a vector of size 4.

Parameters:
rtok - Tokenizer from which vector values are read. Number parsing should be enabled.
Throws:
ImproperSizeException - if this vector has a fixed size which is incompatible with the input
java.io.IOException

toString

java.lang.String toString(NumberFormat fmt)
Returns a String representation of this vector, in which each element is formatted using a C printf style format as decribed by the parameter NumberFormat.

Parameters:
fmt - numeric format
Returns:
String representation of this vector