Actual source code: epsopts.c
slepc-3.9.2 2018-07-02
1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2018, 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> /*I "slepceps.h" I*/
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: . name - the monitor option name
27: . help - message indicating what monitoring is done
28: . manual - manual page for the monitor
29: . monitor - the monitor function, whose context is a PetscViewerAndFormat
30: - trackall - whether this monitor tracks all eigenvalues or not
32: Level: developer
34: .seealso: EPSMonitorSet(), EPSSetTrackAll(), EPSConvMonitorSetFromOptions()
35: @*/
36: PetscErrorCode EPSMonitorSetFromOptions(EPS eps,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*),PetscBool trackall)
37: {
38: PetscErrorCode ierr;
39: PetscBool flg;
40: PetscViewer viewer;
41: PetscViewerFormat format;
42: PetscViewerAndFormat *vf;
45: PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->prefix,name,&viewer,&format,&flg);
46: if (flg) {
47: PetscViewerAndFormatCreate(viewer,format,&vf);
48: PetscObjectDereference((PetscObject)viewer);
49: EPSMonitorSet(eps,(PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
50: if (trackall) {
51: EPSSetTrackAll(eps,PETSC_TRUE);
52: }
53: }
54: return(0);
55: }
57: /*@C
58: EPSConvMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
59: indicated by the user (for monitors that only show iteration numbers of convergence).
61: Collective on EPS
63: Input Parameters:
64: + eps - the eigensolver context
65: . name - the monitor option name
66: . help - message indicating what monitoring is done
67: . manual - manual page for the monitor
68: - monitor - the monitor function, whose context is a SlepcConvMonitor
70: Level: developer
72: .seealso: EPSMonitorSet(), EPSMonitorSetFromOptions()
73: @*/
74: PetscErrorCode EPSConvMonitorSetFromOptions(EPS eps,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor))
75: {
76: PetscErrorCode ierr;
77: PetscBool flg;
78: PetscViewer viewer;
79: PetscViewerFormat format;
80: SlepcConvMonitor ctx;
83: PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->prefix,name,&viewer,&format,&flg);
84: if (flg) {
85: SlepcConvMonitorCreate(viewer,format,&ctx);
86: PetscObjectDereference((PetscObject)viewer);
87: EPSMonitorSet(eps,(PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*))monitor,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
88: }
89: return(0);
90: }
92: /*@
93: EPSSetFromOptions - Sets EPS options from the options database.
94: This routine must be called before EPSSetUp() if the user is to be
95: allowed to set the solver type.
97: Collective on EPS
99: Input Parameters:
100: . eps - the eigensolver context
102: Notes:
103: To see all options, run your program with the -help option.
105: Level: beginner
106: @*/
107: PetscErrorCode EPSSetFromOptions(EPS eps)
108: {
110: char type[256];
111: PetscBool set,flg,flg1,flg2,flg3,purif;
112: PetscReal r,array[2]={0,0};
113: PetscScalar s;
114: PetscInt i,j,k;
115: PetscDrawLG lg;
116: EPSBalance bal;
120: EPSRegisterAll();
121: PetscObjectOptionsBegin((PetscObject)eps);
122: PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
123: if (flg) {
124: EPSSetType(eps,type);
125: } else if (!((PetscObject)eps)->type_name) {
126: EPSSetType(eps,EPSKRYLOVSCHUR);
127: }
129: PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg);
130: if (flg) { EPSSetProblemType(eps,EPS_HEP); }
131: PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg);
132: if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
133: PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
134: if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
135: PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
136: if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
137: PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
138: if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
139: PetscOptionsBoolGroupEnd("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
140: if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }
142: PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
143: if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
144: PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg);
145: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
146: PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg);
147: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
148: PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg);
149: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
150: PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg);
151: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
152: PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg);
153: if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
154: PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg);
155: if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }
157: bal = eps->balance;
158: PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1);
159: j = eps->balance_its;
160: PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2);
161: r = eps->balance_cutoff;
162: PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3);
163: if (flg1 || flg2 || flg3) { EPSSetBalance(eps,bal,j,r); }
165: i = eps->max_it? eps->max_it: PETSC_DEFAULT;
166: PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
167: r = eps->tol;
168: PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,&flg2);
169: if (flg1 || flg2) { EPSSetTolerances(eps,r,i); }
171: PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
172: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_REL); }
173: PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
174: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
175: PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
176: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
177: PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
178: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_USER); }
180: PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg);
181: if (flg) { EPSSetStoppingTest(eps,EPS_STOP_BASIC); }
182: PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg);
183: if (flg) { EPSSetStoppingTest(eps,EPS_STOP_USER); }
185: i = eps->nev;
186: PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
187: j = eps->ncv? eps->ncv: PETSC_DEFAULT;
188: PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
189: k = eps->mpd? eps->mpd: PETSC_DEFAULT;
190: PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
191: if (flg1 || flg2 || flg3) { EPSSetDimensions(eps,i,j,k); }
193: PetscOptionsBoolGroupBegin("-eps_largest_magnitude","Compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
194: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
195: PetscOptionsBoolGroup("-eps_smallest_magnitude","Compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
196: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
197: PetscOptionsBoolGroup("-eps_largest_real","Compute eigenvalues with largest real parts","EPSSetWhichEigenpairs",&flg);
198: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
199: PetscOptionsBoolGroup("-eps_smallest_real","Compute eigenvalues with smallest real parts","EPSSetWhichEigenpairs",&flg);
200: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
201: PetscOptionsBoolGroup("-eps_largest_imaginary","Compute eigenvalues with largest imaginary parts","EPSSetWhichEigenpairs",&flg);
202: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
203: PetscOptionsBoolGroup("-eps_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
204: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
205: PetscOptionsBoolGroup("-eps_target_magnitude","Compute eigenvalues closest to target","EPSSetWhichEigenpairs",&flg);
206: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
207: PetscOptionsBoolGroup("-eps_target_real","Compute eigenvalues with real parts closest to target","EPSSetWhichEigenpairs",&flg);
208: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
209: PetscOptionsBoolGroup("-eps_target_imaginary","Compute eigenvalues with imaginary parts closest to target","EPSSetWhichEigenpairs",&flg);
210: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
211: PetscOptionsBoolGroupEnd("-eps_all","Compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg);
212: if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }
214: PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
215: if (flg) {
216: if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) {
217: EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
218: }
219: EPSSetTarget(eps,s);
220: }
222: k = 2;
223: PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
224: if (flg) {
225: if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
226: EPSSetWhichEigenpairs(eps,EPS_ALL);
227: EPSSetInterval(eps,array[0],array[1]);
228: }
230: PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
231: PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&purif,&flg);
232: if (flg) { EPSSetPurify(eps,purif); }
234: /* -----------------------------------------------------------------------*/
235: /*
236: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
237: */
238: PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
239: if (set && flg) {
240: EPSMonitorCancel(eps);
241: }
242: /*
243: Text monitors
244: */
245: EPSMonitorSetFromOptions(eps,"-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorFirst",EPSMonitorFirst,PETSC_FALSE);
246: EPSConvMonitorSetFromOptions(eps,"-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorConverged",EPSMonitorConverged);
247: EPSMonitorSetFromOptions(eps,"-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorAll",EPSMonitorAll,PETSC_TRUE);
248: /*
249: Line graph monitors
250: */
251: PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",PETSC_FALSE,&flg,&set);
252: if (set && flg) {
253: EPSMonitorLGCreate(PetscObjectComm((PetscObject)eps),NULL,"Error estimates",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
254: EPSMonitorSet(eps,EPSMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
255: }
256: PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",PETSC_FALSE,&flg,&set);
257: if (set && flg) {
258: EPSMonitorLGCreate(PetscObjectComm((PetscObject)eps),NULL,"Error estimates",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
259: EPSMonitorSet(eps,EPSMonitorLGAll,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
260: EPSSetTrackAll(eps,PETSC_TRUE);
261: }
263: /* -----------------------------------------------------------------------*/
264: PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
265: PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
266: PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
267: PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSReasonView",NULL);
268: PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
269: PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
270: PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);
272: if (eps->ops->setfromoptions) {
273: (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
274: }
275: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)eps);
276: PetscOptionsEnd();
278: if (!eps->V) { EPSGetBV(eps,&eps->V); }
279: BVSetFromOptions(eps->V);
280: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
281: RGSetFromOptions(eps->rg);
282: if (eps->useds) {
283: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
284: DSSetFromOptions(eps->ds);
285: }
286: if (!eps->st) { EPSGetST(eps,&eps->st); }
287: EPSSetDefaultST(eps);
288: STSetFromOptions(eps->st);
289: return(0);
290: }
292: /*@C
293: EPSGetTolerances - Gets the tolerance and maximum iteration count used
294: by the EPS convergence tests.
296: Not Collective
298: Input Parameter:
299: . eps - the eigensolver context
301: Output Parameters:
302: + tol - the convergence tolerance
303: - maxits - maximum number of iterations
305: Notes:
306: The user can specify NULL for any parameter that is not needed.
308: Level: intermediate
310: .seealso: EPSSetTolerances()
311: @*/
312: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
313: {
316: if (tol) *tol = eps->tol;
317: if (maxits) *maxits = eps->max_it;
318: return(0);
319: }
321: /*@
322: EPSSetTolerances - Sets the tolerance and maximum iteration count used
323: by the EPS convergence tests.
325: Logically Collective on EPS
327: Input Parameters:
328: + eps - the eigensolver context
329: . tol - the convergence tolerance
330: - maxits - maximum number of iterations to use
332: Options Database Keys:
333: + -eps_tol <tol> - Sets the convergence tolerance
334: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
336: Notes:
337: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
339: Level: intermediate
341: .seealso: EPSGetTolerances()
342: @*/
343: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
344: {
349: if (tol == PETSC_DEFAULT) {
350: eps->tol = PETSC_DEFAULT;
351: eps->state = EPS_STATE_INITIAL;
352: } else {
353: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
354: eps->tol = tol;
355: }
356: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
357: eps->max_it = 0;
358: eps->state = EPS_STATE_INITIAL;
359: } else {
360: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
361: eps->max_it = maxits;
362: }
363: return(0);
364: }
366: /*@C
367: EPSGetDimensions - Gets the number of eigenvalues to compute
368: and the dimension of the subspace.
370: Not Collective
372: Input Parameter:
373: . eps - the eigensolver context
375: Output Parameters:
376: + nev - number of eigenvalues to compute
377: . ncv - the maximum dimension of the subspace to be used by the solver
378: - mpd - the maximum dimension allowed for the projected problem
380: Level: intermediate
382: .seealso: EPSSetDimensions()
383: @*/
384: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
385: {
388: if (nev) *nev = eps->nev;
389: if (ncv) *ncv = eps->ncv;
390: if (mpd) *mpd = eps->mpd;
391: return(0);
392: }
394: /*@
395: EPSSetDimensions - Sets the number of eigenvalues to compute
396: and the dimension of the subspace.
398: Logically Collective on EPS
400: Input Parameters:
401: + eps - the eigensolver context
402: . nev - number of eigenvalues to compute
403: . ncv - the maximum dimension of the subspace to be used by the solver
404: - mpd - the maximum dimension allowed for the projected problem
406: Options Database Keys:
407: + -eps_nev <nev> - Sets the number of eigenvalues
408: . -eps_ncv <ncv> - Sets the dimension of the subspace
409: - -eps_mpd <mpd> - Sets the maximum projected dimension
411: Notes:
412: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
413: dependent on the solution method.
415: The parameters ncv and mpd are intimately related, so that the user is advised
416: to set one of them at most. Normal usage is that
417: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
418: (b) in cases where nev is large, the user sets mpd.
420: The value of ncv should always be between nev and (nev+mpd), typically
421: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
422: a smaller value should be used.
424: When computing all eigenvalues in an interval, see EPSSetInterval(), these
425: parameters lose relevance, and tuning must be done with
426: EPSKrylovSchurSetDimensions().
428: Level: intermediate
430: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
431: @*/
432: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
433: {
439: if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
440: eps->nev = nev;
441: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
442: eps->ncv = 0;
443: } else {
444: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
445: eps->ncv = ncv;
446: }
447: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
448: eps->mpd = 0;
449: } else {
450: if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
451: eps->mpd = mpd;
452: }
453: eps->state = EPS_STATE_INITIAL;
454: return(0);
455: }
457: /*@
458: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
459: to be sought.
461: Logically Collective on EPS
463: Input Parameters:
464: + eps - eigensolver context obtained from EPSCreate()
465: - which - the portion of the spectrum to be sought
467: Possible values:
468: The parameter 'which' can have one of these values
470: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
471: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
472: . EPS_LARGEST_REAL - largest real parts
473: . EPS_SMALLEST_REAL - smallest real parts
474: . EPS_LARGEST_IMAGINARY - largest imaginary parts
475: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
476: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
477: . EPS_TARGET_REAL - eigenvalues with real part closest to target
478: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
479: . EPS_ALL - all eigenvalues contained in a given interval or region
480: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
482: Options Database Keys:
483: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
484: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
485: . -eps_largest_real - Sets largest real parts
486: . -eps_smallest_real - Sets smallest real parts
487: . -eps_largest_imaginary - Sets largest imaginary parts
488: . -eps_smallest_imaginary - Sets smallest imaginary parts
489: . -eps_target_magnitude - Sets eigenvalues closest to target
490: . -eps_target_real - Sets real parts closest to target
491: . -eps_target_imaginary - Sets imaginary parts closest to target
492: - -eps_all - Sets all eigenvalues in an interval or region
494: Notes:
495: Not all eigensolvers implemented in EPS account for all the possible values
496: stated above. Also, some values make sense only for certain types of
497: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
498: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
499: for eigenvalue selection.
501: The target is a scalar value provided with EPSSetTarget().
503: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
504: SLEPc have been built with complex scalars.
506: EPS_ALL is intended for use in combination with an interval (see
507: EPSSetInterval()), when all eigenvalues within the interval are requested,
508: or in the context of the CISS solver for computing all eigenvalues in a region.
509: In those cases, the number of eigenvalues is unknown, so the nev parameter
510: has a different sense, see EPSSetDimensions().
512: Level: intermediate
514: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
515: EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
516: @*/
517: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
518: {
522: switch (which) {
523: case EPS_LARGEST_MAGNITUDE:
524: case EPS_SMALLEST_MAGNITUDE:
525: case EPS_LARGEST_REAL:
526: case EPS_SMALLEST_REAL:
527: case EPS_LARGEST_IMAGINARY:
528: case EPS_SMALLEST_IMAGINARY:
529: case EPS_TARGET_MAGNITUDE:
530: case EPS_TARGET_REAL:
531: #if defined(PETSC_USE_COMPLEX)
532: case EPS_TARGET_IMAGINARY:
533: #endif
534: case EPS_ALL:
535: case EPS_WHICH_USER:
536: if (eps->which != which) {
537: eps->state = EPS_STATE_INITIAL;
538: eps->which = which;
539: }
540: break;
541: default:
542: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
543: }
544: return(0);
545: }
547: /*@
548: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
549: sought.
551: Not Collective
553: Input Parameter:
554: . eps - eigensolver context obtained from EPSCreate()
556: Output Parameter:
557: . which - the portion of the spectrum to be sought
559: Notes:
560: See EPSSetWhichEigenpairs() for possible values of 'which'.
562: Level: intermediate
564: .seealso: EPSSetWhichEigenpairs(), EPSWhich
565: @*/
566: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
567: {
571: *which = eps->which;
572: return(0);
573: }
575: /*@C
576: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
577: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
579: Logically Collective on EPS
581: Input Parameters:
582: + eps - eigensolver context obtained from EPSCreate()
583: . func - a pointer to the comparison function
584: - ctx - a context pointer (the last parameter to the comparison function)
586: Calling Sequence of func:
587: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
589: + ar - real part of the 1st eigenvalue
590: . ai - imaginary part of the 1st eigenvalue
591: . br - real part of the 2nd eigenvalue
592: . bi - imaginary part of the 2nd eigenvalue
593: . res - result of comparison
594: - ctx - optional context, as set by EPSSetEigenvalueComparison()
596: Note:
597: The returning parameter 'res' can be
598: + negative - if the 1st eigenvalue is preferred to the 2st one
599: . zero - if both eigenvalues are equally preferred
600: - positive - if the 2st eigenvalue is preferred to the 1st one
602: Level: advanced
604: .seealso: EPSSetWhichEigenpairs(), EPSWhich
605: @*/
606: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
607: {
610: eps->sc->comparison = func;
611: eps->sc->comparisonctx = ctx;
612: eps->which = EPS_WHICH_USER;
613: return(0);
614: }
616: /*@C
617: EPSSetArbitrarySelection - Specifies a function intended to look for
618: eigenvalues according to an arbitrary selection criterion. This criterion
619: can be based on a computation involving the current eigenvector approximation.
621: Logically Collective on EPS
623: Input Parameters:
624: + eps - eigensolver context obtained from EPSCreate()
625: . func - a pointer to the evaluation function
626: - ctx - a context pointer (the last parameter to the evaluation function)
628: Calling Sequence of func:
629: $ func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
631: + er - real part of the current eigenvalue approximation
632: . ei - imaginary part of the current eigenvalue approximation
633: . xr - real part of the current eigenvector approximation
634: . xi - imaginary part of the current eigenvector approximation
635: . rr - result of evaluation (real part)
636: . ri - result of evaluation (imaginary part)
637: - ctx - optional context, as set by EPSSetArbitrarySelection()
639: Notes:
640: This provides a mechanism to select eigenpairs by evaluating a user-defined
641: function. When a function has been provided, the default selection based on
642: sorting the eigenvalues is replaced by the sorting of the results of this
643: function (with the same sorting criterion given in EPSSetWhichEigenpairs()).
645: For instance, suppose you want to compute those eigenvectors that maximize
646: a certain computable expression. Then implement the computation using
647: the arguments xr and xi, and return the result in rr. Then set the standard
648: sorting by magnitude so that the eigenpair with largest value of rr is
649: selected.
651: This evaluation function is collective, that is, all processes call it and
652: it can use collective operations; furthermore, the computed result must
653: be the same in all processes.
655: The result of func is expressed as a complex number so that it is possible to
656: use the standard eigenvalue sorting functions, but normally only rr is used.
657: Set ri to zero unless it is meaningful in your application.
659: Level: advanced
661: .seealso: EPSSetWhichEigenpairs()
662: @*/
663: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
664: {
667: eps->arbitrary = func;
668: eps->arbitraryctx = ctx;
669: eps->state = EPS_STATE_INITIAL;
670: return(0);
671: }
673: /*@C
674: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
675: used in the convergence test.
677: Logically Collective on EPS
679: Input Parameters:
680: + eps - eigensolver context obtained from EPSCreate()
681: . func - a pointer to the convergence test function
682: . ctx - context for private data for the convergence routine (may be null)
683: - destroy - a routine for destroying the context (may be null)
685: Calling Sequence of func:
686: $ func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
688: + eps - eigensolver context obtained from EPSCreate()
689: . eigr - real part of the eigenvalue
690: . eigi - imaginary part of the eigenvalue
691: . res - residual norm associated to the eigenpair
692: . errest - (output) computed error estimate
693: - ctx - optional context, as set by EPSSetConvergenceTestFunction()
695: Note:
696: If the error estimate returned by the convergence test function is less than
697: the tolerance, then the eigenvalue is accepted as converged.
699: Level: advanced
701: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
702: @*/
703: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
704: {
709: if (eps->convergeddestroy) {
710: (*eps->convergeddestroy)(eps->convergedctx);
711: }
712: eps->convergeduser = func;
713: eps->convergeddestroy = destroy;
714: eps->convergedctx = ctx;
715: if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
716: else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
717: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
718: else {
719: eps->conv = EPS_CONV_USER;
720: eps->converged = eps->convergeduser;
721: }
722: return(0);
723: }
725: /*@
726: EPSSetConvergenceTest - Specifies how to compute the error estimate
727: used in the convergence test.
729: Logically Collective on EPS
731: Input Parameters:
732: + eps - eigensolver context obtained from EPSCreate()
733: - conv - the type of convergence test
735: Options Database Keys:
736: + -eps_conv_abs - Sets the absolute convergence test
737: . -eps_conv_rel - Sets the convergence test relative to the eigenvalue
738: . -eps_conv_norm - Sets the convergence test relative to the matrix norms
739: - -eps_conv_user - Selects the user-defined convergence test
741: Note:
742: The parameter 'conv' can have one of these values
743: + EPS_CONV_ABS - absolute error ||r||
744: . EPS_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
745: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
746: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
748: Level: intermediate
750: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
751: @*/
752: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
753: {
757: switch (conv) {
758: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
759: case EPS_CONV_REL: eps->converged = EPSConvergedRelative; break;
760: case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
761: case EPS_CONV_USER:
762: if (!eps->convergeduser) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetConvergenceTestFunction() first");
763: eps->converged = eps->convergeduser;
764: break;
765: default:
766: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
767: }
768: eps->conv = conv;
769: return(0);
770: }
772: /*@
773: EPSGetConvergenceTest - Gets the method used to compute the error estimate
774: used in the convergence test.
776: Not Collective
778: Input Parameters:
779: . eps - eigensolver context obtained from EPSCreate()
781: Output Parameters:
782: . conv - the type of convergence test
784: Level: intermediate
786: .seealso: EPSSetConvergenceTest(), EPSConv
787: @*/
788: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
789: {
793: *conv = eps->conv;
794: return(0);
795: }
797: /*@C
798: EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
799: iteration of the eigensolver.
801: Logically Collective on EPS
803: Input Parameters:
804: + eps - eigensolver context obtained from EPSCreate()
805: . func - pointer to the stopping test function
806: . ctx - context for private data for the stopping routine (may be null)
807: - destroy - a routine for destroying the context (may be null)
809: Calling Sequence of func:
810: $ func(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx)
812: + eps - eigensolver context obtained from EPSCreate()
813: . its - current number of iterations
814: . max_it - maximum number of iterations
815: . nconv - number of currently converged eigenpairs
816: . nev - number of requested eigenpairs
817: . reason - (output) result of the stopping test
818: - ctx - optional context, as set by EPSSetStoppingTestFunction()
820: Note:
821: Normal usage is to first call the default routine EPSStoppingBasic() and then
822: set reason to EPS_CONVERGED_USER if some user-defined conditions have been
823: met. To let the eigensolver continue iterating, the result must be left as
824: EPS_CONVERGED_ITERATING.
826: Level: advanced
828: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
829: @*/
830: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
831: {
836: if (eps->stoppingdestroy) {
837: (*eps->stoppingdestroy)(eps->stoppingctx);
838: }
839: eps->stoppinguser = func;
840: eps->stoppingdestroy = destroy;
841: eps->stoppingctx = ctx;
842: if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
843: else {
844: eps->stop = EPS_STOP_USER;
845: eps->stopping = eps->stoppinguser;
846: }
847: return(0);
848: }
850: /*@
851: EPSSetStoppingTest - Specifies how to decide the termination of the outer
852: loop of the eigensolver.
854: Logically Collective on EPS
856: Input Parameters:
857: + eps - eigensolver context obtained from EPSCreate()
858: - stop - the type of stopping test
860: Options Database Keys:
861: + -eps_stop_basic - Sets the default stopping test
862: - -eps_stop_user - Selects the user-defined stopping test
864: Note:
865: The parameter 'stop' can have one of these values
866: + EPS_STOP_BASIC - default stopping test
867: - EPS_STOP_USER - function set by EPSSetStoppingTestFunction()
869: Level: advanced
871: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
872: @*/
873: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
874: {
878: switch (stop) {
879: case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
880: case EPS_STOP_USER:
881: if (!eps->stoppinguser) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetStoppingTestFunction() first");
882: eps->stopping = eps->stoppinguser;
883: break;
884: default:
885: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
886: }
887: eps->stop = stop;
888: return(0);
889: }
891: /*@
892: EPSGetStoppingTest - Gets the method used to decide the termination of the outer
893: loop of the eigensolver.
895: Not Collective
897: Input Parameters:
898: . eps - eigensolver context obtained from EPSCreate()
900: Output Parameters:
901: . stop - the type of stopping test
903: Level: advanced
905: .seealso: EPSSetStoppingTest(), EPSStop
906: @*/
907: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
908: {
912: *stop = eps->stop;
913: return(0);
914: }
916: /*@
917: EPSSetProblemType - Specifies the type of the eigenvalue problem.
919: Logically Collective on EPS
921: Input Parameters:
922: + eps - the eigensolver context
923: - type - a known type of eigenvalue problem
925: Options Database Keys:
926: + -eps_hermitian - Hermitian eigenvalue problem
927: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
928: . -eps_non_hermitian - non-Hermitian eigenvalue problem
929: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
930: - -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
931: with positive semi-definite B
933: Notes:
934: Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
935: (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
936: (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
937: (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).
939: This function must be used to instruct SLEPc to exploit symmetry. If no
940: problem type is specified, by default a non-Hermitian problem is assumed
941: (either standard or generalized). If the user knows that the problem is
942: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
943: B positive definite) then it is recommended to set the problem type so
944: that eigensolver can exploit these properties.
946: Level: intermediate
948: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
949: @*/
950: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
951: {
955: if (type == eps->problem_type) return(0);
956: switch (type) {
957: case EPS_HEP:
958: eps->isgeneralized = PETSC_FALSE;
959: eps->ishermitian = PETSC_TRUE;
960: eps->ispositive = PETSC_FALSE;
961: break;
962: case EPS_NHEP:
963: eps->isgeneralized = PETSC_FALSE;
964: eps->ishermitian = PETSC_FALSE;
965: eps->ispositive = PETSC_FALSE;
966: break;
967: case EPS_GHEP:
968: eps->isgeneralized = PETSC_TRUE;
969: eps->ishermitian = PETSC_TRUE;
970: eps->ispositive = PETSC_TRUE;
971: break;
972: case EPS_GNHEP:
973: eps->isgeneralized = PETSC_TRUE;
974: eps->ishermitian = PETSC_FALSE;
975: eps->ispositive = PETSC_FALSE;
976: break;
977: case EPS_PGNHEP:
978: eps->isgeneralized = PETSC_TRUE;
979: eps->ishermitian = PETSC_FALSE;
980: eps->ispositive = PETSC_TRUE;
981: break;
982: case EPS_GHIEP:
983: eps->isgeneralized = PETSC_TRUE;
984: eps->ishermitian = PETSC_TRUE;
985: eps->ispositive = PETSC_FALSE;
986: break;
987: default:
988: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
989: }
990: eps->problem_type = type;
991: eps->state = EPS_STATE_INITIAL;
992: return(0);
993: }
995: /*@
996: EPSGetProblemType - Gets the problem type from the EPS object.
998: Not Collective
1000: Input Parameter:
1001: . eps - the eigensolver context
1003: Output Parameter:
1004: . type - the problem type
1006: Level: intermediate
1008: .seealso: EPSSetProblemType(), EPSProblemType
1009: @*/
1010: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
1011: {
1015: *type = eps->problem_type;
1016: return(0);
1017: }
1019: /*@
1020: EPSSetExtraction - Specifies the type of extraction technique to be employed
1021: by the eigensolver.
1023: Logically Collective on EPS
1025: Input Parameters:
1026: + eps - the eigensolver context
1027: - extr - a known type of extraction
1029: Options Database Keys:
1030: + -eps_ritz - Rayleigh-Ritz extraction
1031: . -eps_harmonic - harmonic Ritz extraction
1032: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
1033: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
1034: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
1035: (without target)
1036: . -eps_refined - refined Ritz extraction
1037: - -eps_refined_harmonic - refined harmonic Ritz extraction
1039: Notes:
1040: Not all eigensolvers support all types of extraction. See the SLEPc
1041: Users Manual for details.
1043: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
1044: may be useful when computing interior eigenvalues.
1046: Harmonic-type extractions are used in combination with a 'target'.
1048: Level: advanced
1050: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
1051: @*/
1052: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
1053: {
1057: eps->extraction = extr;
1058: return(0);
1059: }
1061: /*@
1062: EPSGetExtraction - Gets the extraction type used by the EPS object.
1064: Not Collective
1066: Input Parameter:
1067: . eps - the eigensolver context
1069: Output Parameter:
1070: . extr - name of extraction type
1072: Level: advanced
1074: .seealso: EPSSetExtraction(), EPSExtraction
1075: @*/
1076: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1077: {
1081: *extr = eps->extraction;
1082: return(0);
1083: }
1085: /*@
1086: EPSSetBalance - Specifies the balancing technique to be employed by the
1087: eigensolver, and some parameters associated to it.
1089: Logically Collective on EPS
1091: Input Parameters:
1092: + eps - the eigensolver context
1093: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1094: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1095: . its - number of iterations of the balancing algorithm
1096: - cutoff - cutoff value
1098: Options Database Keys:
1099: + -eps_balance <method> - the balancing method, where <method> is one of
1100: 'none', 'oneside', 'twoside', or 'user'
1101: . -eps_balance_its <its> - number of iterations
1102: - -eps_balance_cutoff <cutoff> - cutoff value
1104: Notes:
1105: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1106: where D is an appropriate diagonal matrix. This improves the accuracy of
1107: the computed results in some cases. See the SLEPc Users Manual for details.
1109: Balancing makes sense only for non-Hermitian problems when the required
1110: precision is high (i.e. a small tolerance such as 1e-15).
1112: By default, balancing is disabled. The two-sided method is much more
1113: effective than the one-sided counterpart, but it requires the system
1114: matrices to have the MatMultTranspose operation defined.
1116: The parameter 'its' is the number of iterations performed by the method. The
1117: cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
1118: a reasonably good value.
1120: User-defined balancing is allowed provided that the corresponding matrix
1121: is set via STSetBalanceMatrix.
1123: Level: intermediate
1125: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1126: @*/
1127: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1128: {
1134: switch (bal) {
1135: case EPS_BALANCE_NONE:
1136: case EPS_BALANCE_ONESIDE:
1137: case EPS_BALANCE_TWOSIDE:
1138: case EPS_BALANCE_USER:
1139: if (eps->balance != bal) {
1140: eps->state = EPS_STATE_INITIAL;
1141: eps->balance = bal;
1142: }
1143: break;
1144: default:
1145: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1146: }
1147: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1148: else {
1149: if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1150: eps->balance_its = its;
1151: }
1152: if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1153: else {
1154: if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1155: eps->balance_cutoff = cutoff;
1156: }
1157: return(0);
1158: }
1160: /*@C
1161: EPSGetBalance - Gets the balancing type used by the EPS object, and the
1162: associated parameters.
1164: Not Collective
1166: Input Parameter:
1167: . eps - the eigensolver context
1169: Output Parameters:
1170: + bal - the balancing method
1171: . its - number of iterations of the balancing algorithm
1172: - cutoff - cutoff value
1174: Level: intermediate
1176: Note:
1177: The user can specify NULL for any parameter that is not needed.
1179: .seealso: EPSSetBalance(), EPSBalance
1180: @*/
1181: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1182: {
1185: if (bal) *bal = eps->balance;
1186: if (its) *its = eps->balance_its;
1187: if (cutoff) *cutoff = eps->balance_cutoff;
1188: return(0);
1189: }
1191: /*@
1192: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1193: explicitly or not.
1195: Logically Collective on EPS
1197: Input Parameters:
1198: + eps - the eigensolver context
1199: - trueres - whether true residuals are required or not
1201: Options Database Keys:
1202: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1204: Notes:
1205: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1206: the true residual for each eigenpair approximation, and uses it for
1207: convergence testing. Computing the residual is usually an expensive
1208: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1209: by using a cheap estimate of the residual norm, but this may sometimes
1210: give inaccurate results (especially if a spectral transform is being
1211: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1212: do rely on computing the true residual, so this option is irrelevant for them.
1214: Level: advanced
1216: .seealso: EPSGetTrueResidual()
1217: @*/
1218: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1219: {
1223: eps->trueres = trueres;
1224: return(0);
1225: }
1227: /*@
1228: EPSGetTrueResidual - Returns the flag indicating whether true
1229: residuals must be computed explicitly or not.
1231: Not Collective
1233: Input Parameter:
1234: . eps - the eigensolver context
1236: Output Parameter:
1237: . trueres - the returned flag
1239: Level: advanced
1241: .seealso: EPSSetTrueResidual()
1242: @*/
1243: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1244: {
1248: *trueres = eps->trueres;
1249: return(0);
1250: }
1252: /*@
1253: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1254: approximate eigenpairs or not.
1256: Logically Collective on EPS
1258: Input Parameters:
1259: + eps - the eigensolver context
1260: - trackall - whether to compute all residuals or not
1262: Notes:
1263: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1264: the residual norm for each eigenpair approximation. Computing the residual is
1265: usually an expensive operation and solvers commonly compute only the residual
1266: associated to the first unconverged eigenpair.
1268: The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1269: activate this option.
1271: Level: developer
1273: .seealso: EPSGetTrackAll()
1274: @*/
1275: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1276: {
1280: eps->trackall = trackall;
1281: return(0);
1282: }
1284: /*@
1285: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1286: be computed or not.
1288: Not Collective
1290: Input Parameter:
1291: . eps - the eigensolver context
1293: Output Parameter:
1294: . trackall - the returned flag
1296: Level: developer
1298: .seealso: EPSSetTrackAll()
1299: @*/
1300: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1301: {
1305: *trackall = eps->trackall;
1306: return(0);
1307: }
1309: /*@
1310: EPSSetPurify - Deactivate eigenvector purification (which is activated by default).
1312: Logically Collective on EPS
1314: Input Parameters:
1315: + eps - the eigensolver context
1316: - purify - whether purification is required or not
1318: Options Database Keys:
1319: . -eps_purify <boolean> - Sets/resets the boolean flag 'purify'
1321: Notes:
1322: By default, eigenvectors of generalized symmetric eigenproblems are purified
1323: in order to purge directions in the nullspace of matrix B. If the user knows
1324: that B is non-singular, then purification can be safely deactivated and some
1325: computational cost is avoided (this is particularly important in interval computations).
1327: Level: intermediate
1329: .seealso: EPSGetPurify(), EPSSetInterval()
1330: @*/
1331: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1332: {
1336: eps->purify = purify;
1337: if (purify && !eps->purify) eps->state = EPS_STATE_INITIAL;
1338: return(0);
1339: }
1341: /*@
1342: EPSGetPurify - Returns the flag indicating whether purification is activated
1343: or not.
1345: Not Collective
1347: Input Parameter:
1348: . eps - the eigensolver context
1350: Output Parameter:
1351: . purify - the returned flag
1353: Level: intermediate
1355: .seealso: EPSSetPurify()
1356: @*/
1357: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1358: {
1362: *purify = eps->purify;
1363: return(0);
1364: }
1366: /*@C
1367: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1368: EPS options in the database.
1370: Logically Collective on EPS
1372: Input Parameters:
1373: + eps - the eigensolver context
1374: - prefix - the prefix string to prepend to all EPS option requests
1376: Notes:
1377: A hyphen (-) must NOT be given at the beginning of the prefix name.
1378: The first character of all runtime options is AUTOMATICALLY the
1379: hyphen.
1381: For example, to distinguish between the runtime options for two
1382: different EPS contexts, one could call
1383: .vb
1384: EPSSetOptionsPrefix(eps1,"eig1_")
1385: EPSSetOptionsPrefix(eps2,"eig2_")
1386: .ve
1388: Level: advanced
1390: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1391: @*/
1392: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1393: {
1398: if (!eps->st) { EPSGetST(eps,&eps->st); }
1399: STSetOptionsPrefix(eps->st,prefix);
1400: if (!eps->V) { EPSGetBV(eps,&eps->V); }
1401: BVSetOptionsPrefix(eps->V,prefix);
1402: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1403: DSSetOptionsPrefix(eps->ds,prefix);
1404: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1405: RGSetOptionsPrefix(eps->rg,prefix);
1406: PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1407: return(0);
1408: }
1410: /*@C
1411: EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1412: EPS options in the database.
1414: Logically Collective on EPS
1416: Input Parameters:
1417: + eps - the eigensolver context
1418: - prefix - the prefix string to prepend to all EPS option requests
1420: Notes:
1421: A hyphen (-) must NOT be given at the beginning of the prefix name.
1422: The first character of all runtime options is AUTOMATICALLY the hyphen.
1424: Level: advanced
1426: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1427: @*/
1428: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1429: {
1434: if (!eps->st) { EPSGetST(eps,&eps->st); }
1435: STAppendOptionsPrefix(eps->st,prefix);
1436: if (!eps->V) { EPSGetBV(eps,&eps->V); }
1437: BVAppendOptionsPrefix(eps->V,prefix);
1438: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1439: DSAppendOptionsPrefix(eps->ds,prefix);
1440: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1441: RGAppendOptionsPrefix(eps->rg,prefix);
1442: PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1443: return(0);
1444: }
1446: /*@C
1447: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1448: EPS options in the database.
1450: Not Collective
1452: Input Parameters:
1453: . eps - the eigensolver context
1455: Output Parameters:
1456: . prefix - pointer to the prefix string used is returned
1458: Note:
1459: On the Fortran side, the user should pass in a string 'prefix' of
1460: sufficient length to hold the prefix.
1462: Level: advanced
1464: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1465: @*/
1466: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1467: {
1473: PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1474: return(0);
1475: }