===========================
Some BLAS Level 1 Functions                                         [TOC]
===========================

- For the sake of simplicity we will only consider matrix/vector elements
  of type `double` in this class.
- All vectors must be allocated before the function gets called.
- An operator description like $x \rightarrow y$ is read as _vector $y$
  gets overwritten with vector $y$_.
- Furthermore:
   - lower case letters indicate vectors, upper case letters matrices.
   - it is assumed that different letters refer to non-overlapping
     vectors/matrices, i.e. they have no elements in common.
     *Otherwise the result might be undefined.*


All BLAS function names get an additional prefix that depends on the
matrix/vector element type:

   +-----------------+---------------------------+-----------------------+
   | *Prefix*        | *Meaning*                 | *Element Type in C*   |
   +-----------------+---------------------------+-----------------------+
   | s               | single precision          | float                 |
   +-----------------+---------------------------+-----------------------+
   | d               | double precision          | double                |
   +-----------------+---------------------------+-----------------------+
   | c               | complex single precision  | float _Complex        |
   +-----------------+---------------------------+-----------------------+
   | z               | complex double precision  | double _Complex       |
   +-----------------+---------------------------+-----------------------+

So functions `scopy`, `dcopy`, `ccopy` and `zcopy` provide the same
functionality for vectors where elements are of type `float`, `double`,
`float _Complex` and `double _Complex` respectively.

Short Description of some BLAS Level 1 Functions
================================================

`copy`: Copy Vectors
--------------------

   +---------------------+-------------------------------------------+
   | Operation           | Signature                                 |
   +---------------------+-------------------------------------------+
   | $x \rightarrow y$   | ==== CODE(Type=c)======================== |
   |                     | void                                      |
   |                     | dcopy(size_t n,                           |
   |                     |       const double *x, ptrdiff_t incX,    |
   |                     |       double *y, ptrdiff_t incY);         |
   |                     | ========================================= |
   +---------------------+-------------------------------------------+


`swap`: Interchanging Vectors
-----------------------------

   +-------------------------+-------------------------------------------+
   | Operation               | Signature                                 |
   +-------------------------+-------------------------------------------+
   | $x \leftrightarrow y$   | ==== CODE(Type=c)======================== |
   |                         | void                                      |
   |                         | dswap(size_t n,                           |
   |                         |       double *x, ptrdiff_t incX,          |
   |                         |       double *y, ptrdiff_t incY);         |
   |                         | ========================================= |
   +-------------------------+-------------------------------------------+


`axpy`: Adding Vectors (Alpha x Plus y)
---------------------------------------

   +-------------------------+-------------------------------------------+
   | Operation               | Signature                                 |
   +-------------------------+-------------------------------------------+
   |$\alpha x+y\rightarrow y$| ==== CODE(Type=c)======================== |
   |                         | void                                      |
   |                         | daxpy(size_t n, double alpha,             |
   |                         |       const double *x, ptrdiff_t incX,    |
   |                         |       double *y, ptrdiff_t incY);         |
   |                         | ========================================= |
   +-------------------------+-------------------------------------------+

- In the special case $\alpha=0$ the function returns immediately (_NOP case_).

`scal`: Scaling Vectors
-----------------------

   +-------------------------+-------------------------------------------+
   | Operation               | Signature                                 |
   +-------------------------+-------------------------------------------+
   | $\alpha x\rightarrow x$ | ==== CODE(Type=c)======================== |
   |                         | void                                      |
   |                         | dscal(size_t n, double alpha,             |
   |                         |       double *x, ptrdiff_t incX);         |
   |                         | ========================================= |
   +-------------------------+-------------------------------------------+

- In the special case $\alpha=1$ the function returns immediately (_NOP case_).
- In the special case $\alpha=0$ must not multiply elements of $x$ with zero.
  Instead $x$ gets overwritten with zeros.  Hence, in this case we allow that
  $x$ contains `NaN` values.

`dot`: dot product
------------------

   +----------------------------+-------------------------------------------+
   | Operation                  | Signature                                 |
   +----------------------------+-------------------------------------------+
   | $x^T y \rightarrow alpha$  | ==== CODE(Type=c)======================== |
   |                            | double                                    |
   |                            | ddot(size_t n,                            |
   |                            |      const double *x, ptrdiff_t incX,     |
   |                            |      const double *y, ptrdiff_t incY);    |
   |                            | ========================================= |
   +----------------------------+-------------------------------------------+


Exercise
========

Complete the following code by

- implementing the BLAS Level 1 functions and
- doing some (very) simple test calls in function `main`

:import: session04/blas1_ex.c


:navigate: up    -> doc:index
           next  -> doc:session04/page02