====================================================================
daxpy examples
====================================================================

For each of the following examples we assume that we have preset
the variables to the following values. Note that the daxpy function
will modify the second array. Each example assumes we have reset
the variables to these values.

a:PRIMARR(DFLOAT):=[ [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0] ]
b:PRIMARR(DFLOAT):=[ [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0] ]

then we compute the sum of the first 3 elements of each vector
and we show the steps of the computation with trailing comments.
The comments show which elements are changed and what the computation is.

daxpy(3,2.0,a,1,b,1) ==> [3.,6.,9.,4.,5.,6.,7.]
  dy(0)[3.0] = dy(0)[1.0] + ( da[2.0] * dx(0)[1.0] )
  dy(1)[6.0] = dy(1)[2.0] + ( da[2.0] * dx(1)[2.0] )
  dy(2)[9.0] = dy(2)[3.0] + ( da[2.0] * dx(2)[3.0] )

or we compute the first 7 elements of each vector

daxpy(7,2.0,a,1,b,1) ==> [3.,6.,9.,12.,15.,18.,21.]
  dy(0) [3.0] = dy(0)[1.0] + ( da[2.0] * dx(0)[1.0] )
  dy(1) [6.0] = dy(1)[2.0] + ( da[2.0] * dx(1)[2.0] )
  dy(2) [9.0] = dy(2)[3.0] + ( da[2.0] * dx(2)[3.0] )
  dy(3)[12.0] = dy(3)[4.0] + ( da[2.0] * dx(3)[4.0] )
  dy(4)[15.0] = dy(4)[5.0] + ( da[2.0] * dx(4)[5.0] )
  dy(5)[18.0] = dy(5)[6.0] + ( da[2.0] * dx(5)[6.0] )
  dy(6)[21.0] = dy(6)[7.0] + ( da[2.0] * dx(6)[7.0] )

or we compute the first 8 elements, which fails due to the fact that
the vectors are not long enough.

daxpy(8,2.0,a,1,b,1) ==> [1.,2.,3.,4.,5.,6.,7.]

or we compute the 3 elements, taking every 3rd element, giving the
index of 0, 3, 6

daxpy(3,2.0,a,3,b,3) ==> [3.,2.,3.,12.,5.,6.,21.]
  dy(0) [3.0] = dy(0)[1.0] + ( da[2.0] * dx(0)[1.0] )
  dy(3)[12.0] = dy(3)[4.0] + ( da[2.0] * dx(3)[4.0] )
  dy(6)[21.0] = dy(6)[7.0] + ( da[2.0] * dx(6)[7.0] )

or we compute 4 elements, taking every 2nd element, giving the
index of 0, 2, 4, 6

daxpy(4,2.0,a,2,b,2) ==> [3.,2.,9.,4.,15.,6.,21.]
  dy(0) [3.0] = dy(0)[1.0] + ( da[2.0] * dx(0)[1.0] )
  dy(2) [9.0] = dy(2)[3.0] + ( da[2.0] * dx(2)[3.0] )
  dy(4)[15.0] = dy(4)[5.0] + ( da[2.0] * dx(4)[5.0] )
  dy(6)[21.0] = dy(6)[7.0] + ( da[2.0] * dx(6)[7.0] )

or we compute 5 elements, taking every 2nd element, which fails
due to vector length

daxpy(5,2.0,a,2,b,2) ==> [1.,2.,3.,4.,5.,6.,7.]

or we compute 3 elements, taking every 2nd value, giving the 
index of 0, 2, 4

daxpy(3,2.0,a,2,b,2) ==> [3.,2.,9.,4.,15.,6.,7.]
  dy(0) [3.0] = dy(0)[1.0] + ( da[2.0] * dx(0)[1.0] )
  dy(2) [9.0] = dy(2)[3.0] + ( da[2.0] * dx(2)[3.0] )
  dy(4)[15.0] = dy(4)[5.0] + ( da[2.0] * dx(4)[5.0] )

or we compute 3 elements, taking every 2nd value, giving the
index of 0, 2, 4 but with a negative multiplier

daxpy(3,-2.0,a,2,b,2) ==> [- 1.,2.,- 3.,4.,- 5.,6.,7.]
  dy(0)[-1.0] = dy(0)[1.0] + ( da[-2.0] * dx(0)[1.0] )
  dy(2)[-3.0] = dy(2)[3.0] + ( da[-2.0] * dx(2)[3.0] )
  dy(4)[-5.0] = dy(4)[5.0] + ( da[-2.0] * dx(4)[5.0] )

or we change the lengths of the input vectors, making them unequal.
So for the next two examples we assume the arrays look like:

a:PRIMARR(DFLOAT):=[ [ 1.0, 2.0, 3.0] ]
b:PRIMARR(DFLOAT):=[ [ 1.0, 2.0, 3.0, 4.0, 5.0] ]

We compute 3 elements, with a negative multiplier, and different increments
using an index for the 'a' array having values 0, 1, 2
using an index for the 'b' array having values 0, 2, 3

daxpy(3,-2.0,a,1,b,2) ==> [- 1.,2.,- 1.,4.,- 1.]
  dy(0)[-1.0] = dy(0)[1.0] + ( da[-2.0] * dx(0)[1.0] )
  dy(2)[-1.0] = dy(2)[3.0] + ( da[-2.0] * dx(1)[2.0] )
  dy(4)[-1.0] = dy(4)[5.0] + ( da[-2.0] * dx(2)[3.0] )

or we compute 3 elements with a multiplier of 0.0 which fails

daxpy(3,0.0,a,1,b,2) ==> [1.,2.,3.,4.,5.,6.,7.]

====================================================================
Man Page Details
====================================================================

NAME
       DAXPY - BLAS level one axpy subroutine

SYNOPSIS
       SUBROUTINE DAXPY    ( n, alpha, x, incx, y, incy )

           INTEGER           n, incx, incy

           DOUBLE PRECISION  alpha, x, y


DESCRIPTION
       DAXPY  adds  a  scalar multiple of a double precision vector to another
       double precision vector.

       DAXPY computes a constant alpha times a vector x plus a vector y.   The
       result overwrites the initial values of vector y.

       This routine performs the following vector operation:

            y  <--  alpha*x + y

       incx and incy specify the increment between two consecutive
       elements of respectively vector x and y.

ARGUMENTS
       n       INTEGER. (input)
               Number  of  elements in the vectors.  If n <= 0, these routines
               return without any computation.

       alpha   DOUBLE PRECISION. (input)
               If alpha = 0 this routine returns without any computation.

       x       DOUBLE PRECISION, (input)
               Array of dimension (n-1) * |incx| + 1.  Contains the vector  to
               be scaled before summation.

       incx    INTEGER. (input)
               Increment between elements of x.
               If incx = 0, the results will be unpredictable.

       y       DOUBLE PRECISION, (input and output)
               array of dimension (n-1) * |incy| + 1.
               Before calling the routine, y contains the vector to be summed.
               After the routine ends, y contains the result of the summation.

       incy    INTEGER. (input)
               Increment between elements of y.
               If incy = 0, the results will be unpredictable.

RETURN VALUES
       When  n <= 0, double precision alpha = 0., this routine returns immedi-
       ately with no change in its arguments.

