License Information

This file is part of PRIMME.

PRIMME is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

PRIMME is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Contact Information (reporting bugs or questions about functionality)

Purpose

PRIMME Version 1.2 (December 21, 2014)

Finds a number of eigenvalues and their corresponding eigenvectors of a real symmetric, or complex hermitian matrix A. Largest, smallest and interior eigenvalues are supported. Preconditioning can be used to accelarate convergence.

PRIMME is written in C, but a complete Fortran77 interface is also provided.

Pronounced as "prime"

How to cite this code

To cite PRIMME, please cite paper [1].
More information on the algorithms and research that led to this software can be found in the rest of the papers. The work has been supported by a number of grants from the National Science Foundation.

Directory structure

PRIMME/

Making & Linking

Users must customize Make_flags to create the library.
Users may customize Link_flags to create the test programs.

makefile can perform the following functions:

The dependencies in (D)ZTEST need not be built unless the test code has changed, or the d/zdependencies_* files have been deleted.

The sequential and parallel versions of d/zprimme (the front-ends to PRIMME) are the same, compiled with any sequential compiler. Parallel programs can just link with and call dprimme (see below).

In DTEST/
The driver_seq.c is the driver for the sequential test. It fairly well structured and reads all or any of the parameters from two configuration files. It should be the best starting point. Makefile_seq is used for this.

The provided sample preconditioner and matvec are from SPARSKIT:
See http://www-users.cs.umn.edu/~saad/software/SPARSKIT/sparskit.html

The driver_par.c is the driver for the parallel test. It follows closely the structure of driver_seq.c. It uses MPI for communication and performs matrix- vector multiplications and Sparse Approximate Inverse preconditioning using the ParaSails library. Makefile_par specifies parallel compilation/linking.

ParaSails can be downloaded from: http://computation.llnl.gov/casc/parasails

The driver_f77seq.f is a sample f77 program made with Makefile_f77seq. It calls the Fortran interface provided by PRIMME. This interface includes a set of wrapper functions that are callable from Fortran to manipulate the structure and evoke the eigensolver. For a description of the F77 interface see at the end of this file.

In ZTEST/
We provide driver_seq.c and driver_f77seq.f as in the real case, with Makefile_seq and Makefile_f77seq respectively. Two different diagonal preconditioners can be used, but no ILUT or Parasails.

Systems where the code has been tested

C Library Interface

To solve real symmetric standard eigenproblems call:

int dprimme(double *evals, double *evecs, double *resNorms, primme_params *primme);

To solve hermitian standard eigenproblems call:

int zprimme(double *evals, Complex_Z *evecs, double *resNorms, primme_params *primme);

The following interface functions are available in  PRIMMESRC/COMMONSRC/primme_interface.c

void primme_initialize(primme_params *primme);

int primme_set_method(primme_preset_method method, primme_params *params);

void primme_display_params(primme_params primme);

void *primme_calloc(size_t nelem, size_t elsize, const char *target);

void *primme_valloc(size_t numBytes, const char *target);

void primme_Free(primme_params primme);

To view the primme data structure click here.

Running

To call dprimme follow the basic steps below (look also at  DTEST/driver_seq.c).

• Include:

  #include "primme.h"

• Initialize a primme structure for default settings:
  

  primme_params primme;

  primme_initialize(&primme);

• Then, for a given eigenproblem, set one of the preset methods :

  ret = primme_set_method(method, &primme);

  or/and set some of the various structure members manually (see below and PRIMMESRC/COMMONSRC/primme.h)

• Then call dprimme:

  ret = dprimme(evals, evecs, rnorms, &primme);

  evals	a double array of size primme.numEvals	OUTPUT
  evecs	a double array of size primme.nLocal*primme.n	INPUT / OUTPUT
  rNorms	a double array of size primme.numEvals	OUTPUT
  primme	the above struct. Some members return values	INPUT / OUTPUT
  ret	error return code	OUTPUT

• Before exiting or running primme again free the work arrays in primme:

  primme_Free(&primme);

Required parameter setting

PRIMME requires the user to set at least the following members of the primme struct, as they define the problem to be solved:

In addition, most users would want to specify how many eigenpairs to find, and provide a preconditioner (if available), a mass matrix matvec function (if a generalized eigenproblem), and a globalSum operation (if parallel).

It is useful to have set all these before calling primme_set_method. Also, if users have a preference on basisSize, blockSize, etc, they should also provide them into primme prior to the primme_set_method() call. This helps primme_set_method make the right choice on other parameters.

Preset parameter setting

To use one of the default methods call:

ret = primme_set_method(method, &primme);

with method one of the following:

primme_preset_method method;

In the absense of preset values in the primme structure, primme_set_method() uses expertly tuned default values for all parameters so that users can set a method with minimum or no input.

Users can control any parameter before or after calling primme_set_method().

• Example: if primme.maxBasisSize is set before calling primme_set_method(),
  other parameters (restart size, maximum block size) are computed accordingly.
• Example: Only primme.maxBlockSize and primme.numEvals need be set before calling
  LOBPCG_OrthoBasis_Window, and only primme.numEvals if calling LOBPCG_OrthoBasis.
• Example: Expert users may decide to modify some choices made by primme_set_method(),
  e.g., increasing the maxBasisSize afterwards and before calling (z)dprimme().

See primme_set_method in PRIMMESRC/COMMONSRC/primme_interface.c for exact description of how each method sets the members of the primme structure.

Displaying the primme configuration

The user can call

primme_display_params(primme);

to display all the settings of primme variables. This is done in a format similar to the input format required by our (D)ZTEST drivers. Note that in some cases, a couple of primme variables may change internally in dprimme(). Calling primme_display_params() after dprimme() shows the actual values used.

Primme_params structure

Customized parameter setting

primme has the following members: (indicating also OUTPUT members)

This is the dimension of the matrix.

Block matrix-Multivector multiplication. y = A*x. x is one dimensional array containing the input blockSize vectors packed one after the other, each of size primme.nLocal. y contains the output blockSize vectors in the same fashion. BlockSize is by reference to facilitate a possible Fortran interface. x, y are void* arrays. Thus, the user must cast them before use:

Block preconditioner-multivector application. y = applyPreconditioner(x) BlockSize is by reference to facilitate a possible Fortran interface. x, y are void* arrays, that must be cast accordingly before use.

If this preconditioner is to be used, set also correctionParams.precondition to 1

Block matrix-Multivector multiplication. y = B*x. B is the mass matrix in generalized eigenvalue problems. BlockSize is by reference to facilitate a possible Fortran interface. x, y are void* arrays, that must be cast accordingly before use.

  Only needed if pnumProcs == 1 to set the nLocal by default to n.
  The user might possibly need this info in matvec or precond.

ProcessID. Only procID == 0 prints information.

Number of local rows on this processor.  nLocal = n if sequential.

A pointer to whatever parallel environment structures needed.
For example, with MPI, it could be set to point to the MPI communicator.
PRIMME does not use this. It is available for possible use in
matrixMatvec, applyPreconditioner, massMatrixMatvec and globalSumDouble.

Global sum function for parallel programs. No need to set for sequential.
recvBuf(i) = sum_over_all_processors( sendBuf(i) ), for all i=1,count
When MPI is used this is simply a wrapper to MPI_Allreduce()
primme is needed only for primme->commInfo (eg, MPI communicator)
Count is by reference to facilitate a possible Fortran interface.
The data type is always double (even for zprimme).

The level of message reporting from the code.

output key:

Struct with the following members. If an error occurs the function
primme_PrintStackTrace(primme) prints the calling stack from top
to the function that caused the error. Nothing to set.

int callingFunction;
int failedFunction;
int errorCode;
int lineNumber;
char fileName[PRIMME_MAX_NAME_LENGTH];
struct stackTraceNode *nextNode;

Struct with the following members to report statistics back.
Nothing has to be set. Can be checked also during execution,
e.g., in the user provided Matvec or preconditioning function.

int numOuterIterations;
int numRestarts;
int numMatvecs;
double elapsedTime;

structure with the following members:

int precondition; [default = 0]

Set to 1 if preconditioning is to be performed. Make sure the applyPreconditioner is not NULL then!

int robustShifts;

Set to 1 to use robustShifting. It helps avoid stagnation and missconvergence some times.

int maxInnerIterations;

Number of inner QMR iterations:

double relTolBase;

This is a legacy from classical JDQR. Inner QMR is iterated until linear system residual < relTolBase^(-OuterIterations). We recommend STRONGLY against its use.

primme_convergencetest convTest;

How to stop the inner QMR method.

The last scheme simply stops inner iterations when 1 order of magnitude has been achieved for the eigenresidual (NOT the linear system residual)

struct JD_projectors projectors;

Set the following to 1:

see setup_JD_projectors() in inner_solve.c for more information.

The following two tests could be combined in all possible ways.
Eg: maxInnerIterations convTest

Choice of GD projectors:

Choice of JD projectors:

Fortran Library Interface

The following functions are available for users to call from FORTRAN.
Notice the appendix _f77.

call dprimme_f77(double *evals, double *evecs, double *rnorms, primme_params **primme, int *ierr);

call zprimme_f77(double *evals, Complex_Z *evecs, double *rnorms, primme_params **primme, int *ierr);

call primme_initialize_f77(primme_params **primme);

call primme_free_f77(primme_params **primme);

call primme_display_params_f77(primme_params **primme);

call primme_printstacktrace_f77(primme_params **primme);

call primme_set_method_f77(primme_params **primme, int *method,int *ierr);

call primme_set_member_f77(primme_params **primme, int *label, void *ptr);

call primme_get_prec_shift_f77(primme_params *primme, int *i, double *shift);

call primme_get_member_f77(primme_params *primme, int *label, void *ptr);

call primmetop_get_member_f77(primme_params **primme, int *label, void *ptr);

call primmetop_get_prec_shift_f77(primme_params **primme, int *i, double *shift);

Running From Fortran

To call d/zprimme from Fortran, look at (D)ZTEST/driver_f77seq.c. Basic steps:

* Include "primme_f77.h"
* initialize a primme structure for default settings:

integer primme   (or integer*8 primme if running on a 64 bit operating system)

call primme_initialize_f77(primme)

Then, set the various structure members and possibly the method to be used. Individual primme members can be set by calling:

call primme_set_member_f77(primme, MEMBER_LABEL, variable)

where MEMBER_LABEL is the name of the primme member prepended with PRIMMEF77_ and replacing all dots (.) with underscores (_). See primme_f77.h Eg.:

call primme_set_member_f77(primme, PRIMMEF77_correctionParams_precondition, 1)

sets the primme->correctionParams.precondition = 1

Matrix-vector and preconditioning fortran function must be declared external and passed in the same way to primme:

external MV
...
call primme_set_member_f77(primme, PRIMMEF77_matrixMatvec, MV)

call primme_set_method_f77(primme, METHOD, RealMem)

where METHOD has the name of the preset method as above, prepended by PRIMMEF77_ All these are defined in primme_f77.

call primme_set_method_f77(primme, PRIMMEF77_JDQMR_ETol, ierr)

Then call dprimme:

call dprimme_f77(evals, evecs, rnorms, primme, ierr)

How to obtain the value of a member of the PRIMME structure depends on whether it is called from an F77 subroutine called directly by the driver, or by an F77 function invoked by PRIMME (such as matrixMatvec, applyPreconditioner, massMatrixMatvec or globalSumDouble)

From the driver: primme is really: primme_params **primme

call primmetop_get_member_f77(primme, MEMBER_LABEL, ResultVariable)

From matrixMatvec, applyPreconditioner, massMatrixMatvec and globalSumDouble: primme is really: primme_params *primme, so a different function must be used:

call primme_get_member_f77(primme, MEMBER_LABEL, ResultVariable)

In preconditioning, a PRIMME provided shift may be used. Assuming a block of blockSize, from which the i-th shift is needed, i = 1,2,3...,blockSize the user can call from inside the f77 applyPreconditioner() the following function:

call primme_get_prec_shift_f77(primme, i, shift)

List of error codes returned by dprimme() / zprimme()

These can be found also in  primme_d.c or primme_z.c