Tim Mitchell

eigsPlus

eigsPlus provides an enhanced, alternative version to Matlab's eigs routine, supported on Matlab R2012b and later and Octave, providing the following features:

  1. Only the converged eigenvalues and eigenvalue eigenvector pairs are returned, so the user no longer needs to worry about accidentally using the placeholder zeros (R2013a and earlier) or NaNs for unconverged Ritz values in a subsequent computation.
  2. The eigenvalues are always returned in a column vector, and never a diagonal matrix, unlike Matlab's eigs routine, which will return the eigenvalues as a diagonal matrix when eigenvectors are always requested.
  3. If no eigenvalues are resolved, a warning is issued instead of throwing an error. In this case, the returned eigenvalues and eigenvectors will respectively be an empty vector and an empty matrix.
  4. The number of ARPACK iterations incurred is returned via the third output argument. The output argument flag is no longer returned as the user can always equivalently check if the number of eigenvalues returned is less than what the user requested.
  5. The user may set opts.isreal = false to force the complex ARPACK routines to be used even if matrix A is real and opts.v0 is either real or complex. Matlabs's eigs would throw an error in either of these cases. eigsPlus will throw an error in either of these cases if opts.isreal is either not provided or if it is set to true.
Note that only features (1) and (2) are supported on Octave.

How to install and use eigsPlus

  1. Download the latest version of eigsPlus on GitLab (v2.0).
  2. The requirements for installing eigsPlus are:

    • Matlab R2012b (or newer) or Octave (Note that not all eigsPlus features are supported on Octave.)
    • The patch command, supporting patches created with diff -u, must be available on the system terminal
    • The md5 command must also be available on the system terminal
    For Linux and Mac users, the patch and md5 commands should already be present. Windows users may need to install these tools themselves.

  3. To install eigsPlus:

    • Add the desired location of the extracted eigsPlus folder to the search path in Matlab
    • Run makeEigsPlus(); to install eigsPlus for the currently running version of Matlab. It will either print a confirmation of successful installation or throw an error detailing why eigsPlus could not be installed.
    • Note that each eigsPlus installation is version specific; if you change releases of Matlab (e.g. R2014b to R2015a), you will need to rerun makeEigsPlus() to update your eigsPlus installation. The eigsPlus command will throw an error if eigsPlus is not installed for the currently running version of Matlab.
  4. To read the eigsPlus documentation, enter: help eigsPlus help makeEigsPlus help cleanEigsPlus
  5. Instead of calling eigs, call the eigsPlus command, which share identical input arguments. While the output arguments of eigsPlus are not exactly identical to the output arguments of eigs, migrating preexisting code should still be extremely straightforward.

    Note that the first call to eigsPlus may be a slightly longer than subsequent calls, due to initialization cost. Though this is likely to be insignificant, it is nonetheless prudent to make sure eigsPlus is called at least once before conducting sensitive timing experiments.

Citing

If you publish work that either refers to or makes use of eigsPlus, please cite both its name and version number, e.g. eigsPlus v2.0. Note that eigsPlus, in monospaced font, refers to the command/routine, not the name of the software package.

License

eigsPlus is licensed under the GNU Affero General Public License, version 3.