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-2016, 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*/
26: #include <petscdraw.h>
30: /*@C
31: EPSMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
32: indicated by the user.
34: Collective on EPS 36: Input Parameters:
37: + eps - the eigensolver context
38: . name - the monitor option name
39: . help - message indicating what monitoring is done
40: . manual - manual page for the monitor
41: . monitor - the monitor function, whose context is a PetscViewerAndFormat
42: - trackall - whether this monitor tracks all eigenvalues or not
44: Level: developer
46: .seealso: EPSMonitorSet(), EPSSetTrackAll(), EPSConvMonitorSetFromOptions()
47: @*/
48: 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) 49: {
50: PetscErrorCode ierr;
51: PetscBool flg;
52: PetscViewer viewer;
53: PetscViewerFormat format;
54: PetscViewerAndFormat *vf;
57: PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->prefix,name,&viewer,&format,&flg);
58: if (flg) {
59: PetscViewerAndFormatCreate(viewer,format,&vf);
60: PetscObjectDereference((PetscObject)viewer);
61: EPSMonitorSet(eps,(PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
62: if (trackall) {
63: EPSSetTrackAll(eps,PETSC_TRUE);
64: }
65: }
66: return(0);
67: }
71: /*@C
72: EPSConvMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
73: indicated by the user (for monitors that only show iteration numbers of convergence).
75: Collective on EPS 77: Input Parameters:
78: + eps - the eigensolver context
79: . name - the monitor option name
80: . help - message indicating what monitoring is done
81: . manual - manual page for the monitor
82: - monitor - the monitor function, whose context is a SlepcConvMonitor
84: Level: developer
86: .seealso: EPSMonitorSet(), EPSMonitorSetFromOptions()
87: @*/
88: PetscErrorCode EPSConvMonitorSetFromOptions(EPS eps,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor)) 89: {
90: PetscErrorCode ierr;
91: PetscBool flg;
92: PetscViewer viewer;
93: PetscViewerFormat format;
94: SlepcConvMonitor ctx;
97: PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->prefix,name,&viewer,&format,&flg);
98: if (flg) {
99: SlepcConvMonitorCreate(viewer,format,&ctx);
100: PetscObjectDereference((PetscObject)viewer);
101: EPSMonitorSet(eps,(PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*))monitor,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
102: }
103: return(0);
104: }
108: /*@
109: EPSSetFromOptions - Sets EPS options from the options database.
110: This routine must be called before EPSSetUp() if the user is to be
111: allowed to set the solver type.
113: Collective on EPS115: Input Parameters:
116: . eps - the eigensolver context
118: Notes:
119: To see all options, run your program with the -help option.
121: Level: beginner
122: @*/
123: PetscErrorCode EPSSetFromOptions(EPS eps)124: {
126: char type[256];
127: PetscBool set,flg,flg1,flg2,flg3;
128: PetscReal r,array[2]={0,0};
129: PetscScalar s;
130: PetscInt i,j,k;
131: PetscDrawLG lg;
135: EPSRegisterAll();
136: PetscObjectOptionsBegin((PetscObject)eps);
137: PetscOptionsFList("-eps_type","Eigenvalue Problem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
138: if (flg) {
139: EPSSetType(eps,type);
140: }
141: /*
142: Set the type if it was never set.
143: */
144: if (!((PetscObject)eps)->type_name) {
145: EPSSetType(eps,EPSKRYLOVSCHUR);
146: }
148: PetscOptionsBoolGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);
149: if (flg) { EPSSetProblemType(eps,EPS_HEP); }
150: PetscOptionsBoolGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);
151: if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
152: PetscOptionsBoolGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
153: if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
154: PetscOptionsBoolGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
155: if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
156: PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
157: if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
158: PetscOptionsBoolGroupEnd("-eps_gen_indefinite","generalized hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
159: if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }
161: PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
162: if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
163: PetscOptionsBoolGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);
164: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
165: PetscOptionsBoolGroup("-eps_harmonic_relative","relative harmonic Ritz extraction","EPSSetExtraction",&flg);
166: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
167: PetscOptionsBoolGroup("-eps_harmonic_right","right harmonic Ritz extraction","EPSSetExtraction",&flg);
168: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
169: PetscOptionsBoolGroup("-eps_harmonic_largest","largest harmonic Ritz extraction","EPSSetExtraction",&flg);
170: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
171: PetscOptionsBoolGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);
172: if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
173: PetscOptionsBoolGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);
174: if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }
176: PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)eps->balance,(PetscEnum*)&eps->balance,NULL);
178: j = eps->balance_its;
179: PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg1);
180: r = eps->balance_cutoff;
181: PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg2);
182: if (flg1 || flg2) {
183: EPSSetBalance(eps,eps->balance,j,r);
184: }
186: i = eps->max_it? eps->max_it: PETSC_DEFAULT;
187: PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
188: r = eps->tol;
189: PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,&flg2);
190: if (flg1 || flg2) {
191: EPSSetTolerances(eps,r,i);
192: }
194: PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
195: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_REL); }
196: PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
197: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
198: PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
199: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
200: PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
201: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_USER); }
203: PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg);
204: if (flg) { EPSSetStoppingTest(eps,EPS_STOP_BASIC); }
205: PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg);
206: if (flg) { EPSSetStoppingTest(eps,EPS_STOP_USER); }
208: i = eps->nev;
209: PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
210: j = eps->ncv? eps->ncv: PETSC_DEFAULT;
211: PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
212: k = eps->mpd? eps->mpd: PETSC_DEFAULT;
213: PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
214: if (flg1 || flg2 || flg3) {
215: EPSSetDimensions(eps,i,j,k);
216: }
218: /* -----------------------------------------------------------------------*/
219: /*
220: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
221: */
222: PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
223: if (set && flg) {
224: EPSMonitorCancel(eps);
225: }
226: /*
227: Text monitors
228: */
229: EPSMonitorSetFromOptions(eps,"-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorFirst",EPSMonitorFirst,PETSC_FALSE);
230: EPSConvMonitorSetFromOptions(eps,"-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorConverged",EPSMonitorConverged);
231: EPSMonitorSetFromOptions(eps,"-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorAll",EPSMonitorAll,PETSC_TRUE);
232: /*
233: Line graph monitors
234: */
235: PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",PETSC_FALSE,&flg,&set);
236: if (set && flg) {
237: EPSMonitorLGCreate(PetscObjectComm((PetscObject)eps),NULL,"Error estimates",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
238: EPSMonitorSet(eps,EPSMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
239: }
240: PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",PETSC_FALSE,&flg,&set);
241: if (set && flg) {
242: EPSMonitorLGCreate(PetscObjectComm((PetscObject)eps),NULL,"Error estimates",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
243: EPSMonitorSet(eps,EPSMonitorLGAll,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
244: EPSSetTrackAll(eps,PETSC_TRUE);
245: }
246: /* -----------------------------------------------------------------------*/
247: PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
248: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
249: PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
250: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
251: PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
252: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
253: PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
254: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
255: PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
256: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
257: PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
258: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
259: PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);
260: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
261: PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);
262: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
263: PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);
264: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
265: PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg);
266: if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }
268: PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
269: if (flg) {
270: if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) {
271: EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
272: }
273: EPSSetTarget(eps,s);
274: }
275: k = 2;
276: PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
277: if (flg) {
278: if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
279: EPSSetWhichEigenpairs(eps,EPS_ALL);
280: EPSSetInterval(eps,array[0],array[1]);
281: }
283: PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
284: PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&eps->purify,NULL);
286: PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
287: PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
288: PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
289: PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSReasonView",NULL);
290: PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
291: PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
292: PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);
294: if (eps->ops->setfromoptions) {
295: (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
296: }
297: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)eps);
298: PetscOptionsEnd();
300: if (!eps->V) { EPSGetBV(eps,&eps->V); }
301: BVSetFromOptions(eps->V);
302: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
303: RGSetFromOptions(eps->rg);
304: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
305: DSSetFromOptions(eps->ds);
306: if (!eps->st) { EPSGetST(eps,&eps->st); }
307: STSetFromOptions(eps->st);
308: return(0);
309: }
313: /*@
314: EPSGetTolerances - Gets the tolerance and maximum iteration count used
315: by the EPS convergence tests.
317: Not Collective
319: Input Parameter:
320: . eps - the eigensolver context
322: Output Parameters:
323: + tol - the convergence tolerance
324: - maxits - maximum number of iterations
326: Notes:
327: The user can specify NULL for any parameter that is not needed.
329: Level: intermediate
331: .seealso: EPSSetTolerances()
332: @*/
333: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)334: {
337: if (tol) *tol = eps->tol;
338: if (maxits) *maxits = eps->max_it;
339: return(0);
340: }
344: /*@
345: EPSSetTolerances - Sets the tolerance and maximum iteration count used
346: by the EPS convergence tests.
348: Logically Collective on EPS350: Input Parameters:
351: + eps - the eigensolver context
352: . tol - the convergence tolerance
353: - maxits - maximum number of iterations to use
355: Options Database Keys:
356: + -eps_tol <tol> - Sets the convergence tolerance
357: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
359: Notes:
360: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
362: Level: intermediate
364: .seealso: EPSGetTolerances()
365: @*/
366: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)367: {
372: if (tol == PETSC_DEFAULT) {
373: eps->tol = PETSC_DEFAULT;
374: eps->state = EPS_STATE_INITIAL;
375: } else {
376: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
377: eps->tol = tol;
378: }
379: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
380: eps->max_it = 0;
381: eps->state = EPS_STATE_INITIAL;
382: } else {
383: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
384: eps->max_it = maxits;
385: }
386: return(0);
387: }
391: /*@
392: EPSGetDimensions - Gets the number of eigenvalues to compute
393: and the dimension of the subspace.
395: Not Collective
397: Input Parameter:
398: . eps - the eigensolver context
400: Output Parameters:
401: + nev - number of eigenvalues to compute
402: . ncv - the maximum dimension of the subspace to be used by the solver
403: - mpd - the maximum dimension allowed for the projected problem
405: Level: intermediate
407: .seealso: EPSSetDimensions()
408: @*/
409: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)410: {
413: if (nev) *nev = eps->nev;
414: if (ncv) *ncv = eps->ncv;
415: if (mpd) *mpd = eps->mpd;
416: return(0);
417: }
421: /*@
422: EPSSetDimensions - Sets the number of eigenvalues to compute
423: and the dimension of the subspace.
425: Logically Collective on EPS427: Input Parameters:
428: + eps - the eigensolver context
429: . nev - number of eigenvalues to compute
430: . ncv - the maximum dimension of the subspace to be used by the solver
431: - mpd - the maximum dimension allowed for the projected problem
433: Options Database Keys:
434: + -eps_nev <nev> - Sets the number of eigenvalues
435: . -eps_ncv <ncv> - Sets the dimension of the subspace
436: - -eps_mpd <mpd> - Sets the maximum projected dimension
438: Notes:
439: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
440: dependent on the solution method.
442: The parameters ncv and mpd are intimately related, so that the user is advised
443: to set one of them at most. Normal usage is that
444: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
445: (b) in cases where nev is large, the user sets mpd.
447: The value of ncv should always be between nev and (nev+mpd), typically
448: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
449: a smaller value should be used.
451: When computing all eigenvalues in an interval, see EPSSetInterval(), these
452: parameters lose relevance, and tuning must be done with
453: EPSKrylovSchurSetDimensions().
455: Level: intermediate
457: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
458: @*/
459: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)460: {
466: if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
467: eps->nev = nev;
468: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
469: eps->ncv = 0;
470: } else {
471: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
472: eps->ncv = ncv;
473: }
474: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
475: eps->mpd = 0;
476: } else {
477: if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
478: eps->mpd = mpd;
479: }
480: eps->state = EPS_STATE_INITIAL;
481: return(0);
482: }
486: /*@
487: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
488: to be sought.
490: Logically Collective on EPS492: Input Parameters:
493: + eps - eigensolver context obtained from EPSCreate()
494: - which - the portion of the spectrum to be sought
496: Possible values:
497: The parameter 'which' can have one of these values
499: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
500: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
501: . EPS_LARGEST_REAL - largest real parts
502: . EPS_SMALLEST_REAL - smallest real parts
503: . EPS_LARGEST_IMAGINARY - largest imaginary parts
504: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
505: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
506: . EPS_TARGET_REAL - eigenvalues with real part closest to target
507: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
508: . EPS_ALL - all eigenvalues contained in a given interval or region
509: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
511: Options Database Keys:
512: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
513: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
514: . -eps_largest_real - Sets largest real parts
515: . -eps_smallest_real - Sets smallest real parts
516: . -eps_largest_imaginary - Sets largest imaginary parts
517: . -eps_smallest_imaginary - Sets smallest imaginary parts
518: . -eps_target_magnitude - Sets eigenvalues closest to target
519: . -eps_target_real - Sets real parts closest to target
520: . -eps_target_imaginary - Sets imaginary parts closest to target
521: - -eps_all - Sets all eigenvalues in an interval or region
523: Notes:
524: Not all eigensolvers implemented in EPS account for all the possible values
525: stated above. Also, some values make sense only for certain types of
526: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
527: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
528: for eigenvalue selection.
530: The target is a scalar value provided with EPSSetTarget().
532: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
533: SLEPc have been built with complex scalars.
535: EPS_ALL is intended for use in combination with an interval (see
536: EPSSetInterval()), when all eigenvalues within the interval are requested,
537: or in the context of the CISS solver for computing all eigenvalues in a region.
538: In those cases, the number of eigenvalues is unknown, so the nev parameter
539: has a different sense, see EPSSetDimensions().
541: Level: intermediate
543: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
544: EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich545: @*/
546: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)547: {
551: switch (which) {
552: case EPS_LARGEST_MAGNITUDE:
553: case EPS_SMALLEST_MAGNITUDE:
554: case EPS_LARGEST_REAL:
555: case EPS_SMALLEST_REAL:
556: case EPS_LARGEST_IMAGINARY:
557: case EPS_SMALLEST_IMAGINARY:
558: case EPS_TARGET_MAGNITUDE:
559: case EPS_TARGET_REAL:
560: #if defined(PETSC_USE_COMPLEX)
561: case EPS_TARGET_IMAGINARY:
562: #endif
563: case EPS_ALL:
564: case EPS_WHICH_USER:
565: if (eps->which != which) {
566: eps->state = EPS_STATE_INITIAL;
567: eps->which = which;
568: }
569: break;
570: default:571: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
572: }
573: return(0);
574: }
578: /*@
579: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
580: sought.
582: Not Collective
584: Input Parameter:
585: . eps - eigensolver context obtained from EPSCreate()
587: Output Parameter:
588: . which - the portion of the spectrum to be sought
590: Notes:
591: See EPSSetWhichEigenpairs() for possible values of 'which'.
593: Level: intermediate
595: .seealso: EPSSetWhichEigenpairs(), EPSWhich596: @*/
597: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)598: {
602: *which = eps->which;
603: return(0);
604: }
608: /*@C
609: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
610: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
612: Logically Collective on EPS614: Input Parameters:
615: + eps - eigensolver context obtained from EPSCreate()
616: . func - a pointer to the comparison function
617: - ctx - a context pointer (the last parameter to the comparison function)
619: Calling Sequence of func:
620: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
622: + ar - real part of the 1st eigenvalue
623: . ai - imaginary part of the 1st eigenvalue
624: . br - real part of the 2nd eigenvalue
625: . bi - imaginary part of the 2nd eigenvalue
626: . res - result of comparison
627: - ctx - optional context, as set by EPSSetEigenvalueComparison()
629: Note:
630: The returning parameter 'res' can be:
631: + negative - if the 1st eigenvalue is preferred to the 2st one
632: . zero - if both eigenvalues are equally preferred
633: - positive - if the 2st eigenvalue is preferred to the 1st one
635: Level: advanced
637: .seealso: EPSSetWhichEigenpairs(), EPSWhich638: @*/
639: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)640: {
643: eps->sc->comparison = func;
644: eps->sc->comparisonctx = ctx;
645: eps->which = EPS_WHICH_USER;
646: return(0);
647: }
651: /*@C
652: EPSSetArbitrarySelection - Specifies a function intended to look for
653: eigenvalues according to an arbitrary selection criterion. This criterion
654: can be based on a computation involving the current eigenvector approximation.
656: Logically Collective on EPS658: Input Parameters:
659: + eps - eigensolver context obtained from EPSCreate()
660: . func - a pointer to the evaluation function
661: - ctx - a context pointer (the last parameter to the evaluation function)
663: Calling Sequence of func:
664: $ func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
666: + er - real part of the current eigenvalue approximation
667: . ei - imaginary part of the current eigenvalue approximation
668: . xr - real part of the current eigenvector approximation
669: . xi - imaginary part of the current eigenvector approximation
670: . rr - result of evaluation (real part)
671: . ri - result of evaluation (imaginary part)
672: - ctx - optional context, as set by EPSSetArbitrarySelection()
674: Notes:
675: This provides a mechanism to select eigenpairs by evaluating a user-defined
676: function. When a function has been provided, the default selection based on
677: sorting the eigenvalues is replaced by the sorting of the results of this
678: function (with the same sorting criterion given in EPSSetWhichEigenpairs()).
680: For instance, suppose you want to compute those eigenvectors that maximize
681: a certain computable expression. Then implement the computation using
682: the arguments xr and xi, and return the result in rr. Then set the standard
683: sorting by magnitude so that the eigenpair with largest value of rr is
684: selected.
686: This evaluation function is collective, that is, all processes call it and
687: it can use collective operations; furthermore, the computed result must
688: be the same in all processes.
690: The result of func is expressed as a complex number so that it is possible to
691: use the standard eigenvalue sorting functions, but normally only rr is used.
692: Set ri to zero unless it is meaningful in your application.
694: Level: advanced
696: .seealso: EPSSetWhichEigenpairs()
697: @*/
698: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)699: {
702: eps->arbitrary = func;
703: eps->arbitraryctx = ctx;
704: eps->state = EPS_STATE_INITIAL;
705: return(0);
706: }
710: /*@C
711: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
712: used in the convergence test.
714: Logically Collective on EPS716: Input Parameters:
717: + eps - eigensolver context obtained from EPSCreate()
718: . func - a pointer to the convergence test function
719: . ctx - context for private data for the convergence routine (may be null)
720: - destroy - a routine for destroying the context (may be null)
722: Calling Sequence of func:
723: $ func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
725: + eps - eigensolver context obtained from EPSCreate()
726: . eigr - real part of the eigenvalue
727: . eigi - imaginary part of the eigenvalue
728: . res - residual norm associated to the eigenpair
729: . errest - (output) computed error estimate
730: - ctx - optional context, as set by EPSSetConvergenceTestFunction()
732: Note:
733: If the error estimate returned by the convergence test function is less than
734: the tolerance, then the eigenvalue is accepted as converged.
736: Level: advanced
738: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
739: @*/
740: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))741: {
746: if (eps->convergeddestroy) {
747: (*eps->convergeddestroy)(eps->convergedctx);
748: }
749: eps->converged = func;
750: eps->convergeddestroy = destroy;
751: eps->convergedctx = ctx;
752: if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
753: else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
754: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
755: else eps->conv = EPS_CONV_USER;
756: return(0);
757: }
761: /*@
762: EPSSetConvergenceTest - Specifies how to compute the error estimate
763: used in the convergence test.
765: Logically Collective on EPS767: Input Parameters:
768: + eps - eigensolver context obtained from EPSCreate()
769: - conv - the type of convergence test
771: Options Database Keys:
772: + -eps_conv_abs - Sets the absolute convergence test
773: . -eps_conv_rel - Sets the convergence test relative to the eigenvalue
774: . -eps_conv_norm - Sets the convergence test relative to the matrix norms
775: - -eps_conv_user - Selects the user-defined convergence test
777: Note:
778: The parameter 'conv' can have one of these values
779: + EPS_CONV_ABS - absolute error ||r||
780: . EPS_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
781: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
782: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
784: Level: intermediate
786: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv787: @*/
788: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)789: {
793: switch (conv) {
794: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
795: case EPS_CONV_REL: eps->converged = EPSConvergedRelative; break;
796: case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
797: case EPS_CONV_USER: break;
798: default:799: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
800: }
801: eps->conv = conv;
802: return(0);
803: }
807: /*@
808: EPSGetConvergenceTest - Gets the method used to compute the error estimate
809: used in the convergence test.
811: Not Collective
813: Input Parameters:
814: . eps - eigensolver context obtained from EPSCreate()
816: Output Parameters:
817: . conv - the type of convergence test
819: Level: intermediate
821: .seealso: EPSSetConvergenceTest(), EPSConv822: @*/
823: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)824: {
828: *conv = eps->conv;
829: return(0);
830: }
834: /*@C
835: EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
836: iteration of the eigensolver.
838: Logically Collective on EPS840: Input Parameters:
841: + eps - eigensolver context obtained from EPSCreate()
842: . func - pointer to the stopping test function
843: . ctx - context for private data for the stopping routine (may be null)
844: - destroy - a routine for destroying the context (may be null)
846: Calling Sequence of func:
847: $ func(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx)
849: + eps - eigensolver context obtained from EPSCreate()
850: . its - current number of iterations
851: . max_it - maximum number of iterations
852: . nconv - number of currently converged eigenpairs
853: . nev - number of requested eigenpairs
854: . reason - (output) result of the stopping test
855: - ctx - optional context, as set by EPSSetStoppingTestFunction()
857: Note:
858: Normal usage is to first call the default routine EPSStoppingBasic() and then
859: set reason to EPS_CONVERGED_USER if some user-defined conditions have been
860: met. To let the eigensolver continue iterating, the result must be left as
861: EPS_CONVERGED_ITERATING.
863: Level: advanced
865: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
866: @*/
867: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))868: {
873: if (eps->stoppingdestroy) {
874: (*eps->stoppingdestroy)(eps->stoppingctx);
875: }
876: eps->stopping = func;
877: eps->stoppingdestroy = destroy;
878: eps->stoppingctx = ctx;
879: if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
880: else eps->stop = EPS_STOP_USER;
881: return(0);
882: }
886: /*@
887: EPSSetStoppingTest - Specifies how to decide the termination of the outer
888: loop of the eigensolver.
890: Logically Collective on EPS892: Input Parameters:
893: + eps - eigensolver context obtained from EPSCreate()
894: - stop - the type of stopping test
896: Options Database Keys:
897: + -eps_stop_basic - Sets the default stopping test
898: - -eps_stop_user - Selects the user-defined stopping test
900: Note:
901: The parameter 'stop' can have one of these values
902: + EPS_STOP_BASIC - default stopping test
903: - EPS_STOP_USER - function set by EPSSetStoppingTestFunction()
905: Level: advanced
907: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop908: @*/
909: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)910: {
914: switch (stop) {
915: case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
916: case EPS_STOP_USER: break;
917: default:918: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
919: }
920: eps->stop = stop;
921: return(0);
922: }
926: /*@
927: EPSGetStoppingTest - Gets the method used to decide the termination of the outer
928: loop of the eigensolver.
930: Not Collective
932: Input Parameters:
933: . eps - eigensolver context obtained from EPSCreate()
935: Output Parameters:
936: . stop - the type of stopping test
938: Level: advanced
940: .seealso: EPSSetStoppingTest(), EPSStop941: @*/
942: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)943: {
947: *stop = eps->stop;
948: return(0);
949: }
953: /*@
954: EPSSetProblemType - Specifies the type of the eigenvalue problem.
956: Logically Collective on EPS958: Input Parameters:
959: + eps - the eigensolver context
960: - type - a known type of eigenvalue problem
962: Options Database Keys:
963: + -eps_hermitian - Hermitian eigenvalue problem
964: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
965: . -eps_non_hermitian - non-Hermitian eigenvalue problem
966: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
967: - -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
968: with positive semi-definite B
970: Notes:
971: Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
972: (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
973: (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
974: (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).
976: This function must be used to instruct SLEPc to exploit symmetry. If no
977: problem type is specified, by default a non-Hermitian problem is assumed
978: (either standard or generalized). If the user knows that the problem is
979: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
980: B positive definite) then it is recommended to set the problem type so
981: that eigensolver can exploit these properties.
983: Level: intermediate
985: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType986: @*/
987: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)988: {
992: if (type == eps->problem_type) return(0);
993: switch (type) {
994: case EPS_HEP:
995: eps->isgeneralized = PETSC_FALSE;
996: eps->ishermitian = PETSC_TRUE;
997: eps->ispositive = PETSC_FALSE;
998: break;
999: case EPS_NHEP:
1000: eps->isgeneralized = PETSC_FALSE;
1001: eps->ishermitian = PETSC_FALSE;
1002: eps->ispositive = PETSC_FALSE;
1003: break;
1004: case EPS_GHEP:
1005: eps->isgeneralized = PETSC_TRUE;
1006: eps->ishermitian = PETSC_TRUE;
1007: eps->ispositive = PETSC_TRUE;
1008: break;
1009: case EPS_GNHEP:
1010: eps->isgeneralized = PETSC_TRUE;
1011: eps->ishermitian = PETSC_FALSE;
1012: eps->ispositive = PETSC_FALSE;
1013: break;
1014: case EPS_PGNHEP:
1015: eps->isgeneralized = PETSC_TRUE;
1016: eps->ishermitian = PETSC_FALSE;
1017: eps->ispositive = PETSC_TRUE;
1018: break;
1019: case EPS_GHIEP:
1020: eps->isgeneralized = PETSC_TRUE;
1021: eps->ishermitian = PETSC_TRUE;
1022: eps->ispositive = PETSC_FALSE;
1023: break;
1024: default:1025: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
1026: }
1027: eps->problem_type = type;
1028: eps->state = EPS_STATE_INITIAL;
1029: return(0);
1030: }
1034: /*@
1035: EPSGetProblemType - Gets the problem type from the EPS object.
1037: Not Collective
1039: Input Parameter:
1040: . eps - the eigensolver context
1042: Output Parameter:
1043: . type - name of EPS problem type
1045: Level: intermediate
1047: .seealso: EPSSetProblemType(), EPSProblemType1048: @*/
1049: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)1050: {
1054: *type = eps->problem_type;
1055: return(0);
1056: }
1060: /*@
1061: EPSSetExtraction - Specifies the type of extraction technique to be employed
1062: by the eigensolver.
1064: Logically Collective on EPS1066: Input Parameters:
1067: + eps - the eigensolver context
1068: - extr - a known type of extraction
1070: Options Database Keys:
1071: + -eps_ritz - Rayleigh-Ritz extraction
1072: . -eps_harmonic - harmonic Ritz extraction
1073: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
1074: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
1075: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
1076: (without target)
1077: . -eps_refined - refined Ritz extraction
1078: - -eps_refined_harmonic - refined harmonic Ritz extraction
1080: Notes:
1081: Not all eigensolvers support all types of extraction. See the SLEPc
1082: Users Manual for details.
1084: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
1085: may be useful when computing interior eigenvalues.
1087: Harmonic-type extractions are used in combination with a 'target'.
1089: Level: advanced
1091: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction1092: @*/
1093: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)1094: {
1098: eps->extraction = extr;
1099: return(0);
1100: }
1104: /*@
1105: EPSGetExtraction - Gets the extraction type used by the EPS object.
1107: Not Collective
1109: Input Parameter:
1110: . eps - the eigensolver context
1112: Output Parameter:
1113: . extr - name of extraction type
1115: Level: advanced
1117: .seealso: EPSSetExtraction(), EPSExtraction1118: @*/
1119: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)1120: {
1124: *extr = eps->extraction;
1125: return(0);
1126: }
1130: /*@
1131: EPSSetBalance - Specifies the balancing technique to be employed by the
1132: eigensolver, and some parameters associated to it.
1134: Logically Collective on EPS1136: Input Parameters:
1137: + eps - the eigensolver context
1138: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1139: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1140: . its - number of iterations of the balancing algorithm
1141: - cutoff - cutoff value
1143: Options Database Keys:
1144: + -eps_balance <method> - the balancing method, where <method> is one of
1145: 'none', 'oneside', 'twoside', or 'user'
1146: . -eps_balance_its <its> - number of iterations
1147: - -eps_balance_cutoff <cutoff> - cutoff value
1149: Notes:
1150: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1151: where D is an appropriate diagonal matrix. This improves the accuracy of
1152: the computed results in some cases. See the SLEPc Users Manual for details.
1154: Balancing makes sense only for non-Hermitian problems when the required
1155: precision is high (i.e. a small tolerance such as 1e-15).
1157: By default, balancing is disabled. The two-sided method is much more
1158: effective than the one-sided counterpart, but it requires the system
1159: matrices to have the MatMultTranspose operation defined.
1161: The parameter 'its' is the number of iterations performed by the method. The
1162: cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
1163: a reasonably good value.
1165: User-defined balancing is allowed provided that the corresponding matrix
1166: is set via STSetBalanceMatrix.
1168: Level: intermediate
1170: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1171: @*/
1172: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)1173: {
1179: switch (bal) {
1180: case EPS_BALANCE_NONE:
1181: case EPS_BALANCE_ONESIDE:
1182: case EPS_BALANCE_TWOSIDE:
1183: case EPS_BALANCE_USER:
1184: eps->balance = bal;
1185: break;
1186: default:1187: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1188: }
1189: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1190: else {
1191: if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1192: eps->balance_its = its;
1193: }
1194: if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1195: else {
1196: if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1197: eps->balance_cutoff = cutoff;
1198: }
1199: return(0);
1200: }
1204: /*@
1205: EPSGetBalance - Gets the balancing type used by the EPS object, and the
1206: associated parameters.
1208: Not Collective
1210: Input Parameter:
1211: . eps - the eigensolver context
1213: Output Parameters:
1214: + bal - the balancing method
1215: . its - number of iterations of the balancing algorithm
1216: - cutoff - cutoff value
1218: Level: intermediate
1220: Note:
1221: The user can specify NULL for any parameter that is not needed.
1223: .seealso: EPSSetBalance(), EPSBalance1224: @*/
1225: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)1226: {
1229: if (bal) *bal = eps->balance;
1230: if (its) *its = eps->balance_its;
1231: if (cutoff) *cutoff = eps->balance_cutoff;
1232: return(0);
1233: }
1237: /*@
1238: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1239: explicitly or not.
1241: Logically Collective on EPS1243: Input Parameters:
1244: + eps - the eigensolver context
1245: - trueres - whether true residuals are required or not
1247: Options Database Keys:
1248: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1250: Notes:
1251: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1252: the true residual for each eigenpair approximation, and uses it for
1253: convergence testing. Computing the residual is usually an expensive
1254: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1255: by using a cheap estimate of the residual norm, but this may sometimes
1256: give inaccurate results (especially if a spectral transform is being
1257: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1258: do rely on computing the true residual, so this option is irrelevant for them.
1260: Level: advanced
1262: .seealso: EPSGetTrueResidual()
1263: @*/
1264: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)1265: {
1269: eps->trueres = trueres;
1270: return(0);
1271: }
1275: /*@
1276: EPSGetTrueResidual - Returns the flag indicating whether true
1277: residuals must be computed explicitly or not.
1279: Not Collective
1281: Input Parameter:
1282: . eps - the eigensolver context
1284: Output Parameter:
1285: . trueres - the returned flag
1287: Level: advanced
1289: .seealso: EPSSetTrueResidual()
1290: @*/
1291: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)1292: {
1296: *trueres = eps->trueres;
1297: return(0);
1298: }
1302: /*@
1303: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1304: approximate eigenpairs or not.
1306: Logically Collective on EPS1308: Input Parameters:
1309: + eps - the eigensolver context
1310: - trackall - whether to compute all residuals or not
1312: Notes:
1313: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1314: the residual norm for each eigenpair approximation. Computing the residual is
1315: usually an expensive operation and solvers commonly compute only the residual
1316: associated to the first unconverged eigenpair.
1318: The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1319: activate this option.
1321: Level: developer
1323: .seealso: EPSGetTrackAll()
1324: @*/
1325: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)1326: {
1330: eps->trackall = trackall;
1331: return(0);
1332: }
1336: /*@
1337: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1338: be computed or not.
1340: Not Collective
1342: Input Parameter:
1343: . eps - the eigensolver context
1345: Output Parameter:
1346: . trackall - the returned flag
1348: Level: developer
1350: .seealso: EPSSetTrackAll()
1351: @*/
1352: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)1353: {
1357: *trackall = eps->trackall;
1358: return(0);
1359: }
1363: /*@
1364: EPSSetPurify - Deactivate eigenvector purification (which is activated by default).
1366: Logically Collective on EPS1368: Input Parameters:
1369: + eps - the eigensolver context
1370: - purify - whether purification is required or not
1372: Options Database Keys:
1373: . -eps_purify <boolean> - Sets/resets the boolean flag 'purify'
1375: Notes:
1376: By default, eigenvectors of generalized symmetric eigenproblems are purified
1377: in order to purge directions in the nullspace of matrix B. If the user knows
1378: that B is non-singular, then purification can be safely deactivated and some
1379: computational cost is avoided (this is particularly important in interval computations).
1381: Level: intermediate
1383: .seealso: EPSGetPurify(), EPSSetInterval()
1384: @*/
1385: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)1386: {
1390: eps->purify = purify;
1391: return(0);
1392: }
1396: /*@
1397: EPSGetPurify - Returns the flag indicating whether purification is activated
1398: or not.
1400: Not Collective
1402: Input Parameter:
1403: . eps - the eigensolver context
1405: Output Parameter:
1406: . purify - the returned flag
1408: Level: intermediate
1410: .seealso: EPSSetPurify()
1411: @*/
1412: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)1413: {
1417: *purify = eps->purify;
1418: return(0);
1419: }
1423: /*@C
1424: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1425: EPS options in the database.
1427: Logically Collective on EPS1429: Input Parameters:
1430: + eps - the eigensolver context
1431: - prefix - the prefix string to prepend to all EPS option requests
1433: Notes:
1434: A hyphen (-) must NOT be given at the beginning of the prefix name.
1435: The first character of all runtime options is AUTOMATICALLY the
1436: hyphen.
1438: For example, to distinguish between the runtime options for two
1439: different EPS contexts, one could call
1440: .vb
1441: EPSSetOptionsPrefix(eps1,"eig1_")
1442: EPSSetOptionsPrefix(eps2,"eig2_")
1443: .ve
1445: Level: advanced
1447: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1448: @*/
1449: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)1450: {
1455: if (!eps->st) { EPSGetST(eps,&eps->st); }
1456: STSetOptionsPrefix(eps->st,prefix);
1457: if (!eps->V) { EPSGetBV(eps,&eps->V); }
1458: BVSetOptionsPrefix(eps->V,prefix);
1459: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1460: DSSetOptionsPrefix(eps->ds,prefix);
1461: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1462: RGSetOptionsPrefix(eps->rg,prefix);
1463: PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1464: return(0);
1465: }
1469: /*@C
1470: EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1471: EPS options in the database.
1473: Logically Collective on EPS1475: Input Parameters:
1476: + eps - the eigensolver context
1477: - prefix - the prefix string to prepend to all EPS option requests
1479: Notes:
1480: A hyphen (-) must NOT be given at the beginning of the prefix name.
1481: The first character of all runtime options is AUTOMATICALLY the hyphen.
1483: Level: advanced
1485: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1486: @*/
1487: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)1488: {
1493: if (!eps->st) { EPSGetST(eps,&eps->st); }
1494: STAppendOptionsPrefix(eps->st,prefix);
1495: if (!eps->V) { EPSGetBV(eps,&eps->V); }
1496: BVSetOptionsPrefix(eps->V,prefix);
1497: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1498: DSSetOptionsPrefix(eps->ds,prefix);
1499: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1500: RGSetOptionsPrefix(eps->rg,prefix);
1501: PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1502: return(0);
1503: }
1507: /*@C
1508: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1509: EPS options in the database.
1511: Not Collective
1513: Input Parameters:
1514: . eps - the eigensolver context
1516: Output Parameters:
1517: . prefix - pointer to the prefix string used is returned
1519: Note:
1520: On the Fortran side, the user should pass in a string 'prefix' of
1521: sufficient length to hold the prefix.
1523: Level: advanced
1525: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1526: @*/
1527: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])1528: {
1534: PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1535: return(0);
1536: }