PLASMA INSTALLATION GUIDE
=========================

This page describes how to install, and test version PLASMA 2.2.0, a linear
algebra package for high-performance computers, on a Linux, Unix and MacOS X System.
Windows installation instructions are not contained in this document.

This work was supported by NSF Grant No. CCF-0811642, NSF Grant No. CCF-0811520 and Microsoft.

Introduction
------------

PLASMA is a linear algebra library for high-performance computers.
The library includes Fortran 77 and C subroutines for the analysis and solution
of systems of simultaneous linear algebraic equations, linear least-squares problems,
and matrix eigenvalue problems.

The Parallel Linear Algebra for Scalable Multi-core Architectures (PLASMA) project
aims to address the critical and highly disruptive situation
that is facing the Linear Algebra and High Performance Computing community
due to the introduction of multi-core architectures.

PLASMA's ultimate goal is to create software frameworks that enable programmers
to simplify the process of developing applications that can achieve both high performance
and portability across a range of new architectures.

The development of programming models that enforce asynchronous, out of order scheduling of operations
is the concept used as the basis for the definition of a scalable yet highly efficient software framework
for Computational Linear Algebra applications.

This guide describes how to install, test, and time this release of PLASMA on a Linux, Unix and Mac OS/X System.

In order to install the PLASMA library, you require a C compiler, a
Fortran Compiler, a BLAS library, a CBLAS Library, a LAPACK library,
the LAPACK C Wrapper Library, and the availability of the pthread
library. If you want to use testings and timings routines, you will
also need the TMG library included in Lapack for matrices generation.
Before PLASMA can be built, or tested, you must define all
machine-specific parameters for the architecture to which you are
installing PLASMA. All machine-specific parameters are contained in
the file make.inc. We provide you an installer to ease the
installation process and to install missing librairies. Users are
strongly encouraged to use it.
We also strongly recommend to install on your system the HWLoc library for a better control of thread binding.
(See http://www.open-mpi.org/projects/hwloc/)

Getting the PLASMA Installer
----------------------------
The PLASMA installer is a set of python scripts developed to ease the installation of the
PLASMA library. It can automatically download, configure and compile the PLASMA
library including its dependencies.
It is available on PLASMA download page:
http://icl.cs.utk.edu/plasma/software/

PLASMA Installer flags
----------------------
Here is a list of the flags that can be used to provide the installer information about the
system like, for example, the C and Fortran compilers, the BLAS library that is already
present on the system and need not be downloaded.

    -h or --help        : display this help and exit
 
    --prefix=[DIR]      : install files in DIR [./install]
 
    --build=[DIR]       : libraries are built in DIR [./build]
                          Contains log, downloads and builds.
 
    --cc=[CMD]          : the C compiler. [cc]
 
    --fc=[CMD]          : the Fortran compiler. [gfortran]
 
    --cflags=[FLAGS]    : the flags for the C compiler [-02]
 
    --fflags=[FLAGS]    : the flags for the Fortran compiler [-O2]
 
    --ldflags_c=[flags] : loader flags when main program is in C. Some
                          compilers (e.g. PGI) require different
                          options when linking C main programs to
                          Fortran subroutines and vice-versa
 
    --ldflags_fc=[flags]: loader flags when main program is in
                          Fortran. Some compilers (e.g. PGI) require
                          different options when linking Fortran main
                          programs to C subroutines and vice-versa.
                          If not set, ldflags_fc = ldflags_c.
 
    --make=[CMD]        : the make command [make]
 
    --blaslib=[LIB]     : a BLAS library
                          (path should be absolute if --prefix is used)
 
    --cblaslib=[LIB]    : a CBLAS library
                          (path should be absolute if --prefix is used)
 
    --lapacklib=[LIB]   : a Lapack library
                          (path should be absolute if --prefix is used)
 
    --lapclib=[DIR]     : path to a LAPACK C wrapper.
                           (path should be absolute if --prefix is used)
 
    --downblas          : Download and install reference BLAS.
                          
    --downcblas         : Download and install reference CBLAS.
 
    --downlapack        : Download and install reference LAPACK.
 
    --downlapc          : Download and install reference LAPACK C Wrapper.
 
    --downall           : Download and install all missing external libraries.
                          If you don't have access to wget or no network 
 			 connection, you can provide the following packages 
 			 in the directory builddir/download:
         http://netlib.org/blas/blas.tgz
         http://www.netlib.org/blas/blast-forum/cblas.tgz
         http://www.netlib.org/lapack/lapack.tgz
         http://icl.cs.utk.edu/projectsfiles/plasma/pubs/lapack_cwrapper.tgz
         http://icl.cs.utk.edu/projectsfiles/plasma/pubs/plasma.tar.gz
 
    --[no]testing       : enables/disables the testings. All externals 
                          libraries are required and tested if enabled.
                          Enable by default.
 
    --nbcores           : The number of cores to be used by the testing. [2]
 
    --clean             : cleans up the installer directory.

The installer will set
....
OMP_NUM_THREADS=1
GOTO_NUM_THREADS=1
MKL_NUM_THREADS=1
....
to disable the multithreading within BLAS. Do not forget to set those environment variables
for any further PLASMA testing you want to run.

PLASMA Installer Usage
----------------------
For an installation with gcc, gfortran and Reference BLAS
....
./setup.py --cc gcc --fc gfortran --downblas
....
For an installation with ifort, icc and MKL (em64t architecture)
....
./setup.py --cc icc --fc ifort --blaslib="-lmkl_em64t -lguide"
....
For an installation with gcc, gfortran and Veclib (Mac OS/X)
....
./setup.py --cc gcc --fc gfortran --blaslib="-framework veclib"
....
For an installation with gcc, gfortran, ATLAS
....
./setup.py --cc gcc --fc gfortran --blaslib="-lf77blas -lcblas -latlas"
....
For an installation with gcc, gfortran, goto BLAS and 4 cores
....
./setup.py --cc gcc --fc gfortran --blaslib="-lgoto" --nbcores=4
....
For an installation with xlc, xlf, essl and 8 cores
....
./setup.py --cc xlc --fc xlf --blaslib="-lessl" --nbcores=8
....

Remarks: By default, the major BLAS librairies (ACML, ESSL, Goto, MKL, ...)
include CBLAS and LAPACK librairies, so you just have to specify which
one you want to use as follow. However, ATLAS library does not include
LAPACK library and only MKL includes TMG library from LAPACK for
matrices generation in tests. In these case, the installer will
automatically download for you the missing libraries and compiles them
with your specified BLAS library.

PLASMA Installer Support
----------------------
Please note that this is an alpha version and, even if it has been tested on a wide set of
systems, may not work. In case you encounter a problem, your feedback would be greatly
appreciated and would be very useful to improve the quality of this installer. Please submit
your complaints and suggestions to the PLASMA forum:
http://icl.cs.utk.edu/plasma/forum/

Tips and Tricks
-----------------
Testings are slow
~~~~~~~~~~~~~~~~~
Please note that, in the case where the installer is asked to automatically download and
install the BLAS library, the reference BLAS is installed and, thus, very low performance is
to be expected. It is strongly recommended that you use an highly optimized BLAS library
(like ATLAS, MKL, GotoBLAS, ESSL etc.) and provide a path to its location through the
-blaslib flag.

For Mac
~~~~~~~~ 
Veclib is accessible if you install the Xcode/developer package provides with your Mac OS
installation CD. On MAC OS/C you may be required to add
--ccflags=' -I/usr/include/sys/'

Processors with Hyper-threading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The plasma installer cannot detect if you have hyper-threading or not on your machine, if you don't use HWLoc library. 
In this case, we advice always to limit the number of core for the first testing of the PLASMA library
to half the numbers of cores available if you do not know your exact architecture. Using
hyper-threading will cause the PLASMA testings to hangs.

Problem with download
~~~~~~~~~~~~~~~~~~~~~
If the required packages cannot be automatically downloaded (for example, because no
network connection is available on the system), you can take them any way you like
from the following URLs and place them in the build/download directory (if the directory does not exist, create it):

BLAS             : http://netlib.org/blas/blas.tgz

CBLAS            : http://www.netlib.org/blas/blast-forum/cblas.tgz

LAPACK           : http://www.netlib.org/lapack/lapack.tgz

LAPACK C WRAPPER : http://icl.cs.utk.edu/projectsfiles/plasma/pubs/lapack_cwrapper.tgz

PLASMA           : http://icl.cs.utk.edu/projectsfiles/plasma/pubs/plasma.tar.gz



