Actual source code: epsopts.c
slepc-3.17.2 2022-08-09
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) PetscFunctionReturn(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: PetscFunctionReturn(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: {
86: char type[256];
87: PetscBool set,flg,flg1,flg2,flg3,bval;
88: PetscReal r,array[2]={0,0};
89: PetscScalar s;
90: PetscInt i,j,k;
91: EPSBalance bal;
94: EPSRegisterAll();
95: ierr = PetscObjectOptionsBegin((PetscObject)eps);
96: PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,sizeof(type),&flg);
97: if (flg) EPSSetType(eps,type);
98: else if (!((PetscObject)eps)->type_name) EPSSetType(eps,EPSKRYLOVSCHUR);
100: PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg);
101: if (flg) EPSSetProblemType(eps,EPS_HEP);
102: PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg);
103: if (flg) EPSSetProblemType(eps,EPS_GHEP);
104: PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
105: if (flg) EPSSetProblemType(eps,EPS_NHEP);
106: PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
107: if (flg) EPSSetProblemType(eps,EPS_GNHEP);
108: PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
109: if (flg) EPSSetProblemType(eps,EPS_PGNHEP);
110: PetscOptionsBoolGroupEnd("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
111: if (flg) EPSSetProblemType(eps,EPS_GHIEP);
113: PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
114: if (flg) EPSSetExtraction(eps,EPS_RITZ);
115: PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg);
116: if (flg) EPSSetExtraction(eps,EPS_HARMONIC);
117: PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg);
118: if (flg) EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE);
119: PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg);
120: if (flg) EPSSetExtraction(eps,EPS_HARMONIC_RIGHT);
121: PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg);
122: if (flg) EPSSetExtraction(eps,EPS_HARMONIC_LARGEST);
123: PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg);
124: if (flg) EPSSetExtraction(eps,EPS_REFINED);
125: PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg);
126: if (flg) EPSSetExtraction(eps,EPS_REFINED_HARMONIC);
128: bal = eps->balance;
129: PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1);
130: j = eps->balance_its;
131: PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2);
132: r = eps->balance_cutoff;
133: PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3);
134: if (flg1 || flg2 || flg3) EPSSetBalance(eps,bal,j,r);
136: i = eps->max_it;
137: PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
138: r = eps->tol;
139: PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",SlepcDefaultTol(eps->tol),&r,&flg2);
140: if (flg1 || flg2) EPSSetTolerances(eps,r,i);
142: PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
143: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_REL);
144: PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
145: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_NORM);
146: PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
147: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_ABS);
148: PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
149: if (flg) EPSSetConvergenceTest(eps,EPS_CONV_USER);
151: PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg);
152: if (flg) EPSSetStoppingTest(eps,EPS_STOP_BASIC);
153: PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg);
154: if (flg) EPSSetStoppingTest(eps,EPS_STOP_USER);
156: i = eps->nev;
157: PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
158: j = eps->ncv;
159: PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
160: k = eps->mpd;
161: PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
162: if (flg1 || flg2 || flg3) EPSSetDimensions(eps,i,j,k);
164: PetscOptionsBoolGroupBegin("-eps_largest_magnitude","Compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
165: if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE);
166: PetscOptionsBoolGroup("-eps_smallest_magnitude","Compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
167: if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE);
168: PetscOptionsBoolGroup("-eps_largest_real","Compute eigenvalues with largest real parts","EPSSetWhichEigenpairs",&flg);
169: if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL);
170: PetscOptionsBoolGroup("-eps_smallest_real","Compute eigenvalues with smallest real parts","EPSSetWhichEigenpairs",&flg);
171: if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL);
172: PetscOptionsBoolGroup("-eps_largest_imaginary","Compute eigenvalues with largest imaginary parts","EPSSetWhichEigenpairs",&flg);
173: if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY);
174: PetscOptionsBoolGroup("-eps_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
175: if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY);
176: PetscOptionsBoolGroup("-eps_target_magnitude","Compute eigenvalues closest to target","EPSSetWhichEigenpairs",&flg);
177: if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
178: PetscOptionsBoolGroup("-eps_target_real","Compute eigenvalues with real parts closest to target","EPSSetWhichEigenpairs",&flg);
179: if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL);
180: PetscOptionsBoolGroup("-eps_target_imaginary","Compute eigenvalues with imaginary parts closest to target","EPSSetWhichEigenpairs",&flg);
181: if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY);
182: PetscOptionsBoolGroupEnd("-eps_all","Compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg);
183: if (flg) EPSSetWhichEigenpairs(eps,EPS_ALL);
185: PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
186: if (flg) {
187: if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
188: EPSSetTarget(eps,s);
189: }
191: k = 2;
192: PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
193: if (flg) {
195: EPSSetWhichEigenpairs(eps,EPS_ALL);
196: EPSSetInterval(eps,array[0],array[1]);
197: }
199: PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
200: PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&bval,&flg);
201: if (flg) EPSSetPurify(eps,bval);
202: PetscOptionsBool("-eps_two_sided","Use two-sided variant (to compute left eigenvectors)","EPSSetTwoSided",eps->twosided,&bval,&flg);
203: if (flg) EPSSetTwoSided(eps,bval);
205: /* -----------------------------------------------------------------------*/
206: /*
207: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
208: */
209: PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
210: if (set && flg) EPSMonitorCancel(eps);
211: EPSMonitorSetFromOptions(eps,"-eps_monitor","first_approximation",NULL,PETSC_FALSE);
212: EPSMonitorSetFromOptions(eps,"-eps_monitor_all","all_approximations",NULL,PETSC_TRUE);
213: EPSMonitorSetFromOptions(eps,"-eps_monitor_conv","convergence_history",NULL,PETSC_FALSE);
215: /* -----------------------------------------------------------------------*/
216: PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
217: PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
218: PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
219: PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSConvergedReasonView",NULL);
220: PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
221: PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
222: PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);
224: if (eps->ops->setfromoptions) (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
225: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)eps);
226: ierr = PetscOptionsEnd();
228: if (!eps->V) EPSGetBV(eps,&eps->V);
229: BVSetFromOptions(eps->V);
230: if (!eps->rg) EPSGetRG(eps,&eps->rg);
231: RGSetFromOptions(eps->rg);
232: if (eps->useds) {
233: if (!eps->ds) EPSGetDS(eps,&eps->ds);
234: DSSetFromOptions(eps->ds);
235: }
236: if (!eps->st) EPSGetST(eps,&eps->st);
237: EPSSetDefaultST(eps);
238: STSetFromOptions(eps->st);
239: PetscFunctionReturn(0);
240: }
242: /*@C
243: EPSGetTolerances - Gets the tolerance and maximum iteration count used
244: by the EPS convergence tests.
246: Not Collective
248: Input Parameter:
249: . eps - the eigensolver context
251: Output Parameters:
252: + tol - the convergence tolerance
253: - maxits - maximum number of iterations
255: Notes:
256: The user can specify NULL for any parameter that is not needed.
258: Level: intermediate
260: .seealso: EPSSetTolerances()
261: @*/
262: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
263: {
265: if (tol) *tol = eps->tol;
266: if (maxits) *maxits = eps->max_it;
267: PetscFunctionReturn(0);
268: }
270: /*@
271: EPSSetTolerances - Sets the tolerance and maximum iteration count used
272: by the EPS convergence tests.
274: Logically Collective on eps
276: Input Parameters:
277: + eps - the eigensolver context
278: . tol - the convergence tolerance
279: - maxits - maximum number of iterations to use
281: Options Database Keys:
282: + -eps_tol <tol> - Sets the convergence tolerance
283: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
285: Notes:
286: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
288: Level: intermediate
290: .seealso: EPSGetTolerances()
291: @*/
292: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
293: {
297: if (tol == PETSC_DEFAULT) {
298: eps->tol = PETSC_DEFAULT;
299: eps->state = EPS_STATE_INITIAL;
300: } else {
302: eps->tol = tol;
303: }
304: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
305: eps->max_it = PETSC_DEFAULT;
306: eps->state = EPS_STATE_INITIAL;
307: } else {
309: eps->max_it = maxits;
310: }
311: PetscFunctionReturn(0);
312: }
314: /*@C
315: EPSGetDimensions - Gets the number of eigenvalues to compute
316: and the dimension of the subspace.
318: Not Collective
320: Input Parameter:
321: . eps - the eigensolver context
323: Output Parameters:
324: + nev - number of eigenvalues to compute
325: . ncv - the maximum dimension of the subspace to be used by the solver
326: - mpd - the maximum dimension allowed for the projected problem
328: Level: intermediate
330: .seealso: EPSSetDimensions()
331: @*/
332: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
333: {
335: if (nev) *nev = eps->nev;
336: if (ncv) *ncv = eps->ncv;
337: if (mpd) *mpd = eps->mpd;
338: PetscFunctionReturn(0);
339: }
341: /*@
342: EPSSetDimensions - Sets the number of eigenvalues to compute
343: and the dimension of the subspace.
345: Logically Collective on eps
347: Input Parameters:
348: + eps - the eigensolver context
349: . nev - number of eigenvalues to compute
350: . ncv - the maximum dimension of the subspace to be used by the solver
351: - mpd - the maximum dimension allowed for the projected problem
353: Options Database Keys:
354: + -eps_nev <nev> - Sets the number of eigenvalues
355: . -eps_ncv <ncv> - Sets the dimension of the subspace
356: - -eps_mpd <mpd> - Sets the maximum projected dimension
358: Notes:
359: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
360: dependent on the solution method.
362: The parameters ncv and mpd are intimately related, so that the user is advised
363: to set one of them at most. Normal usage is that
364: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
365: (b) in cases where nev is large, the user sets mpd.
367: The value of ncv should always be between nev and (nev+mpd), typically
368: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
369: a smaller value should be used.
371: When computing all eigenvalues in an interval, see EPSSetInterval(), these
372: parameters lose relevance, and tuning must be done with
373: EPSKrylovSchurSetDimensions().
375: Level: intermediate
377: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
378: @*/
379: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
380: {
386: eps->nev = nev;
387: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
388: eps->ncv = PETSC_DEFAULT;
389: } else {
391: eps->ncv = ncv;
392: }
393: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
394: eps->mpd = PETSC_DEFAULT;
395: } else {
397: eps->mpd = mpd;
398: }
399: eps->state = EPS_STATE_INITIAL;
400: PetscFunctionReturn(0);
401: }
403: /*@
404: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
405: to be sought.
407: Logically Collective on eps
409: Input Parameters:
410: + eps - eigensolver context obtained from EPSCreate()
411: - which - the portion of the spectrum to be sought
413: Possible values:
414: The parameter 'which' can have one of these values
416: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
417: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
418: . EPS_LARGEST_REAL - largest real parts
419: . EPS_SMALLEST_REAL - smallest real parts
420: . EPS_LARGEST_IMAGINARY - largest imaginary parts
421: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
422: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
423: . EPS_TARGET_REAL - eigenvalues with real part closest to target
424: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
425: . EPS_ALL - all eigenvalues contained in a given interval or region
426: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
428: Options Database Keys:
429: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
430: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
431: . -eps_largest_real - Sets largest real parts
432: . -eps_smallest_real - Sets smallest real parts
433: . -eps_largest_imaginary - Sets largest imaginary parts
434: . -eps_smallest_imaginary - Sets smallest imaginary parts
435: . -eps_target_magnitude - Sets eigenvalues closest to target
436: . -eps_target_real - Sets real parts closest to target
437: . -eps_target_imaginary - Sets imaginary parts closest to target
438: - -eps_all - Sets all eigenvalues in an interval or region
440: Notes:
441: Not all eigensolvers implemented in EPS account for all the possible values
442: stated above. Also, some values make sense only for certain types of
443: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
444: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
445: for eigenvalue selection.
447: The target is a scalar value provided with EPSSetTarget().
449: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
450: SLEPc have been built with complex scalars.
452: EPS_ALL is intended for use in combination with an interval (see
453: EPSSetInterval()), when all eigenvalues within the interval are requested,
454: or in the context of the CISS solver for computing all eigenvalues in a region.
455: In those cases, the number of eigenvalues is unknown, so the nev parameter
456: has a different sense, see EPSSetDimensions().
458: Level: intermediate
460: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
461: EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
462: @*/
463: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
464: {
467: switch (which) {
468: case EPS_LARGEST_MAGNITUDE:
469: case EPS_SMALLEST_MAGNITUDE:
470: case EPS_LARGEST_REAL:
471: case EPS_SMALLEST_REAL:
472: case EPS_LARGEST_IMAGINARY:
473: case EPS_SMALLEST_IMAGINARY:
474: case EPS_TARGET_MAGNITUDE:
475: case EPS_TARGET_REAL:
476: #if defined(PETSC_USE_COMPLEX)
477: case EPS_TARGET_IMAGINARY:
478: #endif
479: case EPS_ALL:
480: case EPS_WHICH_USER:
481: if (eps->which != which) {
482: eps->state = EPS_STATE_INITIAL;
483: eps->which = which;
484: }
485: break;
486: #if !defined(PETSC_USE_COMPLEX)
487: case EPS_TARGET_IMAGINARY:
488: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"EPS_TARGET_IMAGINARY can be used only with complex scalars");
489: #endif
490: default:
491: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
492: }
493: PetscFunctionReturn(0);
494: }
496: /*@
497: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
498: sought.
500: Not Collective
502: Input Parameter:
503: . eps - eigensolver context obtained from EPSCreate()
505: Output Parameter:
506: . which - the portion of the spectrum to be sought
508: Notes:
509: See EPSSetWhichEigenpairs() for possible values of 'which'.
511: Level: intermediate
513: .seealso: EPSSetWhichEigenpairs(), EPSWhich
514: @*/
515: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
516: {
519: *which = eps->which;
520: PetscFunctionReturn(0);
521: }
523: /*@C
524: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
525: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
527: Logically Collective on eps
529: Input Parameters:
530: + eps - eigensolver context obtained from EPSCreate()
531: . func - a pointer to the comparison function
532: - ctx - a context pointer (the last parameter to the comparison function)
534: Calling Sequence of func:
535: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
537: + ar - real part of the 1st eigenvalue
538: . ai - imaginary part of the 1st eigenvalue
539: . br - real part of the 2nd eigenvalue
540: . bi - imaginary part of the 2nd eigenvalue
541: . res - result of comparison
542: - ctx - optional context, as set by EPSSetEigenvalueComparison()
544: Note:
545: The returning parameter 'res' can be
546: + negative - if the 1st eigenvalue is preferred to the 2st one
547: . zero - if both eigenvalues are equally preferred
548: - positive - if the 2st eigenvalue is preferred to the 1st one
550: Level: advanced
552: .seealso: EPSSetWhichEigenpairs(), EPSWhich
553: @*/
554: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
555: {
557: eps->sc->comparison = func;
558: eps->sc->comparisonctx = ctx;
559: eps->which = EPS_WHICH_USER;
560: PetscFunctionReturn(0);
561: }
563: /*@C
564: EPSSetArbitrarySelection - Specifies a function intended to look for
565: eigenvalues according to an arbitrary selection criterion. This criterion
566: can be based on a computation involving the current eigenvector approximation.
568: Logically Collective on eps
570: Input Parameters:
571: + eps - eigensolver context obtained from EPSCreate()
572: . func - a pointer to the evaluation function
573: - ctx - a context pointer (the last parameter to the evaluation function)
575: Calling Sequence of func:
576: $ func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
578: + er - real part of the current eigenvalue approximation
579: . ei - imaginary part of the current eigenvalue approximation
580: . xr - real part of the current eigenvector approximation
581: . xi - imaginary part of the current eigenvector approximation
582: . rr - result of evaluation (real part)
583: . ri - result of evaluation (imaginary part)
584: - ctx - optional context, as set by EPSSetArbitrarySelection()
586: Notes:
587: This provides a mechanism to select eigenpairs by evaluating a user-defined
588: function. When a function has been provided, the default selection based on
589: sorting the eigenvalues is replaced by the sorting of the results of this
590: function (with the same sorting criterion given in EPSSetWhichEigenpairs()).
592: For instance, suppose you want to compute those eigenvectors that maximize
593: a certain computable expression. Then implement the computation using
594: the arguments xr and xi, and return the result in rr. Then set the standard
595: sorting by magnitude so that the eigenpair with largest value of rr is
596: selected.
598: This evaluation function is collective, that is, all processes call it and
599: it can use collective operations; furthermore, the computed result must
600: be the same in all processes.
602: The result of func is expressed as a complex number so that it is possible to
603: use the standard eigenvalue sorting functions, but normally only rr is used.
604: Set ri to zero unless it is meaningful in your application.
606: Level: advanced
608: .seealso: EPSSetWhichEigenpairs()
609: @*/
610: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
611: {
613: eps->arbitrary = func;
614: eps->arbitraryctx = ctx;
615: eps->state = EPS_STATE_INITIAL;
616: PetscFunctionReturn(0);
617: }
619: /*@C
620: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
621: used in the convergence test.
623: Logically Collective on eps
625: Input Parameters:
626: + eps - eigensolver context obtained from EPSCreate()
627: . func - a pointer to the convergence test function
628: . ctx - context for private data for the convergence routine (may be null)
629: - destroy - a routine for destroying the context (may be null)
631: Calling Sequence of func:
632: $ func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
634: + eps - eigensolver context obtained from EPSCreate()
635: . eigr - real part of the eigenvalue
636: . eigi - imaginary part of the eigenvalue
637: . res - residual norm associated to the eigenpair
638: . errest - (output) computed error estimate
639: - ctx - optional context, as set by EPSSetConvergenceTestFunction()
641: Note:
642: If the error estimate returned by the convergence test function is less than
643: the tolerance, then the eigenvalue is accepted as converged.
645: Level: advanced
647: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
648: @*/
649: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
650: {
652: if (eps->convergeddestroy) (*eps->convergeddestroy)(eps->convergedctx);
653: eps->convergeduser = func;
654: eps->convergeddestroy = destroy;
655: eps->convergedctx = ctx;
656: if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
657: else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
658: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
659: else {
660: eps->conv = EPS_CONV_USER;
661: eps->converged = eps->convergeduser;
662: }
663: PetscFunctionReturn(0);
664: }
666: /*@
667: EPSSetConvergenceTest - Specifies how to compute the error estimate
668: used in the convergence test.
670: Logically Collective on eps
672: Input Parameters:
673: + eps - eigensolver context obtained from EPSCreate()
674: - conv - the type of convergence test
676: Options Database Keys:
677: + -eps_conv_abs - Sets the absolute convergence test
678: . -eps_conv_rel - Sets the convergence test relative to the eigenvalue
679: . -eps_conv_norm - Sets the convergence test relative to the matrix norms
680: - -eps_conv_user - Selects the user-defined convergence test
682: Note:
683: The parameter 'conv' can have one of these values
684: + EPS_CONV_ABS - absolute error ||r||
685: . EPS_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
686: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
687: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
689: Level: intermediate
691: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
692: @*/
693: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
694: {
697: switch (conv) {
698: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
699: case EPS_CONV_REL: eps->converged = EPSConvergedRelative; break;
700: case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
701: case EPS_CONV_USER:
703: eps->converged = eps->convergeduser;
704: break;
705: default:
706: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
707: }
708: eps->conv = conv;
709: PetscFunctionReturn(0);
710: }
712: /*@
713: EPSGetConvergenceTest - Gets the method used to compute the error estimate
714: used in the convergence test.
716: Not Collective
718: Input Parameters:
719: . eps - eigensolver context obtained from EPSCreate()
721: Output Parameters:
722: . conv - the type of convergence test
724: Level: intermediate
726: .seealso: EPSSetConvergenceTest(), EPSConv
727: @*/
728: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
729: {
732: *conv = eps->conv;
733: PetscFunctionReturn(0);
734: }
736: /*@C
737: EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
738: iteration of the eigensolver.
740: Logically Collective on eps
742: Input Parameters:
743: + eps - eigensolver context obtained from EPSCreate()
744: . func - pointer to the stopping test function
745: . ctx - context for private data for the stopping routine (may be null)
746: - destroy - a routine for destroying the context (may be null)
748: Calling Sequence of func:
749: $ func(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx)
751: + eps - eigensolver context obtained from EPSCreate()
752: . its - current number of iterations
753: . max_it - maximum number of iterations
754: . nconv - number of currently converged eigenpairs
755: . nev - number of requested eigenpairs
756: . reason - (output) result of the stopping test
757: - ctx - optional context, as set by EPSSetStoppingTestFunction()
759: Note:
760: Normal usage is to first call the default routine EPSStoppingBasic() and then
761: set reason to EPS_CONVERGED_USER if some user-defined conditions have been
762: met. To let the eigensolver continue iterating, the result must be left as
763: EPS_CONVERGED_ITERATING.
765: Level: advanced
767: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
768: @*/
769: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
770: {
772: if (eps->stoppingdestroy) (*eps->stoppingdestroy)(eps->stoppingctx);
773: eps->stoppinguser = func;
774: eps->stoppingdestroy = destroy;
775: eps->stoppingctx = ctx;
776: if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
777: else {
778: eps->stop = EPS_STOP_USER;
779: eps->stopping = eps->stoppinguser;
780: }
781: PetscFunctionReturn(0);
782: }
784: /*@
785: EPSSetStoppingTest - Specifies how to decide the termination of the outer
786: loop of the eigensolver.
788: Logically Collective on eps
790: Input Parameters:
791: + eps - eigensolver context obtained from EPSCreate()
792: - stop - the type of stopping test
794: Options Database Keys:
795: + -eps_stop_basic - Sets the default stopping test
796: - -eps_stop_user - Selects the user-defined stopping test
798: Note:
799: The parameter 'stop' can have one of these values
800: + EPS_STOP_BASIC - default stopping test
801: - EPS_STOP_USER - function set by EPSSetStoppingTestFunction()
803: Level: advanced
805: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
806: @*/
807: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
808: {
811: switch (stop) {
812: case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
813: case EPS_STOP_USER:
815: eps->stopping = eps->stoppinguser;
816: break;
817: default:
818: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
819: }
820: eps->stop = stop;
821: PetscFunctionReturn(0);
822: }
824: /*@
825: EPSGetStoppingTest - Gets the method used to decide the termination of the outer
826: loop of the eigensolver.
828: Not Collective
830: Input Parameters:
831: . eps - eigensolver context obtained from EPSCreate()
833: Output Parameters:
834: . stop - the type of stopping test
836: Level: advanced
838: .seealso: EPSSetStoppingTest(), EPSStop
839: @*/
840: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
841: {
844: *stop = eps->stop;
845: PetscFunctionReturn(0);
846: }
848: /*@
849: EPSSetProblemType - Specifies the type of the eigenvalue problem.
851: Logically Collective on eps
853: Input Parameters:
854: + eps - the eigensolver context
855: - type - a known type of eigenvalue problem
857: Options Database Keys:
858: + -eps_hermitian - Hermitian eigenvalue problem
859: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
860: . -eps_non_hermitian - non-Hermitian eigenvalue problem
861: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
862: . -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
863: with positive semi-definite B
864: - -eps_gen_indefinite - generalized Hermitian-indefinite eigenvalue problem
866: Notes:
867: Allowed values for the problem type are Hermitian (EPS_HEP), non-Hermitian
868: (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
869: (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
870: (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).
872: This function must be used to instruct SLEPc to exploit symmetry. If no
873: problem type is specified, by default a non-Hermitian problem is assumed
874: (either standard or generalized). If the user knows that the problem is
875: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
876: B positive definite) then it is recommended to set the problem type so
877: that eigensolver can exploit these properties.
879: Level: intermediate
881: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
882: @*/
883: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
884: {
887: if (type == eps->problem_type) PetscFunctionReturn(0);
888: switch (type) {
889: case EPS_HEP:
890: eps->isgeneralized = PETSC_FALSE;
891: eps->ishermitian = PETSC_TRUE;
892: eps->ispositive = PETSC_FALSE;
893: break;
894: case EPS_NHEP:
895: eps->isgeneralized = PETSC_FALSE;
896: eps->ishermitian = PETSC_FALSE;
897: eps->ispositive = PETSC_FALSE;
898: break;
899: case EPS_GHEP:
900: eps->isgeneralized = PETSC_TRUE;
901: eps->ishermitian = PETSC_TRUE;
902: eps->ispositive = PETSC_TRUE;
903: break;
904: case EPS_GNHEP:
905: eps->isgeneralized = PETSC_TRUE;
906: eps->ishermitian = PETSC_FALSE;
907: eps->ispositive = PETSC_FALSE;
908: break;
909: case EPS_PGNHEP:
910: eps->isgeneralized = PETSC_TRUE;
911: eps->ishermitian = PETSC_FALSE;
912: eps->ispositive = PETSC_TRUE;
913: break;
914: case EPS_GHIEP:
915: eps->isgeneralized = PETSC_TRUE;
916: eps->ishermitian = PETSC_TRUE;
917: eps->ispositive = PETSC_FALSE;
918: break;
919: default:
920: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
921: }
922: eps->problem_type = type;
923: eps->state = EPS_STATE_INITIAL;
924: PetscFunctionReturn(0);
925: }
927: /*@
928: EPSGetProblemType - Gets the problem type from the EPS object.
930: Not Collective
932: Input Parameter:
933: . eps - the eigensolver context
935: Output Parameter:
936: . type - the problem type
938: Level: intermediate
940: .seealso: EPSSetProblemType(), EPSProblemType
941: @*/
942: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
943: {
946: *type = eps->problem_type;
947: PetscFunctionReturn(0);
948: }
950: /*@
951: EPSSetExtraction - Specifies the type of extraction technique to be employed
952: by the eigensolver.
954: Logically Collective on eps
956: Input Parameters:
957: + eps - the eigensolver context
958: - extr - a known type of extraction
960: Options Database Keys:
961: + -eps_ritz - Rayleigh-Ritz extraction
962: . -eps_harmonic - harmonic Ritz extraction
963: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
964: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
965: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
966: (without target)
967: . -eps_refined - refined Ritz extraction
968: - -eps_refined_harmonic - refined harmonic Ritz extraction
970: Notes:
971: Not all eigensolvers support all types of extraction. See the SLEPc
972: Users Manual for details.
974: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
975: may be useful when computing interior eigenvalues.
977: Harmonic-type extractions are used in combination with a 'target'.
979: Level: advanced
981: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
982: @*/
983: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
984: {
987: eps->extraction = extr;
988: PetscFunctionReturn(0);
989: }
991: /*@
992: EPSGetExtraction - Gets the extraction type used by the EPS object.
994: Not Collective
996: Input Parameter:
997: . eps - the eigensolver context
999: Output Parameter:
1000: . extr - name of extraction type
1002: Level: advanced
1004: .seealso: EPSSetExtraction(), EPSExtraction
1005: @*/
1006: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1007: {
1010: *extr = eps->extraction;
1011: PetscFunctionReturn(0);
1012: }
1014: /*@
1015: EPSSetBalance - Specifies the balancing technique to be employed by the
1016: eigensolver, and some parameters associated to it.
1018: Logically Collective on eps
1020: Input Parameters:
1021: + eps - the eigensolver context
1022: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1023: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1024: . its - number of iterations of the balancing algorithm
1025: - cutoff - cutoff value
1027: Options Database Keys:
1028: + -eps_balance <method> - the balancing method, where <method> is one of
1029: 'none', 'oneside', 'twoside', or 'user'
1030: . -eps_balance_its <its> - number of iterations
1031: - -eps_balance_cutoff <cutoff> - cutoff value
1033: Notes:
1034: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1035: where D is an appropriate diagonal matrix. This improves the accuracy of
1036: the computed results in some cases. See the SLEPc Users Manual for details.
1038: Balancing makes sense only for non-Hermitian problems when the required
1039: precision is high (i.e. a small tolerance such as 1e-15).
1041: By default, balancing is disabled. The two-sided method is much more
1042: effective than the one-sided counterpart, but it requires the system
1043: matrices to have the MatMultTranspose operation defined.
1045: The parameter 'its' is the number of iterations performed by the method. The
1046: cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
1047: a reasonably good value.
1049: User-defined balancing is allowed provided that the corresponding matrix
1050: is set via STSetBalanceMatrix.
1052: Level: intermediate
1054: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1055: @*/
1056: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1057: {
1062: switch (bal) {
1063: case EPS_BALANCE_NONE:
1064: case EPS_BALANCE_ONESIDE:
1065: case EPS_BALANCE_TWOSIDE:
1066: case EPS_BALANCE_USER:
1067: if (eps->balance != bal) {
1068: eps->state = EPS_STATE_INITIAL;
1069: eps->balance = bal;
1070: }
1071: break;
1072: default:
1073: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1074: }
1075: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1076: else {
1078: eps->balance_its = its;
1079: }
1080: if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1081: else {
1083: eps->balance_cutoff = cutoff;
1084: }
1085: PetscFunctionReturn(0);
1086: }
1088: /*@C
1089: EPSGetBalance - Gets the balancing type used by the EPS object, and the
1090: associated parameters.
1092: Not Collective
1094: Input Parameter:
1095: . eps - the eigensolver context
1097: Output Parameters:
1098: + bal - the balancing method
1099: . its - number of iterations of the balancing algorithm
1100: - cutoff - cutoff value
1102: Level: intermediate
1104: Note:
1105: The user can specify NULL for any parameter that is not needed.
1107: .seealso: EPSSetBalance(), EPSBalance
1108: @*/
1109: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1110: {
1112: if (bal) *bal = eps->balance;
1113: if (its) *its = eps->balance_its;
1114: if (cutoff) *cutoff = eps->balance_cutoff;
1115: PetscFunctionReturn(0);
1116: }
1118: /*@
1119: EPSSetTwoSided - Sets the solver to use a two-sided variant so that left
1120: eigenvectors are also computed.
1122: Logically Collective on eps
1124: Input Parameters:
1125: + eps - the eigensolver context
1126: - twosided - whether the two-sided variant is to be used or not
1128: Options Database Keys:
1129: . -eps_two_sided <boolean> - Sets/resets the twosided flag
1131: Notes:
1132: If the user sets twosided=PETSC_TRUE then the solver uses a variant of
1133: the algorithm that computes both right and left eigenvectors. This is
1134: usually much more costly. This option is not available in all solvers.
1136: When using two-sided solvers, the problem matrices must have both the
1137: MatMult and MatMultTranspose operations defined.
1139: Level: advanced
1141: .seealso: EPSGetTwoSided(), EPSGetLeftEigenvector()
1142: @*/
1143: PetscErrorCode EPSSetTwoSided(EPS eps,PetscBool twosided)
1144: {
1147: if (twosided!=eps->twosided) {
1148: eps->twosided = twosided;
1149: eps->state = EPS_STATE_INITIAL;
1150: }
1151: PetscFunctionReturn(0);
1152: }
1154: /*@
1155: EPSGetTwoSided - Returns the flag indicating whether a two-sided variant
1156: of the algorithm is being used or not.
1158: Not Collective
1160: Input Parameter:
1161: . eps - the eigensolver context
1163: Output Parameter:
1164: . twosided - the returned flag
1166: Level: advanced
1168: .seealso: EPSSetTwoSided()
1169: @*/
1170: PetscErrorCode EPSGetTwoSided(EPS eps,PetscBool *twosided)
1171: {
1174: *twosided = eps->twosided;
1175: PetscFunctionReturn(0);
1176: }
1178: /*@
1179: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1180: explicitly or not.
1182: Logically Collective on eps
1184: Input Parameters:
1185: + eps - the eigensolver context
1186: - trueres - whether true residuals are required or not
1188: Options Database Keys:
1189: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1191: Notes:
1192: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1193: the true residual for each eigenpair approximation, and uses it for
1194: convergence testing. Computing the residual is usually an expensive
1195: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1196: by using a cheap estimate of the residual norm, but this may sometimes
1197: give inaccurate results (especially if a spectral transform is being
1198: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1199: do rely on computing the true residual, so this option is irrelevant for them.
1201: Level: advanced
1203: .seealso: EPSGetTrueResidual()
1204: @*/
1205: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1206: {
1209: eps->trueres = trueres;
1210: PetscFunctionReturn(0);
1211: }
1213: /*@
1214: EPSGetTrueResidual - Returns the flag indicating whether true
1215: residuals must be computed explicitly or not.
1217: Not Collective
1219: Input Parameter:
1220: . eps - the eigensolver context
1222: Output Parameter:
1223: . trueres - the returned flag
1225: Level: advanced
1227: .seealso: EPSSetTrueResidual()
1228: @*/
1229: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1230: {
1233: *trueres = eps->trueres;
1234: PetscFunctionReturn(0);
1235: }
1237: /*@
1238: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1239: approximate eigenpairs or not.
1241: Logically Collective on eps
1243: Input Parameters:
1244: + eps - the eigensolver context
1245: - trackall - whether to compute all residuals or not
1247: Notes:
1248: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1249: the residual norm for each eigenpair approximation. Computing the residual is
1250: usually an expensive operation and solvers commonly compute only the residual
1251: associated to the first unconverged eigenpair.
1253: The option '-eps_monitor_all' automatically activates this option.
1255: Level: developer
1257: .seealso: EPSGetTrackAll()
1258: @*/
1259: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1260: {
1263: eps->trackall = trackall;
1264: PetscFunctionReturn(0);
1265: }
1267: /*@
1268: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1269: be computed or not.
1271: Not Collective
1273: Input Parameter:
1274: . eps - the eigensolver context
1276: Output Parameter:
1277: . trackall - the returned flag
1279: Level: developer
1281: .seealso: EPSSetTrackAll()
1282: @*/
1283: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1284: {
1287: *trackall = eps->trackall;
1288: PetscFunctionReturn(0);
1289: }
1291: /*@
1292: EPSSetPurify - Deactivate eigenvector purification (which is activated by default).
1294: Logically Collective on eps
1296: Input Parameters:
1297: + eps - the eigensolver context
1298: - purify - whether purification is required or not
1300: Options Database Keys:
1301: . -eps_purify <boolean> - Sets/resets the boolean flag 'purify'
1303: Notes:
1304: By default, eigenvectors of generalized symmetric eigenproblems are purified
1305: in order to purge directions in the nullspace of matrix B. If the user knows
1306: that B is non-singular, then purification can be safely deactivated and some
1307: computational cost is avoided (this is particularly important in interval computations).
1309: Level: intermediate
1311: .seealso: EPSGetPurify(), EPSSetInterval()
1312: @*/
1313: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1314: {
1317: if (purify!=eps->purify) {
1318: eps->purify = purify;
1319: eps->state = EPS_STATE_INITIAL;
1320: }
1321: PetscFunctionReturn(0);
1322: }
1324: /*@
1325: EPSGetPurify - Returns the flag indicating whether purification is activated
1326: or not.
1328: Not Collective
1330: Input Parameter:
1331: . eps - the eigensolver context
1333: Output Parameter:
1334: . purify - the returned flag
1336: Level: intermediate
1338: .seealso: EPSSetPurify()
1339: @*/
1340: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1341: {
1344: *purify = eps->purify;
1345: PetscFunctionReturn(0);
1346: }
1348: /*@C
1349: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1350: EPS options in the database.
1352: Logically Collective on eps
1354: Input Parameters:
1355: + eps - the eigensolver context
1356: - prefix - the prefix string to prepend to all EPS option requests
1358: Notes:
1359: A hyphen (-) must NOT be given at the beginning of the prefix name.
1360: The first character of all runtime options is AUTOMATICALLY the
1361: hyphen.
1363: For example, to distinguish between the runtime options for two
1364: different EPS contexts, one could call
1365: .vb
1366: EPSSetOptionsPrefix(eps1,"eig1_")
1367: EPSSetOptionsPrefix(eps2,"eig2_")
1368: .ve
1370: Level: advanced
1372: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1373: @*/
1374: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1375: {
1377: if (!eps->st) EPSGetST(eps,&eps->st);
1378: STSetOptionsPrefix(eps->st,prefix);
1379: if (!eps->V) EPSGetBV(eps,&eps->V);
1380: BVSetOptionsPrefix(eps->V,prefix);
1381: if (!eps->ds) EPSGetDS(eps,&eps->ds);
1382: DSSetOptionsPrefix(eps->ds,prefix);
1383: if (!eps->rg) EPSGetRG(eps,&eps->rg);
1384: RGSetOptionsPrefix(eps->rg,prefix);
1385: PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1386: PetscFunctionReturn(0);
1387: }
1389: /*@C
1390: EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1391: EPS options in the database.
1393: Logically Collective on eps
1395: Input Parameters:
1396: + eps - the eigensolver context
1397: - prefix - the prefix string to prepend to all EPS option requests
1399: Notes:
1400: A hyphen (-) must NOT be given at the beginning of the prefix name.
1401: The first character of all runtime options is AUTOMATICALLY the hyphen.
1403: Level: advanced
1405: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1406: @*/
1407: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1408: {
1410: if (!eps->st) EPSGetST(eps,&eps->st);
1411: STAppendOptionsPrefix(eps->st,prefix);
1412: if (!eps->V) EPSGetBV(eps,&eps->V);
1413: BVAppendOptionsPrefix(eps->V,prefix);
1414: if (!eps->ds) EPSGetDS(eps,&eps->ds);
1415: DSAppendOptionsPrefix(eps->ds,prefix);
1416: if (!eps->rg) EPSGetRG(eps,&eps->rg);
1417: RGAppendOptionsPrefix(eps->rg,prefix);
1418: PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1419: PetscFunctionReturn(0);
1420: }
1422: /*@C
1423: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1424: EPS options in the database.
1426: Not Collective
1428: Input Parameters:
1429: . eps - the eigensolver context
1431: Output Parameters:
1432: . prefix - pointer to the prefix string used is returned
1434: Note:
1435: On the Fortran side, the user should pass in a string 'prefix' of
1436: sufficient length to hold the prefix.
1438: Level: advanced
1440: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1441: @*/
1442: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1443: {
1446: PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1447: PetscFunctionReturn(0);
1448: }