Actual source code: epsopts.c
slepc-3.18.1 2022-11-02
1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
6: This file is part of SLEPc.
7: SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9: */
10: /*
11: EPS routines related to options that can be set via the command-line
12: or procedurally.
13: */
15: #include <slepc/private/epsimpl.h>
16: #include <petscdraw.h>
18: /*@C
19: EPSMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective on eps
24: Input Parameters:
25: + eps - the eigensolver context
26: . opt - the command line option for this monitor
27: . name - the monitor type one is seeking
28: . ctx - an optional user context for the monitor, or NULL
29: - trackall - whether this monitor tracks all eigenvalues or not
31: Level: developer
33: .seealso: EPSMonitorSet(), EPSSetTrackAll()
34: @*/
35: PetscErrorCode EPSMonitorSetFromOptions(EPS eps,const char opt[],const char name[],void *ctx,PetscBool trackall)
36: {
37: PetscErrorCode (*mfunc)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
38: PetscErrorCode (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
39: PetscErrorCode (*dfunc)(PetscViewerAndFormat**);
40: PetscViewerAndFormat *vf;
41: PetscViewer viewer;
42: PetscViewerFormat format;
43: PetscViewerType vtype;
44: char key[PETSC_MAX_PATH_LEN];
45: PetscBool flg;
47: PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->options,((PetscObject)eps)->prefix,opt,&viewer,&format,&flg);
48: if (!flg) return 0;
50: PetscViewerGetType(viewer,&vtype);
51: SlepcMonitorMakeKey_Internal(name,vtype,format,key);
52: PetscFunctionListFind(EPSMonitorList,key,&mfunc);
54: PetscFunctionListFind(EPSMonitorCreateList,key,&cfunc);
55: PetscFunctionListFind(EPSMonitorDestroyList,key,&dfunc);
56: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
57: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
59: (*cfunc)(viewer,format,ctx,&vf);
60: PetscObjectDereference((PetscObject)viewer);
61: EPSMonitorSet(eps,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
62: if (trackall) EPSSetTrackAll(eps,PETSC_TRUE);
63: return 0;
64: }
66: /*@
67: EPSSetFromOptions - Sets EPS options from the options database.
68: This routine must be called before EPSSetUp() if the user is to be
69: allowed to set the solver type.
71: Collective on eps
73: Input Parameters:
74: . eps - the eigensolver context
76: Notes:
77: To see all options, run your program with the -help option.
79: Level: beginner
81: .seealso: EPSSetOptionsPrefix()
82: @*/
83: PetscErrorCode EPSSetFromOptions(EPS eps)
84: {
85: char type[256];
86: PetscBool set,flg,flg1,flg2,flg3,bval;
87: PetscReal r,array[2]={0,0};
88: PetscScalar s;
89: PetscInt i,j,k;
90: EPSBalance bal;
93: EPSRegisterAll();
94: PetscObjectOptionsBegin((PetscObject)eps);
95: PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,sizeof(type),&flg);
96: if (flg) EPSSetType(eps,type);
97: else if (!((PetscObject)eps)->type_name) EPSSetType(eps,EPSKRYLOVSCHUR);
99: PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg);
100: if (flg) EPSSetProblemType(eps,EPS_HEP);
101: PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg);
102: if (flg) EPSSetProblemType(eps,EPS_GHEP);
103: PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
104: if (flg) EPSSetProblemType(eps,EPS_NHEP);
105: PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
106: if (flg) EPSSetProblemType(eps,EPS_GNHEP);
107: PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
108: if (flg) EPSSetProblemType(eps,EPS_PGNHEP);
109: PetscOptionsBoolGroupEnd("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
110: if (flg) EPSSetProblemType(eps,EPS_GHIEP);
112: PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
113: if (flg) EPSSetExtraction(eps,EPS_RITZ);
114: PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg);
115: if (flg) EPSSetExtraction(eps,EPS_HARMONIC);
116: PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg);
117: if (flg) EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE);
118: PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg);
119: if (flg) EPSSetExtraction(eps,EPS_HARMONIC_RIGHT);
120: PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg);
121: if (flg) EPSSetExtraction(eps,EPS_HARMONIC_LARGEST);
122: PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg);
123: if (flg) EPSSetExtraction(eps,EPS_REFINED);
124: PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg);
125: if (flg) EPSSetExtraction(eps,EPS_REFINED_HARMONIC);
127: bal = eps->balance;
128: PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1);
129: j = eps->balance_its;
130: PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2);
131: r = eps->balance_cutoff;
132: PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3);
133: if (flg1 || flg2 || flg3) EPSSetBalance(eps,bal,j,r);
135: i = eps->max_it;
136: PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
137: r = eps->tol;
138: PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",SlepcDefaultTol(eps->tol),&r,&flg2);
139: if (flg1 || flg2) EPSSetTolerances(eps,r,i);
141: PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
142: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_REL);
143: PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
144: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_NORM);
145: PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
146: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_ABS);
147: PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
148: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_USER);
150: PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg);
151: if (flg) EPSSetStoppingTest(eps,EPS_STOP_BASIC);
152: PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg);
153: if (flg) EPSSetStoppingTest(eps,EPS_STOP_USER);
155: i = eps->nev;
156: PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
157: j = eps->ncv;
158: PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
159: k = eps->mpd;
160: PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
161: if (flg1 || flg2 || flg3) EPSSetDimensions(eps,i,j,k);
163: PetscOptionsBoolGroupBegin("-eps_largest_magnitude","Compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
164: if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE);
165: PetscOptionsBoolGroup("-eps_smallest_magnitude","Compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
166: if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE);
167: PetscOptionsBoolGroup("-eps_largest_real","Compute eigenvalues with largest real parts","EPSSetWhichEigenpairs",&flg);
168: if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL);
169: PetscOptionsBoolGroup("-eps_smallest_real","Compute eigenvalues with smallest real parts","EPSSetWhichEigenpairs",&flg);
170: if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL);
171: PetscOptionsBoolGroup("-eps_largest_imaginary","Compute eigenvalues with largest imaginary parts","EPSSetWhichEigenpairs",&flg);
172: if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY);
173: PetscOptionsBoolGroup("-eps_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
174: if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY);
175: PetscOptionsBoolGroup("-eps_target_magnitude","Compute eigenvalues closest to target","EPSSetWhichEigenpairs",&flg);
176: if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
177: PetscOptionsBoolGroup("-eps_target_real","Compute eigenvalues with real parts closest to target","EPSSetWhichEigenpairs",&flg);
178: if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL);
179: PetscOptionsBoolGroup("-eps_target_imaginary","Compute eigenvalues with imaginary parts closest to target","EPSSetWhichEigenpairs",&flg);
180: if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY);
181: PetscOptionsBoolGroupEnd("-eps_all","Compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg);
182: if (flg) EPSSetWhichEigenpairs(eps,EPS_ALL);
184: PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
185: if (flg) {
186: if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
187: EPSSetTarget(eps,s);
188: }
190: k = 2;
191: PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
192: if (flg) {
194: EPSSetWhichEigenpairs(eps,EPS_ALL);
195: EPSSetInterval(eps,array[0],array[1]);
196: }
198: PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
199: PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&bval,&flg);
200: if (flg) EPSSetPurify(eps,bval);
201: PetscOptionsBool("-eps_two_sided","Use two-sided variant (to compute left eigenvectors)","EPSSetTwoSided",eps->twosided,&bval,&flg);
202: if (flg) EPSSetTwoSided(eps,bval);
204: /* -----------------------------------------------------------------------*/
205: /*
206: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
207: */
208: PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
209: if (set && flg) EPSMonitorCancel(eps);
210: EPSMonitorSetFromOptions(eps,"-eps_monitor","first_approximation",NULL,PETSC_FALSE);
211: EPSMonitorSetFromOptions(eps,"-eps_monitor_all","all_approximations",NULL,PETSC_TRUE);
212: EPSMonitorSetFromOptions(eps,"-eps_monitor_conv","convergence_history",NULL,PETSC_FALSE);
214: /* -----------------------------------------------------------------------*/
215: PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
216: PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
217: PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
218: PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSConvergedReasonView",NULL);
219: PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
220: PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
221: PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);
223: PetscTryTypeMethod(eps,setfromoptions,PetscOptionsObject);
224: PetscObjectProcessOptionsHandlers((PetscObject)eps,PetscOptionsObject);
225: PetscOptionsEnd();
227: if (!eps->V) EPSGetBV(eps,&eps->V);
228: BVSetFromOptions(eps->V);
229: if (!eps->rg) EPSGetRG(eps,&eps->rg);
230: RGSetFromOptions(eps->rg);
231: if (eps->useds) {
232: if (!eps->ds) EPSGetDS(eps,&eps->ds);
233: DSSetFromOptions(eps->ds);
234: }
235: if (!eps->st) EPSGetST(eps,&eps->st);
236: EPSSetDefaultST(eps);
237: STSetFromOptions(eps->st);
238: return 0;
239: }
241: /*@C
242: EPSGetTolerances - Gets the tolerance and maximum iteration count used
243: by the EPS convergence tests.
245: Not Collective
247: Input Parameter:
248: . eps - the eigensolver context
250: Output Parameters:
251: + tol - the convergence tolerance
252: - maxits - maximum number of iterations
254: Notes:
255: The user can specify NULL for any parameter that is not needed.
257: Level: intermediate
259: .seealso: EPSSetTolerances()
260: @*/
261: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
262: {
264: if (tol) *tol = eps->tol;
265: if (maxits) *maxits = eps->max_it;
266: return 0;
267: }
269: /*@
270: EPSSetTolerances - Sets the tolerance and maximum iteration count used
271: by the EPS convergence tests.
273: Logically Collective on eps
275: Input Parameters:
276: + eps - the eigensolver context
277: . tol - the convergence tolerance
278: - maxits - maximum number of iterations to use
280: Options Database Keys:
281: + -eps_tol <tol> - Sets the convergence tolerance
282: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
284: Notes:
285: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
287: Level: intermediate
289: .seealso: EPSGetTolerances()
290: @*/
291: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
292: {
296: if (tol == PETSC_DEFAULT) {
297: eps->tol = PETSC_DEFAULT;
298: eps->state = EPS_STATE_INITIAL;
299: } else {
301: eps->tol = tol;
302: }
303: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
304: eps->max_it = PETSC_DEFAULT;
305: eps->state = EPS_STATE_INITIAL;
306: } else {
308: eps->max_it = maxits;
309: }
310: return 0;
311: }
313: /*@C
314: EPSGetDimensions - Gets the number of eigenvalues to compute
315: and the dimension of the subspace.
317: Not Collective
319: Input Parameter:
320: . eps - the eigensolver context
322: Output Parameters:
323: + nev - number of eigenvalues to compute
324: . ncv - the maximum dimension of the subspace to be used by the solver
325: - mpd - the maximum dimension allowed for the projected problem
327: Level: intermediate
329: .seealso: EPSSetDimensions()
330: @*/
331: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
332: {
334: if (nev) *nev = eps->nev;
335: if (ncv) *ncv = eps->ncv;
336: if (mpd) *mpd = eps->mpd;
337: return 0;
338: }
340: /*@
341: EPSSetDimensions - Sets the number of eigenvalues to compute
342: and the dimension of the subspace.
344: Logically Collective on eps
346: Input Parameters:
347: + eps - the eigensolver context
348: . nev - number of eigenvalues to compute
349: . ncv - the maximum dimension of the subspace to be used by the solver
350: - mpd - the maximum dimension allowed for the projected problem
352: Options Database Keys:
353: + -eps_nev <nev> - Sets the number of eigenvalues
354: . -eps_ncv <ncv> - Sets the dimension of the subspace
355: - -eps_mpd <mpd> - Sets the maximum projected dimension
357: Notes:
358: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
359: dependent on the solution method.
361: The parameters ncv and mpd are intimately related, so that the user is advised
362: to set one of them at most. Normal usage is that
363: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
364: (b) in cases where nev is large, the user sets mpd.
366: The value of ncv should always be between nev and (nev+mpd), typically
367: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
368: a smaller value should be used.
370: When computing all eigenvalues in an interval, see EPSSetInterval(), these
371: parameters lose relevance, and tuning must be done with
372: EPSKrylovSchurSetDimensions().
374: Level: intermediate
376: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
377: @*/
378: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
379: {
385: eps->nev = nev;
386: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
387: eps->ncv = PETSC_DEFAULT;
388: } else {
390: eps->ncv = ncv;
391: }
392: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
393: eps->mpd = PETSC_DEFAULT;
394: } else {
396: eps->mpd = mpd;
397: }
398: eps->state = EPS_STATE_INITIAL;
399: return 0;
400: }
402: /*@
403: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
404: to be sought.
406: Logically Collective on eps
408: Input Parameters:
409: + eps - eigensolver context obtained from EPSCreate()
410: - which - the portion of the spectrum to be sought
412: Possible values:
413: The parameter 'which' can have one of these values
415: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
416: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
417: . EPS_LARGEST_REAL - largest real parts
418: . EPS_SMALLEST_REAL - smallest real parts
419: . EPS_LARGEST_IMAGINARY - largest imaginary parts
420: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
421: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
422: . EPS_TARGET_REAL - eigenvalues with real part closest to target
423: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
424: . EPS_ALL - all eigenvalues contained in a given interval or region
425: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
427: Options Database Keys:
428: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
429: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
430: . -eps_largest_real - Sets largest real parts
431: . -eps_smallest_real - Sets smallest real parts
432: . -eps_largest_imaginary - Sets largest imaginary parts
433: . -eps_smallest_imaginary - Sets smallest imaginary parts
434: . -eps_target_magnitude - Sets eigenvalues closest to target
435: . -eps_target_real - Sets real parts closest to target
436: . -eps_target_imaginary - Sets imaginary parts closest to target
437: - -eps_all - Sets all eigenvalues in an interval or region
439: Notes:
440: Not all eigensolvers implemented in EPS account for all the possible values
441: stated above. Also, some values make sense only for certain types of
442: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
443: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
444: for eigenvalue selection.
446: The target is a scalar value provided with EPSSetTarget().
448: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
449: SLEPc have been built with complex scalars.
451: EPS_ALL is intended for use in combination with an interval (see
452: EPSSetInterval()), when all eigenvalues within the interval are requested,
453: or in the context of the CISS solver for computing all eigenvalues in a region.
454: In those cases, the number of eigenvalues is unknown, so the nev parameter
455: has a different sense, see EPSSetDimensions().
457: Level: intermediate
459: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
460: EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
461: @*/
462: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
463: {
466: switch (which) {
467: case EPS_LARGEST_MAGNITUDE:
468: case EPS_SMALLEST_MAGNITUDE:
469: case EPS_LARGEST_REAL:
470: case EPS_SMALLEST_REAL:
471: case EPS_LARGEST_IMAGINARY:
472: case EPS_SMALLEST_IMAGINARY:
473: case EPS_TARGET_MAGNITUDE:
474: case EPS_TARGET_REAL:
475: #if defined(PETSC_USE_COMPLEX)
476: case EPS_TARGET_IMAGINARY:
477: #endif
478: case EPS_ALL:
479: case EPS_WHICH_USER:
480: if (eps->which != which) {
481: eps->state = EPS_STATE_INITIAL;
482: eps->which = which;
483: }
484: break;
485: #if !defined(PETSC_USE_COMPLEX)
486: case EPS_TARGET_IMAGINARY:
487: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"EPS_TARGET_IMAGINARY can be used only with complex scalars");
488: #endif
489: default:
490: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
491: }
492: return 0;
493: }
495: /*@
496: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
497: sought.
499: Not Collective
501: Input Parameter:
502: . eps - eigensolver context obtained from EPSCreate()
504: Output Parameter:
505: . which - the portion of the spectrum to be sought
507: Notes:
508: See EPSSetWhichEigenpairs() for possible values of 'which'.
510: Level: intermediate
512: .seealso: EPSSetWhichEigenpairs(), EPSWhich
513: @*/
514: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
515: {
518: *which = eps->which;
519: return 0;
520: }
522: /*@C
523: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
524: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
526: Logically Collective on eps
528: Input Parameters:
529: + eps - eigensolver context obtained from EPSCreate()
530: . func - a pointer to the comparison function
531: - ctx - a context pointer (the last parameter to the comparison function)
533: Calling Sequence of func:
534: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
536: + ar - real part of the 1st eigenvalue
537: . ai - imaginary part of the 1st eigenvalue
538: . br - real part of the 2nd eigenvalue
539: . bi - imaginary part of the 2nd eigenvalue
540: . res - result of comparison
541: - ctx - optional context, as set by EPSSetEigenvalueComparison()
543: Note:
544: The returning parameter 'res' can be
545: + negative - if the 1st eigenvalue is preferred to the 2st one
546: . zero - if both eigenvalues are equally preferred
547: - positive - if the 2st eigenvalue is preferred to the 1st one
549: Level: advanced
551: .seealso: EPSSetWhichEigenpairs(), EPSWhich
552: @*/
553: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
554: {
556: eps->sc->comparison = func;
557: eps->sc->comparisonctx = ctx;
558: eps->which = EPS_WHICH_USER;
559: return 0;
560: }
562: /*@C
563: EPSSetArbitrarySelection - Specifies a function intended to look for
564: eigenvalues according to an arbitrary selection criterion. This criterion
565: can be based on a computation involving the current eigenvector approximation.
567: Logically Collective on eps
569: Input Parameters:
570: + eps - eigensolver context obtained from EPSCreate()
571: . func - a pointer to the evaluation function
572: - ctx - a context pointer (the last parameter to the evaluation function)
574: Calling Sequence of func:
575: $ func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
577: + er - real part of the current eigenvalue approximation
578: . ei - imaginary part of the current eigenvalue approximation
579: . xr - real part of the current eigenvector approximation
580: . xi - imaginary part of the current eigenvector approximation
581: . rr - result of evaluation (real part)
582: . ri - result of evaluation (imaginary part)
583: - ctx - optional context, as set by EPSSetArbitrarySelection()
585: Notes:
586: This provides a mechanism to select eigenpairs by evaluating a user-defined
587: function. When a function has been provided, the default selection based on
588: sorting the eigenvalues is replaced by the sorting of the results of this
589: function (with the same sorting criterion given in EPSSetWhichEigenpairs()).
591: For instance, suppose you want to compute those eigenvectors that maximize
592: a certain computable expression. Then implement the computation using
593: the arguments xr and xi, and return the result in rr. Then set the standard
594: sorting by magnitude so that the eigenpair with largest value of rr is
595: selected.
597: This evaluation function is collective, that is, all processes call it and
598: it can use collective operations; furthermore, the computed result must
599: be the same in all processes.
601: The result of func is expressed as a complex number so that it is possible to
602: use the standard eigenvalue sorting functions, but normally only rr is used.
603: Set ri to zero unless it is meaningful in your application.
605: Level: advanced
607: .seealso: EPSSetWhichEigenpairs()
608: @*/
609: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
610: {
612: eps->arbitrary = func;
613: eps->arbitraryctx = ctx;
614: eps->state = EPS_STATE_INITIAL;
615: return 0;
616: }
618: /*@C
619: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
620: used in the convergence test.
622: Logically Collective on eps
624: Input Parameters:
625: + eps - eigensolver context obtained from EPSCreate()
626: . func - a pointer to the convergence test function
627: . ctx - context for private data for the convergence routine (may be null)
628: - destroy - a routine for destroying the context (may be null)
630: Calling Sequence of func:
631: $ func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
633: + eps - eigensolver context obtained from EPSCreate()
634: . eigr - real part of the eigenvalue
635: . eigi - imaginary part of the eigenvalue
636: . res - residual norm associated to the eigenpair
637: . errest - (output) computed error estimate
638: - ctx - optional context, as set by EPSSetConvergenceTestFunction()
640: Note:
641: If the error estimate returned by the convergence test function is less than
642: the tolerance, then the eigenvalue is accepted as converged.
644: Level: advanced
646: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
647: @*/
648: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
649: {
651: if (eps->convergeddestroy) (*eps->convergeddestroy)(eps->convergedctx);
652: eps->convergeduser = func;
653: eps->convergeddestroy = destroy;
654: eps->convergedctx = ctx;
655: if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
656: else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
657: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
658: else {
659: eps->conv = EPS_CONV_USER;
660: eps->converged = eps->convergeduser;
661: }
662: return 0;
663: }
665: /*@
666: EPSSetConvergenceTest - Specifies how to compute the error estimate
667: used in the convergence test.
669: Logically Collective on eps
671: Input Parameters:
672: + eps - eigensolver context obtained from EPSCreate()
673: - conv - the type of convergence test
675: Options Database Keys:
676: + -eps_conv_abs - Sets the absolute convergence test
677: . -eps_conv_rel - Sets the convergence test relative to the eigenvalue
678: . -eps_conv_norm - Sets the convergence test relative to the matrix norms
679: - -eps_conv_user - Selects the user-defined convergence test
681: Note:
682: The parameter 'conv' can have one of these values
683: + EPS_CONV_ABS - absolute error ||r||
684: . EPS_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
685: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
686: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
688: Level: intermediate
690: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
691: @*/
692: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
693: {
696: switch (conv) {
697: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
698: case EPS_CONV_REL: eps->converged = EPSConvergedRelative; break;
699: case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
700: case EPS_CONV_USER:
702: eps->converged = eps->convergeduser;
703: break;
704: default:
705: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
706: }
707: eps->conv = conv;
708: return 0;
709: }
711: /*@
712: EPSGetConvergenceTest - Gets the method used to compute the error estimate
713: used in the convergence test.
715: Not Collective
717: Input Parameters:
718: . eps - eigensolver context obtained from EPSCreate()
720: Output Parameters:
721: . conv - the type of convergence test
723: Level: intermediate
725: .seealso: EPSSetConvergenceTest(), EPSConv
726: @*/
727: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
728: {
731: *conv = eps->conv;
732: return 0;
733: }
735: /*@C
736: EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
737: iteration of the eigensolver.
739: Logically Collective on eps
741: Input Parameters:
742: + eps - eigensolver context obtained from EPSCreate()
743: . func - pointer to the stopping test function
744: . ctx - context for private data for the stopping routine (may be null)
745: - destroy - a routine for destroying the context (may be null)
747: Calling Sequence of func:
748: $ func(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx)
750: + eps - eigensolver context obtained from EPSCreate()
751: . its - current number of iterations
752: . max_it - maximum number of iterations
753: . nconv - number of currently converged eigenpairs
754: . nev - number of requested eigenpairs
755: . reason - (output) result of the stopping test
756: - ctx - optional context, as set by EPSSetStoppingTestFunction()
758: Note:
759: Normal usage is to first call the default routine EPSStoppingBasic() and then
760: set reason to EPS_CONVERGED_USER if some user-defined conditions have been
761: met. To let the eigensolver continue iterating, the result must be left as
762: EPS_CONVERGED_ITERATING.
764: Level: advanced
766: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
767: @*/
768: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
769: {
771: if (eps->stoppingdestroy) (*eps->stoppingdestroy)(eps->stoppingctx);
772: eps->stoppinguser = func;
773: eps->stoppingdestroy = destroy;
774: eps->stoppingctx = ctx;
775: if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
776: else {
777: eps->stop = EPS_STOP_USER;
778: eps->stopping = eps->stoppinguser;
779: }
780: return 0;
781: }
783: /*@
784: EPSSetStoppingTest - Specifies how to decide the termination of the outer
785: loop of the eigensolver.
787: Logically Collective on eps
789: Input Parameters:
790: + eps - eigensolver context obtained from EPSCreate()
791: - stop - the type of stopping test
793: Options Database Keys:
794: + -eps_stop_basic - Sets the default stopping test
795: - -eps_stop_user - Selects the user-defined stopping test
797: Note:
798: The parameter 'stop' can have one of these values
799: + EPS_STOP_BASIC - default stopping test
800: - EPS_STOP_USER - function set by EPSSetStoppingTestFunction()
802: Level: advanced
804: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
805: @*/
806: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
807: {
810: switch (stop) {
811: case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
812: case EPS_STOP_USER:
814: eps->stopping = eps->stoppinguser;
815: break;
816: default:
817: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
818: }
819: eps->stop = stop;
820: return 0;
821: }
823: /*@
824: EPSGetStoppingTest - Gets the method used to decide the termination of the outer
825: loop of the eigensolver.
827: Not Collective
829: Input Parameters:
830: . eps - eigensolver context obtained from EPSCreate()
832: Output Parameters:
833: . stop - the type of stopping test
835: Level: advanced
837: .seealso: EPSSetStoppingTest(), EPSStop
838: @*/
839: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
840: {
843: *stop = eps->stop;
844: return 0;
845: }
847: /*@
848: EPSSetProblemType - Specifies the type of the eigenvalue problem.
850: Logically Collective on eps
852: Input Parameters:
853: + eps - the eigensolver context
854: - type - a known type of eigenvalue problem
856: Options Database Keys:
857: + -eps_hermitian - Hermitian eigenvalue problem
858: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
859: . -eps_non_hermitian - non-Hermitian eigenvalue problem
860: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
861: . -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
862: with positive semi-definite B
863: - -eps_gen_indefinite - generalized Hermitian-indefinite eigenvalue problem
865: Notes:
866: Allowed values for the problem type are Hermitian (EPS_HEP), non-Hermitian
867: (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
868: (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
869: (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).
871: This function must be used to instruct SLEPc to exploit symmetry. If no
872: problem type is specified, by default a non-Hermitian problem is assumed
873: (either standard or generalized). If the user knows that the problem is
874: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
875: B positive definite) then it is recommended to set the problem type so
876: that eigensolver can exploit these properties.
878: Level: intermediate
880: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
881: @*/
882: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
883: {
886: if (type == eps->problem_type) return 0;
887: switch (type) {
888: case EPS_HEP:
889: eps->isgeneralized = PETSC_FALSE;
890: eps->ishermitian = PETSC_TRUE;
891: eps->ispositive = PETSC_FALSE;
892: break;
893: case EPS_NHEP:
894: eps->isgeneralized = PETSC_FALSE;
895: eps->ishermitian = PETSC_FALSE;
896: eps->ispositive = PETSC_FALSE;
897: break;
898: case EPS_GHEP:
899: eps->isgeneralized = PETSC_TRUE;
900: eps->ishermitian = PETSC_TRUE;
901: eps->ispositive = PETSC_TRUE;
902: break;
903: case EPS_GNHEP:
904: eps->isgeneralized = PETSC_TRUE;
905: eps->ishermitian = PETSC_FALSE;
906: eps->ispositive = PETSC_FALSE;
907: break;
908: case EPS_PGNHEP:
909: eps->isgeneralized = PETSC_TRUE;
910: eps->ishermitian = PETSC_FALSE;
911: eps->ispositive = PETSC_TRUE;
912: break;
913: case EPS_GHIEP:
914: eps->isgeneralized = PETSC_TRUE;
915: eps->ishermitian = PETSC_TRUE;
916: eps->ispositive = PETSC_FALSE;
917: break;
918: default:
919: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
920: }
921: eps->problem_type = type;
922: eps->state = EPS_STATE_INITIAL;
923: return 0;
924: }
926: /*@
927: EPSGetProblemType - Gets the problem type from the EPS object.
929: Not Collective
931: Input Parameter:
932: . eps - the eigensolver context
934: Output Parameter:
935: . type - the problem type
937: Level: intermediate
939: .seealso: EPSSetProblemType(), EPSProblemType
940: @*/
941: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
942: {
945: *type = eps->problem_type;
946: return 0;
947: }
949: /*@
950: EPSSetExtraction - Specifies the type of extraction technique to be employed
951: by the eigensolver.
953: Logically Collective on eps
955: Input Parameters:
956: + eps - the eigensolver context
957: - extr - a known type of extraction
959: Options Database Keys:
960: + -eps_ritz - Rayleigh-Ritz extraction
961: . -eps_harmonic - harmonic Ritz extraction
962: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
963: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
964: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
965: (without target)
966: . -eps_refined - refined Ritz extraction
967: - -eps_refined_harmonic - refined harmonic Ritz extraction
969: Notes:
970: Not all eigensolvers support all types of extraction. See the SLEPc
971: Users Manual for details.
973: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
974: may be useful when computing interior eigenvalues.
976: Harmonic-type extractions are used in combination with a 'target'.
978: Level: advanced
980: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
981: @*/
982: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
983: {
986: eps->extraction = extr;
987: return 0;
988: }
990: /*@
991: EPSGetExtraction - Gets the extraction type used by the EPS object.
993: Not Collective
995: Input Parameter:
996: . eps - the eigensolver context
998: Output Parameter:
999: . extr - name of extraction type
1001: Level: advanced
1003: .seealso: EPSSetExtraction(), EPSExtraction
1004: @*/
1005: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1006: {
1009: *extr = eps->extraction;
1010: return 0;
1011: }
1013: /*@
1014: EPSSetBalance - Specifies the balancing technique to be employed by the
1015: eigensolver, and some parameters associated to it.
1017: Logically Collective on eps
1019: Input Parameters:
1020: + eps - the eigensolver context
1021: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1022: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1023: . its - number of iterations of the balancing algorithm
1024: - cutoff - cutoff value
1026: Options Database Keys:
1027: + -eps_balance <method> - the balancing method, where <method> is one of
1028: 'none', 'oneside', 'twoside', or 'user'
1029: . -eps_balance_its <its> - number of iterations
1030: - -eps_balance_cutoff <cutoff> - cutoff value
1032: Notes:
1033: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1034: where D is an appropriate diagonal matrix. This improves the accuracy of
1035: the computed results in some cases. See the SLEPc Users Manual for details.
1037: Balancing makes sense only for non-Hermitian problems when the required
1038: precision is high (i.e. a small tolerance such as 1e-15).
1040: By default, balancing is disabled. The two-sided method is much more
1041: effective than the one-sided counterpart, but it requires the system
1042: matrices to have the MatMultTranspose operation defined.
1044: The parameter 'its' is the number of iterations performed by the method. The
1045: cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
1046: a reasonably good value.
1048: User-defined balancing is allowed provided that the corresponding matrix
1049: is set via STSetBalanceMatrix.
1051: Level: intermediate
1053: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1054: @*/
1055: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1056: {
1061: switch (bal) {
1062: case EPS_BALANCE_NONE:
1063: case EPS_BALANCE_ONESIDE:
1064: case EPS_BALANCE_TWOSIDE:
1065: case EPS_BALANCE_USER:
1066: if (eps->balance != bal) {
1067: eps->state = EPS_STATE_INITIAL;
1068: eps->balance = bal;
1069: }
1070: break;
1071: default:
1072: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1073: }
1074: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1075: else {
1077: eps->balance_its = its;
1078: }
1079: if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1080: else {
1082: eps->balance_cutoff = cutoff;
1083: }
1084: return 0;
1085: }
1087: /*@C
1088: EPSGetBalance - Gets the balancing type used by the EPS object, and the
1089: associated parameters.
1091: Not Collective
1093: Input Parameter:
1094: . eps - the eigensolver context
1096: Output Parameters:
1097: + bal - the balancing method
1098: . its - number of iterations of the balancing algorithm
1099: - cutoff - cutoff value
1101: Level: intermediate
1103: Note:
1104: The user can specify NULL for any parameter that is not needed.
1106: .seealso: EPSSetBalance(), EPSBalance
1107: @*/
1108: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1109: {
1111: if (bal) *bal = eps->balance;
1112: if (its) *its = eps->balance_its;
1113: if (cutoff) *cutoff = eps->balance_cutoff;
1114: return 0;
1115: }
1117: /*@
1118: EPSSetTwoSided - Sets the solver to use a two-sided variant so that left
1119: eigenvectors are also computed.
1121: Logically Collective on eps
1123: Input Parameters:
1124: + eps - the eigensolver context
1125: - twosided - whether the two-sided variant is to be used or not
1127: Options Database Keys:
1128: . -eps_two_sided <boolean> - Sets/resets the twosided flag
1130: Notes:
1131: If the user sets twosided=PETSC_TRUE then the solver uses a variant of
1132: the algorithm that computes both right and left eigenvectors. This is
1133: usually much more costly. This option is not available in all solvers.
1135: When using two-sided solvers, the problem matrices must have both the
1136: MatMult and MatMultTranspose operations defined.
1138: Level: advanced
1140: .seealso: EPSGetTwoSided(), EPSGetLeftEigenvector()
1141: @*/
1142: PetscErrorCode EPSSetTwoSided(EPS eps,PetscBool twosided)
1143: {
1146: if (twosided!=eps->twosided) {
1147: eps->twosided = twosided;
1148: eps->state = EPS_STATE_INITIAL;
1149: }
1150: return 0;
1151: }
1153: /*@
1154: EPSGetTwoSided - Returns the flag indicating whether a two-sided variant
1155: of the algorithm is being used or not.
1157: Not Collective
1159: Input Parameter:
1160: . eps - the eigensolver context
1162: Output Parameter:
1163: . twosided - the returned flag
1165: Level: advanced
1167: .seealso: EPSSetTwoSided()
1168: @*/
1169: PetscErrorCode EPSGetTwoSided(EPS eps,PetscBool *twosided)
1170: {
1173: *twosided = eps->twosided;
1174: return 0;
1175: }
1177: /*@
1178: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1179: explicitly or not.
1181: Logically Collective on eps
1183: Input Parameters:
1184: + eps - the eigensolver context
1185: - trueres - whether true residuals are required or not
1187: Options Database Keys:
1188: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1190: Notes:
1191: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1192: the true residual for each eigenpair approximation, and uses it for
1193: convergence testing. Computing the residual is usually an expensive
1194: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1195: by using a cheap estimate of the residual norm, but this may sometimes
1196: give inaccurate results (especially if a spectral transform is being
1197: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1198: do rely on computing the true residual, so this option is irrelevant for them.
1200: Level: advanced
1202: .seealso: EPSGetTrueResidual()
1203: @*/
1204: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1205: {
1208: eps->trueres = trueres;
1209: return 0;
1210: }
1212: /*@
1213: EPSGetTrueResidual - Returns the flag indicating whether true
1214: residuals must be computed explicitly or not.
1216: Not Collective
1218: Input Parameter:
1219: . eps - the eigensolver context
1221: Output Parameter:
1222: . trueres - the returned flag
1224: Level: advanced
1226: .seealso: EPSSetTrueResidual()
1227: @*/
1228: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1229: {
1232: *trueres = eps->trueres;
1233: return 0;
1234: }
1236: /*@
1237: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1238: approximate eigenpairs or not.
1240: Logically Collective on eps
1242: Input Parameters:
1243: + eps - the eigensolver context
1244: - trackall - whether to compute all residuals or not
1246: Notes:
1247: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1248: the residual norm for each eigenpair approximation. Computing the residual is
1249: usually an expensive operation and solvers commonly compute only the residual
1250: associated to the first unconverged eigenpair.
1252: The option '-eps_monitor_all' automatically activates this option.
1254: Level: developer
1256: .seealso: EPSGetTrackAll()
1257: @*/
1258: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1259: {
1262: eps->trackall = trackall;
1263: return 0;
1264: }
1266: /*@
1267: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1268: be computed or not.
1270: Not Collective
1272: Input Parameter:
1273: . eps - the eigensolver context
1275: Output Parameter:
1276: . trackall - the returned flag
1278: Level: developer
1280: .seealso: EPSSetTrackAll()
1281: @*/
1282: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1283: {
1286: *trackall = eps->trackall;
1287: return 0;
1288: }
1290: /*@
1291: EPSSetPurify - Deactivate eigenvector purification (which is activated by default).
1293: Logically Collective on eps
1295: Input Parameters:
1296: + eps - the eigensolver context
1297: - purify - whether purification is required or not
1299: Options Database Keys:
1300: . -eps_purify <boolean> - Sets/resets the boolean flag 'purify'
1302: Notes:
1303: By default, eigenvectors of generalized symmetric eigenproblems are purified
1304: in order to purge directions in the nullspace of matrix B. If the user knows
1305: that B is non-singular, then purification can be safely deactivated and some
1306: computational cost is avoided (this is particularly important in interval computations).
1308: Level: intermediate
1310: .seealso: EPSGetPurify(), EPSSetInterval()
1311: @*/
1312: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1313: {
1316: if (purify!=eps->purify) {
1317: eps->purify = purify;
1318: eps->state = EPS_STATE_INITIAL;
1319: }
1320: return 0;
1321: }
1323: /*@
1324: EPSGetPurify - Returns the flag indicating whether purification is activated
1325: or not.
1327: Not Collective
1329: Input Parameter:
1330: . eps - the eigensolver context
1332: Output Parameter:
1333: . purify - the returned flag
1335: Level: intermediate
1337: .seealso: EPSSetPurify()
1338: @*/
1339: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1340: {
1343: *purify = eps->purify;
1344: return 0;
1345: }
1347: /*@C
1348: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1349: EPS options in the database.
1351: Logically Collective on eps
1353: Input Parameters:
1354: + eps - the eigensolver context
1355: - prefix - the prefix string to prepend to all EPS option requests
1357: Notes:
1358: A hyphen (-) must NOT be given at the beginning of the prefix name.
1359: The first character of all runtime options is AUTOMATICALLY the
1360: hyphen.
1362: For example, to distinguish between the runtime options for two
1363: different EPS contexts, one could call
1364: .vb
1365: EPSSetOptionsPrefix(eps1,"eig1_")
1366: EPSSetOptionsPrefix(eps2,"eig2_")
1367: .ve
1369: Level: advanced
1371: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1372: @*/
1373: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1374: {
1376: if (!eps->st) EPSGetST(eps,&eps->st);
1377: STSetOptionsPrefix(eps->st,prefix);
1378: if (!eps->V) EPSGetBV(eps,&eps->V);
1379: BVSetOptionsPrefix(eps->V,prefix);
1380: if (!eps->ds) EPSGetDS(eps,&eps->ds);
1381: DSSetOptionsPrefix(eps->ds,prefix);
1382: if (!eps->rg) EPSGetRG(eps,&eps->rg);
1383: RGSetOptionsPrefix(eps->rg,prefix);
1384: PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1385: return 0;
1386: }
1388: /*@C
1389: EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1390: EPS options in the database.
1392: Logically Collective on eps
1394: Input Parameters:
1395: + eps - the eigensolver context
1396: - prefix - the prefix string to prepend to all EPS option requests
1398: Notes:
1399: A hyphen (-) must NOT be given at the beginning of the prefix name.
1400: The first character of all runtime options is AUTOMATICALLY the hyphen.
1402: Level: advanced
1404: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1405: @*/
1406: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1407: {
1409: if (!eps->st) EPSGetST(eps,&eps->st);
1410: STAppendOptionsPrefix(eps->st,prefix);
1411: if (!eps->V) EPSGetBV(eps,&eps->V);
1412: BVAppendOptionsPrefix(eps->V,prefix);
1413: if (!eps->ds) EPSGetDS(eps,&eps->ds);
1414: DSAppendOptionsPrefix(eps->ds,prefix);
1415: if (!eps->rg) EPSGetRG(eps,&eps->rg);
1416: RGAppendOptionsPrefix(eps->rg,prefix);
1417: PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1418: return 0;
1419: }
1421: /*@C
1422: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1423: EPS options in the database.
1425: Not Collective
1427: Input Parameters:
1428: . eps - the eigensolver context
1430: Output Parameters:
1431: . prefix - pointer to the prefix string used is returned
1433: Note:
1434: On the Fortran side, the user should pass in a string 'prefix' of
1435: sufficient length to hold the prefix.
1437: Level: advanced
1439: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1440: @*/
1441: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1442: {
1445: PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1446: return 0;
1447: }