1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
6: This file is part of SLEPc.
7: SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9: */
10: /*
11: PEP routines related to options that can be set via the command-line
12: or procedurally
13: */
15: #include <slepc/private/pepimpl.h> 16: #include <petscdraw.h>
18: /*@C
19: PEPMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective on pep
24: Input Parameters:
25: + pep - the polynomial eigensolver context
26: . opt - the command line option for this monitor
27: . name - the monitor type one is seeking
28: . ctx - an optional user context for the monitor, or NULL
29: - trackall - whether this monitor tracks all eigenvalues or not
31: Level: developer
33: .seealso: PEPMonitorSet(), PEPSetTrackAll()
34: @*/
35: PetscErrorCode PEPMonitorSetFromOptions(PEP pep,const char opt[],const char name[],void *ctx,PetscBool trackall) 36: {
37: PetscErrorCode (*mfunc)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
38: PetscErrorCode (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
39: PetscErrorCode (*dfunc)(PetscViewerAndFormat**);
40: PetscViewerAndFormat *vf;
41: PetscViewer viewer;
42: PetscViewerFormat format;
43: PetscViewerType vtype;
44: char key[PETSC_MAX_PATH_LEN];
45: PetscBool flg;
47: PetscOptionsGetViewer(PetscObjectComm((PetscObject)pep),((PetscObject)pep)->options,((PetscObject)pep)->prefix,opt,&viewer,&format,&flg);
48: if (!flg) PetscFunctionReturn(0);
50: PetscViewerGetType(viewer,&vtype);
51: SlepcMonitorMakeKey_Internal(name,vtype,format,key);
52: PetscFunctionListFind(PEPMonitorList,key,&mfunc);
54: PetscFunctionListFind(PEPMonitorCreateList,key,&cfunc);
55: PetscFunctionListFind(PEPMonitorDestroyList,key,&dfunc);
56: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
57: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
59: (*cfunc)(viewer,format,ctx,&vf);
60: PetscObjectDereference((PetscObject)viewer);
61: PEPMonitorSet(pep,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
62: if (trackall) PEPSetTrackAll(pep,PETSC_TRUE);
63: PetscFunctionReturn(0);
64: }
66: /*@
67: PEPSetFromOptions - Sets PEP options from the options database.
68: This routine must be called before PEPSetUp() if the user is to be
69: allowed to set the solver type.
71: Collective on pep
73: Input Parameters:
74: . pep - the polynomial eigensolver context
76: Notes:
77: To see all options, run your program with the -help option.
79: Level: beginner
81: .seealso: PEPSetOptionsPrefix()
82: @*/
83: PetscErrorCode PEPSetFromOptions(PEP pep) 84: {
85: PetscErrorCode ierr;
86: char type[256];
87: PetscBool set,flg,flg1,flg2,flg3,flg4,flg5;
88: PetscReal r,t,array[2]={0,0};
89: PetscScalar s;
90: PetscInt i,j,k;
91: PEPScale scale;
92: PEPRefine refine;
93: PEPRefineScheme scheme;
96: PEPRegisterAll();
97: ierr = PetscObjectOptionsBegin((PetscObject)pep);
98: PetscOptionsFList("-pep_type","Polynomial eigensolver method","PEPSetType",PEPList,(char*)(((PetscObject)pep)->type_name?((PetscObject)pep)->type_name:PEPTOAR),type,sizeof(type),&flg);
99: if (flg) PEPSetType(pep,type);
100: else if (!((PetscObject)pep)->type_name) PEPSetType(pep,PEPTOAR);
102: PetscOptionsBoolGroupBegin("-pep_general","General polynomial eigenvalue problem","PEPSetProblemType",&flg);
103: if (flg) PEPSetProblemType(pep,PEP_GENERAL);
104: PetscOptionsBoolGroup("-pep_hermitian","Hermitian polynomial eigenvalue problem","PEPSetProblemType",&flg);
105: if (flg) PEPSetProblemType(pep,PEP_HERMITIAN);
106: PetscOptionsBoolGroup("-pep_hyperbolic","Hyperbolic polynomial eigenvalue problem","PEPSetProblemType",&flg);
107: if (flg) PEPSetProblemType(pep,PEP_HYPERBOLIC);
108: PetscOptionsBoolGroupEnd("-pep_gyroscopic","Gyroscopic polynomial eigenvalue problem","PEPSetProblemType",&flg);
109: if (flg) PEPSetProblemType(pep,PEP_GYROSCOPIC);
111: scale = pep->scale;
112: PetscOptionsEnum("-pep_scale","Scaling strategy","PEPSetScale",PEPScaleTypes,(PetscEnum)scale,(PetscEnum*)&scale,&flg1);
113: r = pep->sfactor;
114: PetscOptionsReal("-pep_scale_factor","Scale factor","PEPSetScale",pep->sfactor,&r,&flg2);
115: if (!flg2 && r==1.0) r = PETSC_DEFAULT;
116: j = pep->sits;
117: PetscOptionsInt("-pep_scale_its","Number of iterations in diagonal scaling","PEPSetScale",pep->sits,&j,&flg3);
118: t = pep->slambda;
119: PetscOptionsReal("-pep_scale_lambda","Estimate of eigenvalue (modulus) for diagonal scaling","PEPSetScale",pep->slambda,&t,&flg4);
120: if (flg1 || flg2 || flg3 || flg4) PEPSetScale(pep,scale,r,NULL,NULL,j,t);
122: PetscOptionsEnum("-pep_extract","Extraction method","PEPSetExtract",PEPExtractTypes,(PetscEnum)pep->extract,(PetscEnum*)&pep->extract,NULL);
124: refine = pep->refine;
125: PetscOptionsEnum("-pep_refine","Iterative refinement method","PEPSetRefine",PEPRefineTypes,(PetscEnum)refine,(PetscEnum*)&refine,&flg1);
126: i = pep->npart;
127: PetscOptionsInt("-pep_refine_partitions","Number of partitions of the communicator for iterative refinement","PEPSetRefine",pep->npart,&i,&flg2);
128: r = pep->rtol;
129: PetscOptionsReal("-pep_refine_tol","Tolerance for iterative refinement","PEPSetRefine",pep->rtol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL/1000:pep->rtol,&r,&flg3);
130: j = pep->rits;
131: PetscOptionsInt("-pep_refine_its","Maximum number of iterations for iterative refinement","PEPSetRefine",pep->rits,&j,&flg4);
132: scheme = pep->scheme;
133: PetscOptionsEnum("-pep_refine_scheme","Scheme used for linear systems within iterative refinement","PEPSetRefine",PEPRefineSchemes,(PetscEnum)scheme,(PetscEnum*)&scheme,&flg5);
134: if (flg1 || flg2 || flg3 || flg4 || flg5) PEPSetRefine(pep,refine,i,r,j,scheme);
136: i = pep->max_it;
137: PetscOptionsInt("-pep_max_it","Maximum number of iterations","PEPSetTolerances",pep->max_it,&i,&flg1);
138: r = pep->tol;
139: PetscOptionsReal("-pep_tol","Tolerance","PEPSetTolerances",SlepcDefaultTol(pep->tol),&r,&flg2);
140: if (flg1 || flg2) PEPSetTolerances(pep,r,i);
142: PetscOptionsBoolGroupBegin("-pep_conv_rel","Relative error convergence test","PEPSetConvergenceTest",&flg);
143: if (flg) PEPSetConvergenceTest(pep,PEP_CONV_REL);
144: PetscOptionsBoolGroup("-pep_conv_norm","Convergence test relative to the matrix norms","PEPSetConvergenceTest",&flg);
145: if (flg) PEPSetConvergenceTest(pep,PEP_CONV_NORM);
146: PetscOptionsBoolGroup("-pep_conv_abs","Absolute error convergence test","PEPSetConvergenceTest",&flg);
147: if (flg) PEPSetConvergenceTest(pep,PEP_CONV_ABS);
148: PetscOptionsBoolGroupEnd("-pep_conv_user","User-defined convergence test","PEPSetConvergenceTest",&flg);
149: if (flg) PEPSetConvergenceTest(pep,PEP_CONV_USER);
151: PetscOptionsBoolGroupBegin("-pep_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","PEPSetStoppingTest",&flg);
152: if (flg) PEPSetStoppingTest(pep,PEP_STOP_BASIC);
153: PetscOptionsBoolGroupEnd("-pep_stop_user","User-defined stopping test","PEPSetStoppingTest",&flg);
154: if (flg) PEPSetStoppingTest(pep,PEP_STOP_USER);
156: i = pep->nev;
157: PetscOptionsInt("-pep_nev","Number of eigenvalues to compute","PEPSetDimensions",pep->nev,&i,&flg1);
158: j = pep->ncv;
159: PetscOptionsInt("-pep_ncv","Number of basis vectors","PEPSetDimensions",pep->ncv,&j,&flg2);
160: k = pep->mpd;
161: PetscOptionsInt("-pep_mpd","Maximum dimension of projected problem","PEPSetDimensions",pep->mpd,&k,&flg3);
162: if (flg1 || flg2 || flg3) PEPSetDimensions(pep,i,j,k);
164: PetscOptionsEnum("-pep_basis","Polynomial basis","PEPSetBasis",PEPBasisTypes,(PetscEnum)pep->basis,(PetscEnum*)&pep->basis,NULL);
166: PetscOptionsBoolGroupBegin("-pep_largest_magnitude","Compute largest eigenvalues in magnitude","PEPSetWhichEigenpairs",&flg);
167: if (flg) PEPSetWhichEigenpairs(pep,PEP_LARGEST_MAGNITUDE);
168: PetscOptionsBoolGroup("-pep_smallest_magnitude","Compute smallest eigenvalues in magnitude","PEPSetWhichEigenpairs",&flg);
169: if (flg) PEPSetWhichEigenpairs(pep,PEP_SMALLEST_MAGNITUDE);
170: PetscOptionsBoolGroup("-pep_largest_real","Compute eigenvalues with largest real parts","PEPSetWhichEigenpairs",&flg);
171: if (flg) PEPSetWhichEigenpairs(pep,PEP_LARGEST_REAL);
172: PetscOptionsBoolGroup("-pep_smallest_real","Compute eigenvalues with smallest real parts","PEPSetWhichEigenpairs",&flg);
173: if (flg) PEPSetWhichEigenpairs(pep,PEP_SMALLEST_REAL);
174: PetscOptionsBoolGroup("-pep_largest_imaginary","Compute eigenvalues with largest imaginary parts","PEPSetWhichEigenpairs",&flg);
175: if (flg) PEPSetWhichEigenpairs(pep,PEP_LARGEST_IMAGINARY);
176: PetscOptionsBoolGroup("-pep_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","PEPSetWhichEigenpairs",&flg);
177: if (flg) PEPSetWhichEigenpairs(pep,PEP_SMALLEST_IMAGINARY);
178: PetscOptionsBoolGroup("-pep_target_magnitude","Compute eigenvalues closest to target","PEPSetWhichEigenpairs",&flg);
179: if (flg) PEPSetWhichEigenpairs(pep,PEP_TARGET_MAGNITUDE);
180: PetscOptionsBoolGroup("-pep_target_real","Compute eigenvalues with real parts closest to target","PEPSetWhichEigenpairs",&flg);
181: if (flg) PEPSetWhichEigenpairs(pep,PEP_TARGET_REAL);
182: PetscOptionsBoolGroup("-pep_target_imaginary","Compute eigenvalues with imaginary parts closest to target","PEPSetWhichEigenpairs",&flg);
183: if (flg) PEPSetWhichEigenpairs(pep,PEP_TARGET_IMAGINARY);
184: PetscOptionsBoolGroupEnd("-pep_all","Compute all eigenvalues in an interval or a region","PEPSetWhichEigenpairs",&flg);
185: if (flg) PEPSetWhichEigenpairs(pep,PEP_ALL);
187: PetscOptionsScalar("-pep_target","Value of the target","PEPSetTarget",pep->target,&s,&flg);
188: if (flg) {
189: if (pep->which!=PEP_TARGET_REAL && pep->which!=PEP_TARGET_IMAGINARY) PEPSetWhichEigenpairs(pep,PEP_TARGET_MAGNITUDE);
190: PEPSetTarget(pep,s);
191: }
193: k = 2;
194: PetscOptionsRealArray("-pep_interval","Computational interval (two real values separated with a comma without spaces)","PEPSetInterval",array,&k,&flg);
195: if (flg) {
197: PEPSetWhichEigenpairs(pep,PEP_ALL);
198: PEPSetInterval(pep,array[0],array[1]);
199: }
201: /* -----------------------------------------------------------------------*/
202: /*
203: Cancels all monitors hardwired into code before call to PEPSetFromOptions()
204: */
205: PetscOptionsBool("-pep_monitor_cancel","Remove any hardwired monitor routines","PEPMonitorCancel",PETSC_FALSE,&flg,&set);
206: if (set && flg) PEPMonitorCancel(pep);
207: PEPMonitorSetFromOptions(pep,"-pep_monitor","first_approximation",NULL,PETSC_FALSE);
208: PEPMonitorSetFromOptions(pep,"-pep_monitor_all","all_approximations",NULL,PETSC_TRUE);
209: PEPMonitorSetFromOptions(pep,"-pep_monitor_conv","convergence_history",NULL,PETSC_FALSE);
211: /* -----------------------------------------------------------------------*/
212: PetscOptionsName("-pep_view","Print detailed information on solver used","PEPView",NULL);
213: PetscOptionsName("-pep_view_vectors","View computed eigenvectors","PEPVectorsView",NULL);
214: PetscOptionsName("-pep_view_values","View computed eigenvalues","PEPValuesView",NULL);
215: PetscOptionsName("-pep_converged_reason","Print reason for convergence, and number of iterations","PEPConvergedReasonView",NULL);
216: PetscOptionsName("-pep_error_absolute","Print absolute errors of each eigenpair","PEPErrorView",NULL);
217: PetscOptionsName("-pep_error_relative","Print relative errors of each eigenpair","PEPErrorView",NULL);
218: PetscOptionsName("-pep_error_backward","Print backward errors of each eigenpair","PEPErrorView",NULL);
220: if (pep->ops->setfromoptions) (*pep->ops->setfromoptions)(PetscOptionsObject,pep);
221: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pep);
222: ierr = PetscOptionsEnd();
224: if (!pep->V) PEPGetBV(pep,&pep->V);
225: BVSetFromOptions(pep->V);
226: if (!pep->rg) PEPGetRG(pep,&pep->rg);
227: RGSetFromOptions(pep->rg);
228: if (!pep->ds) PEPGetDS(pep,&pep->ds);
229: DSSetFromOptions(pep->ds);
230: if (!pep->st) PEPGetST(pep,&pep->st);
231: PEPSetDefaultST(pep);
232: STSetFromOptions(pep->st);
233: if (!pep->refineksp) PEPRefineGetKSP(pep,&pep->refineksp);
234: KSPSetFromOptions(pep->refineksp);
235: PetscFunctionReturn(0);
236: }
238: /*@C
239: PEPGetTolerances - Gets the tolerance and maximum iteration count used
240: by the PEP convergence tests.
242: Not Collective
244: Input Parameter:
245: . pep - the polynomial eigensolver context
247: Output Parameters:
248: + tol - the convergence tolerance
249: - maxits - maximum number of iterations
251: Notes:
252: The user can specify NULL for any parameter that is not needed.
254: Level: intermediate
256: .seealso: PEPSetTolerances()
257: @*/
258: PetscErrorCode PEPGetTolerances(PEP pep,PetscReal *tol,PetscInt *maxits)259: {
261: if (tol) *tol = pep->tol;
262: if (maxits) *maxits = pep->max_it;
263: PetscFunctionReturn(0);
264: }
266: /*@
267: PEPSetTolerances - Sets the tolerance and maximum iteration count used
268: by the PEP convergence tests.
270: Logically Collective on pep
272: Input Parameters:
273: + pep - the polynomial eigensolver context
274: . tol - the convergence tolerance
275: - maxits - maximum number of iterations to use
277: Options Database Keys:
278: + -pep_tol <tol> - Sets the convergence tolerance
279: - -pep_max_it <maxits> - Sets the maximum number of iterations allowed
281: Notes:
282: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
284: Level: intermediate
286: .seealso: PEPGetTolerances()
287: @*/
288: PetscErrorCode PEPSetTolerances(PEP pep,PetscReal tol,PetscInt maxits)289: {
293: if (tol == PETSC_DEFAULT) {
294: pep->tol = PETSC_DEFAULT;
295: pep->state = PEP_STATE_INITIAL;
296: } else {
298: pep->tol = tol;
299: }
300: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
301: pep->max_it = PETSC_DEFAULT;
302: pep->state = PEP_STATE_INITIAL;
303: } else {
305: pep->max_it = maxits;
306: }
307: PetscFunctionReturn(0);
308: }
310: /*@C
311: PEPGetDimensions - Gets the number of eigenvalues to compute
312: and the dimension of the subspace.
314: Not Collective
316: Input Parameter:
317: . pep - the polynomial eigensolver context
319: Output Parameters:
320: + nev - number of eigenvalues to compute
321: . ncv - the maximum dimension of the subspace to be used by the solver
322: - mpd - the maximum dimension allowed for the projected problem
324: Notes:
325: The user can specify NULL for any parameter that is not needed.
327: Level: intermediate
329: .seealso: PEPSetDimensions()
330: @*/
331: PetscErrorCode PEPGetDimensions(PEP pep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)332: {
334: if (nev) *nev = pep->nev;
335: if (ncv) *ncv = pep->ncv;
336: if (mpd) *mpd = pep->mpd;
337: PetscFunctionReturn(0);
338: }
340: /*@
341: PEPSetDimensions - Sets the number of eigenvalues to compute
342: and the dimension of the subspace.
344: Logically Collective on pep
346: Input Parameters:
347: + pep - the polynomial eigensolver context
348: . nev - number of eigenvalues to compute
349: . ncv - the maximum dimension of the subspace to be used by the solver
350: - mpd - the maximum dimension allowed for the projected problem
352: Options Database Keys:
353: + -pep_nev <nev> - Sets the number of eigenvalues
354: . -pep_ncv <ncv> - Sets the dimension of the subspace
355: - -pep_mpd <mpd> - Sets the maximum projected dimension
357: Notes:
358: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
359: dependent on the solution method.
361: The parameters ncv and mpd are intimately related, so that the user is advised
362: to set one of them at most. Normal usage is that
363: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
364: (b) in cases where nev is large, the user sets mpd.
366: The value of ncv should always be between nev and (nev+mpd), typically
367: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
368: a smaller value should be used.
370: When computing all eigenvalues in an interval, see PEPSetInterval(), these
371: parameters lose relevance, and tuning must be done with PEPSTOARSetDimensions().
373: Level: intermediate
375: .seealso: PEPGetDimensions(), PEPSetInterval(), PEPSTOARSetDimensions()
376: @*/
377: PetscErrorCode PEPSetDimensions(PEP pep,PetscInt nev,PetscInt ncv,PetscInt mpd)378: {
384: pep->nev = nev;
385: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
386: pep->ncv = PETSC_DEFAULT;
387: } else {
389: pep->ncv = ncv;
390: }
391: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
392: pep->mpd = PETSC_DEFAULT;
393: } else {
395: pep->mpd = mpd;
396: }
397: pep->state = PEP_STATE_INITIAL;
398: PetscFunctionReturn(0);
399: }
401: /*@
402: PEPSetWhichEigenpairs - Specifies which portion of the spectrum is
403: to be sought.
405: Logically Collective on pep
407: Input Parameters:
408: + pep - eigensolver context obtained from PEPCreate()
409: - which - the portion of the spectrum to be sought
411: Possible values:
412: The parameter 'which' can have one of these values
414: + PEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
415: . PEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
416: . PEP_LARGEST_REAL - largest real parts
417: . PEP_SMALLEST_REAL - smallest real parts
418: . PEP_LARGEST_IMAGINARY - largest imaginary parts
419: . PEP_SMALLEST_IMAGINARY - smallest imaginary parts
420: . PEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
421: . PEP_TARGET_REAL - eigenvalues with real part closest to target
422: . PEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
423: . PEP_ALL - all eigenvalues contained in a given interval or region
424: - PEP_WHICH_USER - user defined ordering set with PEPSetEigenvalueComparison()
426: Options Database Keys:
427: + -pep_largest_magnitude - Sets largest eigenvalues in magnitude
428: . -pep_smallest_magnitude - Sets smallest eigenvalues in magnitude
429: . -pep_largest_real - Sets largest real parts
430: . -pep_smallest_real - Sets smallest real parts
431: . -pep_largest_imaginary - Sets largest imaginary parts
432: . -pep_smallest_imaginary - Sets smallest imaginary parts
433: . -pep_target_magnitude - Sets eigenvalues closest to target
434: . -pep_target_real - Sets real parts closest to target
435: . -pep_target_imaginary - Sets imaginary parts closest to target
436: - -pep_all - Sets all eigenvalues in an interval or region
438: Notes:
439: Not all eigensolvers implemented in PEP account for all the possible values
440: stated above. If SLEPc is compiled for real numbers PEP_LARGEST_IMAGINARY441: and PEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
442: for eigenvalue selection.
444: The target is a scalar value provided with PEPSetTarget().
446: The criterion PEP_TARGET_IMAGINARY is available only in case PETSc and
447: SLEPc have been built with complex scalars.
449: PEP_ALL is intended for use in combination with an interval (see
450: PEPSetInterval()), when all eigenvalues within the interval are requested,
451: and also for computing all eigenvalues in a region with the CISS solver.
452: In both cases, the number of eigenvalues is unknown, so the nev parameter
453: has a different sense, see PEPSetDimensions().
455: Level: intermediate
457: .seealso: PEPGetWhichEigenpairs(), PEPSetTarget(), PEPSetInterval(),
458: PEPSetDimensions(), PEPSetEigenvalueComparison(), PEPWhich459: @*/
460: PetscErrorCode PEPSetWhichEigenpairs(PEP pep,PEPWhich which)461: {
464: switch (which) {
465: case PEP_LARGEST_MAGNITUDE:
466: case PEP_SMALLEST_MAGNITUDE:
467: case PEP_LARGEST_REAL:
468: case PEP_SMALLEST_REAL:
469: case PEP_LARGEST_IMAGINARY:
470: case PEP_SMALLEST_IMAGINARY:
471: case PEP_TARGET_MAGNITUDE:
472: case PEP_TARGET_REAL:
473: #if defined(PETSC_USE_COMPLEX)
474: case PEP_TARGET_IMAGINARY:
475: #endif
476: case PEP_ALL:
477: case PEP_WHICH_USER:
478: if (pep->which != which) {
479: pep->state = PEP_STATE_INITIAL;
480: pep->which = which;
481: }
482: break;
483: #if !defined(PETSC_USE_COMPLEX)
484: case PEP_TARGET_IMAGINARY:
485: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_SUP,"PEP_TARGET_IMAGINARY can be used only with complex scalars");
486: #endif
487: default:488: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
489: }
490: PetscFunctionReturn(0);
491: }
493: /*@
494: PEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
495: sought.
497: Not Collective
499: Input Parameter:
500: . pep - eigensolver context obtained from PEPCreate()
502: Output Parameter:
503: . which - the portion of the spectrum to be sought
505: Notes:
506: See PEPSetWhichEigenpairs() for possible values of 'which'.
508: Level: intermediate
510: .seealso: PEPSetWhichEigenpairs(), PEPWhich511: @*/
512: PetscErrorCode PEPGetWhichEigenpairs(PEP pep,PEPWhich *which)513: {
516: *which = pep->which;
517: PetscFunctionReturn(0);
518: }
520: /*@C
521: PEPSetEigenvalueComparison - Specifies the eigenvalue comparison function
522: when PEPSetWhichEigenpairs() is set to PEP_WHICH_USER.
524: Logically Collective on pep
526: Input Parameters:
527: + pep - eigensolver context obtained from PEPCreate()
528: . func - a pointer to the comparison function
529: - ctx - a context pointer (the last parameter to the comparison function)
531: Calling Sequence of func:
532: $ func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
534: + ar - real part of the 1st eigenvalue
535: . ai - imaginary part of the 1st eigenvalue
536: . br - real part of the 2nd eigenvalue
537: . bi - imaginary part of the 2nd eigenvalue
538: . res - result of comparison
539: - ctx - optional context, as set by PEPSetEigenvalueComparison()
541: Note:
542: The returning parameter 'res' can be
543: + negative - if the 1st eigenvalue is preferred to the 2st one
544: . zero - if both eigenvalues are equally preferred
545: - positive - if the 2st eigenvalue is preferred to the 1st one
547: Level: advanced
549: .seealso: PEPSetWhichEigenpairs(), PEPWhich550: @*/
551: PetscErrorCode PEPSetEigenvalueComparison(PEP pep,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)552: {
554: pep->sc->comparison = func;
555: pep->sc->comparisonctx = ctx;
556: pep->which = PEP_WHICH_USER;
557: PetscFunctionReturn(0);
558: }
560: /*@
561: PEPSetProblemType - Specifies the type of the polynomial eigenvalue problem.
563: Logically Collective on pep
565: Input Parameters:
566: + pep - the polynomial eigensolver context
567: - type - a known type of polynomial eigenvalue problem
569: Options Database Keys:
570: + -pep_general - general problem with no particular structure
571: . -pep_hermitian - problem whose coefficient matrices are Hermitian
572: . -pep_hyperbolic - Hermitian problem that satisfies the definition of hyperbolic
573: - -pep_gyroscopic - problem with Hamiltonian structure
575: Notes:
576: Allowed values for the problem type are general (PEP_GENERAL), Hermitian
577: (PEP_HERMITIAN), hyperbolic (PEP_HYPERBOLIC), and gyroscopic (PEP_GYROSCOPIC).
579: This function is used to instruct SLEPc to exploit certain structure in
580: the polynomial eigenproblem. By default, no particular structure is assumed.
582: If the problem matrices are Hermitian (symmetric in the real case) or
583: Hermitian/skew-Hermitian then the solver can exploit this fact to perform
584: less operations or provide better stability. Hyperbolic problems are a
585: particular case of Hermitian problems, some solvers may treat them simply as
586: Hermitian.
588: Level: intermediate
590: .seealso: PEPSetOperators(), PEPSetType(), PEPGetProblemType(), PEPProblemType591: @*/
592: PetscErrorCode PEPSetProblemType(PEP pep,PEPProblemType type)593: {
597: if (type != pep->problem_type) {
598: pep->problem_type = type;
599: pep->state = PEP_STATE_INITIAL;
600: }
601: PetscFunctionReturn(0);
602: }
604: /*@
605: PEPGetProblemType - Gets the problem type from the PEP object.
607: Not Collective
609: Input Parameter:
610: . pep - the polynomial eigensolver context
612: Output Parameter:
613: . type - the problem type
615: Level: intermediate
617: .seealso: PEPSetProblemType(), PEPProblemType618: @*/
619: PetscErrorCode PEPGetProblemType(PEP pep,PEPProblemType *type)620: {
623: *type = pep->problem_type;
624: PetscFunctionReturn(0);
625: }
627: /*@
628: PEPSetBasis - Specifies the type of polynomial basis used to describe the
629: polynomial eigenvalue problem.
631: Logically Collective on pep
633: Input Parameters:
634: + pep - the polynomial eigensolver context
635: - basis - the type of polynomial basis
637: Options Database Key:
638: . -pep_basis <basis> - Select the basis type
640: Notes:
641: By default, the coefficient matrices passed via PEPSetOperators() are
642: expressed in the monomial basis, i.e.
643: P(lambda) = A_0 + lambda*A_1 + lambda^2*A_2 + ... + lambda^d*A_d.
644: Other polynomial bases may have better numerical behaviour, but the user
645: must then pass the coefficient matrices accordingly.
647: Level: intermediate
649: .seealso: PEPSetOperators(), PEPGetBasis(), PEPBasis650: @*/
651: PetscErrorCode PEPSetBasis(PEP pep,PEPBasis basis)652: {
655: pep->basis = basis;
656: PetscFunctionReturn(0);
657: }
659: /*@
660: PEPGetBasis - Gets the type of polynomial basis from the PEP object.
662: Not Collective
664: Input Parameter:
665: . pep - the polynomial eigensolver context
667: Output Parameter:
668: . basis - the polynomial basis
670: Level: intermediate
672: .seealso: PEPSetBasis(), PEPBasis673: @*/
674: PetscErrorCode PEPGetBasis(PEP pep,PEPBasis *basis)675: {
678: *basis = pep->basis;
679: PetscFunctionReturn(0);
680: }
682: /*@
683: PEPSetTrackAll - Specifies if the solver must compute the residual of all
684: approximate eigenpairs or not.
686: Logically Collective on pep
688: Input Parameters:
689: + pep - the eigensolver context
690: - trackall - whether compute all residuals or not
692: Notes:
693: If the user sets trackall=PETSC_TRUE then the solver explicitly computes
694: the residual for each eigenpair approximation. Computing the residual is
695: usually an expensive operation and solvers commonly compute the associated
696: residual to the first unconverged eigenpair.
698: The option '-pep_monitor_all' automatically activates this option.
700: Level: developer
702: .seealso: PEPGetTrackAll()
703: @*/
704: PetscErrorCode PEPSetTrackAll(PEP pep,PetscBool trackall)705: {
708: pep->trackall = trackall;
709: PetscFunctionReturn(0);
710: }
712: /*@
713: PEPGetTrackAll - Returns the flag indicating whether all residual norms must
714: be computed or not.
716: Not Collective
718: Input Parameter:
719: . pep - the eigensolver context
721: Output Parameter:
722: . trackall - the returned flag
724: Level: developer
726: .seealso: PEPSetTrackAll()
727: @*/
728: PetscErrorCode PEPGetTrackAll(PEP pep,PetscBool *trackall)729: {
732: *trackall = pep->trackall;
733: PetscFunctionReturn(0);
734: }
736: /*@C
737: PEPSetConvergenceTestFunction - Sets a function to compute the error estimate
738: used in the convergence test.
740: Logically Collective on pep
742: Input Parameters:
743: + pep - eigensolver context obtained from PEPCreate()
744: . func - a pointer to the convergence test function
745: . ctx - context for private data for the convergence routine (may be null)
746: - destroy - a routine for destroying the context (may be null)
748: Calling Sequence of func:
749: $ func(PEP pep,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
751: + pep - eigensolver context obtained from PEPCreate()
752: . eigr - real part of the eigenvalue
753: . eigi - imaginary part of the eigenvalue
754: . res - residual norm associated to the eigenpair
755: . errest - (output) computed error estimate
756: - ctx - optional context, as set by PEPSetConvergenceTestFunction()
758: Note:
759: If the error estimate returned by the convergence test function is less than
760: the tolerance, then the eigenvalue is accepted as converged.
762: Level: advanced
764: .seealso: PEPSetConvergenceTest(), PEPSetTolerances()
765: @*/
766: PetscErrorCode PEPSetConvergenceTestFunction(PEP pep,PetscErrorCode (*func)(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))767: {
769: if (pep->convergeddestroy) (*pep->convergeddestroy)(pep->convergedctx);
770: pep->convergeduser = func;
771: pep->convergeddestroy = destroy;
772: pep->convergedctx = ctx;
773: if (func == PEPConvergedRelative) pep->conv = PEP_CONV_REL;
774: else if (func == PEPConvergedNorm) pep->conv = PEP_CONV_NORM;
775: else if (func == PEPConvergedAbsolute) pep->conv = PEP_CONV_ABS;
776: else {
777: pep->conv = PEP_CONV_USER;
778: pep->converged = pep->convergeduser;
779: }
780: PetscFunctionReturn(0);
781: }
783: /*@
784: PEPSetConvergenceTest - Specifies how to compute the error estimate
785: used in the convergence test.
787: Logically Collective on pep
789: Input Parameters:
790: + pep - eigensolver context obtained from PEPCreate()
791: - conv - the type of convergence test
793: Options Database Keys:
794: + -pep_conv_abs - Sets the absolute convergence test
795: . -pep_conv_rel - Sets the convergence test relative to the eigenvalue
796: . -pep_conv_norm - Sets the convergence test relative to the matrix norms
797: - -pep_conv_user - Selects the user-defined convergence test
799: Note:
800: The parameter 'conv' can have one of these values
801: + PEP_CONV_ABS - absolute error ||r||
802: . PEP_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
803: . PEP_CONV_NORM - error relative matrix norms, ||r||/sum_i(l^i*||A_i||)
804: - PEP_CONV_USER - function set by PEPSetConvergenceTestFunction()
806: Level: intermediate
808: .seealso: PEPGetConvergenceTest(), PEPSetConvergenceTestFunction(), PEPSetStoppingTest(), PEPConv809: @*/
810: PetscErrorCode PEPSetConvergenceTest(PEP pep,PEPConv conv)811: {
814: switch (conv) {
815: case PEP_CONV_ABS: pep->converged = PEPConvergedAbsolute; break;
816: case PEP_CONV_REL: pep->converged = PEPConvergedRelative; break;
817: case PEP_CONV_NORM: pep->converged = PEPConvergedNorm; break;
818: case PEP_CONV_USER:
820: pep->converged = pep->convergeduser;
821: break;
822: default:823: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
824: }
825: pep->conv = conv;
826: PetscFunctionReturn(0);
827: }
829: /*@
830: PEPGetConvergenceTest - Gets the method used to compute the error estimate
831: used in the convergence test.
833: Not Collective
835: Input Parameters:
836: . pep - eigensolver context obtained from PEPCreate()
838: Output Parameters:
839: . conv - the type of convergence test
841: Level: intermediate
843: .seealso: PEPSetConvergenceTest(), PEPConv844: @*/
845: PetscErrorCode PEPGetConvergenceTest(PEP pep,PEPConv *conv)846: {
849: *conv = pep->conv;
850: PetscFunctionReturn(0);
851: }
853: /*@C
854: PEPSetStoppingTestFunction - Sets a function to decide when to stop the outer
855: iteration of the eigensolver.
857: Logically Collective on pep
859: Input Parameters:
860: + pep - eigensolver context obtained from PEPCreate()
861: . func - pointer to the stopping test function
862: . ctx - context for private data for the stopping routine (may be null)
863: - destroy - a routine for destroying the context (may be null)
865: Calling Sequence of func:
866: $ func(PEP pep,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,PEPConvergedReason *reason,void *ctx)
868: + pep - eigensolver context obtained from PEPCreate()
869: . its - current number of iterations
870: . max_it - maximum number of iterations
871: . nconv - number of currently converged eigenpairs
872: . nev - number of requested eigenpairs
873: . reason - (output) result of the stopping test
874: - ctx - optional context, as set by PEPSetStoppingTestFunction()
876: Note:
877: Normal usage is to first call the default routine PEPStoppingBasic() and then
878: set reason to PEP_CONVERGED_USER if some user-defined conditions have been
879: met. To let the eigensolver continue iterating, the result must be left as
880: PEP_CONVERGED_ITERATING.
882: Level: advanced
884: .seealso: PEPSetStoppingTest(), PEPStoppingBasic()
885: @*/
886: PetscErrorCode PEPSetStoppingTestFunction(PEP pep,PetscErrorCode (*func)(PEP,PetscInt,PetscInt,PetscInt,PetscInt,PEPConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))887: {
889: if (pep->stoppingdestroy) (*pep->stoppingdestroy)(pep->stoppingctx);
890: pep->stoppinguser = func;
891: pep->stoppingdestroy = destroy;
892: pep->stoppingctx = ctx;
893: if (func == PEPStoppingBasic) pep->stop = PEP_STOP_BASIC;
894: else {
895: pep->stop = PEP_STOP_USER;
896: pep->stopping = pep->stoppinguser;
897: }
898: PetscFunctionReturn(0);
899: }
901: /*@
902: PEPSetStoppingTest - Specifies how to decide the termination of the outer
903: loop of the eigensolver.
905: Logically Collective on pep
907: Input Parameters:
908: + pep - eigensolver context obtained from PEPCreate()
909: - stop - the type of stopping test
911: Options Database Keys:
912: + -pep_stop_basic - Sets the default stopping test
913: - -pep_stop_user - Selects the user-defined stopping test
915: Note:
916: The parameter 'stop' can have one of these values
917: + PEP_STOP_BASIC - default stopping test
918: - PEP_STOP_USER - function set by PEPSetStoppingTestFunction()
920: Level: advanced
922: .seealso: PEPGetStoppingTest(), PEPSetStoppingTestFunction(), PEPSetConvergenceTest(), PEPStop923: @*/
924: PetscErrorCode PEPSetStoppingTest(PEP pep,PEPStop stop)925: {
928: switch (stop) {
929: case PEP_STOP_BASIC: pep->stopping = PEPStoppingBasic; break;
930: case PEP_STOP_USER:
932: pep->stopping = pep->stoppinguser;
933: break;
934: default:935: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
936: }
937: pep->stop = stop;
938: PetscFunctionReturn(0);
939: }
941: /*@
942: PEPGetStoppingTest - Gets the method used to decide the termination of the outer
943: loop of the eigensolver.
945: Not Collective
947: Input Parameters:
948: . pep - eigensolver context obtained from PEPCreate()
950: Output Parameters:
951: . stop - the type of stopping test
953: Level: advanced
955: .seealso: PEPSetStoppingTest(), PEPStop956: @*/
957: PetscErrorCode PEPGetStoppingTest(PEP pep,PEPStop *stop)958: {
961: *stop = pep->stop;
962: PetscFunctionReturn(0);
963: }
965: /*@
966: PEPSetScale - Specifies the scaling strategy to be used.
968: Logically Collective on pep
970: Input Parameters:
971: + pep - the eigensolver context
972: . scale - scaling strategy
973: . alpha - the scaling factor used in the scalar strategy
974: . Dl - the left diagonal matrix of the diagonal scaling algorithm
975: . Dr - the right diagonal matrix of the diagonal scaling algorithm
976: . its - number of iterations of the diagonal scaling algorithm
977: - lambda - approximation to wanted eigenvalues (modulus)
979: Options Database Keys:
980: + -pep_scale <type> - scaling type, one of <none,scalar,diagonal,both>
981: . -pep_scale_factor <alpha> - the scaling factor
982: . -pep_scale_its <its> - number of iterations
983: - -pep_scale_lambda <lambda> - approximation to eigenvalues
985: Notes:
986: There are two non-exclusive scaling strategies, scalar and diagonal.
988: In the scalar strategy, scaling is applied to the eigenvalue, that is,
989: mu = lambda/alpha is the new eigenvalue and all matrices are scaled
990: accordingly. After solving the scaled problem, the original lambda is
991: recovered. Parameter 'alpha' must be positive. Use PETSC_DEFAULT to let
992: the solver compute a reasonable scaling factor.
994: In the diagonal strategy, the solver works implicitly with matrix Dl*A*Dr,
995: where Dl and Dr are appropriate diagonal matrices. This improves the accuracy
996: of the computed results in some cases. The user may provide the Dr and Dl
997: matrices represented as Vec objects storing diagonal elements. If not
998: provided, these matrices are computed internally. This option requires
999: that the polynomial coefficient matrices are of MATAIJ type.
1000: The parameter 'its' is the number of iterations performed by the method.
1001: Parameter 'lambda' must be positive. Use PETSC_DEFAULT or set lambda = 1.0 if
1002: no information about eigenvalues is available.
1004: Level: intermediate
1006: .seealso: PEPGetScale()
1007: @*/
1008: PetscErrorCode PEPSetScale(PEP pep,PEPScale scale,PetscReal alpha,Vec Dl,Vec Dr,PetscInt its,PetscReal lambda)1009: {
1012: pep->scale = scale;
1013: if (scale==PEP_SCALE_SCALAR || scale==PEP_SCALE_BOTH) {
1015: if (alpha == PETSC_DEFAULT || alpha == PETSC_DECIDE) {
1016: pep->sfactor = 0.0;
1017: pep->sfactor_set = PETSC_FALSE;
1018: } else {
1020: pep->sfactor = alpha;
1021: pep->sfactor_set = PETSC_TRUE;
1022: }
1023: }
1024: if (scale==PEP_SCALE_DIAGONAL || scale==PEP_SCALE_BOTH) {
1025: if (Dl) {
1028: PetscObjectReference((PetscObject)Dl);
1029: VecDestroy(&pep->Dl);
1030: pep->Dl = Dl;
1031: }
1032: if (Dr) {
1035: PetscObjectReference((PetscObject)Dr);
1036: VecDestroy(&pep->Dr);
1037: pep->Dr = Dr;
1038: }
1041: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) pep->sits = 5;
1042: else pep->sits = its;
1043: if (lambda==PETSC_DECIDE || lambda==PETSC_DEFAULT) pep->slambda = 1.0;
1044: else {
1046: pep->slambda = lambda;
1047: }
1048: }
1049: pep->state = PEP_STATE_INITIAL;
1050: PetscFunctionReturn(0);
1051: }
1053: /*@C
1054: PEPGetScale - Gets the scaling strategy used by the PEP object, and the
1055: associated parameters.
1057: Not Collectiv, but vectors are shared by all processors that share the PEP1059: Input Parameter:
1060: . pep - the eigensolver context
1062: Output Parameters:
1063: + scale - scaling strategy
1064: . alpha - the scaling factor used in the scalar strategy
1065: . Dl - the left diagonal matrix of the diagonal scaling algorithm
1066: . Dr - the right diagonal matrix of the diagonal scaling algorithm
1067: . its - number of iterations of the diagonal scaling algorithm
1068: - lambda - approximation to wanted eigenvalues (modulus)
1070: Level: intermediate
1072: Note:
1073: The user can specify NULL for any parameter that is not needed.
1075: If Dl or Dr were not set by the user, then the ones computed internally are
1076: returned (or a null pointer if called before PEPSetUp).
1078: .seealso: PEPSetScale(), PEPSetUp()
1079: @*/
1080: PetscErrorCode PEPGetScale(PEP pep,PEPScale *scale,PetscReal *alpha,Vec *Dl,Vec *Dr,PetscInt *its,PetscReal *lambda)1081: {
1083: if (scale) *scale = pep->scale;
1084: if (alpha) *alpha = pep->sfactor;
1085: if (Dl) *Dl = pep->Dl;
1086: if (Dr) *Dr = pep->Dr;
1087: if (its) *its = pep->sits;
1088: if (lambda) *lambda = pep->slambda;
1089: PetscFunctionReturn(0);
1090: }
1092: /*@
1093: PEPSetExtract - Specifies the extraction strategy to be used.
1095: Logically Collective on pep
1097: Input Parameters:
1098: + pep - the eigensolver context
1099: - extract - extraction strategy
1101: Options Database Keys:
1102: . -pep_extract <type> - extraction type, one of <none,norm,residual,structured>
1104: Level: intermediate
1106: .seealso: PEPGetExtract()
1107: @*/
1108: PetscErrorCode PEPSetExtract(PEP pep,PEPExtract extract)1109: {
1112: pep->extract = extract;
1113: PetscFunctionReturn(0);
1114: }
1116: /*@
1117: PEPGetExtract - Gets the extraction strategy used by the PEP object.
1119: Not Collective
1121: Input Parameter:
1122: . pep - the eigensolver context
1124: Output Parameter:
1125: . extract - extraction strategy
1127: Level: intermediate
1129: .seealso: PEPSetExtract(), PEPExtract1130: @*/
1131: PetscErrorCode PEPGetExtract(PEP pep,PEPExtract *extract)1132: {
1135: *extract = pep->extract;
1136: PetscFunctionReturn(0);
1137: }
1139: /*@
1140: PEPSetRefine - Specifies the refinement type (and options) to be used
1141: after the solve.
1143: Logically Collective on pep
1145: Input Parameters:
1146: + pep - the polynomial eigensolver context
1147: . refine - refinement type
1148: . npart - number of partitions of the communicator
1149: . tol - the convergence tolerance
1150: . its - maximum number of refinement iterations
1151: - scheme - which scheme to be used for solving the involved linear systems
1153: Options Database Keys:
1154: + -pep_refine <type> - refinement type, one of <none,simple,multiple>
1155: . -pep_refine_partitions <n> - the number of partitions
1156: . -pep_refine_tol <tol> - the tolerance
1157: . -pep_refine_its <its> - number of iterations
1158: - -pep_refine_scheme - to set the scheme for the linear solves
1160: Notes:
1161: By default, iterative refinement is disabled, since it may be very
1162: costly. There are two possible refinement strategies, simple and multiple.
1163: The simple approach performs iterative refinement on each of the
1164: converged eigenpairs individually, whereas the multiple strategy works
1165: with the invariant pair as a whole, refining all eigenpairs simultaneously.
1166: The latter may be required for the case of multiple eigenvalues.
1168: In some cases, especially when using direct solvers within the
1169: iterative refinement method, it may be helpful for improved scalability
1170: to split the communicator in several partitions. The npart parameter
1171: indicates how many partitions to use (defaults to 1).
1173: The tol and its parameters specify the stopping criterion. In the simple
1174: method, refinement continues until the residual of each eigenpair is
1175: below the tolerance (tol defaults to the PEP tol, but may be set to a
1176: different value). In contrast, the multiple method simply performs its
1177: refinement iterations (just one by default).
1179: The scheme argument is used to change the way in which linear systems are
1180: solved. Possible choices are explicit, mixed block elimination (MBE),
1181: and Schur complement.
1183: Level: intermediate
1185: .seealso: PEPGetRefine()
1186: @*/
1187: PetscErrorCode PEPSetRefine(PEP pep,PEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its,PEPRefineScheme scheme)1188: {
1189: PetscMPIInt size;
1197: pep->refine = refine;
1198: if (refine) { /* process parameters only if not REFINE_NONE */
1199: if (npart!=pep->npart) {
1200: PetscSubcommDestroy(&pep->refinesubc);
1201: KSPDestroy(&pep->refineksp);
1202: }
1203: if (npart == PETSC_DEFAULT || npart == PETSC_DECIDE) {
1204: pep->npart = 1;
1205: } else {
1206: MPI_Comm_size(PetscObjectComm((PetscObject)pep),&size);
1208: pep->npart = npart;
1209: }
1210: if (tol == PETSC_DEFAULT || tol == PETSC_DECIDE) {
1211: pep->rtol = PETSC_DEFAULT;
1212: } else {
1214: pep->rtol = tol;
1215: }
1216: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
1217: pep->rits = PETSC_DEFAULT;
1218: } else {
1220: pep->rits = its;
1221: }
1222: pep->scheme = scheme;
1223: }
1224: pep->state = PEP_STATE_INITIAL;
1225: PetscFunctionReturn(0);
1226: }
1228: /*@C
1229: PEPGetRefine - Gets the refinement strategy used by the PEP object, and the
1230: associated parameters.
1232: Not Collective
1234: Input Parameter:
1235: . pep - the polynomial eigensolver context
1237: Output Parameters:
1238: + refine - refinement type
1239: . npart - number of partitions of the communicator
1240: . tol - the convergence tolerance
1241: . its - maximum number of refinement iterations
1242: - scheme - the scheme used for solving linear systems
1244: Level: intermediate
1246: Note:
1247: The user can specify NULL for any parameter that is not needed.
1249: .seealso: PEPSetRefine()
1250: @*/
1251: PetscErrorCode PEPGetRefine(PEP pep,PEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its,PEPRefineScheme *scheme)1252: {
1254: if (refine) *refine = pep->refine;
1255: if (npart) *npart = pep->npart;
1256: if (tol) *tol = pep->rtol;
1257: if (its) *its = pep->rits;
1258: if (scheme) *scheme = pep->scheme;
1259: PetscFunctionReturn(0);
1260: }
1262: /*@C
1263: PEPSetOptionsPrefix - Sets the prefix used for searching for all
1264: PEP options in the database.
1266: Logically Collective on pep
1268: Input Parameters:
1269: + pep - the polynomial eigensolver context
1270: - prefix - the prefix string to prepend to all PEP option requests
1272: Notes:
1273: A hyphen (-) must NOT be given at the beginning of the prefix name.
1274: The first character of all runtime options is AUTOMATICALLY the
1275: hyphen.
1277: For example, to distinguish between the runtime options for two
1278: different PEP contexts, one could call
1279: .vb
1280: PEPSetOptionsPrefix(pep1,"qeig1_")
1281: PEPSetOptionsPrefix(pep2,"qeig2_")
1282: .ve
1284: Level: advanced
1286: .seealso: PEPAppendOptionsPrefix(), PEPGetOptionsPrefix()
1287: @*/
1288: PetscErrorCode PEPSetOptionsPrefix(PEP pep,const char *prefix)1289: {
1291: if (!pep->st) PEPGetST(pep,&pep->st);
1292: STSetOptionsPrefix(pep->st,prefix);
1293: if (!pep->V) PEPGetBV(pep,&pep->V);
1294: BVSetOptionsPrefix(pep->V,prefix);
1295: if (!pep->ds) PEPGetDS(pep,&pep->ds);
1296: DSSetOptionsPrefix(pep->ds,prefix);
1297: if (!pep->rg) PEPGetRG(pep,&pep->rg);
1298: RGSetOptionsPrefix(pep->rg,prefix);
1299: PetscObjectSetOptionsPrefix((PetscObject)pep,prefix);
1300: PetscFunctionReturn(0);
1301: }
1303: /*@C
1304: PEPAppendOptionsPrefix - Appends to the prefix used for searching for all
1305: PEP options in the database.
1307: Logically Collective on pep
1309: Input Parameters:
1310: + pep - the polynomial eigensolver context
1311: - prefix - the prefix string to prepend to all PEP option requests
1313: Notes:
1314: A hyphen (-) must NOT be given at the beginning of the prefix name.
1315: The first character of all runtime options is AUTOMATICALLY the hyphen.
1317: Level: advanced
1319: .seealso: PEPSetOptionsPrefix(), PEPGetOptionsPrefix()
1320: @*/
1321: PetscErrorCode PEPAppendOptionsPrefix(PEP pep,const char *prefix)1322: {
1324: if (!pep->st) PEPGetST(pep,&pep->st);
1325: STAppendOptionsPrefix(pep->st,prefix);
1326: if (!pep->V) PEPGetBV(pep,&pep->V);
1327: BVAppendOptionsPrefix(pep->V,prefix);
1328: if (!pep->ds) PEPGetDS(pep,&pep->ds);
1329: DSAppendOptionsPrefix(pep->ds,prefix);
1330: if (!pep->rg) PEPGetRG(pep,&pep->rg);
1331: RGAppendOptionsPrefix(pep->rg,prefix);
1332: PetscObjectAppendOptionsPrefix((PetscObject)pep,prefix);
1333: PetscFunctionReturn(0);
1334: }
1336: /*@C
1337: PEPGetOptionsPrefix - Gets the prefix used for searching for all
1338: PEP options in the database.
1340: Not Collective
1342: Input Parameters:
1343: . pep - the polynomial eigensolver context
1345: Output Parameters:
1346: . prefix - pointer to the prefix string used is returned
1348: Note:
1349: On the Fortran side, the user should pass in a string 'prefix' of
1350: sufficient length to hold the prefix.
1352: Level: advanced
1354: .seealso: PEPSetOptionsPrefix(), PEPAppendOptionsPrefix()
1355: @*/
1356: PetscErrorCode PEPGetOptionsPrefix(PEP pep,const char *prefix[])1357: {
1360: PetscObjectGetOptionsPrefix((PetscObject)pep,prefix);
1361: PetscFunctionReturn(0);
1362: }