c
The PRIMME interface is composed of the following functions. To solve real symmetric and complex Hermitian problems, standard Ax = λx and generalized Ax = λBx, call:
not text
- int :c
dprimme <dprimme>
(double *evals, double *evecs, double *resNorms, primme_params *primme)
- int :c
zprimme <zprimme>
(double *evals, PRIMME_COMPLEX_DOUBLE *evecs, double *resNorms, primme_params *primme)
text
int dprimme(double *evals, double *evecs, double *resNorms,
primme_params *primme);
int zprimme(double *evals, PRIMME_COMPLEX_DOUBLE *evecs, double *resNorms,
primme_params *primme);
There are more versions for matrix problems working in other precisions:
Precision | Real | Complex |
---|---|---|
half | :chprimme :chsprimme |
:ckprimme :cksprimme |
single | :csprimme |
:ccprimme |
double | :cdprimme |
:czprimme |
To solve standard eigenproblems with normal but not necessarily Hermitian matrices call:
not text
- int :c
zprimme_normal <zprimme_normal>
(PRIMME_COMPLEX_DOUBLE *evals, PRIMME_COMPLEX_DOUBLE *evecs, double *resNorms, primme_params *primme)
text
int zprimme_normal(PRIMME_COMPLEX_DOUBLE *evals, PRIMME_COMPLEX_DOUBLE *evecs,
double *resNorms, primme_params *primme);
There are more versions for matrix problems working in other precisions:
Precision | Complex |
---|---|
half | :ckprimme_normal :ckcprimme_normal |
single | :ccprimme_normal |
double | :czprimme_normal |
Other useful functions:
not text
void :cprimme_initialize <primme_initialize>
(primme_params *primme) int :cprimme_set_method <primme_set_method>
(primme_preset_method method, primme_params *params) void :cprimme_display_params <primme_display_params>
(primme_params primme) void :cprimme_free <primme_Free>
(primme_params *primme)
text
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 :cprimme_params
. See guide-params
for an introduction about its fields.
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:
not text
:c
primme_params
primme; :cprimme_initialize <primme_initialize>
(&primme);text
primme_params primme; primme_initialize(&primme);
Set problem parameters (see also
guide-params
), and, optionally, set one of the :cpreset methods <primme_preset_method>
:not text
primme. = LaplacianMatrixMatvec; /* MV product */ primme. = 100; /* set problem dimension */ primme. = 10; /* Number of wanted eigenpairs */ ret = :c
primme_set_method <primme_set_method>
(method, &primme); ...text
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 call the solver:
not text
ret = :c
dprimme <dprimme>
(evals, evecs, resNorms, &primme);text
ret = dprimme(evals, evecs, resNorms, &primme);
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:
not text
:c
primme_free <primme_Free>
(&primme);text
primme_free(&primme);
See usage examples at the directory examples.
PRIMME stores the data on the structure :cprimme_params
, which has the next fields:
not text
PRIMME_INT
, matrix dimension.void (*
)(...)
, matrix-vector product.void (*
)(...)
, mass matrix-vector product (null for standard problems).int
, how many eigenpairs to find.primme_target
, which eigenvalues to find.int
, for targeting interior eigenpairs.double *
double
, tolerance of the residual norm of converged eigenpairs.For parallel programs
int
, number of processesint
, rank of this processPRIMME_INT
, number of rows stored in this processvoid (*
)(...)
, sum reduction among processesvoid (*
)(...)
, broadcast array among processesAccelerate the convergence
void (*
)(...)
, preconditioner-vector product.int
, initial vectors as approximate solutions.int
int
int
User data
void *
void *
void *
void *
void *
void *
Advanced options
PRIMME_INT
, leading dimension of the evecs.int
, orthogonal constrains to the eigenvectors.int
int
PRIMME_INT
PRIMME_INT
PRIMME_INT
[4]
double
double
double
int
FILE *
double *
primme_init
struct projection_params
:cprojectionParams <primme_params.projectionParams.projection>
struct restarting_params
:crestartingParams <primme_params.restartingParams.scheme>
struct correction_params
:ccorrectionParams <primme_params.correctionParams.precondition>
struct primme_stats
:cstats <primme_params.stats.numOuterIterations>
void (*
)(...)
, custom convergence criterion.PRIMME_INT
, leading dimension to use in .void (*
)(...)
, custom convergence history.primme_op_datatype
primme_op_datatype
primme_op_datatype
primme_op_datatype
primme_op_datatype
primme_op_datatype
primme_orth
text
/* Basic */
PRIMME_INT n; // matrix dimension
void (*matrixMatvec)(...); // matrix-vector product
void (*massMatrixMatvec)(...); // mass 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 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
void (*broadcastReal)(...); // broadcast array among processes
/* Accelerate the convergence */
void (*applyPreconditioner)(...); // precond-vector product
int initSize; // initial vectors as approximate solutions
int maxBasisSize;
int minRestartSize;
int maxBlockSize;
/* User data */
void *commInfo;
void *matrix;
void *massMatrix;
void *preconditioner;
void *convtest;
void *monitor;
/* Advanced options */
PRIMME_INT ldevecs; // leading dimension of the evecs
int numOrthoConst; // orthogonal constrains to the eigenvectors
int dynamicMethodSwitch;
int locking;
PRIMME_INT maxMatvecs;
PRIMME_INT maxOuterIterations;
PRIMME_INT iseed[4];
double aNorm;
double BNorm;
double invBNorm;
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;
void (*convTestFun)(...); // custom convergence criterion
PRIMME_INT ldOPS; // leading dimension to use in matrixMatvec
void (*monitorFun)(...); // custom convergence history
primme_op_datatype matrixMatvec_type;
primme_op_datatype massMatrixMatvec_type;
primme_op_datatype applyPreconditioner_type;
primme_op_datatype globalSumReal_type;
primme_op_datatype broadcastReal_type;
primme_op_datatype internalPrecision;
primme_orth orth;
PRIMME requires the user to set at least the dimension of the matrix () and the matrix-vector product (), as they define the problem to be solved. For parallel programs, , and 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 :cprimme_set_method
. Also, if users have a preference on , , etc, they should also provide them into :cprimme_params
prior to the :cprimme_set_method
call. This helps :cprimme_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 :cprimme_display_params
.
The next enumerations and functions are declared in primme.h
.