                                 PLASMA README

   Univ. of Tennessee, Univ. of California Berkeley and Univ. of Colorado
   Denver
__________ ____       _____    _________   _____      _____
\______   \    |     /  _  \  /   _____/  /     \    /  _  \
 |     ___/    |    /  /_\  \ \_____  \  /  \ /  \  /  /_\  \
 |    |   |    |___/    |    \/        \/    Y    \/    |    \
 |____|   |_______ \____|__  /_______  /\____|__  /\____|__  /
                  \/       \/        \/         \/         \/

   Parallel Linear Algebra Software for Multicore Architectures

   [1]http://icl.cs.utk.edu/plasma/
     __________________________________________________________________

1. Purpose of PLASMA

   The  main  purpose of PLASMA is to address the performance shortcomings
   of the [2]LAPACK and [3]ScaLAPACK libraries on multicore processors and
   multi-socket  systems of multicore processors. PLASMA provides routines
   to  solve dense general systems of linear equations, symmetric positive
   definite systems of linear equations and linear least squares problems,
   using  LU,  Cholesky,  QR  and  LQ  factorizations. Real arithmetic and
   complex  arithmetic  are  supported in both single precision and double
   precision.

   PLASMA has been designed to supercede LAPACK and ScaLAPACK, principally
   by restructuring the software to achieve much greater efficiency, where
   possible,  on  modern  computers  based on multicore processors. PLASMA
   also  relies  on new or improved algorithms. Currently, however, PLASMA
   does  not  serve  as  a  complete  replacement of LAPACK due to limited
   functionality.  Specifically, PLASMA does not support band matrices and
   does  not  solve  eigenvalue  and singular value problems. Also, PLASMA
   does   not   replace  ScaLAPACK  as  software  for  distributed  memory
   computers, since it only supports shared-memory machines.
     __________________________________________________________________

2. Where to Find More Information

   The  main  repository for PLASMA documentation, created to date, is the
   distribution   ./docs   directory.  The  directory  contains  important
   documents such as the reference manual.

   PLASMA  documentation  is  also available online on the PLASMA website:
   [4]http://icl.cs.utk.edu/plasma/

   For installation please refer to the [5]installation guide.

   In  addition,  the  [6]PLASMA  User  Forum  can be used to post general
   questions and comments as well as to report technical problems.
     __________________________________________________________________

3. Important Information about BLAS and LAPACK

  3.1. Optimized BLAS are Critical for Performance

   It  is absolutely critical for performance to use PLASMA in conjunction
   with   an   optimized   implementation  of  the  Basic  Linear  Algebra
   Subroutines  (BLAS)  library. Such implementations are usually provided
   by  the processor manufacturer and are usually available free of charge
   for non-profit use, such as academic research. Examples include:
     * The AMD Core Math Library (ACML),
     * The Math Kernel Library (MKL) from Intel,
     * The Engineering and Scientific Software Library (ESSL) from IBM,
     * The VecLib from Apple.

   Open-source alternatives also exist, such as:
     * [7]Goto BLAS,
     * [8]Automatically Tuned Linear Algebra Software (ATLAS).

   As a last resort, the [9]FORTRAN implementation of BLAS from Netlib can
   be  used  (often  referred to as reference BLAS). However, since Netlib
   BLAS  are  completely unoptimized, PLASMA with Netlib BLAS will deliver
   correct numerical results, but no performance whatsoever.

  3.2. Multithreading within BLAS Must be Disabled

   Many  Basic  Linear  Algebra Subroutines (BLAS) implementations exploit
   parallelism   within  BLAS  through  multithreading.  PLASMA,  however,
   utilizes  BLAS  for  high  performance  implementations  of single-core
   operations  (often  referred to as kernels) and exploits parallelism at
   the  algorithmic level above the level of BLAS. For that reason, PLASMA
   must  not  be used in conjunction with a multithreaded BLAS, as this is
   likely  to  create more execution threads than actual cores, which will
   annihilate  PLASMA's  performance.  PLASMA  needs  to  be linked with a
   sequential   BLAS   library   or  a  multithreaded  BLAS  library  with
   multithreading  disabled. Typically, disabling of multithreading can be
   done  by  setting  an appropriate environment variable from the command
   prompt, for instance:

> export OMP_NUM_THREADS=1
> export MKL_NUM_THREADS=1
> export GOTO_NUM_THREADS=1

   If you are using the ATLAS library, please provide the serial interface
   rather than the parallel. Take a look at
   [10]http://math-atlas.sourceforge.net/errata.html#LINK for more info.

  3.3. CBLAS Is Not Required

   Although many BLAS implementations provide C language API (CBLAS), some
   deviate  from  the standard. Internally, PLASMA calls BLAS through both
   the  FORTRAN 77 interface and the C interface. However, PLASMA does not
   require  the  user  to  provide  CBLAS.  Instead,  PLASMA  includes the
   [11]Netlib  CBLAS  and only requires BLAS with the FORTRAN 77 interface
   (sometimes referred to as the legacy BLAS).

  3.4. LAPACK Is Not Required

   PLASMA  does  not  require  the user to provide the [12]LAPACK library.
   Internally,  PLASMA  calls  a small subset of LAPACK routines. However,
   all necessary LAPACK routines are included in PLASMA.

  3.5. Thou Shalt Not Mix Compilers

   For  a  given  processor,  the user can have different compilers at his
   disposal.  For instance, GNU, PGI and Intel compilers are available for
   Intel  processors.  Different  compilers  can  have  slightly different
   Application  Binary Interfaces (ABIs) and mixing compilers is generally
   a  bad idea. User's code and the PLASMA library should be compiled with
   the  same  compiler,  and  so  should  be the BLAS library, if a source
   distribution is used. If a binary distribution of the BLAS is used, the
   correct version has to be chosen (the one providing the right ABI). For
   Intel  processors,  the [13]Intel Math Kernel Library Link Line Advisor
   can be used to assist with the choice.
     __________________________________________________________________

4. License Information

   PLASMA  is  a  software  package  provided  by University of Tennessee,
   University  of California, Berkeley and University of Colorado, Denver.
   PLASMA's  license  is  a  BSD-style  permissive  free  software license
   (properly  called  modified BSD). It allows proprietary commercial use,
   and for the software released under the license to be incorporated into
   proprietary  commercial  products.  Works  based on the material may be
   released  under  a  proprietary  license  as  long  as PLASMA's license
   requirements  are maintained, as stated in the LICENSE file, located in
   the  main directory of the PLASMA distribution. In contrast to copyleft
   licenses,  like the GNU General Public License, PLASMA's license allows
   for  copies  and derivatives of the source code to be made available on
   terms more restrictive than those of the original license.
     __________________________________________________________________

5. Publications

   A  number  of  technical reports were written during the development of
   PLASMA  and  published as [14]LAPACK Working Notes by the University of
   Tennessee. Many of these reports later appeared as journal articles.
     __________________________________________________________________

6. Funding

   The  PLASMA  project  is funded by the National Science Foundation (NSF
   Grant  No.  CCF-0811642,  NSF  Grant No. CCF-0811520) and the Microsoft
   Corporation.
     __________________________________________________________________

   Last updated 2009-07-04 11:14:57 MDT

References

   1. http://icl.cs.utk.edu/plasma/
   2. http://www.netlib.org/lapack/
   3. http://www.netlib.org/scalapack/
   4. http://icl.cs.utk.edu/plasma/
   5. file://localhost/var/folders/hX/hXbsuqBhHA0gMHnqXWBuOk+++TI/-Tmp-/InstallationGuide.html
   6. http://icl.cs.utk.edu/plasma/forum/
   7. http://www.tacc.utexas.edu/resources/software/
   8. http://math-atlas.sourceforge.net/
   9. http://www.netlib.org/blas/
  10. http://math-atlas.sourceforge.net/errata.html#LINK
  11. http://www.netlib.org/blas/blast-forum/cblas.tgz
  12. http://www.netlib.org/lapack/
  13. http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor/
  14. http://www.netlib.org/lapack/lawns/downloads/
