%File: ~/OOP/matrix/Vector.tex
%What: "@(#) Vector.tex, revA"

\noindent {\bf Files}   \\
\indent \#include $<\tilde{}$/matrix/Vector.h$>$  \\

\noindent {\bf Class Declaration}  \\
\indent class Vector:  \\

\noindent {\bf Class Hierarchy} \\
\indent {\bf Vector} \\

\noindent {\bf Description}  \\
\indent The Vector class provides the vector abstraction. A vector of
order {\em size} is an ordered 1d array of {\em size} numbers. For
example a vector of order 5: \\

\indent\indent $ x = [x_0$ $x_1$ $x_2$  $x_3$ $x_4]$ \\


In the Vector class the data is stored in a 1d double array of length
equal to the order of the Vector.  At present time none of the methods
are declared as being virtual. THIS MAY CHANGE FOR PARALLEL. \\

\noindent {\bf Class Interface} \\
\indent {// Constructors}  \\ 
\indent {\em Vector();}  \\
\indent {\em  Vector(int size);}  \\
\indent {\em  Vector(double *data, int size)}  \\
\indent {\em  Vector(const Vector \&M); }  \\ \\
\indent {// Destructor}  \\ 
\indent {\em $\tilde{}$Vector();} \\ \\
\indent {// Public Methods}  \\ 
\indent {\em int Size() const;} \\
\indent {\em void Zero();} \\
\indent {\em Assemble(const Vector \&M, const ID \&loc, double
fact = 1.0);} \\ 
\indent {\em int addVector(const Vector \&other, double fact =
1.0);} \\ 
\indent {\em int addMatrixVector(const Matrix \&m, Vector \&v,
double fact = 1.0);} \\  
\indent {\em double Norm(void)} \\ \\
\indent {// Overloaded Operator Functions}  \\
\indent {\em double \&operator()(int x) const;} \\
\indent {\em double \&operator()(int x);} \\
\indent {\em double \&operator[](int x) const;} \\
\indent {\em double \&operator[](int x);} \\
\indent {\em Vector operator()(const ID \&loc) const;}\\ 
\indent {\em Vector \&operator=(const Vector \&M);}\\
\indent {\em  Vector \&operator+=(double fact);} \\
\indent {\em Vector \&operator-=(double fact);} \\
\indent {\em Vector \&operator*=(double fact);} \\
\indent {\em Vector \&operator/=(double fact); } \\
\indent {\em Vector operator+(double fact) const;} \\
\indent {\em Vector operator-(double fact) const;} \\
\indent {\em  Vector operator*(double fact) const;} \\
\indent {\em  Vector operator/(double fact) const;} \\
\indent {\em  Vector \&operator+=(const Vector \&V);} \\
\indent {\em  Vector \&operator-=(const Vector \&V);} \\
\indent {\em  Vector operator+(const Vector \&V);} \\
\indent {\em  Vector operator-(const Vector \&V);} \\
\indent {\em  double operator { }$\hat{ }$(const Vector \&V) const;   } \\
\indent {\em Vector operator/(const Matrix \&M) const; } \\
\indent {\em friend OPS_Stream \&operator$<<$(OPS_Stream \&s, const
Vector \&V);} \\ 
\indent {\em friend istream \&operator$>>$(istream \&s, const
Vector \&V);} \\ 


\noindent {\bf Constructors}  \\
\indent {\em Vector();}  \\
To construct a Vector of order $0$. \\

\indent {\em  Vector(int size);}  \\
To construct a Vector of order {\em size}. The constructor creates an
array to store the data and zeroes this array. If not enough memory is
available a warning message is printed and a Vector of order $0$ is 
returned. The {\em Zero()}  method is invoked on the new Vector before
it is returned.\\ 

\indent {\em  Vector(double *data, int size)}  \\
To construct a Vector of order {\em size} whose data will be stored in the
array pointed to by {\em data}. The array pointed to by data is not set to
zero by the constructor. Note that delete will not be called on this array
in the destructor. It is up to the user to ensure that the array pointed to
by {\em data} is at least as large as {\em size}, if this is not the case
erroneous results or a segmentation fault may occur.\\

\indent {\em  Vector(const Vector \&other); }  \\
To construct a Vector using another Vector. The new Vector will be
identical to the Vector {\em other}. The constructor creates an array
to store the data and zeroes this array. If not enough memory is available
a warning message is printed and a Vector of order $0$ is returned. The
contents of the array are then set equal to the contents of {\em
other}.\\ 

\noindent {\bf Destructor} \\
\indent {\em virtual~ $\tilde{}$Vector();}\\ 
Will delete any space allocated in the constructors. If the array is
passed in the constructor, the space is not deallocated.\\

\noindent {\bf Public Member Functions }  \\
\indent {\em int Size() const;} \\
Returns the order of the Vector, {\em size}. \\

\indent {\em void Zero();} \\
Zeros out the Vector, i.e. sets all the components of the Vector to
$0$. \\

\indent {\em int Assemble(const Vector \&V, 
const ID \&loc,
double fact = 1.0);} \\
Assembles into the current Vector the Vector {\em V}. The contents of the
current Vector at location ({\em loc(i)}) is set equal to the current
value plus {\em fact} times the value of the Vector {\em V} at
location ({\em i}). returns $0$ if successful. A warning message is
printed for each invalid location in the current Vector or {\em V} and a
$-1$ is returned. \\ 

\indent {\em void addVector(const Vector \&other, double fact = 1.0);} \\
To add a factor {\em fact} times the Vector {\em other} to the current
Vector. returns $0$ if successful. An error message is printed and
$-1$ is returned if Vectors are not of the same size. Checks are made
to see if the number of operations can be reduced if {\em fact} is $0$
or $1$. \\ 

\indent {\em void addMatrixVector(const Matrix \&m, Vector \&v, double
fact = 1.0);} \\ 
To add a factor {\em fact} times the Vector formed by the product of
the matrix {\em m} and the Vector {\em v} to the current Vector. No
temporary Vector is created. Returns $0$ if successful. Prints a
warning message and returns $-1$ if sizes are incompatible. Checks are
made to see if the number of operations can be reduced if {\em fact}
is $0$ or $1$. \\ 


\indent {\em double Norm(void)} \\
Returns the 2 norm of the Vector. Returns the {\em sqrt()} of the
result of invoking the $\hat{ }$ operator on the current Vector with
the current Vector as the argument. \\ 

\noindent {\bf Overloaded Operator Functions}  \\
\indent {\em double \&operator()(int x) const;} \\
Returns the data at location {\em x} in the Vector. Assumes ({\em x}) 
is a valid location in the Vector, i.e. $0 <= x $ order, a
segmentation fault or erroneous results can occur if this is not the 
case. \\ 

\indent {\em double \&operator()(int x);} \\
Used to set the data at location({\em x}) in the Vector. Assumes ({\em x})
is a valid location in the Vector, i.e. $0 <= x < $ order, a
segmentation fault or erroneous results can occur if this is not the
case. \\ 

\indent {\em double \&operator[](int x) const;} \\
To safely return the data at location {\em x} in the Vector. Checks to
ensure {\em x} is a valid location, i.e. $0 <= x $ order. If {\em x}
is not a valid location a warning message is printed and
VECTOR\_NOT\_VALID\_ENTRY (a static class variable) is returned. This
is a slower but safer version of {\em () const}.\\ 

\indent {\em double \&operator[](int x);} \\
Used to safely set the data at location({\em x}) in the Vector. Checks
to ensure {\em x} is a valid location, i.e. $0 <= x $ order. If {\em
x} is not a valid location a warning message is printed and
VECTOR\_NOT\_VALID\_ENTRY (a static class variable) is modified. This
is a slower but safer version of {\em ()}.\\ 

\indent {\em Vector operator()(const ID \&loc) const;}\\ 
Returns a Vector of order {\em loc.Size()}. The contents of the new
Vector are given by the contents of the current Vector at the
locations given by the {\em loc}. For example the contents of the new
Vector at location $i$ are equal to the contents of the current Vector
at location {\em loc(i)}. Creates a new Vector, copies the data from
the current Vector and returns the new Vector. For each invalid
location specified in {\em loc} for the current Vector, a warning
message is printed.\\ 

\indent {\em Vector \&operator=(const Vector \&other);}\\
Sets the current Vector to be equal to the Vector given by {\em
other}. If the Vectors are of different sizes, the current data, if
allocated in a constructor, is deallocated and more space allocated
before the contents are copied. If not enough memory is available a
warning message is printed and the order of the current Vector is set
to $0$.\\ 

\indent {\em  Vector \&operator+=(double fact);} \\
A method to add {\em fact} to each component of the current Vector. \\

\indent {\em Vector \&operator-=(double fact);} \\
A method to subtract {\em fact} from each component of the current Vector. \\

\indent {\em Vector \&operator*=(double fact);} \\
A method to multiply each component of the current Vector by fact. \\

\indent {\em Vector \&operator/=(double fact); } \\
A method which will divide each component of the current Vector by
{\em fact}. If {\em fact} is equal to zero an warning message is printed
and the components of the Vector are set to VECTOR\_VERY\_LARGE\_VALUE
(defined in $<$Vector.h$>$). \\

\indent {\em Vector operator+(double fact) const;} \\
A method to return a new Vector whose components are equal to the
components of the current Vector plus the value {\em fact}. A new Vector
is constructed using the current Vector as an argument to the
constructor; before the new matrix is returned, the {\em +=} operator
is invoked on the matrix with {\em fact}. If the new Vector and
current Vector are of different size, i.e. constructor fails to get
enough memory, a warning message is printed. \\ 

\indent {\em Vector operator-(double fact) const;} \\
A method to return a new Vector whose components are equal to the
components of the current Vector minus the value {\em fact}.  A new Vector
is constructed using the current Vector as an argument to the
constructor; before the new matrix is returned, the {\em -=} operator
is invoked on the matrix with {\em fact}. If the new Vector and
current Vector are of different size, i.e. constructor fails to get
enough memory, a warning message is printed. \\ 


\indent {\em  Vector operator*(double fact) const;} \\
A method to return a new Vector whose components are equal to the
components of the current Vector times the value {\em fact}.  A new Vector
is constructed using the current Vector as an argument to the
constructor; before the new matrix is returned, the {\em *=} operator
is invoked on the matrix with {\em fact}. If the new Vector and
current Vector are of different sizes, a warning message is printed. \\


\indent {\em  Vector operator/(double fact) const;} \\
A method to return a new Vector whose components are equal to the
components of the current Vector divided the value {\em fact}. A new
Vector is constructed using the current Vector as an argument to the
constructor; before the new matrix is returned, the {\em /=} operator
is invoked on the matrix with {\em fact}. Warning messages are printed
if {\em fact} is equal to $0$ or if the new Vector and current Vector
are of different sizes. \\ 

\indent {\em  Vector \&operator+=(const Vector \&V);} \\
A method to add the contents of the Vector {\em V} to the current
Vector. If Vectors are not of same order a warning message is printed
and nothing is done.  \\ 

\indent {\em Vector \&operator-=(const Vector \&V);} \\
A method to subtract the contents of the Vector {\em V} from the
current Vector. If Vectors are not of same order a warning message is
printed and nothing is done.  \\ 


\indent {\em  Vector operator+(const Vector \&V);} \\
A method to return a new Vector which is equal to the sum of the
the current Vector and the Vector {\em V}. A new Vector is constructed
using the current Vector as an argument to the constructor; before the
new matrix is returned, the {\em +=} operator is invoked on the matrix
with {\em V}. If the current Vector and {\em V} are not of the same size,
a warning message is printed and a copy of the current Vector is
returned. A warning message is also returned if the new Vector is not
of the correct size, i.e. ran out of memory. \\ 


\indent {\em  Vector operator-(const Vector \&V);} \\
A method to return a new Vector which is equal to the the current
Vector minus the Vector {\em V}. A new Vector is constructed using the
current Vector as an argument to the constructor; before the new
matrix is returned, the {\em -=} operator is invoked on the matrix
with {\em V}. If the current Vector and {\em V} are not of the same size,
a warning message is printed and a copy of the current Vector is
returned. A warning message is also returned if the new Vector is not
of the correct size, i.e. ran out of memory. \\ 


\indent {\em double operator{ }$ \hat{ }$(const Vector \&V) const;   } \\
A method to return the dot product of the current Vector and the
Vector {\em V}. If the current Vector and {\em V} are not of the same
size, a warning message is printed and $0$ returned. \\ 

\indent {\em Vector operator/(const Matrix \&M) const; } \\
A method to return a new Vector, $x$, equal to the solution of the
matrix equation $Mx=$ the current Vector. A new Vector is created for
the return of size {\em M.noRows()}. A new Matrix is created of order
{\em M.noRows()} x {\em M.noRows()} and set equal to {\em M} if {\em
M} is square, or $M^tM$ if {\em M} is not square. The new Vector is
then set equal to the result of invoking {\em Solve(*this)} on the new
Matrix. \\ 

{\em friend OPS_Stream \&operator$<<$(OPS_Stream \&s, const Vector \&V);} \\
A function to print out the contents of the Vector {\em V} to the
output stream {\em s}. prints out the contents of the Vector in the
stream and then prints the newline character. \\

{\em friend istream \&operator$>>$(istream \&s, const Vector \&V);} \\
A function to read the contents of the Vector {\em V} from the input
stream {\em s}. Sets the components of {\em V} equal to the next {\em
V.Size()} entries in the stream.\\ 





