Tim Mitchell


eigsPlus provides an enhanced, alternative version to the MATLAB routine eigs, 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. If none converge, empty arrays are returned.
  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, on R2016b and earlier, eigs would throw an error; on these versions, eigsPlus will instead throw a warning. On R2017a, eigs also adopted the same convention of throwing a warning instead of an error. However, on R2017b, eigs no longer throws a warning or an error. To maintain consistency, as of R2017b, eigsPlus also no longer throws a warning. Recall in the case that no Ritz value converges, the returned eigenvalues and eigenvectors will be empty.
  4. The third output argument, flag, has been repurposed to return the number of iterations that is incurred; the user can always equivalently check if the number of eigenvalues returned is less than what the user requested by checking the dimensions of the eigenvalue and/or eigenvector output arguments. For R2017a and earlier, this is the number of ARPACK iterations. On newer releases, this is the number of Krylov Schur iterations but note that for problems with symmetric positive definite B matrices using shift-invert, the Krylov Schur method may be restarted once, if the first fails; in this case, the number of iterations is the sum of two attempts.
  5. R2017a and earlier only: 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.1).
  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.


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.1. Note that eigsPlus, in monospaced font, refers to the command/routine, not the name of the software package.


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