C Library Interface¶
The PRIMME interface is composed of the following functions. To solve real symmetric and Hermitian standard eigenproblems call respectively:
intsprimme
(float *evals, float *evecs, float *resNorms, primme_params *primme) intcprimme
(float *evals, PRIMME_COMPLEX_FLOAT *evecs, float *resNorms, primme_params *primme) intdprimme
(double *evals, double *evecs, double *resNorms, primme_params *primme) intzprimme
(double *evals, PRIMME_COMPLEX_DOUBLE *evecs, double *resNorms, primme_params *primme)
Other useful functions:
voidprimme_initialize
(primme_params *primme) intprimme_set_method
(primme_preset_method method, primme_params *params) voidprimme_display_params
(primme_params primme) voidprimme_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.
Include:
#include "primme.h" /* header file is required to run primme */
Initialize a PRIMME parameters structure for default settings:
primme_params
primme;primme_initialize
(&primme);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); ...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()
andcprimme()
.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.
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:
PRIMME_INT
n
, matrix dimension.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.int
numProcs
, number of processesint
procID
, rank of this processPRIMME_INT
nLocal
, number of rows stored in this processint
initSize
, initial vectors as approximate solutions.int
maxBasisSize
int
minRestartSize
int
maxBlockSize
void *
commInfo
void *
matrix
void *
preconditioner
void *
convtest
void *
monitor
PRIMME_INT
ldevecs
, leading dimension of the evecs.int
numOrthoConst
, orthogonal constrains to the eigenvectors.int
locking
PRIMME_INT
maxMatvecs
PRIMME_INT
maxOuterIterations
int
intWorkSize
size_t
realWorkSize
int *
intWork
void *
realWork
double
aNorm
int
printLevel
FILE *
outputFile
double *
ShiftsForPreconditioner
primme_init
initBasisMode
struct projection_params
projectionParams
struct restarting_params
restartingParams
struct correction_params
correctionParams
struct primme_stats
stats
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
timesnumEvals
to store columnwise the (local part of the) computed eigenvectors. - primme -- parameters structure.
Returns: error indicator; see Error Codes.
- evals -- array at least of size
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
timesnumEvals
to store columnwise the (local part of the) computed eigenvectors. - primme -- parameters structure.
Returns: error indicator; see Error Codes.
- evals -- array at least of size
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: - method --
preset configuration; one of
- primme -- parameters structure.
See also Preset Methods.
- method --
primme_display_params¶
-
void
primme_display_params
(primme_params primme)¶ Display all printable settings of
primme
into the file descriptoroutputFile
.Parameters: - primme -- parameters structure.
primme_free¶
-
void
primme_free
(primme_params *primme)¶ Free memory allocated by PRIMME.
Parameters: - primme -- parameters structure.