C Library Interface

The PRIMME interface is composed of the following functions. To solve real symmetric and Hermitian standard eigenproblems call respectively:

int sprimme (float *evals, float *evecs, float *resNorms,
                        primme_params *primme)
int cprimme (float *evals, PRIMME_COMPLEX_FLOAT *evecs,
                 float *resNorms, primme_params *primme)
int dprimme (double *evals, double *evecs, double *resNorms,
                        primme_params *primme)
int zprimme (double *evals, PRIMME_COMPLEX_DOUBLE *evecs,
                 double *resNorms, primme_params *primme)

Other useful functions:

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_free (primme_params *primme)

PRIMME stores its data on the structure primme_params. See Parameters Guide for an introduction about its fields.

Running

To use PRIMME, follow these basic steps.

  1. Include:

    #include "primme.h"   /* header file is required to run primme */
    
  2. Initialize a PRIMME parameters structure for default settings:

    primme_params primme;
    primme_initialize (&primme);
    
  3. Set problem parameters (see also Parameters Guide), and, optionally, set one of the preset methods:

    primme.matrixMatvec = LaplacianMatrixMatvec; /* MV product */
    primme.n = 100;                   /* set problem dimension */
    primme.numEvals = 10;       /* Number of wanted eigenpairs */
    ret = primme_set_method (method, &primme);
    ...
    
  4. Then to solve real symmetric standard eigenproblems call:

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

    The previous is the double precision call. There is available calls for complex double, single and complex single; check it out zprimme(), sprimme() and cprimme().

    The call arguments are:

    • evals, array to return the found eigenvalues;
    • evecs, array to return the found eigenvectors;
    • resNorms, array to return the residual norms of the found eigenpairs; and
    • ret, returned error code.
  5. To free the work arrays in PRIMME:

    primme_free (&primme);
    

Parameters Guide

PRIMME stores the data on the structure primme_params, which has the next fields:

Basic
PRIMME_INT n, matrix dimension.
void (* matrixMatvec )(...), matrix-vector product.
int numEvals, how many eigenpairs to find.
primme_target target, which eigenvalues to find.
int numTargetShifts, for targeting interior eigenpairs.
double * targetShifts
double eps, tolerance of the residual norm of converged eigenpairs.

For parallel programs
int numProcs, number of processes
int procID, rank of this process
PRIMME_INT nLocal, number of rows stored in this process
void (* globalSumReal )(...), sum reduction among processes

Accelerate the convergence
void (* applyPreconditioner )(...), preconditioner-vector product.
int initSize, initial vectors as approximate solutions.

User data
void * commInfo
void * matrix
void * convTest
void * monitor

Advanced options
PRIMME_INT ldevecs, leading dimension of the evecs.
int numOrthoConst, orthogonal constrains to the eigenvectors.
PRIMME_INT maxMatvecs
PRIMME_INT iseed [4]
int * intWork
void * realWork
double aNorm
FILE * outputFile
primme_init initBasisMode
struct projection_params projectionParams
struct restarting_params restartingParams
struct correction_params correctionParams
struct primme_stats stats
void (* convTestFun )(...), custom convergence criterion.
PRIMME_INT ldOPs, leading dimension to use in matrixMatvec.
void (* monitorFun )(...), custom convergence history.

PRIMME requires the user to set at least the dimension of the matrix (n) and the matrix-vector product (matrixMatvec), as they define the problem to be solved. For parallel programs, nLocal, procID and globalSumReal are also required.

In addition, most users would want to specify how many eigenpairs to find, and provide a preconditioner (if available).

It is useful to have set all these before calling primme_set_method(). Also, if users have a preference on maxBasisSize, maxBlockSize, etc, they should also provide them into primme_params prior to the primme_set_method() call. This helps primme_set_method() make the right choice on other parameters. It is sometimes useful to check the actual parameters that PRIMME is going to use (before calling it) or used (on return) by printing them with primme_display_params().

Interface Description

The next enumerations and functions are declared in primme.h.

sprimme

int sprimme(float *evals, float *evecs, float *resNorms, primme_params *primme)

Solve a real symmetric standard eigenproblem.

Parameters:
  • evals – array at least of size numEvals to store the computed eigenvalues; all processes in a parallel run return this local array with the same values.
  • resNorms – array at least of size numEvals to store the residual norms of the computed eigenpairs; all processes in parallel run return this local array with the same values.
  • evecs – array at least of size nLocal times numEvals to store columnwise the (local part of the) computed eigenvectors.
  • primme – parameters structure.
Returns:

error indicator; see Error Codes.

dprimme

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

Solve a real symmetric standard eigenproblem.

Parameters:
  • evals – array at least of size numEvals to store the computed eigenvalues; all processes in a parallel run return this local array with the same values.
  • resNorms – array at least of size numEvals to store the residual norms of the computed eigenpairs; all processes in parallel run return this local array with the same values.
  • evecs – array at least of size nLocal times numEvals to store columnwise the (local part of the) computed eigenvectors.
  • primme – parameters structure.
Returns:

error indicator; see Error Codes.

cprimme

int cprimme(float *evals, PRIMME_COMPLEX_FLOAT *evecs, float *resNorms, primme_params *primme)

Solve a Hermitian standard eigenproblem; see function sprimme().

zprimme

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

Solve a Hermitian standard eigenproblem; see function dprimme().

primme_initialize

void primme_initialize(primme_params *primme)

Set PRIMME parameters structure to the default values.

Parameters:
  • primme – parameters structure.

primme_set_method

int primme_set_method(primme_preset_method method, primme_params *primme)

Set PRIMME parameters to one of the preset configurations.

Parameters:

See also Preset Methods.

primme_display_params

void primme_display_params(primme_params primme)

Display all printable settings of primme into the file descriptor outputFile.

Parameters:
  • primme – parameters structure.

primme_free

void primme_free(primme_params *primme)

Free memory allocated by PRIMME.

Parameters:
  • primme – parameters structure.