Arrabit

Augmented Rayleigh-Ritz (ARR) And Block Iteration
for large-cale eigenpair computation

-----------------------------------------------------------------------------
1. Introduction

Arrabit is a MATLAB solver for computing many eigenpairs of large-scale 
sparse (or structured) matrices.  In general, the dominant computational 
cost in Arrabit is the matrix multiplications (A*X). 

Iterations in Arrabit consist of two major steps:
1) a multi-power method (MPM) or a Gauss-Newton (GN) step that generates 
  bases for approximate eigenspaces
2) an ARR projection step that extracts approximate eigenpairs.
Arrabit makes use of a set of polynomial accelerators, as well as other 
techniques such as continuation and deflation.

2. Installation and Setup:

2.1) Download and unzip arrabit_beta1.zip. This should create a directory 
arrabit_beta1.  You may move this directory to a desired location of your 
choice.  We refer to this directory as <arrabit-root>.

2.2) Start MATLAB and add <arrabit-root/src> to your path by the command:
>> addpath <arrabit-root/src>

2.3) To verify the Arrabit installation, go to <arrabit-root/examples> 
and execute the following command:
>> demo_eig

———————————————————————————————————
Note: The performance of Arrabit may be determined by the efficiency
of the matrix-matrix multiplications AX. For example, the sparse
matrix-dense vector products using intel MKL often speed up
the algorithm significantly. 

 http://bicmr.pku.edu.cn/~wenzw/arrabit.html#issue

The following step is not required if sfmult is not used.

2.4) Optional installation with sfmult.cpp in MKL 
- step 1: install the MKL Library
— step 2: choose one of the following methods suitable to your system.

 (i) build sfmult.cpp using the makefile in the subdirectory “src”.
   Please specify the paths to MKL and mex. 

   ** Either a dynamic or static library may be chosen to be built.


 (ii) Matlab 2014b, Mac OS Yosemite:
   ** add the following line in ~/.bash_profile
	source /opt/intel/bin/compilervars.sh intel64
   
   ** run Installmex.m

   ** start matlab from a command line. This is important to ensure that MKL is loaded.
   

 (iii) Matlab 2013b, Ubuntu 12.04
   ** configure mexopts.sh with the following lines
   
   ————————————————
   MKLLIBDIR=$MKLROOT/lib/intel64
   MKLLIBS="$MKLLIBDIR/libmkl_gf_lp64.a $MKLLIBDIR/libmkl_gnu_thread.a $MKLLIBDIR/libmkl_core.a"
   CXXFLAGS='-ansi -D_GNU_SOURCE'
   CXXFLAGS="$CXXFLAGS -fPIC -fno-omit-frame-pointer -pthread   "
   CXXLIBS="$RPATH $MLIBS -lm  -Wl,--start-group $MKLLIBS -Wl,--end-group -ldl"
   ————————————————
    
   ** run Installmex.m or simply the following lines
   mex -O -largeArrayDims -lmwlapack -lmwblas  sfmult.cpp


3. Detailed Usage

       [U,D,Out] = arrabit(A,k,sigma,opts)
    or [U,D,Out] = arrabit(Afun,n,k,sigma,opts)

Input:
       A -- n by n real symmetric matrix (numeric)
    or Afun,n -- function handle and size of A
       k -- number of extreme eigenpairs to compute
   sigma -- 'LA' or 'SA', Largest or Smallest Algebraic
    opts -- optional parameters
Output:
       U -- computed k extreme eigenvectors
              (n by k column-orthonormal matrix)
       D -- computed k extreme eigenvalues
              (k by k sparse matrix)
     Out -- output information


4. Reports:

   @TECHREPORT{WenZhang2015,
       author = {Wen, Zaiwen and Yin, Zhang},
       title = {Block algorithms with augmented Rayleigh-Ritz projections
		        for large-scale eigenpair computation},
       institution = {Rice University},
       year = {2015}
       }

5. Licenses

Arrabit is distributed under the terms of the GNU General Public License 3.0.
http://www.gnu.org/copyleft/gpl.html

6. The Authors

We hope that Arrabit is useful for your application.  If you have
any bug reports or comments, please feel free to email one of the
toolbox authors:

   Zaiwen Wen, wenzw@pku.edu.cn
   Yin Zhang, yzhang@rice.edu
