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
andnLocal
) and counters (such asnumMatvecs
).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 andstd::complex<float>
in C++.
-
PRIMME_COMPLEX_DOUBLE
¶ Macro that is
complex double
in C andstd::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 bydprimme()
.
-
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
xblockSize
in column-major order with leading dimensionldx
. - ldx -- the leading dimension of the array
x
. - y -- matrix of size
nLocal
xblockSize
in column-major order with leading dimensionldy
. - ldy -- the leading dimension of the array
y
. - blockSize -- number of columns in
x
andy
. - 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
andy
depends on which function is being calling. Fordprimme()
, it isdouble
, forzprimme()
it isPRIMME_COMPLEX_DOUBLE
, forsprimme()
it isfloat
and forcprimme()
it isPRIMME_COMPLEX_FLOAT
.Input/output:
primme_initialize()
sets this field to NULL;this field is read bydprimme()
.- x -- matrix of size
Note
If you have performance issues with leading dimension different from
nLocal
, setldOPs
tonLocal
.-
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 bydprimme()
.
-
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 bydprimme()
.Warning
Generalized eigenproblems not implemented in current version. This member is included for future compatibility.
-
int
numProcs
¶ Number of processes calling
dprimme()
orzprimme()
in parallel.Input/output:
primme_initialize()
sets this field to 1;this field is read bydprimme()
.
-
int
procID
¶ The identity of the local process within a parallel execution calling
dprimme()
orzprimme()
. Only the process with id 0 prints information.Input/output:
primme_initialize()
sets this field to 0;this field is read bydprimme()
.
-
int
nLocal
¶ Number of local rows on this process.
Input/output:
primme_initialize()
sets this field to -1;this field is read bydprimme()
.
-
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
andglobalSumReal
.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 ofsendBuf
. - count -- array size of
sendBuf
andrecvBuf
. - 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
andrecvBuf
depends on which function is being calling. Fordprimme()
andzprimme()
it isdouble
, and forsprimme()
andcprimme()
it isfloat
. Note thatcount
is the number of values of the actual type.Input/output:
primme_initialize()
sets this field to an internal function;this field is read bydprimme()
.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()
andcprimme()
replaceMPI_DOUBLE
by`MPI_FLOAT
.- sendBuf -- array of size
-
int
numEvals
¶ Number of eigenvalues wanted.
Input/output:
primme_initialize()
sets this field to 1;
-
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:
primme_initialize()
sets this field toprimme_smallest
;this field is read bydprimme()
.
-
int
numTargetShifts
¶ Size of the array
targetShifts
. Used only whentarget
isprimme_closest_geq
,primme_closest_leq
,primme_closest_abs
orprimme_largest_abs
. The default values is 0.Input/output:
primme_initialize()
sets this field to 0;this field is read bydprimme()
.
-
double *
targetShifts
¶ Array of shifts, at least of size
numTargetShifts
. Used only whentarget
isprimme_closest_geq
,primme_closest_leq
,primme_closest_abs
orprimme_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. IfnumTargetShifts
<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 bydprimme()
.Note
Considerations for interior problems:
- PRIMME will try to compute the eigenvalues in the order given in the
targetShifts
. However, for code efficiency and robustness, the shifts should be ordered. Order them in ascending (descending) order for shifts closer to the lower (higher) end of the spectrum. - If some shift is close to the lower (higher) end of the spectrum,
use either
primme_closest_geq
(primme_closest_leq
) orprimme_closest_abs
. primme_closest_leq
andprimme_closest_geq
are more efficient thanprimme_closest_abs
.- For interior eigenvalues larger
maxBasisSize
is usually more robust. - To find the largest magnitude eigenvalues set
target
toprimme_largest_abs
,numTargetShifts
to 1 andtargetShifts
to an array with a zero value.
- PRIMME will try to compute the eigenvalues in the order given in the
-
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 whenprintLevel
is from 0 to 4. IfprintLevel
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 bydprimme()
.
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 bydprimme()
.
-
double
eps
¶ If
convTestFun
is NULL, an eigenpairs is marked as converged when the 2-norm of the residual vector is less thaneps
*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 bydprimme()
.
-
FILE *
outputFile
¶ Opened file to write down the output.
Input/output:
primme_initialize()
sets this field to the standard output;this field is read bydprimme()
andprimme_display_params()
.
-
int
dynamicMethodSwitch
¶ If this value is 1, it alternates dynamically between
PRIMME_DEFAULT_MIN_TIME
andPRIMME_DEFAULT_MIN_MATVECS
, trying to identify the fastest method.On exit, it holds a recommended method for future runs on this problem:
-1: usePRIMME_DEFAULT_MIN_MATVECS
next time.-2: usePRIMME_DEFAULT_MIN_TIME
next time.-3: close call, usePRIMME_DYNAMIC
next time again.Input/output:
primme_initialize()
sets this field to 0;written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.Note
Even for expert users we do not recommend setting
dynamicMethodSwitch
directly, but throughprimme_set_method()
.Note
The code obtains timings by the
gettimeofday
Unix utility. If a cheaper, more accurate timer is available, modify thePRIMMESRC/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;written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
int
initSize
¶ On input, the number of initial vector guesses provided in
evecs
argument indprimme()
orzprimme()
.On output,
initSize
holds the number of converged eigenpairs. Withoutlocking
allnumEvals
approximations are inevecs
but only theinitSize
ones are converged.During execution, it holds the current number of converged eigenpairs. In addition, if locking is used, these are accessible in
evals
andevecs
.Input/output:
primme_initialize()
sets this field to 0;this field is read and written bydprimme()
.
-
PRIMME_INT
ldevecs
¶ The leading dimension of
evecs
. The default isnLocal
.Input/output:
primme_initialize()
sets this field to -1;this field is read bydprimme()
.
-
int
numOrthoConst
¶ Number of vectors to be used as external orthogonalization constraints. These vectors are provided in the first
numOrthoConst
positions of theevecs
argument indprimme()
orzprimme()
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()
orzprimme()
, possibly with different parameters (see an example inTEST/ex_zseq.c
).Input/output:
primme_initialize()
sets this field to 0;this field is read bydprimme()
.
-
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 byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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 byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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 byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.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 toINT_MAX
;this field is read bydprimme()
.
-
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 toINT_MAX
;this field is read bydprimme()
.
-
int
intWorkSize
¶ If
dprimme()
orzprimme()
is called with all arguments as NULL except forprimme_params
then PRIMME returns immediately withintWorkSize
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 inintWork
. IfintWorkSize
is 0, the code will allocate the required space, which can be freed later by callingprimme_free()
.Input/output:
primme_initialize()
sets this field to 0;this field is read and written bydprimme()
.
-
size_t
realWorkSize
¶ If
dprimme()
orzprimme()
is called with all arguments as NULL except forprimme_params
then PRIMME returns immediately withrealWorkSize
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 inrealWork
. IfrealWorkSize
is 0, the code will allocate the required space, which can be freed later by callingprimme_free()
.Input/output:
primme_initialize()
sets this field to 0;this field is read and written bydprimme()
.
-
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 ofevecs
. If this is the case, a Rayleigh Ritz on returnedevecs
would provide the accurate eigenvectors (see [r4]).Input/output:
primme_initialize()
sets this field to NULL;this field is read and written bydprimme()
.
-
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 bydprimme()
.
-
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 ofprocID
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 bydprimme()
.
-
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 ofdprimme()
andzprimme()
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 bydprimme()
.
-
primme_init
initBasisMode
¶ Select how the search subspace basis is initialized up to
minRestartSize
vectors if not enough initial vectors are provided (seeinitSize
):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 ismaxBlockSize
.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:
primme_initialize()
sets this field toprimme_init_krylov
;this field is read bydprimme()
.
-
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 (seetargetShifts
).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_initialize()
sets this field toprimme_proj_default
;
-
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 toprimme_thick
;written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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
plusmaxPrevRetain
.Input/output:
primme_initialize()
sets this field to 0;this field is read and written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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 byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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;written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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 byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.See also
convTest
.
-
double
correctionParams.relTolBase
¶ Parameter used when
convTest
isprimme_decreasing_LTolerance
.Input/output:
primme_initialize()
sets this field to 0;written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.
-
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 inrelTolBase
; 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
, asprimme_adaptive
but also stopping when the estimated eigenvalue residual has reduced 10 times.
Input/output:
primme_initialize()
sets this field toprimme_adaptive_ETolerance
;written byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.Note
Avoid to set
maxInnerIterations
to -1 andconvTest
toprimme_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
andLeftQ
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
andSkewQ
: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
andSkewX
: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 byprimme_set_method()
(see Preset Methods);this field is read bydprimme()
.See [r3] for a study about different projector configurations in JD.
-
PRIMME_INT
ldOPs
¶ Recommended leading dimension to be used in
matrixMatvec
,applyPreconditioner
andmassMatrixMatvec
. 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 -1;this field is read bydprimme()
.
-
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
andbasisNorms
. - 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
andlockedNorms
. - 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
andblockSize
.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]
fori<iblock[0]
. So those values may correspond to previous iterations. The valuesbasisNorms[i]
fori>iblock[blockSize-1]
are not valid.If
locking
is enabled,lockedEvals
,numLocked
,lockedFlags
andlockedNorms
are also provided.inner_its
andLSRes
are not provided.*event == primme_event_inner_iteration
: every QMR iteration.basisEvals[0]
andbasisNorms[0]
provides the approximate eigenvalue and the residual norm of the pair which is improved in the current correction equation. IfconvTest
isprimme_adaptive
orprimme_adaptive_ETolerance
,basisEvals[0]
andbasisNorms[0]
are updated every QMR iteration.inner_its
andLSRes
are also provided.lockedEvals
,numLocked
,lockedFlags
andlockedNorms
may not be provided.*event == primme_event_converged
: 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
andblockSize[0]==1
.lockedEvals
,numLocked
,lockedFlags
andlockedNorms
may not be provided.inner_its
andLSRes
are not provided.*event == primme_event_locked
: new pair was added to the locked eigenvectors.lockedEvals
,numLocked
,lockedFlags
andlockedNorms
are provided. The last element oflockedEvals
,lockedFlags
andlockedNorms
corresponds to the recent locked pair.basisEvals
,numConverged
,basisFlags
andbasisNorms
may not be provided.inner_its
andLSRes
are not provided.
The values of
basisFlags
andlockedFlags
are:0
: unconverged.1
: internal use; only inbasisFlags
.2
: passed convergence testconvTestFun
.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 bydprimme()
.
-
void *
monitor
¶ This field may be used to pass any required information to the function
monitorFun
.Input/output:
primme_initialize()
sets this field to NULL;
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
double
stats.volumeGlobalSum
¶ Hold how many
REAL
have been reduced byglobalSumReal
. The value is available during execution and at the end.Input/output:
primme_initialize()
sets this field to 0;written bydprimme()
.
-
double
stats.elapsedTime
¶ Hold the wall clock time spent by the call to
dprimme()
orzprimme()
. The value is available at the end of the execution.Input/output:
primme_initialize()
sets this field to 0;written bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
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 bydprimme()
.
-
void
(*convTestFun)
(double *eval, void *evec, 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.
- evec -- one dimensional array of size
nLocal
containing the approximate vector; it can be NULL. - resNorm -- the norm of the 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.
The actual type of
evec
depends on which function is being calling. Fordprimme()
, it isdouble
, forzprimme()
it isPRIMME_COMPLEX_DOUBLE
, forsprimme()
it isfloat
and forcprimme()
it isPRIMME_COMPLEX_FLOAT
.Input/output:
primme_initialize()
sets this field to NULL;this field is read bydprimme()
.
-
void *
convtest
¶ This field may be used to pass any required information to the function
convTestFun
.Input/output:
primme_initialize()
sets this field to NULL;
-
PRIMME_INT
Preset Methods¶
-
primme_preset_method
¶ -
PRIMME_DEFAULT_MIN_TIME
¶ Set as
PRIMME_JDQMR_ETol
whentarget
is eitherprimme_smallest
orprimme_largest
, and asPRIMME_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
andPRIMME_DEFAULT_MIN_MATVECS
.With
PRIMME_DYNAMIC
primme_set_method()
setsdynamicMethodSwitch
= 1 and makes the same changes as for methodPRIMME_DEFAULT_MIN_TIME
.
-
PRIMME_Arnoldi
¶ Arnoldi implemented à la Generalized Davidson.
With
PRIMME_Arnoldi
primme_set_method()
sets:locking
= 0;maxPrevRetain
= 0;
precondition
= 0;maxInnerIterations
= 0.
-
PRIMME_GD
¶ Generalized Davidson.
With
PRIMME_GD
primme_set_method()
sets:locking
= 0;maxPrevRetain
= 0;robustShifts
= 1;
maxInnerIterations
= 0;RightX
= 0;SkewX
= 0.
-
PRIMME_GD_plusK
¶ GD with locally optimal restarting.
With
PRIMME_GD_plusK
primme_set_method()
setsmaxPrevRetain
= 2 ifmaxBlockSize
is 1 andnumEvals
> 1; otherwise it setsmaxPrevRetain
tomaxBlockSize
. Also:locking
= 0;maxInnerIterations
= 0;
-
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 methodPRIMME_GD_plusK
and setsRightX
= 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 methodPRIMME_GD_plusK
and also setsrobustShifts
= 1,RightX
to 1, andSkewX
to 1.
-
PRIMME_RQI
¶ (Accelerated) Rayleigh Quotient Iteration.
With
PRIMME_RQI
primme_set_method()
sets:locking
= 1;maxPrevRetain
= 0;robustShifts
= 1;maxInnerIterations
= -1;LeftQ
= 1;LeftX
= 1;
Note
If
numTargetShifts
> 0 andtargetShifts
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:locking
= 1;maxPrevRetain
= 1;robustShifts
= 0;maxInnerIterations
= 10 if it is 0;LeftQ
= 0;LeftX
= 1;
RightQ
= 1;RightX
= 1;SkewQ
= 1;SkewX
= 1;relTolBase
= 1.5;convTest
=primme_full_LTolerance
.
-
PRIMME_JDQMR
¶ Jacobi-Davidson with adaptive stopping criterion for inner Quasi Minimum Residual (QMR).
With
PRIMME_JDQMR
primme_set_method()
sets:locking
= 0;maxPrevRetain
= 1 if it is 0maxInnerIterations
= -1;LeftQ
=precondition
;LeftX
= 1;
-
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 methodPRIMME_JDQMR
and setsconvTest
=primme_adaptive_ETolerance
.
-
PRIMME_STEEPEST_DESCENT
¶ Steepest descent.
With
PRIMME_STEEPEST_DESCENT
primme_set_method()
sets:locking
= 1;maxBasisSize
=numEvals
* 2;minRestartSize
=numEvals
;maxBlockSize
=numEvals
;scheme
=primme_thick
;
maxPrevRetain
= 0;robustShifts
= 0;maxInnerIterations
= 0;RightX
= 1;SkewX
= 0.
-
PRIMME_LOBPCG_OrthoBasis
¶ LOBPCG with orthogonal basis.
With
PRIMME_LOBPCG_OrthoBasis
primme_set_method()
sets:locking
= 0;maxBasisSize
=numEvals
* 3;minRestartSize
=numEvals
;maxBlockSize
=numEvals
;scheme
=primme_thick
;
maxPrevRetain
=numEvals
;robustShifts
= 0;maxInnerIterations
= 0;RightX
= 1;SkewX
= 0.
-
PRIMME_LOBPCG_OrthoBasis_Window
¶ LOBPCG with sliding window of
maxBlockSize
< 3 *numEvals
.With
PRIMME_LOBPCG_OrthoBasis_Window
primme_set_method()
sets:locking
= 0;maxBasisSize
=maxBlockSize
* 3;minRestartSize
=maxBlockSize
;scheme
=primme_thick
;maxPrevRetain
=maxBlockSize
;
robustShifts
= 0;maxInnerIterations
= 0;RightX
= 1;SkewX
= 0.
-
Error Codes¶
The functions dprimme()
and zprimme()
return one of the next values:
- 0: success.
- 1: reported only amount of required memory.
- -1: failed in allocating int or real workspace.
- -2: malloc failed in allocating a permutation integer array.
- -3: main_iter() encountered problem; the calling stack of the
functions where the error occurred was printed in
stderr
. - -4: if argument
primme
is NULL. - -5: if
n
< 0 ornLocal
< 0 ornLocal
>n
. - -6: if
numProcs
< 1. - -7: if
matrixMatvec
is NULL. - -8: if
applyPreconditioner
is NULL andprecondition
> 0. - -9: if
massMatrixMatvec
is not NULL (generalized Hermitian problem is not supported yet). - -10: if
numEvals
>n
. - -11: if
numEvals
< 0. - -12: if
eps
> 0 andeps
< machine precision. - -13: if
target
is not properly defined. - -14: if
target
is one ofprimme_closest_geq
,primme_closest_leq
,primme_closest_abs
orprimme_largest_abs
butnumTargetShifts
<= 0 (no shifts). - -15: if
target
is one ofprimme_closest_geq
,primme_closest_leq
,primme_closest_abs
orprimme_largest_abs
buttargetShifts
is NULL (no shifts array). - -16: if
numOrthoConst
< 0 ornumOrthoConst
>n
. (no free dimensions left). - -17: if
maxBasisSize
< 2. - -18: if
minRestartSize
< 0 orminRestartSize
shouldn't be zero. - -19: if
maxBlockSize
< 0 ormaxBlockSize
shouldn't be zero. - -20: if
maxPrevRetain
< 0. - -21: if
scheme
is not one of primme_thick or primme_dtr. - -22: if
initSize
< 0. - -23: if
locking
== 0 andinitSize
>maxBasisSize
. - -24: if
locking
andinitSize
>numEvals
. - -25: if
maxPrevRetain
+minRestartSize
>=maxBasisSize
. - -26: if
minRestartSize
>=n
. - -27: if
printLevel
< 0 orprintLevel
> 5. - -28: if
convTest
is not one ofprimme_full_LTolerance
,primme_decreasing_LTolerance
,primme_adaptive_ETolerance
orprimme_adaptive
. - -29: if
convTest
==primme_decreasing_LTolerance
andrelTolBase
<= 1. - -30: if
evals
is NULL, but notevecs
andresNorms
. - -31: if
evecs
is NULL, but notevals
andresNorms
. - -32: if
resNorms
is NULL, but notevecs
andevals
. - -33: if
locking
== 0 andminRestartSize
<numEvals
. - -34: if
ldevecs
<nLocal
. - -35: if
ldOPs
is not zero and less thannLocal
. - -36: not enough memory for
realWork
. - -37: not enough memory for
intWork
. - -38: if
locking
== 0 andtarget
isprimme_closest_leq
orprimme_closest_geq
.