                   readme for vectors directory
/*D
   VEIntro - This is an introduction to the vector routines.

   Description:
   The VE*, DV*, DVP*, ZV*, and ZVP* routines are used to 
generate and manipulate either parallel or serial vectors.
These routines are used extensively in the IT* package 
(iterative solvers) and the SV* package (simplified solvers).

   We define a vector context, VECtnx, which contains pointers 
to the routines which act on vectors, for instance dot products.
These vector routines are the only routines which actually access
the vectors directly. In this way, the vector routines can be changed
completely (for instance for use on a parallel machine) without 
changing the application routines (for instance an iterative
solver) at all. 

  All vector routines take as their first argument a pointer to 
a structure, the first element of which must be the (local) size
of the vector. The rest of the structure is ignored. This structure,
which we call the user context, allows the user to transfer 
information, to, for instance, matrix multiply routine without changing the 
calling sequences, using global variables or common blocks.

$  VECntx has the following entries: (see vector.h)

$    dot(N,x,y,value)       -  value = x'*y; dot product
$    norm(N,x,value)        -  value = sqrt(x'*x); two norm 
$    scal(N,alpha,x)        -  x = alpha*x; scale by a scalar
$    copy(N,x,y)            -  y = x; copy vector
$    swap(N,x,y)            -  x = y and y = x; swap two vectors
$    set(N,alpha,x)         -  x[i] = alpha, for all i
$    axpy(N,alpha,x,y)      -  y = y + alpha * x;
$    aypx(N,alpha,x,y)      -  y = x + alpha *y;
$    waxpy(N,alpha,x,y,w)   -  w = y + alpha * x;
$    obtain_vectors(N,m)    -  a pointer to pointers to m vectors
$    release_vectors(N,v,m) - destroys same 
$    CreateVector(N)        - returns a pointer to one vector
$    DestroyVector(N,v)     - destroys same

$    void *N - pointer to a structure the first element which is the 
$        length of the (local part) of the vector.

$  several default sets of vector operations are provided.

$   Serial double precision                 DV*
$   Serial complex double precision         ZV*
$   Parallel double precision               DVP*
$   Parallel complex double precision       ZVP*
     
$ -------------------------Sample Calling Sequences-----------------

$  VECntx           *vecntx;
$  VEDefaultUsrCntx *N;
$  int              n = 100;

$  vecntx = VECreate();
$  N = VECreateDefaultUserCntx(n);
$  DVSetDefaultFunctions(vecntx);

$  x = DVCreateVector(N);

$   ..... 

$  DVDestroyVector(N,x);
$  VEDestroy(vecntx);
D*/

