Skip to content

Latest commit

 

History

History
410 lines (293 loc) · 13.2 KB

primmec.rst.txt

File metadata and controls

410 lines (293 loc) · 13.2 KB
Raw

c

C Library Interface

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

not text

int :csprimme <sprimme> (float *evals, float *evecs, float *resNorms,

primme_params *primme)

int :ccprimme <cprimme> (float *evals, PRIMME_COMPLEX_FLOAT *evecs,

float *resNorms, primme_params *primme)

int :cdprimme <dprimme> (double *evals, double *evecs, double *resNorms,

primme_params *primme)

int :czprimme <zprimme> (double *evals, PRIMME_COMPLEX_DOUBLE *evecs,

double *resNorms, primme_params *primme)

text

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:

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.

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:

    not text

    :cprimme_params primme; :cprimme_initialize <primme_initialize> (&primme);

    text

    primme_params primme;

primme_initialize(&primme);

  3. 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 = :cprimme_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);
...

  4. Then to solve real symmetric standard eigenproblems call:

    not text

    ret = :cdprimme <dprimme> (evals, evecs, resNorms, &primme);

    text

    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 :czprimme, :csprimme and :ccprimme.

    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:

    not text

    :cprimme_free <primme_Free> (&primme);

    text

    primme_free(&primme);

Parameters Guide

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

not text

Basic
PRIMME_INT , matrix dimension.
void (* )(...), matrix-vector product.
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 processes
int , rank of this process
PRIMME_INT , number of rows stored in this process
void (* )(...), sum reduction among processes

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

User data
void *
void *
void *
void * convTest
void * monitor

Advanced options
PRIMME_INT , leading dimension of the evecs.
int , orthogonal constrains to the eigenvectors.
int
int
PRIMME_INT
PRIMME_INT
int
size_t
PRIMME_INT [4]
int *
void *
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.

text

/* 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 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)(...);     // precond-vector product
int initSize;       // initial vectors as approximate solutions
int maxBasisSize;
int minRestartSize;
int maxBlockSize;

/* User data */
void *commInfo;
void *matrix;
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;
int intWorkSize;
size_t realWorkSize;
PRIMME_INT iseed[4];
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;
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 () 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.

Interface Description

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

sprimme

dprimme

cprimme

zprimme

primme_initialize

primme_set_method

primme_display_params

primme_free