Actual source code: opts.c
1: /*
2: EPS routines related to options that can be set via the command-line
3: or procedurally.
5: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6: SLEPc - Scalable Library for Eigenvalue Problem Computations
7: Copyright (c) 2002-2013, Universitat Politecnica de Valencia, Spain
9: This file is part of SLEPc.
11: SLEPc is free software: you can redistribute it and/or modify it under the
12: terms of version 3 of the GNU Lesser General Public License as published by
13: the Free Software Foundation.
15: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
16: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
18: more details.
20: You should have received a copy of the GNU Lesser General Public License
21: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
22: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
23: */
25: #include <slepc-private/epsimpl.h> /*I "slepceps.h" I*/
29: /*@
30: EPSSetFromOptions - Sets EPS options from the options database.
31: This routine must be called before EPSSetUp() if the user is to be
32: allowed to set the solver type.
34: Collective on EPS
36: Input Parameters:
37: . eps - the eigensolver context
39: Notes:
40: To see all options, run your program with the -help option.
42: Level: beginner
43: @*/
44: PetscErrorCode EPSSetFromOptions(EPS eps)
45: {
46: PetscErrorCode ierr;
47: char type[256],monfilename[PETSC_MAX_PATH_LEN];
48: PetscBool flg,val;
49: PetscReal r,nrma,nrmb,array[2]={0,0};
50: PetscScalar s;
51: PetscInt i,j,k;
52: const char *bal_list[4] = {"none","oneside","twoside","user"};
53: PetscViewer monviewer;
54: SlepcConvMonitor ctx;
58: if (!EPSRegisterAllCalled) { EPSRegisterAll(); }
59: PetscObjectOptionsBegin((PetscObject)eps);
60: PetscOptionsList("-eps_type","Eigenvalue Problem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
61: if (flg) {
62: EPSSetType(eps,type);
63: }
64: /*
65: Set the type if it was never set.
66: */
67: if (!((PetscObject)eps)->type_name) {
68: EPSSetType(eps,EPSKRYLOVSCHUR);
69: }
71: PetscOptionsBoolGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);
72: if (flg) { EPSSetProblemType(eps,EPS_HEP); }
73: PetscOptionsBoolGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);
74: if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
75: PetscOptionsBoolGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
76: if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
77: PetscOptionsBoolGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
78: if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
79: PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
80: if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
81: PetscOptionsBoolGroupEnd("-eps_gen_indefinite","generalized hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
82: if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }
84: PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
85: if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
86: PetscOptionsBoolGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);
87: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
88: PetscOptionsBoolGroup("-eps_harmonic_relative","relative harmonic Ritz extraction","EPSSetExtraction",&flg);
89: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
90: PetscOptionsBoolGroup("-eps_harmonic_right","right harmonic Ritz extraction","EPSSetExtraction",&flg);
91: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
92: PetscOptionsBoolGroup("-eps_harmonic_largest","largest harmonic Ritz extraction","EPSSetExtraction",&flg);
93: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
94: PetscOptionsBoolGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);
95: if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
96: PetscOptionsBoolGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);
97: if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }
99: if (!eps->balance) eps->balance = EPS_BALANCE_NONE;
100: PetscOptionsEList("-eps_balance","Balancing method","EPSSetBalance",bal_list,4,bal_list[eps->balance-EPS_BALANCE_NONE],&i,&flg);
101: if (flg) eps->balance = (EPSBalance)(i+EPS_BALANCE_NONE);
102: r = j = 0;
103: PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,NULL);
104: PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,NULL);
105: EPSSetBalance(eps,(EPSBalance)0,j,r);
107: r = i = 0;
108: PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,NULL);
109: PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,NULL);
110: EPSSetTolerances(eps,r,i);
111: PetscOptionsBoolGroupBegin("-eps_conv_eig","Relative error convergence test","EPSSetConvergenceTest",&flg);
112: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_EIG); }
113: PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
114: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
115: PetscOptionsBoolGroupEnd("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
116: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
118: i = j = k = 0;
119: PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,NULL);
120: PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,NULL);
121: PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,NULL);
122: EPSSetDimensions(eps,i,j,k);
124: /* -----------------------------------------------------------------------*/
125: /*
126: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
127: */
128: flg = PETSC_FALSE;
129: PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",flg,&flg,NULL);
130: if (flg) {
131: EPSMonitorCancel(eps);
132: }
133: /*
134: Prints approximate eigenvalues and error estimates at each iteration
135: */
136: PetscOptionsString("-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
137: if (flg) {
138: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
139: EPSMonitorSet(eps,EPSMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
140: }
141: PetscOptionsString("-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
142: if (flg) {
143: PetscNew(struct _n_SlepcConvMonitor,&ctx);
144: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&ctx->viewer);
145: EPSMonitorSet(eps,EPSMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
146: }
147: PetscOptionsString("-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
148: if (flg) {
149: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
150: EPSMonitorSet(eps,EPSMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
151: EPSSetTrackAll(eps,PETSC_TRUE);
152: }
153: flg = PETSC_FALSE;
154: PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",flg,&flg,NULL);
155: if (flg) {
156: EPSMonitorSet(eps,EPSMonitorLG,NULL,NULL);
157: }
158: flg = PETSC_FALSE;
159: PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",flg,&flg,NULL);
160: if (flg) {
161: EPSMonitorSet(eps,EPSMonitorLGAll,NULL,NULL);
162: EPSSetTrackAll(eps,PETSC_TRUE);
163: }
164: /* -----------------------------------------------------------------------*/
165: PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
166: if (flg) {
167: EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
168: EPSSetTarget(eps,s);
169: }
170: k = 2;
171: PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
172: if (flg) {
173: if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
174: EPSSetWhichEigenpairs(eps,EPS_ALL);
175: EPSSetInterval(eps,array[0],array[1]);
176: }
178: PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
179: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
180: PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
181: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
182: PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
183: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
184: PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
185: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
186: PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
187: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
188: PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
189: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
190: PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);
191: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
192: PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);
193: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
194: PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);
195: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
196: PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval","EPSSetWhichEigenpairs",&flg);
197: if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }
199: PetscOptionsBool("-eps_left_vectors","Compute left eigenvectors also","EPSSetLeftVectorsWanted",eps->leftvecs,&val,&flg);
200: if (flg) {
201: EPSSetLeftVectorsWanted(eps,val);
202: }
203: PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&val,&flg);
204: if (flg) {
205: EPSSetTrueResidual(eps,val);
206: }
208: nrma = nrmb = 0;
209: PetscOptionsReal("-eps_norm_a","Norm of matrix A","EPSSetMatrixNorms",eps->nrma,&nrma,NULL);
210: PetscOptionsReal("-eps_norm_b","Norm of matrix B","EPSSetMatrixNorms",eps->nrmb,&nrmb,NULL);
211: EPSSetMatrixNorms(eps,nrma,nrmb,eps->adaptive);
212: PetscOptionsBool("-eps_norms_adaptive","Update the value of matrix norms adaptively","EPSSetMatrixNorms",eps->adaptive,&val,&flg);
213: if (flg) {
214: EPSSetMatrixNorms(eps,0,0,val);
215: }
217: PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",0);
218: PetscOptionsName("-eps_plot_eigs","Make a plot of the computed eigenvalues","EPSSolve",0);
220: if (eps->ops->setfromoptions) {
221: (*eps->ops->setfromoptions)(eps);
222: }
223: PetscObjectProcessOptionsHandlers((PetscObject)eps);
224: PetscOptionsEnd();
226: if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
227: IPSetFromOptions(eps->ip);
228: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
229: DSSetFromOptions(eps->ds);
230: STSetFromOptions(eps->st);
231: PetscRandomSetFromOptions(eps->rand);
232: return(0);
233: }
237: /*@
238: EPSGetTolerances - Gets the tolerance and maximum iteration count used
239: by the EPS convergence tests.
241: Not Collective
243: Input Parameter:
244: . eps - the eigensolver context
246: Output Parameters:
247: + tol - the convergence tolerance
248: - maxits - maximum number of iterations
250: Notes:
251: The user can specify NULL for any parameter that is not needed.
253: Level: intermediate
255: .seealso: EPSSetTolerances()
256: @*/
257: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
258: {
261: if (tol) *tol = eps->tol;
262: if (maxits) *maxits = eps->max_it;
263: return(0);
264: }
268: /*@
269: EPSSetTolerances - Sets the tolerance and maximum iteration count used
270: by the EPS convergence tests.
272: Logically Collective on EPS
274: Input Parameters:
275: + eps - the eigensolver context
276: . tol - the convergence tolerance
277: - maxits - maximum number of iterations to use
279: Options Database Keys:
280: + -eps_tol <tol> - Sets the convergence tolerance
281: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
283: Notes:
284: Pass 0 for an argument that need not be changed.
286: Use PETSC_DECIDE for maxits to assign a reasonably good value, which is
287: dependent on the solution method.
289: Level: intermediate
291: .seealso: EPSGetTolerances()
292: @*/
293: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
294: {
299: if (tol) {
300: if (tol == PETSC_DEFAULT) {
301: eps->tol = PETSC_DEFAULT;
302: } else {
303: if (tol < 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
304: eps->tol = tol;
305: }
306: }
307: if (maxits) {
308: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
309: eps->max_it = 0;
310: eps->setupcalled = 0;
311: } else {
312: if (maxits < 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
313: eps->max_it = maxits;
314: }
315: }
316: return(0);
317: }
321: /*@
322: EPSGetDimensions - Gets the number of eigenvalues to compute
323: and the dimension of the subspace.
325: Not Collective
327: Input Parameter:
328: . eps - the eigensolver context
330: Output Parameters:
331: + nev - number of eigenvalues to compute
332: . ncv - the maximum dimension of the subspace to be used by the solver
333: - mpd - the maximum dimension allowed for the projected problem
335: Notes:
336: The user can specify NULL for any parameter that is not needed.
338: Level: intermediate
340: .seealso: EPSSetDimensions()
341: @*/
342: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
343: {
346: if (nev) *nev = eps->nev;
347: if (ncv) *ncv = eps->ncv;
348: if (mpd) *mpd = eps->mpd;
349: return(0);
350: }
354: /*@
355: EPSSetDimensions - Sets the number of eigenvalues to compute
356: and the dimension of the subspace.
358: Logically Collective on EPS
360: Input Parameters:
361: + eps - the eigensolver context
362: . nev - number of eigenvalues to compute
363: . ncv - the maximum dimension of the subspace to be used by the solver
364: - mpd - the maximum dimension allowed for the projected problem
366: Options Database Keys:
367: + -eps_nev <nev> - Sets the number of eigenvalues
368: . -eps_ncv <ncv> - Sets the dimension of the subspace
369: - -eps_mpd <mpd> - Sets the maximum projected dimension
371: Notes:
372: Pass 0 to retain the previous value of any parameter.
374: Use PETSC_DECIDE for ncv and mpd to assign a reasonably good value, which is
375: dependent on the solution method.
377: The parameters ncv and mpd are intimately related, so that the user is advised
378: to set one of them at most. Normal usage is that
379: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
380: (b) in cases where nev is large, the user sets mpd.
382: The value of ncv should always be between nev and (nev+mpd), typically
383: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
384: a smaller value should be used.
386: When computing all eigenvalues in an interval, see EPSSetInterval(), the
387: meaning of nev changes. In that case, the number of eigenvalues in the
388: interval is not known a priori; the meaning of nev is then the number of
389: eigenvalues that are computed at a time when sweeping the interval from one
390: end to the other. The value of nev in this case may have an impact on overall
391: performance. The value of ncv should not be assigned in this case.
393: Level: intermediate
395: .seealso: EPSGetDimensions(), EPSSetInterval()
396: @*/
397: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
398: {
404: if (nev) {
405: if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
406: eps->nev = nev;
407: eps->setupcalled = 0;
408: }
409: if (ncv) {
410: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
411: eps->ncv = 0;
412: } else {
413: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
414: eps->ncv = ncv;
415: }
416: eps->setupcalled = 0;
417: }
418: if (mpd) {
419: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
420: eps->mpd = 0;
421: } else {
422: if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
423: eps->mpd = mpd;
424: }
425: }
426: return(0);
427: }
431: /*@
432: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
433: to be sought.
435: Logically Collective on EPS
437: Input Parameters:
438: + eps - eigensolver context obtained from EPSCreate()
439: - which - the portion of the spectrum to be sought
441: Possible values:
442: The parameter 'which' can have one of these values
444: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
445: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
446: . EPS_LARGEST_REAL - largest real parts
447: . EPS_SMALLEST_REAL - smallest real parts
448: . EPS_LARGEST_IMAGINARY - largest imaginary parts
449: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
450: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
451: . EPS_TARGET_REAL - eigenvalues with real part closest to target
452: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
453: . EPS_ALL - all eigenvalues contained in a given interval
454: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
456: Options Database Keys:
457: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
458: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
459: . -eps_largest_real - Sets largest real parts
460: . -eps_smallest_real - Sets smallest real parts
461: . -eps_largest_imaginary - Sets largest imaginary parts
462: . -eps_smallest_imaginary - Sets smallest imaginary parts
463: . -eps_target_magnitude - Sets eigenvalues closest to target
464: . -eps_target_real - Sets real parts closest to target
465: . -eps_target_imaginary - Sets imaginary parts closest to target
466: - -eps_all - Sets all eigenvalues in an interval
468: Notes:
469: Not all eigensolvers implemented in EPS account for all the possible values
470: stated above. Also, some values make sense only for certain types of
471: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
472: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
473: for eigenvalue selection.
475: The target is a scalar value provided with EPSSetTarget().
477: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
478: SLEPc have been built with complex scalars.
480: EPS_ALL is intended for use in combination with an interval (see
481: EPSSetInterval()), when all eigenvalues within the interval are requested.
482: In that case, the number of eigenvalues is unknown, so the nev parameter
483: has a different sense, see EPSSetDimensions().
485: Level: intermediate
487: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
488: EPSSetDimensions(), EPSSetEigenvalueComparison(),
489: EPSSortEigenvalues(), EPSWhich
490: @*/
491: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
492: {
496: if (which) {
497: if (which==PETSC_DECIDE || which==PETSC_DEFAULT) eps->which = (EPSWhich)0;
498: else switch (which) {
499: case EPS_LARGEST_MAGNITUDE:
500: case EPS_SMALLEST_MAGNITUDE:
501: case EPS_LARGEST_REAL:
502: case EPS_SMALLEST_REAL:
503: case EPS_LARGEST_IMAGINARY:
504: case EPS_SMALLEST_IMAGINARY:
505: case EPS_TARGET_MAGNITUDE:
506: case EPS_TARGET_REAL:
507: #if defined(PETSC_USE_COMPLEX)
508: case EPS_TARGET_IMAGINARY:
509: #endif
510: case EPS_ALL:
511: case EPS_WHICH_USER:
512: if (eps->which != which) {
513: eps->setupcalled = 0;
514: eps->which = which;
515: }
516: break;
517: default:
518: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
519: }
520: }
521: return(0);
522: }
526: /*@C
527: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
528: sought.
530: Not Collective
532: Input Parameter:
533: . eps - eigensolver context obtained from EPSCreate()
535: Output Parameter:
536: . which - the portion of the spectrum to be sought
538: Notes:
539: See EPSSetWhichEigenpairs() for possible values of 'which'.
541: Level: intermediate
543: .seealso: EPSSetWhichEigenpairs(), EPSWhich
544: @*/
545: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
546: {
550: *which = eps->which;
551: return(0);
552: }
556: /*@
557: EPSSetLeftVectorsWanted - Specifies which eigenvectors are required.
559: Logically Collective on EPS
561: Input Parameters:
562: + eps - the eigensolver context
563: - leftvecs - whether left eigenvectors are required or not
565: Options Database Keys:
566: . -eps_left_vectors <boolean> - Sets/resets the boolean flag 'leftvecs'
568: Notes:
569: If the user sets leftvecs=PETSC_TRUE then the solver uses a variant of
570: the algorithm that computes both right and left eigenvectors. This is
571: usually much more costly. This option is not available in all solvers.
573: Level: intermediate
575: .seealso: EPSGetLeftVectorsWanted(), EPSGetEigenvectorLeft()
576: @*/
577: PetscErrorCode EPSSetLeftVectorsWanted(EPS eps,PetscBool leftvecs)
578: {
582: if (eps->leftvecs != leftvecs) {
583: eps->leftvecs = leftvecs;
584: eps->setupcalled = 0;
585: }
586: return(0);
587: }
591: /*@
592: EPSGetLeftVectorsWanted - Returns the flag indicating whether left
593: eigenvectors are required or not.
595: Not Collective
597: Input Parameter:
598: . eps - the eigensolver context
600: Output Parameter:
601: . leftvecs - the returned flag
603: Level: intermediate
605: .seealso: EPSSetLeftVectorsWanted(), EPSWhich
606: @*/
607: PetscErrorCode EPSGetLeftVectorsWanted(EPS eps,PetscBool *leftvecs)
608: {
612: *leftvecs = eps->leftvecs;
613: return(0);
614: }
618: /*@
619: EPSSetMatrixNorms - Gives the reference values of the matrix norms
620: and specifies whether these values should be improved adaptively.
622: Logically Collective on EPS
624: Input Parameters:
625: + eps - the eigensolver context
626: . nrma - a reference value for the norm of matrix A
627: . nrmb - a reference value for the norm of matrix B
628: - adaptive - whether matrix norms are improved adaptively
630: Options Database Keys:
631: + -eps_norm_a <nrma> - norm of A
632: . -eps_norm_b <nrma> - norm of B
633: - -eps_norms_adaptive <boolean> - Sets/resets the boolean flag 'adaptive'
635: Notes:
636: If the user sets adaptive=PETSC_FALSE then the solver uses the values
637: of nrma and nrmb for the matrix norms, and these values do not change
638: throughout the iteration.
640: If the user sets adaptive=PETSC_TRUE then the solver tries to adaptively
641: improve the supplied values, with the numerical information generated
642: during the iteration. This option is not available in all solvers.
644: If a passed value is PETSC_DEFAULT, the corresponding norm will be set to 1.
645: If a passed value is PETSC_DETERMINE, the corresponding norm will be computed
646: as the NORM_INFINITY with MatNorm().
648: Level: intermediate
650: .seealso: EPSGetMatrixNorms()
651: @*/
652: PetscErrorCode EPSSetMatrixNorms(EPS eps,PetscReal nrma,PetscReal nrmb,PetscBool adaptive)
653: {
659: if (nrma) {
660: if (nrma == PETSC_DEFAULT) eps->nrma = 1.0;
661: else if (nrma == PETSC_DETERMINE) {
662: eps->nrma = nrma;
663: eps->setupcalled = 0;
664: } else {
665: if (nrma < 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nrma. Must be > 0");
666: eps->nrma = nrma;
667: }
668: }
669: if (nrmb) {
670: if (!eps->isgeneralized) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Norm of B only allowed in generalized problems");
671: if (nrmb == PETSC_DEFAULT) eps->nrmb = 1.0;
672: else if (nrmb == PETSC_DETERMINE) {
673: eps->nrmb = nrmb;
674: eps->setupcalled = 0;
675: } else {
676: if (nrmb < 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nrmb. Must be > 0");
677: eps->nrmb = nrmb;
678: }
679: }
680: if (eps->adaptive != adaptive) {
681: eps->adaptive = adaptive;
682: eps->setupcalled = 0;
683: if (adaptive) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"Sorry, adaptive norms are not implemented in this release");
684: }
685: return(0);
686: }
690: /*@
691: EPSGetMatrixNorms - Returns the value of the matrix norms (either set
692: by the user or estimated by the solver) and the flag indicating whether
693: the norms are being adaptively improved.
695: Not Collective
697: Input Parameter:
698: . eps - the eigensolver context
700: Output Parameters:
701: + nrma - the norm of matrix A
702: . nrmb - the norm of matrix B
703: - adaptive - whether matrix norms are improved adaptively
705: Level: intermediate
707: .seealso: EPSSetMatrixNorms()
708: @*/
709: PetscErrorCode EPSGetMatrixNorms(EPS eps,PetscReal *nrma,PetscReal *nrmb,PetscBool *adaptive)
710: {
713: if (nrma) *nrma = eps->nrma;
714: if (nrmb) *nrmb = eps->nrmb;
715: if (adaptive) *adaptive = eps->adaptive;
716: return(0);
717: }
721: /*@C
722: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
723: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
725: Logically Collective on EPS
727: Input Parameters:
728: + eps - eigensolver context obtained from EPSCreate()
729: . func - a pointer to the comparison function
730: - ctx - a context pointer (the last parameter to the comparison function)
732: Calling Sequence of func:
733: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
735: + ar - real part of the 1st eigenvalue
736: . ai - imaginary part of the 1st eigenvalue
737: . br - real part of the 2nd eigenvalue
738: . bi - imaginary part of the 2nd eigenvalue
739: . res - result of comparison
740: - ctx - optional context, as set by EPSSetEigenvalueComparison()
742: Note:
743: The returning parameter 'res' can be:
744: + negative - if the 1st eigenvalue is preferred to the 2st one
745: . zero - if both eigenvalues are equally preferred
746: - positive - if the 2st eigenvalue is preferred to the 1st one
748: Level: advanced
750: .seealso: EPSSetWhichEigenpairs(), EPSSortEigenvalues(), EPSWhich
751: @*/
752: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
753: {
756: eps->comparison = func;
757: eps->comparisonctx = ctx;
758: eps->which = EPS_WHICH_USER;
759: return(0);
760: }
764: /*@C
765: EPSSetArbitrarySelection - Specifies a function intended to look for
766: eigenvalues according to an arbitrary selection criterion. This criterion
767: can be based on a computation involving the current eigenvector approximation.
769: Logically Collective on EPS
771: Input Parameters:
772: + eps - eigensolver context obtained from EPSCreate()
773: . func - a pointer to the evaluation function
774: - ctx - a context pointer (the last parameter to the evaluation function)
776: Calling Sequence of func:
777: $ func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
779: + er - real part of the current eigenvalue approximation
780: . ei - imaginary part of the current eigenvalue approximation
781: . xr - real part of the current eigenvector approximation
782: . xi - imaginary part of the current eigenvector approximation
783: . rr - result of evaluation (real part)
784: . ri - result of evaluation (imaginary part)
785: - ctx - optional context, as set by EPSSetArbitrarySelection()
787: Note:
788: This provides a mechanism to select eigenpairs by evaluating a user-defined
789: function. When a function has been provided, the default selection based on
790: sorting the eigenvalues is replaced by the sorting of the results of this
791: function (with the same sorting criterion given in EPSSortEigenvalues()).
793: For instance, suppose you want to compute those eigenvectors that maximize
794: a certain computable expression. Then implement the computation using
795: the arguments xr and xi, and return the result in rr. Then set the standard
796: sorting by magnitude so that the eigenpair with largest value of rr is
797: selected.
799: The result of func is expressed as a complex number so that it is possible to
800: use the standard eigenvalue sorting functions, but normally only rr is used.
801: Set ri to zero unless it is meaningful in your application.
803: Level: advanced
805: .seealso: EPSSetWhichEigenpairs(), EPSSortEigenvalues()
806: @*/
807: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
808: {
811: eps->arbitrary = func;
812: eps->arbitraryctx = ctx;
813: eps->setupcalled = 0;
814: return(0);
815: }
819: /*@C
820: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
821: used in the convergence test.
823: Logically Collective on EPS
825: Input Parameters:
826: + eps - eigensolver context obtained from EPSCreate()
827: . func - a pointer to the convergence test function
828: - ctx - a context pointer (the last parameter to the convergence test function)
830: Calling Sequence of func:
831: $ func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
833: + eps - eigensolver context obtained from EPSCreate()
834: . eigr - real part of the eigenvalue
835: . eigi - imaginary part of the eigenvalue
836: . res - residual norm associated to the eigenpair
837: . errest - (output) computed error estimate
838: - ctx - optional context, as set by EPSSetConvergenceTest()
840: Note:
841: If the error estimate returned by the convergence test function is less than
842: the tolerance, then the eigenvalue is accepted as converged.
844: Level: advanced
846: .seealso: EPSSetConvergenceTest(),EPSSetTolerances()
847: @*/
848: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx)
849: {
852: eps->converged = func;
853: eps->convergedctx = ctx;
854: if (func == EPSConvergedEigRelative) eps->conv = EPS_CONV_EIG;
855: else if (func == EPSConvergedNormRelative) eps->conv = EPS_CONV_NORM;
856: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
857: else eps->conv = EPS_CONV_USER;
858: return(0);
859: }
863: /*@
864: EPSSetConvergenceTest - Specifies how to compute the error estimate
865: used in the convergence test.
867: Logically Collective on EPS
869: Input Parameters:
870: + eps - eigensolver context obtained from EPSCreate()
871: - conv - the type of convergence test
873: Options Database Keys:
874: + -eps_conv_abs - Sets the absolute convergence test
875: . -eps_conv_eig - Sets the convergence test relative to the eigenvalue
876: - -eps_conv_norm - Sets the convergence test relative to the matrix norms
878: Note:
879: The parameter 'conv' can have one of these values
880: + EPS_CONV_ABS - absolute error ||r||
881: . EPS_CONV_EIG - error relative to the eigenvalue l, ||r||/|l|
882: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
883: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
885: Level: intermediate
887: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSConv
888: @*/
889: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
890: {
894: switch (conv) {
895: case EPS_CONV_EIG: eps->converged = EPSConvergedEigRelative; break;
896: case EPS_CONV_NORM: eps->converged = EPSConvergedNormRelative; break;
897: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
898: case EPS_CONV_USER: break;
899: default:
900: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
901: }
902: eps->conv = conv;
903: return(0);
904: }
908: /*@
909: EPSGetConvergenceTest - Gets the method used to compute the error estimate
910: used in the convergence test.
912: Not Collective
914: Input Parameters:
915: . eps - eigensolver context obtained from EPSCreate()
917: Output Parameters:
918: . conv - the type of convergence test
920: Level: intermediate
922: .seealso: EPSSetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSConv
923: @*/
924: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
925: {
929: *conv = eps->conv;
930: return(0);
931: }
935: /*@
936: EPSSetProblemType - Specifies the type of the eigenvalue problem.
938: Logically Collective on EPS
940: Input Parameters:
941: + eps - the eigensolver context
942: - type - a known type of eigenvalue problem
944: Options Database Keys:
945: + -eps_hermitian - Hermitian eigenvalue problem
946: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
947: . -eps_non_hermitian - non-Hermitian eigenvalue problem
948: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
949: - -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
950: with positive semi-definite B
952: Notes:
953: Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
954: (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
955: (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
956: (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).
958: This function must be used to instruct SLEPc to exploit symmetry. If no
959: problem type is specified, by default a non-Hermitian problem is assumed
960: (either standard or generalized). If the user knows that the problem is
961: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
962: B positive definite) then it is recommended to set the problem type so
963: that eigensolver can exploit these properties.
965: Level: beginner
967: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
968: @*/
969: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
970: {
974: switch (type) {
975: case EPS_HEP:
976: eps->isgeneralized = PETSC_FALSE;
977: eps->ishermitian = PETSC_TRUE;
978: eps->ispositive = PETSC_FALSE;
979: break;
980: case EPS_NHEP:
981: eps->isgeneralized = PETSC_FALSE;
982: eps->ishermitian = PETSC_FALSE;
983: eps->ispositive = PETSC_FALSE;
984: break;
985: case EPS_GHEP:
986: eps->isgeneralized = PETSC_TRUE;
987: eps->ishermitian = PETSC_TRUE;
988: eps->ispositive = PETSC_TRUE;
989: break;
990: case EPS_GNHEP:
991: eps->isgeneralized = PETSC_TRUE;
992: eps->ishermitian = PETSC_FALSE;
993: eps->ispositive = PETSC_FALSE;
994: break;
995: case EPS_PGNHEP:
996: eps->isgeneralized = PETSC_TRUE;
997: eps->ishermitian = PETSC_FALSE;
998: eps->ispositive = PETSC_TRUE;
999: break;
1000: case EPS_GHIEP:
1001: eps->isgeneralized = PETSC_TRUE;
1002: eps->ishermitian = PETSC_TRUE;
1003: eps->ispositive = PETSC_FALSE;
1004: break;
1005: default:
1006: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
1007: }
1008: eps->problem_type = type;
1009: return(0);
1010: }
1014: /*@C
1015: EPSGetProblemType - Gets the problem type from the EPS object.
1017: Not Collective
1019: Input Parameter:
1020: . eps - the eigensolver context
1022: Output Parameter:
1023: . type - name of EPS problem type
1025: Level: intermediate
1027: .seealso: EPSSetProblemType(), EPSProblemType
1028: @*/
1029: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
1030: {
1034: *type = eps->problem_type;
1035: return(0);
1036: }
1040: /*@
1041: EPSSetExtraction - Specifies the type of extraction technique to be employed
1042: by the eigensolver.
1044: Logically Collective on EPS
1046: Input Parameters:
1047: + eps - the eigensolver context
1048: - extr - a known type of extraction
1050: Options Database Keys:
1051: + -eps_ritz - Rayleigh-Ritz extraction
1052: . -eps_harmonic - harmonic Ritz extraction
1053: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
1054: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
1055: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
1056: (without target)
1057: . -eps_refined - refined Ritz extraction
1058: - -eps_refined_harmonic - refined harmonic Ritz extraction
1060: Notes:
1061: Not all eigensolvers support all types of extraction. See the SLEPc
1062: Users Manual for details.
1064: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
1065: may be useful when computing interior eigenvalues.
1067: Harmonic-type extractions are used in combination with a 'target'.
1069: Level: beginner
1071: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
1072: @*/
1073: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
1074: {
1078: eps->extraction = extr;
1079: return(0);
1080: }
1084: /*@C
1085: EPSGetExtraction - Gets the extraction type used by the EPS object.
1087: Not Collective
1089: Input Parameter:
1090: . eps - the eigensolver context
1092: Output Parameter:
1093: . extr - name of extraction type
1095: Level: intermediate
1097: .seealso: EPSSetExtraction(), EPSExtraction
1098: @*/
1099: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1100: {
1104: *extr = eps->extraction;
1105: return(0);
1106: }
1110: /*@
1111: EPSSetBalance - Specifies the balancing technique to be employed by the
1112: eigensolver, and some parameters associated to it.
1114: Logically Collective on EPS
1116: Input Parameters:
1117: + eps - the eigensolver context
1118: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1119: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1120: . its - number of iterations of the balancing algorithm
1121: - cutoff - cutoff value
1123: Options Database Keys:
1124: + -eps_balance <method> - the balancing method, where <method> is one of
1125: 'none', 'oneside', 'twoside', or 'user'
1126: . -eps_balance_its <its> - number of iterations
1127: - -eps_balance_cutoff <cutoff> - cutoff value
1129: Notes:
1130: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1131: where D is an appropriate diagonal matrix. This improves the accuracy of
1132: the computed results in some cases. See the SLEPc Users Manual for details.
1134: Balancing makes sense only for non-Hermitian problems when the required
1135: precision is high (i.e. a small tolerance such as 1e-15).
1137: By default, balancing is disabled. The two-sided method is much more
1138: effective than the one-sided counterpart, but it requires the system
1139: matrices to have the MatMultTranspose operation defined.
1141: The parameter 'its' is the number of iterations performed by the method. The
1142: cutoff value is used only in the two-side variant. Pass 0 for an argument
1143: that need not be changed. Use PETSC_DECIDE to assign a reasonably good value.
1145: User-defined balancing is allowed provided that the corresponding matrix
1146: is set via STSetBalanceMatrix.
1148: Level: intermediate
1150: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1151: @*/
1152: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1153: {
1159: if (bal) {
1160: if (bal==PETSC_DECIDE || bal==PETSC_DEFAULT) eps->balance = EPS_BALANCE_TWOSIDE;
1161: else switch (bal) {
1162: case EPS_BALANCE_NONE:
1163: case EPS_BALANCE_ONESIDE:
1164: case EPS_BALANCE_TWOSIDE:
1165: case EPS_BALANCE_USER:
1166: eps->balance = bal;
1167: break;
1168: default:
1169: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1170: }
1171: }
1172: if (its) {
1173: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1174: else eps->balance_its = its;
1175: }
1176: if (cutoff) {
1177: if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1178: else eps->balance_cutoff = cutoff;
1179: }
1180: return(0);
1181: }
1185: /*@
1186: EPSGetBalance - Gets the balancing type used by the EPS object, and the associated
1187: parameters.
1189: Not Collective
1191: Input Parameter:
1192: . eps - the eigensolver context
1194: Output Parameters:
1195: + bal - the balancing method
1196: . its - number of iterations of the balancing algorithm
1197: - cutoff - cutoff value
1199: Level: intermediate
1201: Note:
1202: The user can specify NULL for any parameter that is not needed.
1204: .seealso: EPSSetBalance(), EPSBalance
1205: @*/
1206: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1207: {
1210: if (bal) *bal = eps->balance;
1211: if (its) *its = eps->balance_its;
1212: if (cutoff) *cutoff = eps->balance_cutoff;
1213: return(0);
1214: }
1218: /*@
1219: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1220: explicitly or not.
1222: Logically Collective on EPS
1224: Input Parameters:
1225: + eps - the eigensolver context
1226: - trueres - whether true residuals are required or not
1228: Options Database Keys:
1229: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1231: Notes:
1232: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1233: the true residual for each eigenpair approximation, and uses it for
1234: convergence testing. Computing the residual is usually an expensive
1235: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1236: by using a cheap estimate of the residual norm, but this may sometimes
1237: give inaccurate results (especially if a spectral transform is being
1238: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1239: do rely on computing the true residual, so this option is irrelevant for them.
1241: Level: intermediate
1243: .seealso: EPSGetTrueResidual()
1244: @*/
1245: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1246: {
1250: eps->trueres = trueres;
1251: return(0);
1252: }
1256: /*@C
1257: EPSGetTrueResidual - Returns the flag indicating whether true
1258: residuals must be computed explicitly or not.
1260: Not Collective
1262: Input Parameter:
1263: . eps - the eigensolver context
1265: Output Parameter:
1266: . trueres - the returned flag
1268: Level: intermediate
1270: .seealso: EPSSetTrueResidual()
1271: @*/
1272: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1273: {
1277: *trueres = eps->trueres;
1278: return(0);
1279: }
1283: /*@
1284: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1285: approximate eigenpairs or not.
1287: Logically Collective on EPS
1289: Input Parameters:
1290: + eps - the eigensolver context
1291: - trackall - whether to compute all residuals or not
1293: Notes:
1294: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1295: the residual norm for each eigenpair approximation. Computing the residual is
1296: usually an expensive operation and solvers commonly compute only the residual
1297: associated to the first unconverged eigenpair.
1299: The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1300: activate this option.
1302: Level: intermediate
1304: .seealso: EPSGetTrackAll()
1305: @*/
1306: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1307: {
1311: eps->trackall = trackall;
1312: return(0);
1313: }
1317: /*@
1318: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1319: be computed or not.
1321: Not Collective
1323: Input Parameter:
1324: . eps - the eigensolver context
1326: Output Parameter:
1327: . trackall - the returned flag
1329: Level: intermediate
1331: .seealso: EPSSetTrackAll()
1332: @*/
1333: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1334: {
1338: *trackall = eps->trackall;
1339: return(0);
1340: }
1344: /*@C
1345: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1346: EPS options in the database.
1348: Logically Collective on EPS
1350: Input Parameters:
1351: + eps - the eigensolver context
1352: - prefix - the prefix string to prepend to all EPS option requests
1354: Notes:
1355: A hyphen (-) must NOT be given at the beginning of the prefix name.
1356: The first character of all runtime options is AUTOMATICALLY the
1357: hyphen.
1359: For example, to distinguish between the runtime options for two
1360: different EPS contexts, one could call
1361: .vb
1362: EPSSetOptionsPrefix(eps1,"eig1_")
1363: EPSSetOptionsPrefix(eps2,"eig2_")
1364: .ve
1366: Level: advanced
1368: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1369: @*/
1370: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1371: {
1376: if (!eps->st) { EPSGetST(eps,&eps->st); }
1377: STSetOptionsPrefix(eps->st,prefix);
1378: if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
1379: IPSetOptionsPrefix(eps->ip,prefix);
1380: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1381: DSSetOptionsPrefix(eps->ds,prefix);
1382: PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1383: return(0);
1384: }
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: {
1412: if (!eps->st) { EPSGetST(eps,&eps->st); }
1413: STAppendOptionsPrefix(eps->st,prefix);
1414: if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
1415: IPSetOptionsPrefix(eps->ip,prefix);
1416: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1417: DSSetOptionsPrefix(eps->ds,prefix);
1418: PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1419: return(0);
1420: }
1424: /*@C
1425: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1426: EPS options in the database.
1428: Not Collective
1430: Input Parameters:
1431: . eps - the eigensolver context
1433: Output Parameters:
1434: . prefix - pointer to the prefix string used is returned
1436: Notes: On the fortran side, the user should pass in a string 'prefix' of
1437: sufficient length to hold the prefix.
1439: Level: advanced
1441: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1442: @*/
1443: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1444: {
1450: PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1451: return(0);
1452: }