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-2015, Universitat Politecnica de Valencia, Spain
9: This file is part of SLEPc.
11: SLEPc is free software: you can redistribute it and/or modify it under the
12: terms of version 3 of the GNU Lesser General Public License as published by
13: the Free Software Foundation.
15: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
16: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
18: more details.
20: You should have received a copy of the GNU Lesser General Public License
21: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
22: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
23: */
25: #include <slepc/private/epsimpl.h> /*I "slepceps.h" I*/
29: /*@
30: EPSSetFromOptions - Sets EPS options from the options database.
31: This routine must be called before EPSSetUp() if the user is to be
32: allowed to set the solver type.
34: Collective on EPS 36: Input Parameters:
37: . eps - the eigensolver context
39: Notes:
40: To see all options, run your program with the -help option.
42: Level: beginner
43: @*/
44: PetscErrorCode EPSSetFromOptions(EPS eps) 45: {
46: PetscErrorCode ierr;
47: char type[256],monfilename[PETSC_MAX_PATH_LEN];
48: PetscBool flg,flg1,flg2,flg3;
49: PetscReal r,array[2]={0,0};
50: PetscScalar s;
51: PetscInt i,j,k;
52: PetscViewer monviewer;
53: SlepcConvMonitor ctx;
57: EPSRegisterAll();
58: PetscObjectOptionsBegin((PetscObject)eps);
59: PetscOptionsFList("-eps_type","Eigenvalue Problem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
60: if (flg) {
61: EPSSetType(eps,type);
62: }
63: /*
64: Set the type if it was never set.
65: */
66: if (!((PetscObject)eps)->type_name) {
67: EPSSetType(eps,EPSKRYLOVSCHUR);
68: }
70: PetscOptionsBoolGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);
71: if (flg) { EPSSetProblemType(eps,EPS_HEP); }
72: PetscOptionsBoolGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);
73: if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
74: PetscOptionsBoolGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
75: if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
76: PetscOptionsBoolGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
77: if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
78: PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
79: if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
80: PetscOptionsBoolGroupEnd("-eps_gen_indefinite","generalized hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
81: if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }
83: PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
84: if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
85: PetscOptionsBoolGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);
86: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
87: PetscOptionsBoolGroup("-eps_harmonic_relative","relative harmonic Ritz extraction","EPSSetExtraction",&flg);
88: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
89: PetscOptionsBoolGroup("-eps_harmonic_right","right harmonic Ritz extraction","EPSSetExtraction",&flg);
90: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
91: PetscOptionsBoolGroup("-eps_harmonic_largest","largest harmonic Ritz extraction","EPSSetExtraction",&flg);
92: if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
93: PetscOptionsBoolGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);
94: if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
95: PetscOptionsBoolGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);
96: if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }
98: PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)eps->balance,(PetscEnum*)&eps->balance,NULL);
100: j = eps->balance_its;
101: PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg1);
102: r = eps->balance_cutoff;
103: PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg2);
104: if (flg1 || flg2) {
105: EPSSetBalance(eps,eps->balance,j,r);
106: }
108: i = eps->max_it? eps->max_it: PETSC_DEFAULT;
109: PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
110: r = eps->tol;
111: PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,&flg2);
112: if (flg1 || flg2) {
113: EPSSetTolerances(eps,r,i);
114: }
116: PetscOptionsBoolGroupBegin("-eps_conv_eig","Relative error convergence test","EPSSetConvergenceTest",&flg);
117: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_EIG); }
118: PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
119: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
120: PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
121: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
122: PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
123: if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_USER); }
125: i = eps->nev;
126: PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
127: j = eps->ncv? eps->ncv: PETSC_DEFAULT;
128: PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
129: k = eps->mpd? eps->mpd: PETSC_DEFAULT;
130: PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
131: if (flg1 || flg2 || flg3) {
132: EPSSetDimensions(eps,i,j,k);
133: }
135: /* -----------------------------------------------------------------------*/
136: /*
137: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
138: */
139: flg = PETSC_FALSE;
140: PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",flg,&flg,NULL);
141: if (flg) {
142: EPSMonitorCancel(eps);
143: }
144: /*
145: Prints approximate eigenvalues and error estimates at each iteration
146: */
147: PetscOptionsString("-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
148: if (flg) {
149: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
150: EPSMonitorSet(eps,EPSMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
151: }
152: PetscOptionsString("-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
153: if (flg) {
154: PetscNew(&ctx);
155: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&ctx->viewer);
156: EPSMonitorSet(eps,EPSMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
157: }
158: PetscOptionsString("-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
159: if (flg) {
160: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
161: EPSMonitorSet(eps,EPSMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
162: EPSSetTrackAll(eps,PETSC_TRUE);
163: }
164: flg = PETSC_FALSE;
165: PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",flg,&flg,NULL);
166: if (flg) {
167: EPSMonitorSet(eps,EPSMonitorLG,NULL,NULL);
168: }
169: flg = PETSC_FALSE;
170: PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",flg,&flg,NULL);
171: if (flg) {
172: EPSMonitorSet(eps,EPSMonitorLGAll,NULL,NULL);
173: EPSSetTrackAll(eps,PETSC_TRUE);
174: }
175: /* -----------------------------------------------------------------------*/
176: PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
177: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
178: PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
179: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
180: PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
181: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
182: PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
183: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
184: PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
185: if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
186: PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
187: if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
188: PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);
189: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
190: PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);
191: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
192: PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);
193: if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
194: PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval","EPSSetWhichEigenpairs",&flg);
195: if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }
197: PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
198: if (flg) {
199: if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) {
200: EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
201: }
202: EPSSetTarget(eps,s);
203: }
204: k = 2;
205: PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
206: if (flg) {
207: if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
208: EPSSetWhichEigenpairs(eps,EPS_ALL);
209: EPSSetInterval(eps,array[0],array[1]);
210: }
212: PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
213: PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&eps->purify,NULL);
215: PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",0);
216: PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",0);
217: PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",0);
218: PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSReasonView",0);
219: PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",0);
220: PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",0);
221: PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",0);
223: if (eps->ops->setfromoptions) {
224: (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
225: }
226: PetscObjectProcessOptionsHandlers((PetscObject)eps);
227: PetscOptionsEnd();
229: if (!eps->V) { EPSGetBV(eps,&eps->V); }
230: BVSetFromOptions(eps->V);
231: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
232: RGSetFromOptions(eps->rg);
233: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
234: DSSetFromOptions(eps->ds);
235: if (!eps->st) { EPSGetST(eps,&eps->st); }
236: STSetFromOptions(eps->st);
237: PetscRandomSetFromOptions(eps->rand);
238: return(0);
239: }
243: /*@
244: EPSGetTolerances - Gets the tolerance and maximum iteration count used
245: by the EPS convergence tests.
247: Not Collective
249: Input Parameter:
250: . eps - the eigensolver context
252: Output Parameters:
253: + tol - the convergence tolerance
254: - maxits - maximum number of iterations
256: Notes:
257: The user can specify NULL for any parameter that is not needed.
259: Level: intermediate
261: .seealso: EPSSetTolerances()
262: @*/
263: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)264: {
267: if (tol) *tol = eps->tol;
268: if (maxits) *maxits = eps->max_it;
269: return(0);
270: }
274: /*@
275: EPSSetTolerances - Sets the tolerance and maximum iteration count used
276: by the EPS convergence tests.
278: Logically Collective on EPS280: Input Parameters:
281: + eps - the eigensolver context
282: . tol - the convergence tolerance
283: - maxits - maximum number of iterations to use
285: Options Database Keys:
286: + -eps_tol <tol> - Sets the convergence tolerance
287: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
289: Notes:
290: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
292: Level: intermediate
294: .seealso: EPSGetTolerances()
295: @*/
296: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)297: {
302: if (tol == PETSC_DEFAULT) {
303: eps->tol = PETSC_DEFAULT;
304: eps->state = EPS_STATE_INITIAL;
305: } else {
306: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
307: eps->tol = tol;
308: }
309: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
310: eps->max_it = 0;
311: eps->state = EPS_STATE_INITIAL;
312: } else {
313: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
314: eps->max_it = maxits;
315: }
316: return(0);
317: }
321: /*@
322: EPSGetDimensions - Gets the number of eigenvalues to compute
323: and the dimension of the subspace.
325: Not Collective
327: Input Parameter:
328: . eps - the eigensolver context
330: Output Parameters:
331: + nev - number of eigenvalues to compute
332: . ncv - the maximum dimension of the subspace to be used by the solver
333: - mpd - the maximum dimension allowed for the projected problem
335: Level: intermediate
337: .seealso: EPSSetDimensions()
338: @*/
339: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)340: {
343: if (nev) *nev = eps->nev;
344: if (ncv) *ncv = eps->ncv;
345: if (mpd) *mpd = eps->mpd;
346: return(0);
347: }
351: /*@
352: EPSSetDimensions - Sets the number of eigenvalues to compute
353: and the dimension of the subspace.
355: Logically Collective on EPS357: Input Parameters:
358: + eps - the eigensolver context
359: . nev - number of eigenvalues to compute
360: . ncv - the maximum dimension of the subspace to be used by the solver
361: - mpd - the maximum dimension allowed for the projected problem
363: Options Database Keys:
364: + -eps_nev <nev> - Sets the number of eigenvalues
365: . -eps_ncv <ncv> - Sets the dimension of the subspace
366: - -eps_mpd <mpd> - Sets the maximum projected dimension
368: Notes:
369: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
370: dependent on the solution method.
372: The parameters ncv and mpd are intimately related, so that the user is advised
373: to set one of them at most. Normal usage is that
374: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
375: (b) in cases where nev is large, the user sets mpd.
377: The value of ncv should always be between nev and (nev+mpd), typically
378: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
379: a smaller value should be used.
381: When computing all eigenvalues in an interval, see EPSSetInterval(), these
382: parameters lose relevance, and tuning must be done with
383: EPSKrylovSchurSetDimensions().
385: Level: intermediate
387: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
388: @*/
389: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)390: {
396: if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
397: eps->nev = nev;
398: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
399: eps->ncv = 0;
400: } else {
401: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
402: eps->ncv = ncv;
403: }
404: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
405: eps->mpd = 0;
406: } else {
407: if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
408: eps->mpd = mpd;
409: }
410: eps->state = EPS_STATE_INITIAL;
411: return(0);
412: }
416: /*@
417: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
418: to be sought.
420: Logically Collective on EPS422: Input Parameters:
423: + eps - eigensolver context obtained from EPSCreate()
424: - which - the portion of the spectrum to be sought
426: Possible values:
427: The parameter 'which' can have one of these values
429: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
430: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
431: . EPS_LARGEST_REAL - largest real parts
432: . EPS_SMALLEST_REAL - smallest real parts
433: . EPS_LARGEST_IMAGINARY - largest imaginary parts
434: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
435: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
436: . EPS_TARGET_REAL - eigenvalues with real part closest to target
437: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
438: . EPS_ALL - all eigenvalues contained in a given interval
439: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
441: Options Database Keys:
442: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
443: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
444: . -eps_largest_real - Sets largest real parts
445: . -eps_smallest_real - Sets smallest real parts
446: . -eps_largest_imaginary - Sets largest imaginary parts
447: . -eps_smallest_imaginary - Sets smallest imaginary parts
448: . -eps_target_magnitude - Sets eigenvalues closest to target
449: . -eps_target_real - Sets real parts closest to target
450: . -eps_target_imaginary - Sets imaginary parts closest to target
451: - -eps_all - Sets all eigenvalues in an interval
453: Notes:
454: Not all eigensolvers implemented in EPS account for all the possible values
455: stated above. Also, some values make sense only for certain types of
456: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
457: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
458: for eigenvalue selection.
460: The target is a scalar value provided with EPSSetTarget().
462: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
463: SLEPc have been built with complex scalars.
465: EPS_ALL is intended for use in combination with an interval (see
466: EPSSetInterval()), when all eigenvalues within the interval are requested.
467: In that case, the number of eigenvalues is unknown, so the nev parameter
468: has a different sense, see EPSSetDimensions().
470: Level: intermediate
472: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
473: EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich474: @*/
475: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)476: {
480: switch (which) {
481: case EPS_LARGEST_MAGNITUDE:
482: case EPS_SMALLEST_MAGNITUDE:
483: case EPS_LARGEST_REAL:
484: case EPS_SMALLEST_REAL:
485: case EPS_LARGEST_IMAGINARY:
486: case EPS_SMALLEST_IMAGINARY:
487: case EPS_TARGET_MAGNITUDE:
488: case EPS_TARGET_REAL:
489: #if defined(PETSC_USE_COMPLEX)
490: case EPS_TARGET_IMAGINARY:
491: #endif
492: case EPS_ALL:
493: case EPS_WHICH_USER:
494: if (eps->which != which) {
495: eps->state = EPS_STATE_INITIAL;
496: eps->which = which;
497: }
498: break;
499: default:500: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
501: }
502: return(0);
503: }
507: /*@
508: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
509: sought.
511: Not Collective
513: Input Parameter:
514: . eps - eigensolver context obtained from EPSCreate()
516: Output Parameter:
517: . which - the portion of the spectrum to be sought
519: Notes:
520: See EPSSetWhichEigenpairs() for possible values of 'which'.
522: Level: intermediate
524: .seealso: EPSSetWhichEigenpairs(), EPSWhich525: @*/
526: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)527: {
531: *which = eps->which;
532: return(0);
533: }
537: /*@C
538: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
539: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
541: Logically Collective on EPS543: Input Parameters:
544: + eps - eigensolver context obtained from EPSCreate()
545: . func - a pointer to the comparison function
546: - ctx - a context pointer (the last parameter to the comparison function)
548: Calling Sequence of func:
549: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
551: + ar - real part of the 1st eigenvalue
552: . ai - imaginary part of the 1st eigenvalue
553: . br - real part of the 2nd eigenvalue
554: . bi - imaginary part of the 2nd eigenvalue
555: . res - result of comparison
556: - ctx - optional context, as set by EPSSetEigenvalueComparison()
558: Note:
559: The returning parameter 'res' can be:
560: + negative - if the 1st eigenvalue is preferred to the 2st one
561: . zero - if both eigenvalues are equally preferred
562: - positive - if the 2st eigenvalue is preferred to the 1st one
564: Level: advanced
566: .seealso: EPSSetWhichEigenpairs(), EPSWhich567: @*/
568: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)569: {
572: eps->sc->comparison = func;
573: eps->sc->comparisonctx = ctx;
574: eps->which = EPS_WHICH_USER;
575: return(0);
576: }
580: /*@C
581: EPSSetArbitrarySelection - Specifies a function intended to look for
582: eigenvalues according to an arbitrary selection criterion. This criterion
583: can be based on a computation involving the current eigenvector approximation.
585: Logically Collective on EPS587: Input Parameters:
588: + eps - eigensolver context obtained from EPSCreate()
589: . func - a pointer to the evaluation function
590: - ctx - a context pointer (the last parameter to the evaluation function)
592: Calling Sequence of func:
593: $ func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
595: + er - real part of the current eigenvalue approximation
596: . ei - imaginary part of the current eigenvalue approximation
597: . xr - real part of the current eigenvector approximation
598: . xi - imaginary part of the current eigenvector approximation
599: . rr - result of evaluation (real part)
600: . ri - result of evaluation (imaginary part)
601: - ctx - optional context, as set by EPSSetArbitrarySelection()
603: Notes:
604: This provides a mechanism to select eigenpairs by evaluating a user-defined
605: function. When a function has been provided, the default selection based on
606: sorting the eigenvalues is replaced by the sorting of the results of this
607: function (with the same sorting criterion given in EPSSetWhichEigenpairs()).
609: For instance, suppose you want to compute those eigenvectors that maximize
610: a certain computable expression. Then implement the computation using
611: the arguments xr and xi, and return the result in rr. Then set the standard
612: sorting by magnitude so that the eigenpair with largest value of rr is
613: selected.
615: This evaluation function is collective, that is, all processes call it and
616: it can use collective operations; furthermore, the computed result must
617: be the same in all processes.
619: The result of func is expressed as a complex number so that it is possible to
620: use the standard eigenvalue sorting functions, but normally only rr is used.
621: Set ri to zero unless it is meaningful in your application.
623: Level: advanced
625: .seealso: EPSSetWhichEigenpairs()
626: @*/
627: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)628: {
631: eps->arbitrary = func;
632: eps->arbitraryctx = ctx;
633: eps->state = EPS_STATE_INITIAL;
634: return(0);
635: }
639: /*@C
640: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
641: used in the convergence test.
643: Logically Collective on EPS645: Input Parameters:
646: + eps - eigensolver context obtained from EPSCreate()
647: . func - a pointer to the convergence test function
648: . ctx - [optional] context for private data for the convergence routine
649: - destroy - [optional] destructor for the context (may be NULL;
650: PETSC_NULL_FUNCTION in Fortran)
652: Calling Sequence of func:
653: $ func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
655: + eps - eigensolver context obtained from EPSCreate()
656: . eigr - real part of the eigenvalue
657: . eigi - imaginary part of the eigenvalue
658: . res - residual norm associated to the eigenpair
659: . errest - (output) computed error estimate
660: - ctx - optional context, as set by EPSSetConvergenceTest()
662: Note:
663: If the error estimate returned by the convergence test function is less than
664: the tolerance, then the eigenvalue is accepted as converged.
666: Level: advanced
668: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
669: @*/
670: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))671: {
676: if (eps->convergeddestroy) {
677: (*eps->convergeddestroy)(eps->convergedctx);
678: }
679: eps->converged = func;
680: eps->convergeddestroy = destroy;
681: eps->convergedctx = ctx;
682: if (func == EPSConvergedEigRelative) eps->conv = EPS_CONV_EIG;
683: else if (func == EPSConvergedNormRelative) eps->conv = EPS_CONV_NORM;
684: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
685: else eps->conv = EPS_CONV_USER;
686: return(0);
687: }
691: /*@
692: EPSSetConvergenceTest - Specifies how to compute the error estimate
693: used in the convergence test.
695: Logically Collective on EPS697: Input Parameters:
698: + eps - eigensolver context obtained from EPSCreate()
699: - conv - the type of convergence test
701: Options Database Keys:
702: + -eps_conv_abs - Sets the absolute convergence test
703: . -eps_conv_eig - Sets the convergence test relative to the eigenvalue
704: . -eps_conv_norm - Sets the convergence test relative to the matrix norms
705: - -eps_conv_user - Selects the user-defined convergence test
707: Note:
708: The parameter 'conv' can have one of these values
709: + EPS_CONV_ABS - absolute error ||r||
710: . EPS_CONV_EIG - error relative to the eigenvalue l, ||r||/|l|
711: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
712: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
714: Level: intermediate
716: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSConv717: @*/
718: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)719: {
723: switch (conv) {
724: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
725: case EPS_CONV_EIG: eps->converged = EPSConvergedEigRelative; break;
726: case EPS_CONV_NORM: eps->converged = EPSConvergedNormRelative; break;
727: case EPS_CONV_USER: break;
728: default:729: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
730: }
731: eps->conv = conv;
732: return(0);
733: }
737: /*@
738: EPSGetConvergenceTest - Gets the method used to compute the error estimate
739: used in the convergence test.
741: Not Collective
743: Input Parameters:
744: . eps - eigensolver context obtained from EPSCreate()
746: Output Parameters:
747: . conv - the type of convergence test
749: Level: intermediate
751: .seealso: EPSSetConvergenceTest(), EPSConv752: @*/
753: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)754: {
758: *conv = eps->conv;
759: return(0);
760: }
764: /*@
765: EPSSetProblemType - Specifies the type of the eigenvalue problem.
767: Logically Collective on EPS769: Input Parameters:
770: + eps - the eigensolver context
771: - type - a known type of eigenvalue problem
773: Options Database Keys:
774: + -eps_hermitian - Hermitian eigenvalue problem
775: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
776: . -eps_non_hermitian - non-Hermitian eigenvalue problem
777: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
778: - -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
779: with positive semi-definite B
781: Notes:
782: Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
783: (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
784: (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
785: (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).
787: This function must be used to instruct SLEPc to exploit symmetry. If no
788: problem type is specified, by default a non-Hermitian problem is assumed
789: (either standard or generalized). If the user knows that the problem is
790: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
791: B positive definite) then it is recommended to set the problem type so
792: that eigensolver can exploit these properties.
794: Level: intermediate
796: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType797: @*/
798: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)799: {
803: switch (type) {
804: case EPS_HEP:
805: eps->isgeneralized = PETSC_FALSE;
806: eps->ishermitian = PETSC_TRUE;
807: eps->ispositive = PETSC_FALSE;
808: break;
809: case EPS_NHEP:
810: eps->isgeneralized = PETSC_FALSE;
811: eps->ishermitian = PETSC_FALSE;
812: eps->ispositive = PETSC_FALSE;
813: break;
814: case EPS_GHEP:
815: eps->isgeneralized = PETSC_TRUE;
816: eps->ishermitian = PETSC_TRUE;
817: eps->ispositive = PETSC_TRUE;
818: break;
819: case EPS_GNHEP:
820: eps->isgeneralized = PETSC_TRUE;
821: eps->ishermitian = PETSC_FALSE;
822: eps->ispositive = PETSC_FALSE;
823: break;
824: case EPS_PGNHEP:
825: eps->isgeneralized = PETSC_TRUE;
826: eps->ishermitian = PETSC_FALSE;
827: eps->ispositive = PETSC_TRUE;
828: break;
829: case EPS_GHIEP:
830: eps->isgeneralized = PETSC_TRUE;
831: eps->ishermitian = PETSC_TRUE;
832: eps->ispositive = PETSC_FALSE;
833: break;
834: default:835: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
836: }
837: eps->problem_type = type;
838: return(0);
839: }
843: /*@
844: EPSGetProblemType - Gets the problem type from the EPS object.
846: Not Collective
848: Input Parameter:
849: . eps - the eigensolver context
851: Output Parameter:
852: . type - name of EPS problem type
854: Level: intermediate
856: .seealso: EPSSetProblemType(), EPSProblemType857: @*/
858: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)859: {
863: *type = eps->problem_type;
864: return(0);
865: }
869: /*@
870: EPSSetExtraction - Specifies the type of extraction technique to be employed
871: by the eigensolver.
873: Logically Collective on EPS875: Input Parameters:
876: + eps - the eigensolver context
877: - extr - a known type of extraction
879: Options Database Keys:
880: + -eps_ritz - Rayleigh-Ritz extraction
881: . -eps_harmonic - harmonic Ritz extraction
882: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
883: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
884: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
885: (without target)
886: . -eps_refined - refined Ritz extraction
887: - -eps_refined_harmonic - refined harmonic Ritz extraction
889: Notes:
890: Not all eigensolvers support all types of extraction. See the SLEPc
891: Users Manual for details.
893: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
894: may be useful when computing interior eigenvalues.
896: Harmonic-type extractions are used in combination with a 'target'.
898: Level: advanced
900: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction901: @*/
902: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)903: {
907: eps->extraction = extr;
908: return(0);
909: }
913: /*@
914: EPSGetExtraction - Gets the extraction type used by the EPS object.
916: Not Collective
918: Input Parameter:
919: . eps - the eigensolver context
921: Output Parameter:
922: . extr - name of extraction type
924: Level: advanced
926: .seealso: EPSSetExtraction(), EPSExtraction927: @*/
928: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)929: {
933: *extr = eps->extraction;
934: return(0);
935: }
939: /*@
940: EPSSetBalance - Specifies the balancing technique to be employed by the
941: eigensolver, and some parameters associated to it.
943: Logically Collective on EPS945: Input Parameters:
946: + eps - the eigensolver context
947: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
948: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
949: . its - number of iterations of the balancing algorithm
950: - cutoff - cutoff value
952: Options Database Keys:
953: + -eps_balance <method> - the balancing method, where <method> is one of
954: 'none', 'oneside', 'twoside', or 'user'
955: . -eps_balance_its <its> - number of iterations
956: - -eps_balance_cutoff <cutoff> - cutoff value
958: Notes:
959: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
960: where D is an appropriate diagonal matrix. This improves the accuracy of
961: the computed results in some cases. See the SLEPc Users Manual for details.
963: Balancing makes sense only for non-Hermitian problems when the required
964: precision is high (i.e. a small tolerance such as 1e-15).
966: By default, balancing is disabled. The two-sided method is much more
967: effective than the one-sided counterpart, but it requires the system
968: matrices to have the MatMultTranspose operation defined.
970: The parameter 'its' is the number of iterations performed by the method. The
971: cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
972: a reasonably good value.
974: User-defined balancing is allowed provided that the corresponding matrix
975: is set via STSetBalanceMatrix.
977: Level: intermediate
979: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
980: @*/
981: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)982: {
988: switch (bal) {
989: case EPS_BALANCE_NONE:
990: case EPS_BALANCE_ONESIDE:
991: case EPS_BALANCE_TWOSIDE:
992: case EPS_BALANCE_USER:
993: eps->balance = bal;
994: break;
995: default:996: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
997: }
998: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
999: else {
1000: if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1001: eps->balance_its = its;
1002: }
1003: if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1004: else {
1005: if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1006: eps->balance_cutoff = cutoff;
1007: }
1008: return(0);
1009: }
1013: /*@
1014: EPSGetBalance - Gets the balancing type used by the EPS object, and the
1015: associated parameters.
1017: Not Collective
1019: Input Parameter:
1020: . eps - the eigensolver context
1022: Output Parameters:
1023: + bal - the balancing method
1024: . its - number of iterations of the balancing algorithm
1025: - cutoff - cutoff value
1027: Level: intermediate
1029: Note:
1030: The user can specify NULL for any parameter that is not needed.
1032: .seealso: EPSSetBalance(), EPSBalance1033: @*/
1034: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)1035: {
1038: if (bal) *bal = eps->balance;
1039: if (its) *its = eps->balance_its;
1040: if (cutoff) *cutoff = eps->balance_cutoff;
1041: return(0);
1042: }
1046: /*@
1047: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1048: explicitly or not.
1050: Logically Collective on EPS1052: Input Parameters:
1053: + eps - the eigensolver context
1054: - trueres - whether true residuals are required or not
1056: Options Database Keys:
1057: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1059: Notes:
1060: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1061: the true residual for each eigenpair approximation, and uses it for
1062: convergence testing. Computing the residual is usually an expensive
1063: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1064: by using a cheap estimate of the residual norm, but this may sometimes
1065: give inaccurate results (especially if a spectral transform is being
1066: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1067: do rely on computing the true residual, so this option is irrelevant for them.
1069: Level: advanced
1071: .seealso: EPSGetTrueResidual()
1072: @*/
1073: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)1074: {
1078: eps->trueres = trueres;
1079: return(0);
1080: }
1084: /*@
1085: EPSGetTrueResidual - Returns the flag indicating whether true
1086: residuals must be computed explicitly or not.
1088: Not Collective
1090: Input Parameter:
1091: . eps - the eigensolver context
1093: Output Parameter:
1094: . trueres - the returned flag
1096: Level: advanced
1098: .seealso: EPSSetTrueResidual()
1099: @*/
1100: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)1101: {
1105: *trueres = eps->trueres;
1106: return(0);
1107: }
1111: /*@
1112: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1113: approximate eigenpairs or not.
1115: Logically Collective on EPS1117: Input Parameters:
1118: + eps - the eigensolver context
1119: - trackall - whether to compute all residuals or not
1121: Notes:
1122: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1123: the residual norm for each eigenpair approximation. Computing the residual is
1124: usually an expensive operation and solvers commonly compute only the residual
1125: associated to the first unconverged eigenpair.
1127: The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1128: activate this option.
1130: Level: developer
1132: .seealso: EPSGetTrackAll()
1133: @*/
1134: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)1135: {
1139: eps->trackall = trackall;
1140: return(0);
1141: }
1145: /*@
1146: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1147: be computed or not.
1149: Not Collective
1151: Input Parameter:
1152: . eps - the eigensolver context
1154: Output Parameter:
1155: . trackall - the returned flag
1157: Level: developer
1159: .seealso: EPSSetTrackAll()
1160: @*/
1161: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)1162: {
1166: *trackall = eps->trackall;
1167: return(0);
1168: }
1172: /*@
1173: EPSSetPurify - Deactivate eigenvector purification (which is activated by default).
1175: Logically Collective on EPS1177: Input Parameters:
1178: + eps - the eigensolver context
1179: - purify - whether purification is required or not
1181: Options Database Keys:
1182: . -eps_purify <boolean> - Sets/resets the boolean flag 'purify'
1184: Notes:
1185: By default, eigenvectors of generalized symmetric eigenproblems are purified
1186: in order to purge directions in the nullspace of matrix B. If the user knows
1187: that B is non-singular, then purification can be safely deactivated and some
1188: computational cost is avoided (this is particularly important in interval computations).
1190: Level: intermediate
1192: .seealso: EPSGetPurify(), EPSSetInterval()
1193: @*/
1194: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)1195: {
1199: eps->purify = purify;
1200: return(0);
1201: }
1205: /*@
1206: EPSGetPurify - Returns the flag indicating whether purification is activated
1207: or not.
1209: Not Collective
1211: Input Parameter:
1212: . eps - the eigensolver context
1214: Output Parameter:
1215: . purify - the returned flag
1217: Level: intermediate
1219: .seealso: EPSSetPurify()
1220: @*/
1221: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)1222: {
1226: *purify = eps->purify;
1227: return(0);
1228: }
1232: /*@C
1233: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1234: EPS options in the database.
1236: Logically Collective on EPS1238: Input Parameters:
1239: + eps - the eigensolver context
1240: - prefix - the prefix string to prepend to all EPS option requests
1242: Notes:
1243: A hyphen (-) must NOT be given at the beginning of the prefix name.
1244: The first character of all runtime options is AUTOMATICALLY the
1245: hyphen.
1247: For example, to distinguish between the runtime options for two
1248: different EPS contexts, one could call
1249: .vb
1250: EPSSetOptionsPrefix(eps1,"eig1_")
1251: EPSSetOptionsPrefix(eps2,"eig2_")
1252: .ve
1254: Level: advanced
1256: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1257: @*/
1258: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)1259: {
1264: if (!eps->st) { EPSGetST(eps,&eps->st); }
1265: STSetOptionsPrefix(eps->st,prefix);
1266: if (!eps->V) { EPSGetBV(eps,&eps->V); }
1267: BVSetOptionsPrefix(eps->V,prefix);
1268: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1269: DSSetOptionsPrefix(eps->ds,prefix);
1270: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1271: RGSetOptionsPrefix(eps->rg,prefix);
1272: PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1273: return(0);
1274: }
1278: /*@C
1279: EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1280: EPS options in the database.
1282: Logically Collective on EPS1284: Input Parameters:
1285: + eps - the eigensolver context
1286: - prefix - the prefix string to prepend to all EPS option requests
1288: Notes:
1289: A hyphen (-) must NOT be given at the beginning of the prefix name.
1290: The first character of all runtime options is AUTOMATICALLY the hyphen.
1292: Level: advanced
1294: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1295: @*/
1296: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)1297: {
1302: if (!eps->st) { EPSGetST(eps,&eps->st); }
1303: STAppendOptionsPrefix(eps->st,prefix);
1304: if (!eps->V) { EPSGetBV(eps,&eps->V); }
1305: BVSetOptionsPrefix(eps->V,prefix);
1306: if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1307: DSSetOptionsPrefix(eps->ds,prefix);
1308: if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1309: RGSetOptionsPrefix(eps->rg,prefix);
1310: PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1311: return(0);
1312: }
1316: /*@C
1317: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1318: EPS options in the database.
1320: Not Collective
1322: Input Parameters:
1323: . eps - the eigensolver context
1325: Output Parameters:
1326: . prefix - pointer to the prefix string used is returned
1328: Notes: On the fortran side, the user should pass in a string 'prefix' of
1329: sufficient length to hold the prefix.
1331: Level: advanced
1333: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1334: @*/
1335: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])1336: {
1342: PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1343: return(0);
1344: }