ABLEpack Simple Users' Guide

• Introduction
• Getting Started
  • MATLAB Path for ABLEpack
  • ABLEpack Demos
• Using ABLEpack
  • Simple Use and Expert Use
  • ppp Input
  • Calling ppp
  • ppp Output
• Examples

Introduction

Getting Started

• MATLAB Path for ABLEpack

  ABLEpack must be in your MATLAB path before you attempt to use it. Here's how to add the ABLEpack directory to your path, assuming you started MATLAB in a directory containing the ABLEpack directory. The last two lines are not needed if you do not have the testing components of ABLEpack.

          path( path, 'ABLEpack/src/' );
          path( path, 'ABLEpack/testing/testsrc/' );
  	path( path, 'ABLEpack/testing/testmat/' );
  

• ABLEpack Demos

  To see what ABLEpack's ppp routine can do, Start MATLAB, put ABLEpack in your MATLAB path, and type shortdriver at the MATLAB prompt to see a short demonstration. You can also type pabledemo to see a longer demo program. In these demonstrations, Lanczos computation is performed by the pable routine, pre- and post-processing by the ppp routine.
  

Using ABLEpack

• Simple Use and Expert Use

  This section is intended for simple users of ABLEpack, those new to it and those who would like to make use of ABLEpack quickly and easily. For this reason, the focus will be on the ppp function, which encapsulates the pable function and provides convenient pre-processing (matrix balancing, shift-and-invert spectral transformation) and post-processing. The ppp function is easier to use because it has less parameters than the pable function. The expert user may call pable directly. Consult code documentation to do so.
  
  

• ppp Input

  The ppp routine takes quite a few parameters, but not all of them are required. If you pass only the required parameters, default values will be used for the rest. Please note, you must either pass none of the optional input parameters or all of them.
  
  Minimum (Required) Input Parameters
  
  

  Name	Type	Description
  problem	integer	1: standard eigenvalue problem A x = lambda x 2: generalized eigenvalue problem A x = lambda B x
  matbal	integer	Only meaningful if problem == 1. 0: do not perform matrix balance pre-processing 1: perform matrix balance pre-processing
  A	sparse matrix	matrix A
  B	sparse matrix	matrix B, only meaningful if problem != 1 should be set to the identity matrix if problem == 1
  neig	integer	minimum number of eigenvalues desired

  
  
  Optional Input Parameters
  
  

  Name	Type	Default Value	Description
  fulldual	integer	1	if == 1, rebiorthogonalization at every step
  semidual	integer	0	if == 1, rebiorthogonalize only at selected steps
  group	integer	0	if == 1, adapt blocksize
  treatbd	integer	0	if == 1, treat breakdown
  nb	integer	1	number of blocks, if > 1, block Lanczos used
  maxit	integer	n	maximum number of iterations
  precond	integer	0	0: no preconditioning 1: LU factorization, shift-and-invert others described in file matvec.m, but not tuned for problem type 2, precond is ALWAYS 1, regardless of user input
  alpha	double	0.0	shift value, meaningless if precond == 0 do NOT use a shift value of zero with singular matrices
  L	matrix	0	L factor of LU decomposition of (A - alpha * B) if both L and U are zero, they will be computed
  U	matrix	0	U factor of LU decomposition of (A - alpha * B) if both L and U are zero, they will be computed

  
  The algorithm has four different performance levels, determined by the parameters fulldual, semidual, group, and treatbd. Level 2 is the defualt level.

    level  fulldual  semidual  group  treatbd
      1       0         0        0       0     (eigenvalues only)
      2       1         0        0       0
      3       0         1        0       0
      4       1         1        1       1     (only one of fulldual or semidual is required)
  

• Calling ppp

  You can call ppp with just the minimal required input, or with all of its input.
  
  Here, ppp is called with just the minimal required input.

  [ neig, ritz, eigvecl, eigvecr, resl, resr, condnum ]...
   = ppp( problem, matbal, A, B, neig );
  

  Here, all the input is provided.

  [ neig, ritz, eigvecl, eigvecr, resl, resr, condnum ]...
   = ppp( problem, matbal, A, B, neig, ...
          fulldual, semidual, group, treatbd, ...
          nb, maxit, precond, alpha, L, U );
  

  In the current version, you must either provide all of the optional input parameters, or none of them, you can't provide some but not others.
  
  The calling sequences above showed ppp returning seven output parameters. It can return more than that, but those seven are the ones most commonly used. The other output parameters are listed in order in the output section below.
  
  

• ppp Output

  The table below shows a partial list of ppp's output parameters. These are the most commonly used "essential" output parameters.
  
  Essential Output Parameters
  
  

  Name	Type	Description
  neig	integer	number of converged Ritz values
  ritz	double array	Ritz values (approximate eigenvalues)
  eigvecl	double array	left eigenvectors
  eigvecr	double array	right eigenvectors
  resl	double array	left residual norms of all Ritz pairs
  resr	double array	right residual norms of all Ritz pairs
  condnum	double array	condition number of converged Ritz values only returned if level >= 2

  
  
  Expert users may wish to retrieve all of ppp's output parameters. This table shows the rest of the output parameters. If you wish to use the printout script to display your own output, you must retrieve these output parameters.
  
  Complete Output Parameters
  
  The table of "essential" output parameters above, along with the table below provide a complete list of ppp's output parameters.
  
  

  ritzvalue	double array	eigenvalues of matrix T
  szoft	integer	size of T, reduced (block) tridiagonal matrix
  duality	double array	estimated duality (biorthogonality) of Lanczos vectors
  exdual	double array	exact duality
  omega	double array	k'th element of omega is the smallest singular value of P_k^T*Q_k, where P_k and Q_k are the k'th blocks of the left and right eigenvectors.
  resl_e	double array	exact left residuals
  resr_e	double array	exact right residuals
  tolconv	double	stopping criterion for convergence test
  numlsteps	integer	number of Lanczos steps

  
  
  Check out the examples section and the file printout.m to see how to display the output.

Examples

• example1.m standard non-Hermitian problem, find eigenvalues, input - complete, output - essential only
• example2.m standard non-Hermitian problem, find eigentriplets, input - minimal, output - essential only
• example3.m generalized non-Hermitian problem, find eigentriplets, input - complete, output - complete, shows use of printout script