                           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
   [1]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:
   [2]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:
   [3]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 : [4]http://netlib.org/blas/blas.tgz

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

   LAPACK : [6]http://www.netlib.org/lapack/lapack.tgz

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

   PLASMA :
   [8]http://icl.cs.utk.edu/projectsfiles/plasma/pubs/plasma.tar.gz
     __________________________________________________________________

   Last updated 2010-07-12 17:18:18 EDT

Références

   1. http://www.open-mpi.org/projects/hwloc/
   2. http://icl.cs.utk.edu/plasma/software/
   3. http://icl.cs.utk.edu/plasma/forum/
   4. http://netlib.org/blas/blas.tgz
   5. http://www.netlib.org/blas/blast-forum/cblas.tgz
   6. http://www.netlib.org/lapack/lapack.tgz
   7. http://icl.cs.utk.edu/projectsfiles/plasma/pubs/lapack_cwrapper.tgz
   8. http://icl.cs.utk.edu/projectsfiles/plasma/pubs/plasma.tar.gz
