Actual source code: pepopts.c
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: /*@
19: PEPMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective
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: [](ch:pep), `PEPMonitorSet()`, `PEPSetTrackAll()`
34: @*/
35: PetscErrorCode PEPMonitorSetFromOptions(PEP pep,const char opt[],const char name[],PetscCtx 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: PetscFunctionBegin;
48: PetscCall(PetscOptionsCreateViewer(PetscObjectComm((PetscObject)pep),((PetscObject)pep)->options,((PetscObject)pep)->prefix,opt,&viewer,&format,&flg));
49: if (!flg) PetscFunctionReturn(PETSC_SUCCESS);
51: PetscCall(PetscViewerGetType(viewer,&vtype));
52: PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
53: PetscCall(PetscFunctionListFind(PEPMonitorList,key,&mfunc));
54: PetscCheck(mfunc,PetscObjectComm((PetscObject)pep),PETSC_ERR_SUP,"Specified viewer and format not supported");
55: PetscCall(PetscFunctionListFind(PEPMonitorCreateList,key,&cfunc));
56: PetscCall(PetscFunctionListFind(PEPMonitorDestroyList,key,&dfunc));
57: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
58: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
60: PetscCall((*cfunc)(viewer,format,ctx,&vf));
61: PetscCall(PetscViewerDestroy(&viewer));
62: PetscCall(PEPMonitorSet(pep,mfunc,vf,(PetscCtxDestroyFn*)dfunc));
63: if (trackall) PetscCall(PEPSetTrackAll(pep,PETSC_TRUE));
64: PetscFunctionReturn(PETSC_SUCCESS);
65: }
67: /*@
68: PEPSetFromOptions - Sets `PEP` options from the options database.
69: This routine must be called before `PEPSetUp()` if the user is to be
70: allowed to configure the solver.
72: Collective
74: Input Parameter:
75: . pep - the polynomial eigensolver context
77: Note:
78: To see all options, run your program with the `-help` option.
80: Level: beginner
82: .seealso: [](ch:pep), `PEPSetOptionsPrefix()`
83: @*/
84: PetscErrorCode PEPSetFromOptions(PEP pep)
85: {
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;
95: PetscFunctionBegin;
97: PetscCall(PEPRegisterAll());
98: PetscObjectOptionsBegin((PetscObject)pep);
99: PetscCall(PetscOptionsFList("-pep_type","Polynomial eigensolver method","PEPSetType",PEPList,(char*)(((PetscObject)pep)->type_name?((PetscObject)pep)->type_name:PEPTOAR),type,sizeof(type),&flg));
100: if (flg) PetscCall(PEPSetType(pep,type));
101: else if (!((PetscObject)pep)->type_name) PetscCall(PEPSetType(pep,PEPTOAR));
103: PetscCall(PetscOptionsBoolGroupBegin("-pep_general","General polynomial eigenvalue problem","PEPSetProblemType",&flg));
104: if (flg) PetscCall(PEPSetProblemType(pep,PEP_GENERAL));
105: PetscCall(PetscOptionsBoolGroup("-pep_hermitian","Hermitian polynomial eigenvalue problem","PEPSetProblemType",&flg));
106: if (flg) PetscCall(PEPSetProblemType(pep,PEP_HERMITIAN));
107: PetscCall(PetscOptionsBoolGroup("-pep_hyperbolic","Hyperbolic polynomial eigenvalue problem","PEPSetProblemType",&flg));
108: if (flg) PetscCall(PEPSetProblemType(pep,PEP_HYPERBOLIC));
109: PetscCall(PetscOptionsBoolGroupEnd("-pep_gyroscopic","Gyroscopic polynomial eigenvalue problem","PEPSetProblemType",&flg));
110: if (flg) PetscCall(PEPSetProblemType(pep,PEP_GYROSCOPIC));
112: scale = pep->scale;
113: PetscCall(PetscOptionsEnum("-pep_scale","Scaling strategy","PEPSetScale",PEPScaleTypes,(PetscEnum)scale,(PetscEnum*)&scale,&flg1));
114: r = pep->sfactor;
115: PetscCall(PetscOptionsReal("-pep_scale_factor","Scale factor","PEPSetScale",pep->sfactor,&r,&flg2));
116: if (!flg2 && r==1.0) r = PETSC_DETERMINE;
117: j = pep->sits;
118: PetscCall(PetscOptionsInt("-pep_scale_its","Number of iterations in diagonal scaling","PEPSetScale",pep->sits,&j,&flg3));
119: t = pep->slambda;
120: PetscCall(PetscOptionsReal("-pep_scale_lambda","Estimate of eigenvalue (modulus) for diagonal scaling","PEPSetScale",pep->slambda,&t,&flg4));
121: if (flg1 || flg2 || flg3 || flg4) PetscCall(PEPSetScale(pep,scale,r,NULL,NULL,j,t));
123: PetscCall(PetscOptionsEnum("-pep_extract","Extraction method","PEPSetExtract",PEPExtractTypes,(PetscEnum)pep->extract,(PetscEnum*)&pep->extract,NULL));
125: refine = pep->refine;
126: PetscCall(PetscOptionsEnum("-pep_refine","Iterative refinement method","PEPSetRefine",PEPRefineTypes,(PetscEnum)refine,(PetscEnum*)&refine,&flg1));
127: i = pep->npart;
128: PetscCall(PetscOptionsInt("-pep_refine_partitions","Number of partitions of the communicator for iterative refinement","PEPSetRefine",pep->npart,&i,&flg2));
129: r = pep->rtol;
130: PetscCall(PetscOptionsReal("-pep_refine_tol","Tolerance for iterative refinement","PEPSetRefine",pep->rtol==(PetscReal)PETSC_DETERMINE?SLEPC_DEFAULT_TOL/1000:pep->rtol,&r,&flg3));
131: j = pep->rits;
132: PetscCall(PetscOptionsInt("-pep_refine_its","Maximum number of iterations for iterative refinement","PEPSetRefine",pep->rits,&j,&flg4));
133: scheme = pep->scheme;
134: PetscCall(PetscOptionsEnum("-pep_refine_scheme","Scheme used for linear systems within iterative refinement","PEPSetRefine",PEPRefineSchemes,(PetscEnum)scheme,(PetscEnum*)&scheme,&flg5));
135: if (flg1 || flg2 || flg3 || flg4 || flg5) PetscCall(PEPSetRefine(pep,refine,i,r,j,scheme));
137: i = pep->max_it;
138: PetscCall(PetscOptionsInt("-pep_max_it","Maximum number of iterations","PEPSetTolerances",pep->max_it,&i,&flg1));
139: r = pep->tol;
140: PetscCall(PetscOptionsReal("-pep_tol","Tolerance","PEPSetTolerances",SlepcDefaultTol(pep->tol),&r,&flg2));
141: if (flg1 || flg2) PetscCall(PEPSetTolerances(pep,r,i));
143: PetscCall(PetscOptionsBoolGroupBegin("-pep_conv_rel","Relative error convergence test","PEPSetConvergenceTest",&flg));
144: if (flg) PetscCall(PEPSetConvergenceTest(pep,PEP_CONV_REL));
145: PetscCall(PetscOptionsBoolGroup("-pep_conv_norm","Convergence test relative to the matrix norms","PEPSetConvergenceTest",&flg));
146: if (flg) PetscCall(PEPSetConvergenceTest(pep,PEP_CONV_NORM));
147: PetscCall(PetscOptionsBoolGroup("-pep_conv_abs","Absolute error convergence test","PEPSetConvergenceTest",&flg));
148: if (flg) PetscCall(PEPSetConvergenceTest(pep,PEP_CONV_ABS));
149: PetscCall(PetscOptionsBoolGroupEnd("-pep_conv_user","User-defined convergence test","PEPSetConvergenceTest",&flg));
150: if (flg) PetscCall(PEPSetConvergenceTest(pep,PEP_CONV_USER));
152: PetscCall(PetscOptionsBoolGroupBegin("-pep_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","PEPSetStoppingTest",&flg));
153: if (flg) PetscCall(PEPSetStoppingTest(pep,PEP_STOP_BASIC));
154: PetscCall(PetscOptionsBoolGroupEnd("-pep_stop_user","User-defined stopping test","PEPSetStoppingTest",&flg));
155: if (flg) PetscCall(PEPSetStoppingTest(pep,PEP_STOP_USER));
157: i = pep->nev;
158: PetscCall(PetscOptionsInt("-pep_nev","Number of eigenvalues to compute","PEPSetDimensions",pep->nev,&i,&flg1));
159: j = pep->ncv;
160: PetscCall(PetscOptionsInt("-pep_ncv","Number of basis vectors","PEPSetDimensions",pep->ncv,&j,&flg2));
161: k = pep->mpd;
162: PetscCall(PetscOptionsInt("-pep_mpd","Maximum dimension of projected problem","PEPSetDimensions",pep->mpd,&k,&flg3));
163: if (flg1 || flg2 || flg3) PetscCall(PEPSetDimensions(pep,i,j,k));
165: PetscCall(PetscOptionsEnum("-pep_basis","Polynomial basis","PEPSetBasis",PEPBasisTypes,(PetscEnum)pep->basis,(PetscEnum*)&pep->basis,NULL));
167: PetscCall(PetscOptionsBoolGroupBegin("-pep_largest_magnitude","Compute largest eigenvalues in magnitude","PEPSetWhichEigenpairs",&flg));
168: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_LARGEST_MAGNITUDE));
169: PetscCall(PetscOptionsBoolGroup("-pep_smallest_magnitude","Compute smallest eigenvalues in magnitude","PEPSetWhichEigenpairs",&flg));
170: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_SMALLEST_MAGNITUDE));
171: PetscCall(PetscOptionsBoolGroup("-pep_largest_real","Compute eigenvalues with largest real parts","PEPSetWhichEigenpairs",&flg));
172: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_LARGEST_REAL));
173: PetscCall(PetscOptionsBoolGroup("-pep_smallest_real","Compute eigenvalues with smallest real parts","PEPSetWhichEigenpairs",&flg));
174: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_SMALLEST_REAL));
175: PetscCall(PetscOptionsBoolGroup("-pep_largest_imaginary","Compute eigenvalues with largest imaginary parts","PEPSetWhichEigenpairs",&flg));
176: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_LARGEST_IMAGINARY));
177: PetscCall(PetscOptionsBoolGroup("-pep_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","PEPSetWhichEigenpairs",&flg));
178: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_SMALLEST_IMAGINARY));
179: PetscCall(PetscOptionsBoolGroup("-pep_target_magnitude","Compute eigenvalues closest to target","PEPSetWhichEigenpairs",&flg));
180: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_TARGET_MAGNITUDE));
181: PetscCall(PetscOptionsBoolGroup("-pep_target_real","Compute eigenvalues with real parts closest to target","PEPSetWhichEigenpairs",&flg));
182: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_TARGET_REAL));
183: PetscCall(PetscOptionsBoolGroup("-pep_target_imaginary","Compute eigenvalues with imaginary parts closest to target","PEPSetWhichEigenpairs",&flg));
184: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_TARGET_IMAGINARY));
185: PetscCall(PetscOptionsBoolGroup("-pep_all","Compute all eigenvalues in an interval or a region","PEPSetWhichEigenpairs",&flg));
186: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_ALL));
187: PetscCall(PetscOptionsBoolGroupEnd("-pep_which_user","Select the user-defined selection criterion","PEPSetWhichEigenpairs",&flg));
188: if (flg) PetscCall(PEPSetWhichEigenpairs(pep,PEP_WHICH_USER));
190: PetscCall(PetscOptionsScalar("-pep_target","Value of the target","PEPSetTarget",pep->target,&s,&flg));
191: if (flg) {
192: if (pep->which!=PEP_TARGET_REAL && pep->which!=PEP_TARGET_IMAGINARY) PetscCall(PEPSetWhichEigenpairs(pep,PEP_TARGET_MAGNITUDE));
193: PetscCall(PEPSetTarget(pep,s));
194: }
196: k = 2;
197: PetscCall(PetscOptionsRealArray("-pep_interval","Computational interval (two real values separated with a comma without spaces)","PEPSetInterval",array,&k,&flg));
198: if (flg) {
199: PetscCheck(k>1,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_SIZ,"Must pass two values in -pep_interval (comma-separated without spaces)");
200: PetscCall(PEPSetWhichEigenpairs(pep,PEP_ALL));
201: PetscCall(PEPSetInterval(pep,array[0],array[1]));
202: }
204: /* -----------------------------------------------------------------------*/
205: /*
206: Cancels all monitors hardwired into code before call to PEPSetFromOptions()
207: */
208: PetscCall(PetscOptionsBool("-pep_monitor_cancel","Remove any hardwired monitor routines","PEPMonitorCancel",PETSC_FALSE,&flg,&set));
209: if (set && flg) PetscCall(PEPMonitorCancel(pep));
210: PetscCall(PEPMonitorSetFromOptions(pep,"-pep_monitor","first_approximation",NULL,PETSC_FALSE));
211: PetscCall(PEPMonitorSetFromOptions(pep,"-pep_monitor_all","all_approximations",NULL,PETSC_TRUE));
212: PetscCall(PEPMonitorSetFromOptions(pep,"-pep_monitor_conv","convergence_history",NULL,PETSC_FALSE));
214: /* -----------------------------------------------------------------------*/
215: PetscCall(PetscOptionsName("-pep_view","Print detailed information on solver used","PEPView",&set));
216: PetscCall(PetscOptionsName("-pep_view_vectors","View computed eigenvectors","PEPVectorsView",&set));
217: PetscCall(PetscOptionsName("-pep_view_values","View computed eigenvalues","PEPValuesView",&set));
218: PetscCall(PetscOptionsName("-pep_converged_reason","Print reason for convergence, and number of iterations","PEPConvergedReasonView",&set));
219: PetscCall(PetscOptionsName("-pep_error_absolute","Print absolute errors of each eigenpair","PEPErrorView",&set));
220: PetscCall(PetscOptionsName("-pep_error_relative","Print relative errors of each eigenpair","PEPErrorView",&set));
221: PetscCall(PetscOptionsName("-pep_error_backward","Print backward errors of each eigenpair","PEPErrorView",&set));
223: PetscTryTypeMethod(pep,setfromoptions,PetscOptionsObject);
224: PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)pep,PetscOptionsObject));
225: PetscOptionsEnd();
227: if (!pep->V) PetscCall(PEPGetBV(pep,&pep->V));
228: PetscCall(BVSetFromOptions(pep->V));
229: if (!pep->rg) PetscCall(PEPGetRG(pep,&pep->rg));
230: PetscCall(RGSetFromOptions(pep->rg));
231: if (!pep->ds) PetscCall(PEPGetDS(pep,&pep->ds));
232: PetscCall(PEPSetDSType(pep));
233: PetscCall(DSSetFromOptions(pep->ds));
234: if (!pep->st) PetscCall(PEPGetST(pep,&pep->st));
235: PetscCall(PEPSetDefaultST(pep));
236: PetscCall(STSetFromOptions(pep->st));
237: if (!pep->refineksp) PetscCall(PEPRefineGetKSP(pep,&pep->refineksp));
238: PetscCall(KSPSetFromOptions(pep->refineksp));
239: pep->setfromoptionscalled++;
240: PetscFunctionReturn(PETSC_SUCCESS);
241: }
243: /*@
244: PEPGetTolerances - Gets the tolerance and maximum iteration count used
245: by the `PEP` convergence tests.
247: Not Collective
249: Input Parameter:
250: . pep - the polynomial eigensolver context
252: Output Parameters:
253: + tol - the convergence tolerance
254: - maxits - maximum number of iterations
256: Note:
257: The user can specify `NULL` for any parameter that is not needed.
259: Level: intermediate
261: .seealso: [](ch:pep), `PEPSetTolerances()`
262: @*/
263: PetscErrorCode PEPGetTolerances(PEP pep,PetscReal *tol,PetscInt *maxits)
264: {
265: PetscFunctionBegin;
267: if (tol) *tol = pep->tol;
268: if (maxits) *maxits = pep->max_it;
269: PetscFunctionReturn(PETSC_SUCCESS);
270: }
272: /*@
273: PEPSetTolerances - Sets the tolerance and maximum iteration count used
274: by the `PEP` convergence tests.
276: Logically Collective
278: Input Parameters:
279: + pep - the polynomial eigensolver context
280: . tol - the convergence tolerance
281: - maxits - maximum number of iterations to use
283: Options Database Keys:
284: + -pep_tol tol - sets the convergence tolerance
285: - -pep_max_it maxits - sets the maximum number of iterations allowed
287: Note:
288: Use `PETSC_CURRENT` to retain the current value of any of the parameters.
289: Use `PETSC_DETERMINE` for either argument to assign a default value computed
290: internally (may be different in each solver).
291: For `maxits` use `PETSC_UNLIMITED` to indicate there is no upper bound on this value.
293: Level: intermediate
295: .seealso: [](ch:pep), `PEPGetTolerances()`
296: @*/
297: PetscErrorCode PEPSetTolerances(PEP pep,PetscReal tol,PetscInt maxits)
298: {
299: PetscFunctionBegin;
303: if (tol == (PetscReal)PETSC_DETERMINE) {
304: pep->tol = PETSC_DETERMINE;
305: pep->state = PEP_STATE_INITIAL;
306: } else if (tol != (PetscReal)PETSC_CURRENT) {
307: PetscCheck(tol>0.0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
308: pep->tol = tol;
309: }
310: if (maxits == PETSC_DETERMINE) {
311: pep->max_it = PETSC_DETERMINE;
312: pep->state = PEP_STATE_INITIAL;
313: } else if (maxits == PETSC_UNLIMITED) {
314: pep->max_it = PETSC_INT_MAX;
315: } else if (maxits != PETSC_CURRENT) {
316: PetscCheck(maxits>0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
317: pep->max_it = maxits;
318: }
319: PetscFunctionReturn(PETSC_SUCCESS);
320: }
322: /*@
323: PEPGetDimensions - Gets the number of eigenvalues to compute
324: and the dimension of the subspace.
326: Not Collective
328: Input Parameter:
329: . pep - the polynomial eigensolver context
331: Output Parameters:
332: + nev - number of eigenvalues to compute
333: . ncv - the maximum dimension of the subspace to be used by the solver
334: - mpd - the maximum dimension allowed for the projected problem
336: Notes:
337: The user can specify `NULL` for any parameter that is not needed.
339: Level: intermediate
341: .seealso: [](ch:pep), `PEPSetDimensions()`
342: @*/
343: PetscErrorCode PEPGetDimensions(PEP pep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
344: {
345: PetscFunctionBegin;
347: if (nev) *nev = pep->nev;
348: if (ncv) *ncv = pep->ncv;
349: if (mpd) *mpd = pep->mpd;
350: PetscFunctionReturn(PETSC_SUCCESS);
351: }
353: /*@
354: PEPSetDimensions - Sets the number of eigenvalues to compute
355: and the dimension of the subspace.
357: Logically Collective
359: Input Parameters:
360: + pep - the polynomial eigensolver context
361: . nev - number of eigenvalues to compute
362: . ncv - the maximum dimension of the subspace to be used by the solver
363: - mpd - the maximum dimension allowed for the projected problem
365: Options Database Keys:
366: + -pep_nev nev - sets the number of eigenvalues
367: . -pep_ncv ncv - sets the dimension of the subspace
368: - -pep_mpd mpd - sets the maximum projected dimension
370: Notes:
371: Use `PETSC_DETERMINE` for `ncv` and `mpd` to assign a reasonably good value, which is
372: dependent on the solution method. For any of the arguments, use `PETSC_CURRENT`
373: to preserve the current value.
375: The parameters `ncv` and `mpd` are intimately related, so that the user is advised
376: to set one of them at most. Normal usage is\:
378: 1. in cases where `nev` is small, the user sets `ncv` (a reasonable default is `2*nev`).
379: 2. in cases where `nev` is large, the user sets `mpd`.
381: The value of `ncv` should always be between `nev` and `(nev+mpd)`, typically
382: `ncv=nev+mpd`. If `nev` is not too large, `mpd=nev` is a reasonable choice, otherwise
383: a smaller value should be used.
385: When computing all eigenvalues in an interval, see `PEPSetInterval()`, these
386: parameters lose relevance, and tuning must be done with
387: `PEPSTOARSetDimensions()`.
389: Level: intermediate
391: .seealso: [](ch:pep), `PEPGetDimensions()`, `PEPSetInterval()`, `PEPSTOARSetDimensions()`
392: @*/
393: PetscErrorCode PEPSetDimensions(PEP pep,PetscInt nev,PetscInt ncv,PetscInt mpd)
394: {
395: PetscFunctionBegin;
400: if (nev != PETSC_CURRENT) {
401: PetscCheck(nev>0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
402: pep->nev = nev;
403: }
404: if (ncv == PETSC_DETERMINE) {
405: pep->ncv = PETSC_DETERMINE;
406: } else if (ncv != PETSC_CURRENT) {
407: PetscCheck(ncv>0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
408: pep->ncv = ncv;
409: }
410: if (mpd == PETSC_DETERMINE) {
411: pep->mpd = PETSC_DETERMINE;
412: } else if (mpd != PETSC_CURRENT) {
413: PetscCheck(mpd>0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
414: pep->mpd = mpd;
415: }
416: pep->state = PEP_STATE_INITIAL;
417: PetscFunctionReturn(PETSC_SUCCESS);
418: }
420: /*@
421: PEPSetWhichEigenpairs - Specifies which portion of the spectrum is
422: to be sought.
424: Logically Collective
426: Input Parameters:
427: + pep - the polynomial eigensolver context
428: - which - the portion of the spectrum to be sought, see `PEPWhich` for possible values
430: Options Database Keys:
431: + -pep_largest_magnitude - sets largest eigenvalues in magnitude
432: . -pep_smallest_magnitude - sets smallest eigenvalues in magnitude
433: . -pep_largest_real - sets largest real parts
434: . -pep_smallest_real - sets smallest real parts
435: . -pep_largest_imaginary - sets largest imaginary parts
436: . -pep_smallest_imaginary - sets smallest imaginary parts
437: . -pep_target_magnitude - sets eigenvalues closest to target
438: . -pep_target_real - sets real parts closest to target
439: . -pep_target_imaginary - sets imaginary parts closest to target
440: . -pep_all - sets all eigenvalues in an interval or region
441: - -pep_which_user - select the user-defined selection criterion
443: Notes:
444: Not all eigensolvers implemented in `PEP` account for all the possible values
445: of `which`. Also, some values make sense only for certain types of
446: problems. If SLEPc is compiled for real numbers `PEP_LARGEST_IMAGINARY`
447: and `PEP_SMALLEST_IMAGINARY` use the absolute value of the imaginary part
448: for eigenvalue selection.
450: The target is a scalar value provided with `PEPSetTarget()`.
452: The criterion `PEP_TARGET_IMAGINARY` is available only in case PETSc and
453: SLEPc have been built with complex scalars.
455: `PEP_ALL` is intended for use in combination with an interval (see
456: `PEPSetInterval()`), when all eigenvalues within the interval are requested,
457: and also for computing all eigenvalues in a region with the `PEPCISS` solver.
459: Level: intermediate
461: .seealso: [](ch:pep), `PEPGetWhichEigenpairs()`, `PEPSetTarget()`, `PEPSetInterval()`, `PEPSetDimensions()`, `PEPSetEigenvalueComparison()`, `PEPWhich`
462: @*/
463: PetscErrorCode PEPSetWhichEigenpairs(PEP pep,PEPWhich which)
464: {
465: PetscFunctionBegin;
468: switch (which) {
469: case PEP_LARGEST_MAGNITUDE:
470: case PEP_SMALLEST_MAGNITUDE:
471: case PEP_LARGEST_REAL:
472: case PEP_SMALLEST_REAL:
473: case PEP_LARGEST_IMAGINARY:
474: case PEP_SMALLEST_IMAGINARY:
475: case PEP_TARGET_MAGNITUDE:
476: case PEP_TARGET_REAL:
477: #if PetscDefined(USE_COMPLEX)
478: case PEP_TARGET_IMAGINARY:
479: #endif
480: case PEP_ALL:
481: case PEP_WHICH_USER:
482: if (pep->which != which) {
483: pep->state = PEP_STATE_INITIAL;
484: pep->which = which;
485: }
486: break;
487: #if !PetscDefined(USE_COMPLEX)
488: case PEP_TARGET_IMAGINARY:
489: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_SUP,"PEP_TARGET_IMAGINARY can be used only with complex scalars");
490: #endif
491: default:
492: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
493: }
494: PetscFunctionReturn(PETSC_SUCCESS);
495: }
497: /*@
498: PEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
499: sought.
501: Not Collective
503: Input Parameter:
504: . pep - the polynomial eigensolver context
506: Output Parameter:
507: . which - the portion of the spectrum to be sought
509: Level: intermediate
511: .seealso: [](ch:pep), `PEPSetWhichEigenpairs()`, `PEPWhich`
512: @*/
513: PetscErrorCode PEPGetWhichEigenpairs(PEP pep,PEPWhich *which)
514: {
515: PetscFunctionBegin;
517: PetscAssertPointer(which,2);
518: *which = pep->which;
519: PetscFunctionReturn(PETSC_SUCCESS);
520: }
522: /*@
523: PEPSetEigenvalueComparison - Specifies the eigenvalue comparison function
524: when `PEPSetWhichEigenpairs()` is set to `PEP_WHICH_USER`.
526: Logically Collective
528: Input Parameters:
529: + pep - the polynomial eigensolver context
530: . comp - the comparison function, see `SlepcEigenvalueComparisonFn` for the calling sequence
531: - ctx - a context pointer (the last parameter to the comparison function)
533: Level: advanced
535: .seealso: [](ch:pep), `PEPSetWhichEigenpairs()`, `PEPWhich`
536: @*/
537: PetscErrorCode PEPSetEigenvalueComparison(PEP pep,SlepcEigenvalueComparisonFn *comp,PetscCtx ctx)
538: {
539: PetscFunctionBegin;
541: pep->sc->comparison = comp;
542: pep->sc->comparisonctx = ctx;
543: pep->which = PEP_WHICH_USER;
544: PetscFunctionReturn(PETSC_SUCCESS);
545: }
547: /*@
548: PEPSetProblemType - Specifies the type of the polynomial eigenvalue problem.
550: Logically Collective
552: Input Parameters:
553: + pep - the polynomial eigensolver context
554: - type - a known type of polynomial eigenvalue problem
556: Options Database Keys:
557: + -pep_general - general problem with no particular structure
558: . -pep_hermitian - problem whose coefficient matrices are Hermitian
559: . -pep_hyperbolic - Hermitian problem that satisfies the definition of hyperbolic
560: - -pep_gyroscopic - problem with gyroscopic structure
562: Notes:
563: See `PEPProblemType` for possible problem types.
565: This function is used to instruct SLEPc to exploit certain structure in
566: the polynomial eigenproblem. By default, no particular structure is assumed.
568: If the problem matrices are Hermitian (symmetric in the real case) or
569: Hermitian/skew-Hermitian then the solver can exploit this fact to perform
570: less operations or provide better stability. Hyperbolic problems are a
571: particular case of Hermitian problems, some solvers may treat them simply as
572: Hermitian.
574: Level: intermediate
576: .seealso: [](ch:pep), `PEPSetOperators()`, `PEPSetType()`, `PEPGetProblemType()`, `PEPProblemType`
577: @*/
578: PetscErrorCode PEPSetProblemType(PEP pep,PEPProblemType type)
579: {
580: PetscFunctionBegin;
583: PetscCheck(type==PEP_GENERAL || type==PEP_HERMITIAN || type==PEP_HYPERBOLIC || type==PEP_GYROSCOPIC,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
584: if (type != pep->problem_type) {
585: pep->problem_type = type;
586: pep->state = PEP_STATE_INITIAL;
587: }
588: PetscFunctionReturn(PETSC_SUCCESS);
589: }
591: /*@
592: PEPGetProblemType - Gets the problem type from the `PEP` object.
594: Not Collective
596: Input Parameter:
597: . pep - the polynomial eigensolver context
599: Output Parameter:
600: . type - the problem type
602: Level: intermediate
604: .seealso: [](ch:pep), `PEPSetProblemType()`, `PEPProblemType`
605: @*/
606: PetscErrorCode PEPGetProblemType(PEP pep,PEPProblemType *type)
607: {
608: PetscFunctionBegin;
610: PetscAssertPointer(type,2);
611: *type = pep->problem_type;
612: PetscFunctionReturn(PETSC_SUCCESS);
613: }
615: /*@
616: PEPSetBasis - Specifies the type of polynomial basis used to describe the
617: polynomial eigenvalue problem.
619: Logically Collective
621: Input Parameters:
622: + pep - the polynomial eigensolver context
623: - basis - the type of polynomial basis, see `PEPBasis` for possible values
625: Options Database Key:
626: . -pep_basis (monomial|chebyshev1|chebyshev2|legendre|laguerre|hermite) - select the basis type
628: Note:
629: By default, the coefficient matrices passed via `PEPSetOperators()` are
630: expressed in the monomial basis, i.e.
631: $P(\lambda) = A_0 + \lambda A_1 + \lambda^2 A_2 + \dots + \lambda^d A_d$.
632: Other polynomial bases may have better numerical behavior, but the user
633: must then pass the coefficient matrices accordingly.
635: Level: intermediate
637: .seealso: [](ch:pep), `PEPSetOperators()`, `PEPGetBasis()`, `PEPBasis`
638: @*/
639: PetscErrorCode PEPSetBasis(PEP pep,PEPBasis basis)
640: {
641: PetscFunctionBegin;
644: pep->basis = basis;
645: PetscFunctionReturn(PETSC_SUCCESS);
646: }
648: /*@
649: PEPGetBasis - Gets the type of polynomial basis from the `PEP` object.
651: Not Collective
653: Input Parameter:
654: . pep - the polynomial eigensolver context
656: Output Parameter:
657: . basis - the polynomial basis
659: Level: intermediate
661: .seealso: [](ch:pep), `PEPSetBasis()`, `PEPBasis`
662: @*/
663: PetscErrorCode PEPGetBasis(PEP pep,PEPBasis *basis)
664: {
665: PetscFunctionBegin;
667: PetscAssertPointer(basis,2);
668: *basis = pep->basis;
669: PetscFunctionReturn(PETSC_SUCCESS);
670: }
672: /*@
673: PEPSetTrackAll - Specifies if the solver must compute the residual of all
674: approximate eigenpairs or not.
676: Logically Collective
678: Input Parameters:
679: + pep - the polynomial eigensolver context
680: - trackall - whether compute all residuals or not
682: Notes:
683: If the user sets `trackall`=`PETSC_TRUE` then the solver explicitly computes
684: the residual for each eigenpair approximation. Computing the residual is
685: usually an expensive operation and solvers commonly compute the associated
686: residual to the first unconverged eigenpair.
688: The option `-pep_monitor_all` automatically activates this option.
690: Level: developer
692: .seealso: [](ch:pep), `PEPGetTrackAll()`
693: @*/
694: PetscErrorCode PEPSetTrackAll(PEP pep,PetscBool trackall)
695: {
696: PetscFunctionBegin;
699: pep->trackall = trackall;
700: PetscFunctionReturn(PETSC_SUCCESS);
701: }
703: /*@
704: PEPGetTrackAll - Returns the flag indicating whether all residual norms must
705: be computed or not.
707: Not Collective
709: Input Parameter:
710: . pep - the polynomial eigensolver context
712: Output Parameter:
713: . trackall - the returned flag
715: Level: developer
717: .seealso: [](ch:pep), `PEPSetTrackAll()`
718: @*/
719: PetscErrorCode PEPGetTrackAll(PEP pep,PetscBool *trackall)
720: {
721: PetscFunctionBegin;
723: PetscAssertPointer(trackall,2);
724: *trackall = pep->trackall;
725: PetscFunctionReturn(PETSC_SUCCESS);
726: }
728: /*@
729: PEPSetConvergenceTestFunction - Sets a function to compute the error estimate
730: used in the convergence test.
732: Logically Collective
734: Input Parameters:
735: + pep - the polynomial eigensolver context
736: . conv - convergence test function, see `PEPConvergenceTestFn` for the calling sequence
737: . ctx - context for private data for the convergence routine (may be `NULL`)
738: - destroy - a routine for destroying the context (may be `NULL`), see `PetscCtxDestroyFn`
739: for the calling sequence
741: Notes:
742: When this is called with a user-defined function, then the convergence
743: criterion is set to `PEP_CONV_USER`, see `PEPSetConvergenceTest()`.
745: If the error estimate returned by the convergence test function is less than
746: the tolerance, then the eigenvalue is accepted as converged.
748: Level: advanced
750: .seealso: [](ch:pep), `PEPSetConvergenceTest()`, `PEPSetTolerances()`
751: @*/
752: PetscErrorCode PEPSetConvergenceTestFunction(PEP pep,PEPConvergenceTestFn *conv,PetscCtx ctx,PetscCtxDestroyFn *destroy)
753: {
754: PetscFunctionBegin;
756: if (pep->convergeddestroy) PetscCall((*pep->convergeddestroy)(&pep->convergedctx));
757: pep->convergeduser = conv;
758: pep->convergeddestroy = destroy;
759: pep->convergedctx = ctx;
760: if (conv == PEPConvergedRelative) pep->conv = PEP_CONV_REL;
761: else if (conv == PEPConvergedNorm) pep->conv = PEP_CONV_NORM;
762: else if (conv == PEPConvergedAbsolute) pep->conv = PEP_CONV_ABS;
763: else {
764: pep->conv = PEP_CONV_USER;
765: pep->converged = pep->convergeduser;
766: }
767: PetscFunctionReturn(PETSC_SUCCESS);
768: }
770: /*@
771: PEPSetConvergenceTest - Specifies how to compute the error estimate
772: used in the convergence test.
774: Logically Collective
776: Input Parameters:
777: + pep - the polynomial eigensolver context
778: - conv - the type of convergence test, see `PEPConv` for possible values
780: Options Database Keys:
781: + -pep_conv_abs - sets the absolute convergence test
782: . -pep_conv_rel - sets the convergence test relative to the eigenvalue
783: . -pep_conv_norm - sets the convergence test relative to the matrix norms
784: - -pep_conv_user - selects the user-defined convergence test
786: Level: intermediate
788: .seealso: [](ch:pep), `PEPGetConvergenceTest()`, `PEPSetConvergenceTestFunction()`, `PEPSetStoppingTest()`, `PEPConv`
789: @*/
790: PetscErrorCode PEPSetConvergenceTest(PEP pep,PEPConv conv)
791: {
792: PetscFunctionBegin;
795: switch (conv) {
796: case PEP_CONV_ABS: pep->converged = PEPConvergedAbsolute; break;
797: case PEP_CONV_REL: pep->converged = PEPConvergedRelative; break;
798: case PEP_CONV_NORM: pep->converged = PEPConvergedNorm; break;
799: case PEP_CONV_USER:
800: PetscCheck(pep->convergeduser,PetscObjectComm((PetscObject)pep),PETSC_ERR_ORDER,"Must call PEPSetConvergenceTestFunction() first");
801: pep->converged = pep->convergeduser;
802: break;
803: default:
804: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
805: }
806: pep->conv = conv;
807: PetscFunctionReturn(PETSC_SUCCESS);
808: }
810: /*@
811: PEPGetConvergenceTest - Gets the method used to compute the error estimate
812: used in the convergence test.
814: Not Collective
816: Input Parameter:
817: . pep - the polynomial eigensolver context
819: Output Parameter:
820: . conv - the type of convergence test
822: Level: intermediate
824: .seealso: [](ch:pep), `PEPSetConvergenceTest()`, `PEPConv`
825: @*/
826: PetscErrorCode PEPGetConvergenceTest(PEP pep,PEPConv *conv)
827: {
828: PetscFunctionBegin;
830: PetscAssertPointer(conv,2);
831: *conv = pep->conv;
832: PetscFunctionReturn(PETSC_SUCCESS);
833: }
835: /*@
836: PEPSetStoppingTestFunction - Sets a function to decide when to stop the outer
837: iteration of the eigensolver.
839: Logically Collective
841: Input Parameters:
842: + pep - the polynomial eigensolver context
843: . stop - stopping test function, see `PEPStoppingTestFn` for the calling sequence
844: . ctx - context for private data for the stopping routine (may be `NULL`)
845: - destroy - a routine for destroying the context (may be `NULL`), see `PetscCtxDestroyFn`
846: for the calling sequence
848: Note:
849: When implementing a function for this, normal usage is to first call the
850: default routine `PEPStoppingBasic()` and then set `reason` to `PEP_CONVERGED_USER`
851: if some user-defined conditions have been met. To let the eigensolver continue
852: iterating, the result must be left as `PEP_CONVERGED_ITERATING`.
854: Level: advanced
856: .seealso: [](ch:pep), `PEPSetStoppingTest()`, `PEPStoppingBasic()`
857: @*/
858: PetscErrorCode PEPSetStoppingTestFunction(PEP pep,PEPStoppingTestFn *stop,PetscCtx ctx,PetscCtxDestroyFn *destroy)
859: {
860: PetscFunctionBegin;
862: if (pep->stoppingdestroy) PetscCall((*pep->stoppingdestroy)(&pep->stoppingctx));
863: pep->stoppinguser = stop;
864: pep->stoppingdestroy = destroy;
865: pep->stoppingctx = ctx;
866: if (stop == PEPStoppingBasic) pep->stop = PEP_STOP_BASIC;
867: else {
868: pep->stop = PEP_STOP_USER;
869: pep->stopping = pep->stoppinguser;
870: }
871: PetscFunctionReturn(PETSC_SUCCESS);
872: }
874: /*@
875: PEPSetStoppingTest - Specifies how to decide the termination of the outer
876: loop of the eigensolver.
878: Logically Collective
880: Input Parameters:
881: + pep - the polynomial eigensolver context
882: - stop - the type of stopping test, see `PEPStop`
884: Options Database Keys:
885: + -pep_stop_basic - sets the default stopping test
886: - -pep_stop_user - selects the user-defined stopping test
888: Level: advanced
890: .seealso: [](ch:pep), `PEPGetStoppingTest()`, `PEPSetStoppingTestFunction()`, `PEPSetConvergenceTest()`, `PEPStop`
891: @*/
892: PetscErrorCode PEPSetStoppingTest(PEP pep,PEPStop stop)
893: {
894: PetscFunctionBegin;
897: switch (stop) {
898: case PEP_STOP_BASIC: pep->stopping = PEPStoppingBasic; break;
899: case PEP_STOP_USER:
900: PetscCheck(pep->stoppinguser,PetscObjectComm((PetscObject)pep),PETSC_ERR_ORDER,"Must call PEPSetStoppingTestFunction() first");
901: pep->stopping = pep->stoppinguser;
902: break;
903: default:
904: SETERRQ(PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
905: }
906: pep->stop = stop;
907: PetscFunctionReturn(PETSC_SUCCESS);
908: }
910: /*@
911: PEPGetStoppingTest - Gets the method used to decide the termination of the outer
912: loop of the eigensolver.
914: Not Collective
916: Input Parameter:
917: . pep - the polynomial eigensolver context
919: Output Parameter:
920: . stop - the type of stopping test
922: Level: advanced
924: .seealso: [](ch:pep), `PEPSetStoppingTest()`, `PEPStop`
925: @*/
926: PetscErrorCode PEPGetStoppingTest(PEP pep,PEPStop *stop)
927: {
928: PetscFunctionBegin;
930: PetscAssertPointer(stop,2);
931: *stop = pep->stop;
932: PetscFunctionReturn(PETSC_SUCCESS);
933: }
935: /*@
936: PEPSetScale - Specifies the scaling strategy to be used.
938: Collective
940: Input Parameters:
941: + pep - the polynomial eigensolver context
942: . scale - scaling strategy, see `PEPScale` for possible values
943: . alpha - the scaling factor used in the scalar strategy
944: . Dl - the left diagonal matrix of the diagonal scaling algorithm
945: . Dr - the right diagonal matrix of the diagonal scaling algorithm
946: . its - number of iterations of the diagonal scaling algorithm
947: - lambda - approximation to wanted eigenvalues (modulus)
949: Options Database Keys:
950: + -pep_scale (none|scalar|diagonal|both) - set the scaling type
951: . -pep_scale_factor alpha - set the scaling factor
952: . -pep_scale_its its - set the number of iterations
953: - -pep_scale_lambda lambda - set the approximation to eigenvalues
955: Notes:
956: There are two non-exclusive scaling strategies, scalar and diagonal.
957: See discussion in section [](#sec:scaling).
959: In the scalar strategy, scaling is applied to the eigenvalue, that is,
960: $\mu = \lambda/\alpha$ is the new eigenvalue and all matrices are scaled
961: accordingly. After solving the scaled problem, the original $\lambda$ is
962: recovered. Parameter `alpha` must be positive. Use `PETSC_DETERMINE` to let
963: the solver compute a reasonable scaling factor, and `PETSC_CURRENT` to
964: retain a previously set value.
966: In the diagonal strategy, the solver works implicitly with matrix $D_\ell P(\lambda)D_r$,
967: where $D_\ell$ and $D_r$ are appropriate diagonal matrices. This improves the accuracy
968: of the computed results in some cases. The user may provide the `Dl` and `Dr`
969: matrices represented as `Vec` objects storing diagonal elements. If not
970: provided, these matrices are computed internally. This option requires
971: that the polynomial coefficient matrices are of `MATAIJ` type.
972: The parameter `its` is the number of iterations performed by the method.
973: Parameter `lambda` must be positive. Use `PETSC_DETERMINE` or set `lambda` = 1.0
974: if no information about eigenvalues is available. `PETSC_CURRENT` can also
975: be used to leave `its` and `lambda` unchanged.
977: Level: intermediate
979: .seealso: [](ch:pep), [](#sec:scaling), `PEPGetScale()`
980: @*/
981: PetscErrorCode PEPSetScale(PEP pep,PEPScale scale,PetscReal alpha,Vec Dl,Vec Dr,PetscInt its,PetscReal lambda)
982: {
983: PetscFunctionBegin;
986: pep->scale = scale;
987: if (scale==PEP_SCALE_SCALAR || scale==PEP_SCALE_BOTH) {
989: if (alpha == (PetscReal)PETSC_DETERMINE) {
990: pep->sfactor = 0.0;
991: pep->sfactor_set = PETSC_FALSE;
992: } else if (alpha != (PetscReal)PETSC_CURRENT) {
993: PetscCheck(alpha>0.0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of alpha. Must be > 0");
994: pep->sfactor = alpha;
995: pep->sfactor_set = PETSC_TRUE;
996: }
997: }
998: if (scale==PEP_SCALE_DIAGONAL || scale==PEP_SCALE_BOTH) {
999: if (Dl) {
1001: PetscCheckSameComm(pep,1,Dl,4);
1002: PetscCall(PetscObjectReference((PetscObject)Dl));
1003: PetscCall(VecDestroy(&pep->Dl));
1004: pep->Dl = Dl;
1005: }
1006: if (Dr) {
1008: PetscCheckSameComm(pep,1,Dr,5);
1009: PetscCall(PetscObjectReference((PetscObject)Dr));
1010: PetscCall(VecDestroy(&pep->Dr));
1011: pep->Dr = Dr;
1012: }
1015: if (its==PETSC_DETERMINE) pep->sits = 5;
1016: else if (its!=PETSC_CURRENT) {
1017: PetscCheck(its>0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1018: pep->sits = its;
1019: }
1020: if (lambda == (PetscReal)PETSC_DETERMINE) pep->slambda = 1.0;
1021: else if (lambda != (PetscReal)PETSC_CURRENT) {
1022: PetscCheck(lambda>0.0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of lambda. Must be > 0");
1023: pep->slambda = lambda;
1024: }
1025: }
1026: pep->state = PEP_STATE_INITIAL;
1027: PetscFunctionReturn(PETSC_SUCCESS);
1028: }
1030: /*@
1031: PEPGetScale - Gets the scaling strategy used by the `PEP` object, and the
1032: associated parameters.
1034: Not Collective
1036: Input Parameter:
1037: . pep - the polynomial eigensolver context
1039: Output Parameters:
1040: + scale - scaling strategy
1041: . alpha - the scaling factor used in the scalar strategy
1042: . Dl - the left diagonal matrix of the diagonal scaling algorithm
1043: . Dr - the right diagonal matrix of the diagonal scaling algorithm
1044: . its - number of iterations of the diagonal scaling algorithm
1045: - lambda - approximation to wanted eigenvalues (modulus)
1047: Notes:
1048: The user can specify `NULL` for any parameter that is not needed.
1050: If `Dl` or `Dr` were not set by the user, then the ones computed internally are
1051: returned (or a `NULL` pointer if called before `PEPSetUp()`).
1053: Level: intermediate
1055: .seealso: [](ch:pep), `PEPSetScale()`, `PEPSetUp()`
1056: @*/
1057: PetscErrorCode PEPGetScale(PEP pep,PEPScale *scale,PetscReal *alpha,Vec *Dl,Vec *Dr,PetscInt *its,PetscReal *lambda)
1058: {
1059: PetscFunctionBegin;
1061: if (scale) *scale = pep->scale;
1062: if (alpha) *alpha = pep->sfactor;
1063: if (Dl) *Dl = pep->Dl;
1064: if (Dr) *Dr = pep->Dr;
1065: if (its) *its = pep->sits;
1066: if (lambda) *lambda = pep->slambda;
1067: PetscFunctionReturn(PETSC_SUCCESS);
1068: }
1070: /*@
1071: PEPSetExtract - Specifies the extraction strategy to be used.
1073: Logically Collective
1075: Input Parameters:
1076: + pep - the polynomial eigensolver context
1077: - extract - extraction strategy, see `PEPExtract` for possible values
1079: Options Database Key:
1080: . -pep_extract (none|norm|residual|structured) - set the extraction type
1082: Note:
1083: This is relevant for solvers based on linearization. Once the solver has
1084: converged, the polynomial eigenvectors can be extracted from the
1085: eigenvectors of the linearized problem in different ways. See the
1086: discussion in section [](#sec:pepextr).
1088: Level: intermediate
1090: .seealso: [](ch:pep), [](#sec:pepextr), `PEPExtract`, `PEPGetExtract()`
1091: @*/
1092: PetscErrorCode PEPSetExtract(PEP pep,PEPExtract extract)
1093: {
1094: PetscFunctionBegin;
1097: pep->extract = extract;
1098: PetscFunctionReturn(PETSC_SUCCESS);
1099: }
1101: /*@
1102: PEPGetExtract - Gets the extraction strategy used by the `PEP` object.
1104: Not Collective
1106: Input Parameter:
1107: . pep - the polynomial eigensolver context
1109: Output Parameter:
1110: . extract - extraction strategy
1112: Level: intermediate
1114: .seealso: [](ch:pep), `PEPSetExtract()`, `PEPExtract`
1115: @*/
1116: PetscErrorCode PEPGetExtract(PEP pep,PEPExtract *extract)
1117: {
1118: PetscFunctionBegin;
1120: PetscAssertPointer(extract,2);
1121: *extract = pep->extract;
1122: PetscFunctionReturn(PETSC_SUCCESS);
1123: }
1125: /*@
1126: PEPSetRefine - Specifies the refinement type (and options) to be used
1127: after the solve.
1129: Logically Collective
1131: Input Parameters:
1132: + pep - the polynomial eigensolver context
1133: . refine - refinement type, see `PEPRefine` for possible values
1134: . npart - number of partitions of the communicator
1135: . tol - the convergence tolerance
1136: . its - maximum number of refinement iterations
1137: - scheme - the scheme for solving the involved linear systems, see `PEPRefineScheme`
1138: for possible values
1140: Options Database Keys:
1141: + -pep_refine (none|simple|multiple) - set the refinement type
1142: . -pep_refine_partitions npart - set the number of partitions
1143: . -pep_refine_tol tol - set the tolerance
1144: . -pep_refine_its its - set the number of iterations
1145: - -pep_refine_scheme (schur|mbe|explicit) - set the scheme for the linear solves
1147: Notes:
1148: This function configures the parameters of Newton iterative refinement,
1149: see section [](#sec:refine) for a discussion of the different strategies.
1151: By default, iterative refinement is disabled, since it may be very
1152: costly. There are two possible refinement strategies, simple and multiple.
1153: The simple approach performs iterative refinement on each of the
1154: converged eigenpairs individually, whereas the multiple strategy works
1155: with the invariant pair as a whole, refining all eigenpairs simultaneously.
1156: The latter may be required for the case of multiple eigenvalues.
1158: In some cases, especially when using direct solvers within the
1159: iterative refinement method, it may be helpful for improved scalability
1160: to split the communicator in several partitions. The `npart` parameter
1161: indicates how many partitions to use (defaults to 1).
1163: The `tol` and `its` parameters specify the stopping criterion. In the simple
1164: method, refinement continues until the residual of each eigenpair is
1165: below the tolerance (`tol` defaults to the `PEP` tolerance, but may be set to a
1166: different value). In contrast, the multiple method simply performs its
1167: refinement iterations (just one by default).
1169: The `scheme` argument is used to change the way in which linear systems are
1170: solved. Possible choices are explicit, mixed block elimination (MBE),
1171: and Schur complement.
1173: Use `PETSC_CURRENT` to retain the current value of `npart`, `tol` or `its`. Use
1174: `PETSC_DETERMINE` to assign a default value.
1176: Level: intermediate
1178: .seealso: [](ch:pep), [](#sec:refine), `PEPGetRefine()`
1179: @*/
1180: PetscErrorCode PEPSetRefine(PEP pep,PEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its,PEPRefineScheme scheme)
1181: {
1182: PetscMPIInt size;
1184: PetscFunctionBegin;
1191: pep->refine = refine;
1192: if (refine) { /* process parameters only if not REFINE_NONE */
1193: if (npart!=pep->npart) {
1194: PetscCall(PetscSubcommDestroy(&pep->refinesubc));
1195: PetscCall(KSPDestroy(&pep->refineksp));
1196: }
1197: if (npart == PETSC_DETERMINE) {
1198: pep->npart = 1;
1199: } else if (npart != PETSC_CURRENT) {
1200: PetscCallMPI(MPI_Comm_size(PetscObjectComm((PetscObject)pep),&size));
1201: PetscCheck(npart>0 && npart<=size,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
1202: pep->npart = npart;
1203: }
1204: if (tol == (PetscReal)PETSC_DETERMINE) {
1205: pep->rtol = PETSC_DETERMINE;
1206: } else if (tol != (PetscReal)PETSC_CURRENT) {
1207: PetscCheck(tol>0.0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
1208: pep->rtol = tol;
1209: }
1210: if (its==PETSC_DETERMINE) {
1211: pep->rits = PETSC_DETERMINE;
1212: } else if (its != PETSC_CURRENT) {
1213: PetscCheck(its>=0,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
1214: pep->rits = its;
1215: }
1216: pep->scheme = scheme;
1217: }
1218: pep->state = PEP_STATE_INITIAL;
1219: PetscFunctionReturn(PETSC_SUCCESS);
1220: }
1222: /*@
1223: PEPGetRefine - Gets the refinement strategy used by the `PEP` object, and the
1224: associated parameters.
1226: Not Collective
1228: Input Parameter:
1229: . pep - the polynomial eigensolver context
1231: Output Parameters:
1232: + refine - refinement type
1233: . npart - number of partitions of the communicator
1234: . tol - the convergence tolerance
1235: . its - maximum number of refinement iterations
1236: - scheme - the scheme used for solving linear systems
1238: Note:
1239: The user can specify `NULL` for any parameter that is not needed.
1241: Level: intermediate
1243: .seealso: [](ch:pep), `PEPSetRefine()`
1244: @*/
1245: PetscErrorCode PEPGetRefine(PEP pep,PEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its,PEPRefineScheme *scheme)
1246: {
1247: PetscFunctionBegin;
1249: if (refine) *refine = pep->refine;
1250: if (npart) *npart = pep->npart;
1251: if (tol) *tol = pep->rtol;
1252: if (its) *its = pep->rits;
1253: if (scheme) *scheme = pep->scheme;
1254: PetscFunctionReturn(PETSC_SUCCESS);
1255: }
1257: /*@
1258: PEPSetOptionsPrefix - Sets the prefix used for searching for all
1259: `PEP` options in the database.
1261: Logically Collective
1263: Input Parameters:
1264: + pep - the polynomial eigensolver context
1265: - prefix - the prefix string to prepend to all `PEP` option requests
1267: Notes:
1268: A hyphen (-) must NOT be given at the beginning of the prefix name.
1269: The first character of all runtime options is AUTOMATICALLY the
1270: hyphen.
1272: For example, to distinguish between the runtime options for two
1273: different `PEP` contexts, one could call
1274: .vb
1275: PEPSetOptionsPrefix(pep1,"qeig1_")
1276: PEPSetOptionsPrefix(pep2,"qeig2_")
1277: .ve
1279: Level: advanced
1281: .seealso: [](ch:pep), `PEPAppendOptionsPrefix()`, `PEPGetOptionsPrefix()`
1282: @*/
1283: PetscErrorCode PEPSetOptionsPrefix(PEP pep,const char prefix[])
1284: {
1285: PetscFunctionBegin;
1287: if (!pep->st) PetscCall(PEPGetST(pep,&pep->st));
1288: PetscCall(STSetOptionsPrefix(pep->st,prefix));
1289: if (!pep->V) PetscCall(PEPGetBV(pep,&pep->V));
1290: PetscCall(BVSetOptionsPrefix(pep->V,prefix));
1291: if (!pep->ds) PetscCall(PEPGetDS(pep,&pep->ds));
1292: PetscCall(DSSetOptionsPrefix(pep->ds,prefix));
1293: if (!pep->rg) PetscCall(PEPGetRG(pep,&pep->rg));
1294: PetscCall(RGSetOptionsPrefix(pep->rg,prefix));
1295: PetscCall(PetscObjectSetOptionsPrefix((PetscObject)pep,prefix));
1296: PetscFunctionReturn(PETSC_SUCCESS);
1297: }
1299: /*@
1300: PEPAppendOptionsPrefix - Appends to the prefix used for searching for all
1301: `PEP` options in the database.
1303: Logically Collective
1305: Input Parameters:
1306: + pep - the polynomial eigensolver context
1307: - prefix - the prefix string to prepend to all `PEP` option requests
1309: Notes:
1310: A hyphen (-) must NOT be given at the beginning of the prefix name.
1311: The first character of all runtime options is AUTOMATICALLY the hyphen.
1313: Level: advanced
1315: .seealso: [](ch:pep), `PEPSetOptionsPrefix()`, `PEPGetOptionsPrefix()`
1316: @*/
1317: PetscErrorCode PEPAppendOptionsPrefix(PEP pep,const char prefix[])
1318: {
1319: PetscFunctionBegin;
1321: if (!pep->st) PetscCall(PEPGetST(pep,&pep->st));
1322: PetscCall(STAppendOptionsPrefix(pep->st,prefix));
1323: if (!pep->V) PetscCall(PEPGetBV(pep,&pep->V));
1324: PetscCall(BVAppendOptionsPrefix(pep->V,prefix));
1325: if (!pep->ds) PetscCall(PEPGetDS(pep,&pep->ds));
1326: PetscCall(DSAppendOptionsPrefix(pep->ds,prefix));
1327: if (!pep->rg) PetscCall(PEPGetRG(pep,&pep->rg));
1328: PetscCall(RGAppendOptionsPrefix(pep->rg,prefix));
1329: PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)pep,prefix));
1330: PetscFunctionReturn(PETSC_SUCCESS);
1331: }
1333: /*@
1334: PEPGetOptionsPrefix - Gets the prefix used for searching for all
1335: `PEP` options in the database.
1337: Not Collective
1339: Input Parameter:
1340: . pep - the polynomial eigensolver context
1342: Output Parameter:
1343: . prefix - pointer to the prefix string used is returned
1345: Level: advanced
1347: .seealso: [](ch:pep), `PEPSetOptionsPrefix()`, `PEPAppendOptionsPrefix()`
1348: @*/
1349: PetscErrorCode PEPGetOptionsPrefix(PEP pep,const char *prefix[])
1350: {
1351: PetscFunctionBegin;
1353: PetscAssertPointer(prefix,2);
1354: PetscCall(PetscObjectGetOptionsPrefix((PetscObject)pep,prefix));
1355: PetscFunctionReturn(PETSC_SUCCESS);
1356: }