Parameters Description

Types

The following data types are macros used in PRIMME as followed.

PRIMME_INT

Integer type used in matrix dimensions (such as n and nLocal) and counters (such as numMatvecs).

The integer size is controlled by the compilation flag PRIMME_INT_SIZE, see Making and Linking.

PRIMME_COMPLEX_FLOAT

Macro that is complex float in C and std::complex<float> in C++.

PRIMME_COMPLEX_DOUBLE

Macro that is complex double in C and std::complex<double> in C++.

primme_params

primme_params

Structure to set the problem matrices and eigensolver options.

PRIMME_INT n

Dimension of the matrix.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
void (*matrixMatvec)(void *x, PRIMME_INT *ldx, void *y, PRIMME_INT *ldy, int *blockSize, primme_params *primme, int *ierr)

Block matrix-multivector multiplication, \(y = A x\) in solving \(A x = \lambda x\) or \(A x = \lambda B x\).

Parameters:
  • x – matrix of size nLocal x blockSize in column-major order with leading dimension ldx.
  • ldx – the leading dimension of the array x.
  • y – matrix of size nLocal x blockSize in column-major order with leading dimension ldy.
  • ldy – the leading dimension of the array y.
  • blockSize – number of columns in x and y.
  • primme – parameters structure.
  • ierr – output error code; if it is set to non-zero, the current call to PRIMME will stop.

The actual type of x and y depends on which function is being calling. For dprimme(), it is double, for zprimme() it is PRIMME_COMPLEX_DOUBLE, for sprimme() it is float and for cprimme() it is PRIMME_COMPLEX_FLOAT.

Input/output:

primme_initialize() sets this field to NULL;
this field is read by dprimme().

Note

If you have performance issues with leading dimension different from nLocal, set ldOPs to nLocal.

void (*applyPreconditioner)(void *x, PRIMME_INT *ldx, void *y, PRIMME_INT *ldy, int *blockSize, primme_params *primme, int *ierr)

Block preconditioner-multivector application, \(y = M^{-1}x\) where \(M\) is usually an approximation of \(A - \sigma I\) or \(A - \sigma B\) for finding eigenvalues close to \(\sigma\). The function follows the convention of matrixMatvec.

Input/output:

primme_initialize() sets this field to NULL;
this field is read by dprimme().
void (*massMatrixMatvec)(void *x, PRIMME_INT *ldx, void *y, PRIMME_INT *ldy, int *blockSize, primme_params *primme, int *ierr)

Block matrix-multivector multiplication, \(y = B x\) in solving \(A x = \lambda B x\). The function follows the convention of matrixMatvec.

Input/output:

primme_initialize() sets this field to NULL;
this field is read by dprimme().

Warning

Generalized eigenproblems not implemented in current version. This member is included for future compatibility.

int numProcs

Number of processes calling dprimme() or zprimme() in parallel.

Input/output:

primme_initialize() sets this field to 1;
this field is read by dprimme().
int procID

The identity of the local process within a parallel execution calling dprimme() or zprimme(). Only the process with id 0 prints information.

Input/output:

primme_initialize() sets this field to 0;
dprimme() sets this field to 0 if numProcs is 1;
this field is read by dprimme().
int nLocal

Number of local rows on this process.

Input/output:

primme_initialize() sets this field to 0;
dprimme() sets this field to n if numProcs is 1;
this field is read by dprimme().
void *commInfo

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

Input/output:

primme_initialize() sets this field to NULL;
void (*globalSumReal)(void *sendBuf, void *recvBuf, int *count, primme_params *primme, int *ierr)

Global sum reduction function. No need to set for sequential programs.

Parameters:
  • sendBuf – array of size count with the local input values.
  • recvBuf – array of size count with the global output values so that the i-th element of recvBuf is the sum over all processes of the i-th element of sendBuf.
  • count – array size of sendBuf and recvBuf.
  • primme – parameters structure.
  • ierr – output error code; if it is set to non-zero, the current call to PRIMME will stop.

The actual type of sendBuf and recvBuf depends on which function is being calling. For dprimme() and zprimme() it is double, and for sprimme() and cprimme() it is float. Note that count is the number of values of the actual type.

Input/output:

primme_initialize() sets this field to an internal function;
dprimme() sets this field to an internal function if numProcs is 1 and globalSumReal is NULL;
this field is read by dprimme().

When MPI is used, this can be a simply wrapper to MPI_Allreduce() as shown below:

void par_GlobalSumForDouble(void *sendBuf, void *recvBuf, int *count,
                         primme_params *primme, int *ierr) {
   MPI_Comm communicator = *(MPI_Comm *) primme->commInfo;
   if(MPI_Allreduce(sendBuf, recvBuf, *count, MPI_DOUBLE, MPI_SUM,
                 communicator) == MPI_SUCCESS) {
      *ierr = 0;
   } else {
      *ierr = 1;
   }
}

}

When calling sprimme() and cprimme() replace MPI_DOUBLE by `MPI_FLOAT.

int numEvals

Number of eigenvalues wanted.

Input/output:

primme_initialize() sets this field to 1;
this field is read by primme_set_method() (see Preset Methods) and dprimme().
primme_target target

Which eigenpairs to find:

primme_smallest
Smallest algebraic eigenvalues; targetShifts is ignored.
primme_largest
Largest algebraic eigenvalues; targetShifts is ignored.
primme_closest_geq
Closest to, but greater or equal than the shifts in targetShifts.
primme_closest_leq
Closest to, but less or equal than the shifts in targetShifts.
primme_closest_abs
Closest in absolute value to the shifts in targetShifts.
primme_largest_abs
Furthest in absolute value to the shifts in targetShifts.

Input/output:

this field is read by dprimme().
int numTargetShifts

Size of the array targetShifts. Used only when target is primme_closest_geq, primme_closest_leq, primme_closest_abs or primme_largest_abs. The default values is 0.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
double *targetShifts

Array of shifts, at least of size numTargetShifts. Used only when target is primme_closest_geq, primme_closest_leq, primme_closest_abs or primme_largest_abs.

Eigenvalues are computed in order so that the i-th eigenvalue is the closest (or closest but left or closest but right, see target) to the i-th shift. If numTargetShifts < numEvals, the last shift given is used for all the remaining i’s.

Input/output:

primme_initialize() sets this field to NULL;
this field is read by dprimme().

Note

Considerations for interior problems:

int printLevel

The level of message reporting from the code. All output is written in outputFile.

One of:

  • 0: silent.

  • 1: print some error messages when these occur.

  • 2: as in 1, and info about targeted eigenpairs when they are marked as converged:

    #Converged $1 eval[ $2 ]= $3 norm $4 Mvecs $5 Time $7
    

    or locked:

    #Lock epair[ $1 ]= $3 norm $4 Mvecs $5 Time $7
    
  • 3: in as 2, and info about targeted eigenpairs every outer iteration:

    OUT $6 conv $1 blk $8 MV $5 Sec $7 EV $3 |r| $4
    

    Also, if it is used the dynamic method, show JDQMR/GDk performance ratio and the current method in use.

  • 4: in as 3, and info about targeted eigenpairs every inner iteration:

    INN MV $5 Sec $7 Eval $3 Lin|r| $9 EV|r| $4
    
  • 5: in as 4, and verbose info about certain choices of the algorithm.

Output key:

$1: Number of converged pairs up to now.
$2: The index of the pair currently converged.
$3: The eigenvalue.
$4: Its residual norm.
$5: The current number of matrix-vector products.
$6: The current number of outer iterations.
$7: The current elapsed time.
$8: Index within the block of the targeted pair .
$9: QMR norm of the linear system residual.

In parallel programs, output is produced in call with procID 0 when printLevel is from 0 to 4. If printLevel is 5 output can be produced in any of the parallel calls.

Input/output:

primme_initialize() sets this field to 1;
this field is read by dprimme().

Note

Convergence history for plotting may be produced simply by:

grep OUT outpufile | awk '{print $8" "$14}' > out
grep INN outpufile | awk '{print $3" "$11}' > inn

Then in gnuplot:

plot 'out' w lp, 'inn' w lp
double aNorm

An estimate of the norm of \(A\), which is used in the default convergence criterion (see eps).

If aNorm is less than or equal to 0, the code uses the largest absolute Ritz value seen. On return, aNorm is then replaced with that value.

Input/output:

primme_initialize() sets this field to 0.0;
this field is read and written by dprimme().
double eps

If convTestFun is NULL, an eigenpairs is marked as converged when the 2-norm of the residual vector is less than eps * aNorm. The residual vector is \(A x - \lambda x\) or \(A x - \lambda B x\).

The default value is machine precision times \(10^4\).

Input/output:

primme_initialize() sets this field to 0.0;
this field is read and written by dprimme().
FILE *outputFile

Opened file to write down the output.

Input/output:

primme_initialize() sets this field to the standard output;
this field is read by dprimme() and primme_display_params().
int dynamicMethodSwitch

If this value is 1, it alternates dynamically between PRIMME_DEFAULT_MIN_TIME and PRIMME_DEFAULT_MIN_MATVECS, trying to identify the fastest method.

On exit, it holds a recommended method for future runs on this problem:

-1: use PRIMME_DEFAULT_MIN_MATVECS next time.
-2: use PRIMME_DEFAULT_MIN_TIME next time.
-3: close call, use PRIMME_DYNAMIC next time again.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().

Note

Even for expert users we do not recommend setting dynamicMethodSwitch directly, but through primme_set_method().

Note

The code obtains timings by the gettimeofday Unix utility. If a cheaper, more accurate timer is available, modify the PRIMMESRC/COMMONSRC/wtime.c

int locking

If set to 1, hard locking will be used (locking converged eigenvectors out of the search basis). If set to 0, the code will try to use soft locking (à la ARPACK), when large enough minRestartSize is available.

Input/output:

primme_initialize() sets this field to -1;
this field is read by dprimme().
int initSize

On input, the number of initial vector guesses provided in evecs argument in dprimme() or zprimme().

On output, initSize holds the number of converged eigenpairs. Without locking all numEvals approximations are in evecs but only the initSize ones are converged.

During execution, it holds the current number of converged eigenpairs. In addition, if locking is used, these are accessible in evals and evecs.

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by dprimme().
PRIMME_INT ldevecs

The leading dimension of evecs. The default is nLocal.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
int numOrthoConst

Number of vectors to be used as external orthogonalization constraints. These vectors are provided in the first numOrthoConst positions of the evecs argument in dprimme() or zprimme() and must be orthonormal.

PRIMME finds new eigenvectors orthogonal to these constraints (equivalent to solving the problem with \((I-YY^*)A(I-YY^*)\) and \((I-YY^*)B(I-YY^*)\) matrices where \(Y\) are the given constraint vectors). This is a handy feature if some eigenvectors are already known, or for finding more eigenvalues after a call to dprimme() or zprimme(), possibly with different parameters (see an example in TEST/ex_zseq.c).

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
int maxBasisSize

The maximum basis size allowed in the main iteration. This has memory implications.

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by primme_set_method() (see Preset Methods);
this field is read by dprimme().
int minRestartSize

Maximum Ritz vectors kept after restarting the basis.

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by primme_set_method() (see Preset Methods);
this field is read by dprimme().
int maxBlockSize

The maximum block size the code will try to use.

The user should set this based on the architecture specifics of the target computer, as well as any a priori knowledge of multiplicities. The code does not require that maxBlockSize > 1 to find multiple eigenvalues. For some methods, keeping to 1 yields the best overall performance.

Input/output:

primme_initialize() sets this field to 1;
this field is read and written by primme_set_method() (see Preset Methods);
this field is read by dprimme().

Note

Inner iterations of QMR are not performed in a block fashion. Every correction equation from a block is solved independently.

PRIMME_INT maxMatvecs

Maximum number of matrix vector multiplications (approximately equal to the number of preconditioning operations) that the code is allowed to perform before it exits.

Input/output:

primme_initialize() sets this field to INT_MAX;
this field is read by dprimme().
PRIMME_INT maxOuterIterations

Maximum number of outer iterations that the code is allowed to perform before it exits.

Input/output:

primme_initialize() sets this field to INT_MAX;
this field is read by dprimme().
int intWorkSize

If dprimme() or zprimme() is called with all arguments as NULL except for primme_params then PRIMME returns immediately with intWorkSize containing the size in bytes of the integer workspace that will be required by the parameters set in PRIMME.

Otherwise if intWorkSize is not 0, it should be the size of the integer work array in bytes that the user provides in intWork. If intWorkSize is 0, the code will allocate the required space, which can be freed later by calling primme_free().

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by dprimme().
size_t realWorkSize

If dprimme() or zprimme() is called with all arguments as NULL except for primme_params then PRIMME returns immediately with realWorkSize containing the size in bytes of the real workspace that will be required by the parameters set in PRIMME.

Otherwise if realWorkSize is not 0, it should be the size of the real work array in bytes that the user provides in realWork. If realWorkSize is 0, the code will allocate the required space, which can be freed later by calling primme_free().

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by dprimme().
int *intWork

Integer work array.

If NULL, the code will allocate its own workspace. If the provided space is not enough, the code will return the error code -37.

On exit, the first element shows if a locking problem has occurred. Using locking for large numEvals may, in some rare cases, cause some pairs to be practically converged, in the sense that their components are in the basis of evecs. If this is the case, a Rayleigh Ritz on returned evecs would provide the accurate eigenvectors (see [r4]).

Input/output:

primme_initialize() sets this field to NULL;
this field is read and written by dprimme().
void *realWork

Real work array.

If NULL, the code will allocate its own workspace. If the provided space is not enough, the code will return the error code -36.

Input/output:

primme_initialize() sets this field to NULL;
this field is read and written by dprimme().
PRIMME_INT iseed

The PRIMME_INT iseed[4] is an array with the seeds needed by the LAPACK dlarnv and zlarnv.

The default value is an array with values -1, -1, -1 and -1. In that case, iseed is set based on the value of procID to avoid every parallel process generating the same sequence of pseudorandom numbers.

Input/output:

primme_initialize() sets this field to [-1, -1, -1, -1];
this field is read and written by dprimme().
void *matrix

This field may be used to pass any required information in the matrix-vector product matrixMatvec.

Input/output:

primme_initialize() sets this field to NULL;
void *preconditioner

This field may be used to pass any required information in the preconditioner function applyPreconditioner.

Input/output:

primme_initialize() sets this field to NULL;
double *ShiftsForPreconditioner

Array of size blockSize provided during execution of dprimme() and zprimme() holding the shifts to be used (if needed) in the preconditioning operation.

For example if the block size is 3, there will be an array of three shifts in ShiftsForPreconditioner. Then the user can invert a shifted preconditioner for each of the block vectors \((M-ShiftsForPreconditioner_i)^{-1} x_i\). Classical Davidson (diagonal) preconditioning is an example of this.

this field is read and written by dprimme().
primme_init initBasisMode

Select how the search subspace basis is initialized up to minRestartSize vectors if not enough initial vectors are provided (see initSize):

  • primme_init_krylov, with a block Krylov subspace generated by the matrix problem and the last initial vectors if given or a random vector otherwise; the size of the block is maxBlockSize.
  • primme_init_random, with random vectors.
  • primme_init_user, the initial basis will have only initial vectors if given, or a single random vector.

Input/output:

this field is read by dprimme().
primme_projection projectionParams.projection

Select the extraction technique, i.e., how the approximate eigenvectors \(x_i\) and eigenvalues \(\lambda_i\) are computed from the search subspace \(\mathcal V\):

  • primme_proj_RR, Rayleigh-Ritz, \(Ax_i - Bx_i\lambda_i \perp \mathcal V\).
  • primme_proj_harmonic, Harmonic Rayleigh-Ritz, \(Ax_i - Bx_i\lambda_i \perp (A-\tau B)\mathcal V\), where \(\tau\) is the current target shift (see targetShifts).
  • primme_proj_refined, refined extraction, compute \(x_i\) with \(||x_i||=1\) that minimizes \(||(A-\tau B)x_i||\); the eigenvalues are computed as the Rayleigh quotients, \(\lambda_i=\frac{x_i^*Ax_i}{x_i^*Bx_i}\).

Input/output:

primme_restartscheme restartingParams.scheme

Select a restarting strategy:

  • primme_thick, Thick restarting. This is the most efficient and robust in the general case.
  • primme_dtr, Dynamic thick restarting. Helpful without preconditioning but it is expensive to implement.

Input/output:

primme_initialize() sets this field to primme_thick;
this field is read by dprimme().
int restartingParams.maxPrevRetain

Number of approximations from previous iteration to be retained after restart (this is the locally optimal restarting, see [r2]). The restart size is minRestartSize plus maxPrevRetain.

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by primme_set_method() (see Preset Methods);
this field is read by dprimme().
int correctionParams.precondition

Set to 1 to use preconditioning. Make sure applyPreconditioner is not NULL then!

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by primme_set_method() (see Preset Methods);
this field is read by dprimme().
int correctionParams.robustShifts

Set to 1 to use robust shifting. It tries to avoid stagnation and misconvergence by providing as shifts in ShiftsForPreconditioner the Ritz values displaced by an approximation of the eigenvalue error.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
int correctionParams.maxInnerIterations

Control the maximum number of inner QMR iterations:

  • 0: no inner iterations;
  • >0: perform at most that number of inner iterations per outer step;
  • <0: perform at most the rest of the remaining matrix-vector products up to reach maxMatvecs.

Input/output:

primme_initialize() sets this field to 0;
this field is read and written by primme_set_method() (see Preset Methods);
this field is read by dprimme().

See also convTest.

double correctionParams.relTolBase

Parameter used when convTest is primme_decreasing_LTolerance.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
primme_convergencetest correctionParams.convTest

Set how to stop the inner QMR method:

  • primme_full_LTolerance: stop by iterations only;
  • primme_decreasing_LTolerance, stop when \(\text{relTolBase}^{-\text{outIts}}\) where outIts is the number of outer iterations and retTolBase is set in relTolBase; This is a legacy option from classical JDQR and we recommend strongly against its use.
  • primme_adaptive, stop when the estimated eigenvalue residual has reached the required tolerance (based on Notay’s JDCG).
  • primme_adaptive_ETolerance, as primme_adaptive but also stopping when the estimated eigenvalue residual has reduced 10 times.

Input/output:

primme_initialize() sets this field to primme_adaptive_ETolerance;
this field is read by dprimme().

Note

Avoid to set maxInnerIterations to -1 and convTest to primme_full_LTolerance.

See also maxInnerIterations.

int correctionParams.projectors.LeftQ
int correctionParams.projectors.LeftX
int correctionParams.projectors.RightQ
int correctionParams.projectors.RightX
int correctionParams.projectors.SkewQ
int correctionParams.projectors.SkewX

Control the projectors involved in the computation of the correction appended to the basis every (outer) iteration.

Consider the current selected Ritz value \(\Lambda\) and vectors \(X\), the residual associated vectors \(R=AX-X\Lambda\), the previous locked vectors \(Q\), and the preconditioner \(M^{-1}\).

When maxInnerIterations is 0, the correction \(D\) appended to the basis in GD is:

RightX SkewX \(D\)
0 0 \(M^{-1}R\) (Classic GD)
1 0 \(M^{-1}(R-\Delta X)\) (cheap Olsen’s Method)
1 1 \((I- M^{-1}X(X^*M^{-1}X)^{-1}X^*)M^{-1}R\) (Olsen’s Method)
0 1 error

Where \(\Delta\) is a diagonal matrix that \(\Delta_{i,i}\) holds an estimation of the error of the approximate eigenvalue \(\Lambda_{i,i}\).

The values of RightQ, SkewQ, LeftX and LeftQ are ignored.

When maxInnerIterations is not 0, the correction \(D\) in Jacobi-Davidson results from solving:

\[P_Q^l P_X^l (A-\sigma I) P_X^r P_Q^r M^{-1} D' = -R, \ \ \ D = P_X^r P_Q^l M^{-1}D'.\]

For LeftQ:

0: \(P_Q^l = I\);
1: \(P_Q^l = I - QQ^*\).

For LeftX:

0: \(P_X^l = I\);
1: \(P_X^l = I - XX^*\).

For RightQ and SkewQ:

RightQ SkewQ \(P_Q^r\)
0 0 \(I\)
1 0 \(I - QQ^*\)
1 1 \(I - KQ(Q^*KQ)^{-1}Q^*\)
0 1 error

For RightX and SkewX:

RightX SkewX \(P_X^r\)
0 0 \(I\)
1 0 \(I - XX^*\)
1 1 \(I - KX(X^*KX)^{-1}X^*\)
0 1 error

Input/output:

primme_initialize() sets all of them to 0;
this field is written by primme_set_method() (see Preset Methods);
this field is read by dprimme().

See [r3] for a study about different projector configurations in JD.

PRIMME_INT ldOPs

Recommended leading dimension to be used in matrixMatvec, applyPreconditioner and massMatrixMatvec. The default value is zero, which means no user recommendation. In that case, PRIMME computes ldOPs internally to get better memory performance.

Input/output:

primme_initialize() sets this field to 0;
this field is read by dprimme().
void (*monitorFun)(void *basisEvals, int *basisSize, int *basisFlags, int *iblock, int *blockSize, void *basisNorms, int *numConverged, void *lockedEvals, int *numLocked, int *lockedFlags, void *lockedNorms, int *inner_its, void *LSRes, primme_event *event, struct primme_params *primme, int *ierr)

Convergence monitor. Used to customize how to report solver information during execution (iteration number, matvecs, time, unconverged and converged eigenvalues, residual norms, targets, etc).

Parameters:
  • basisEvals – array with approximate eigenvalues of the basis.
  • basisSize – size of the arrays, basisEvals, basisFlags and basisNorms.
  • basisFlags – state of every approximate pair in the basis.
  • iblock – indices of the approximate pairs in the block targeted during current iteration.
  • blockSize – size of array iblock.
  • basisNorms – array with residual norms of the pairs in the basis.
  • numConverged – number of pairs converged in the basis plus the number of the locked pairs (note that this value isn’t monotonic).
  • lockedEvals – array with the locked eigenvalues.
  • numLocked – size of the arrays lockedEvals, lockedFlags and lockedNorms.
  • lockedFlags – state of each locked eigenpair.
  • lockedNorms – array with the residual norms of the locked pairs.
  • inner_its – number of performed QMR iterations in the current correction equation. It resets for each block vector.
  • LSRes – residual norm of the linear system at the current QMR iteration.
  • event – event reported.
  • primme – parameters structure; the counter in stats are updated with the current number of matrix-vector products, iterations, elapsed time, etc., since start.
  • ierr – output error code; if it is set to non-zero, the current call to PRIMME will stop.

This function is called at the following events:

  • *event == primme_event_outer_iteration: every outer iterations.

    For this event the following inputs are provided: basisEvals, basisNorms, basisSize, basisFlags, iblock and blockSize.

    basisNorms[iblock[i]] has the residual norm for the selected pair in the block. PRIMME avoids computing the residual of soft-locked pairs, basisNorms[i] for i<iblock[0]. So those values may correspond to previous iterations. The values basisNorms[i] for i>iblock[blockSize-1] are not valid.

    If locking is enabled, lockedEvals, numLocked, lockedFlags and lockedNorms are also provided.

    inner_its and LSRes are not provided.

  • *event == primme_event_inner_iteration: every QMR iteration.

    basisEvals[0] and basisNorms[0] provides the approximate eigenvalue and the residual norm of the pair which is improved in the current correction equation. If convTest is primme_adaptive or primme_adaptive_ETolerance, basisEvals[0] and basisNorms[0] are updated every QMR iteration.

    inner_its and LSRes are also provided.

    lockedEvals, numLocked, lockedFlags and lockedNorms may not be provided.

  • *event == primme_event_convergence: a new eigenpair in the basis passed the convergence criterion.

    iblock[0] is the index of the newly converged pair in the basis which will be locked or soft-locked. The following are provided: basisEvals, basisNorms, basisSize, basisFlags and blockSize[0]==1.

    lockedEvals, numLocked, lockedFlags and lockedNorms may not be provided.

    inner_its and LSRes are not provided.

  • *event == primme_event_locked: new pair was added to the locked eigenvectors.

    lockedEvals, numLocked, lockedFlags and lockedNorms are provided. The last element of lockedEvals, lockedFlags and lockedNorms corresponds to the recent locked pair.

    basisEvals, numConverged, basisFlags and basisNorms may not be provided.

    inner_its and LSRes are not provided.

The values of basisFlags and lockedFlags are:

  • 0: unconverged.
  • 1: internal use; only in basisFlags.
  • 2: passed convergence test convTestFun.
  • 3: practically converged because the solver may not be able to reduce the residual norm further without recombining the locked eigenvectors.

Input/output:

primme_initialize() sets this field to NULL;
dprimme() sets this field to an internal function if it is NULL;
this field is read by dprimme().
PRIMME_INT stats.numOuterIterations

Hold the number of outer iterations. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
PRIMME_INT stats.numRestarts

Hold the number of restarts during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
PRIMME_INT stats.numMatvecs

Hold how many vectors the operator in matrixMatvec has been applied on. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
PRIMME_INT stats.numPreconds

Hold how many vectors the operator in applyPreconditioner has been applied on. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
PRIMME_INT stats.numGlobalSum

Hold how many times globalSumReal has been called. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.volumeGlobalSum

Hold how many REAL have been reduced by globalSumReal. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.elapsedTime

Hold the wall clock time spent by the call to dprimme() or zprimme(). The value is available at the end of the execution.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.timeMatvec

Hold the wall clock time spent by matrixMatvec. The value is available at the end of the execution.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.timePrecond

Hold the wall clock time spent by applyPreconditioner. The value is available at the end of the execution.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.timeOrtho

Hold the wall clock time spent by orthogonalization. The value is available at the end of the execution.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.timeGlobalSum

Hold the wall clock time spent by globalSumReal. The value is available at the end of the execution.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.estimateMinEVal

Hold the estimation of the smallest eigenvalue for the current eigenproblem. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.estimateMaxEVal

Hold the estimation of the largest eigenvalue for the current eigenproblem. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.estimateLargestSVal

Hold the estimation of the largest singular value (i.e., the absolute value of the eigenvalue with largest absolute value) for the current eigenproblem. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
double stats.maxConvTol

Hold the maximum residual norm of the converged eigenvectors. The value is available during execution and at the end.

Input/output:

primme_initialize() sets this field to 0;
written by dprimme().
void (*convTestFun)(double *eval, void *evecs, double *resNorm, int *isconv, primme_params *primme, int *ierr)

Function that evaluates if the approximate eigenpair has converged. If NULL, it is used the default convergence criteria (see eps).

Parameters:
  • eval – the approximate value to evaluate.
  • x – one dimensional array of size nLocal containing the approximate vector; it can be NULL. The actual type depends on which function is being calling. For dprimme(), it is double, for zprimme() it is PRIMME_COMPLEX_DOUBLE, for sprimme() it is float and for for cprimme() it is PRIMME_COMPLEX_FLOAT.
  • resNorm – the norm of residual vector.
  • isconv – (output) the function sets zero if the pair is not converged and non zero otherwise.
  • primme – parameters structure.
  • ierr – output error code; if it is set to non-zero, the current call to PRIMME will stop.

Input/output:

primme_initialize() sets this field to NULL;
this field is read by dprimme().

Preset Methods

primme_preset_method
PRIMME_DEFAULT_MIN_TIME

Set as PRIMME_JDQMR_ETol when target is either primme_smallest or primme_largest, and as PRIMME_JDQMR otherwise. This method is usually the fastest if the cost of the matrix vector product is inexpensive.

PRIMME_DEFAULT_MIN_MATVECS

Currently set as PRIMME_GD_Olsen_plusK; this method usually performs fewer matrix vector products than other methods, so it’s a good choice when this operation is expensive.

PRIMME_DYNAMIC

Switches to the best method dynamically; currently, between methods PRIMME_DEFAULT_MIN_TIME and PRIMME_DEFAULT_MIN_MATVECS.

With PRIMME_DYNAMIC primme_set_method() sets dynamicMethodSwitch = 1 and makes the same changes as for method PRIMME_DEFAULT_MIN_TIME.

PRIMME_Arnoldi

Arnoldi implemented à la Generalized Davidson.

With PRIMME_Arnoldi primme_set_method() sets:

PRIMME_GD

Generalized Davidson.

With PRIMME_GD primme_set_method() sets:

PRIMME_GD_plusK

GD with locally optimal restarting.

With PRIMME_GD_plusK primme_set_method() sets maxPrevRetain = 2 if maxBlockSize is 1 and numEvals > 1; otherwise it sets maxPrevRetain to maxBlockSize. Also:

PRIMME_GD_Olsen_plusK

GD+k and the cheap Olsen’s Method.

With PRIMME_GD_Olsen_plusK primme_set_method() makes the same changes as for method PRIMME_GD_plusK and sets RightX = 1.

PRIMME_JD_Olsen_plusK

GD+k and Olsen’s Method.

With PRIMME_JD_Olsen_plusK primme_set_method() makes the same changes as for method PRIMME_GD_plusK and also sets robustShifts = 1, RightX to 1, and SkewX to 1.

PRIMME_RQI

(Accelerated) Rayleigh Quotient Iteration.

With PRIMME_RQI primme_set_method() sets:

Note

If numTargetShifts > 0 and targetShifts are provided, the interior problem solved uses these shifts in the correction equation. Therefore RQI becomes INVIT (inverse iteration) in that case.

PRIMME_JDQR

Jacobi-Davidson with fixed number of inner steps.

With PRIMME_JDQR primme_set_method() sets:

PRIMME_JDQMR

Jacobi-Davidson with adaptive stopping criterion for inner Quasi Minimum Residual (QMR).

With PRIMME_JDQMR primme_set_method() sets:

PRIMME_JDQMR_ETol

JDQMR but QMR stops after residual norm reduces by a 0.1 factor.

With PRIMME_JDQMR_ETol primme_set_method() makes the same changes as for the method PRIMME_JDQMR and sets convTest = primme_adaptive_ETolerance.

PRIMME_STEEPEST_DESCENT

Steepest descent.

With PRIMME_STEEPEST_DESCENT primme_set_method() sets:

PRIMME_LOBPCG_OrthoBasis

LOBPCG with orthogonal basis.

With PRIMME_LOBPCG_OrthoBasis primme_set_method() sets:

PRIMME_LOBPCG_OrthoBasis_Window

LOBPCG with sliding window of maxBlockSize < 3 * numEvals.

With PRIMME_LOBPCG_OrthoBasis_Window primme_set_method() sets:

Error Codes

The functions dprimme() and zprimme() return one of the next values: