1: /*
2: NEP routines related to options that can be set via the command-line
3: or procedurally.
5: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6: SLEPc - Scalable Library for Eigenvalue Problem Computations
7: Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain
9: This file is part of SLEPc.
11: SLEPc is free software: you can redistribute it and/or modify it under the
12: terms of version 3 of the GNU Lesser General Public License as published by
13: the Free Software Foundation.
15: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
16: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
18: more details.
20: You should have received a copy of the GNU Lesser General Public License
21: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
22: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
23: */
25: #include <slepc/private/nepimpl.h> /*I "slepcnep.h" I*/
29: /*@
30: NEPSetFromOptions - Sets NEP options from the options database.
31: This routine must be called before NEPSetUp() if the user is to be
32: allowed to set the solver type.
34: Collective on NEP 36: Input Parameters:
37: . nep - the nonlinear eigensolver context
39: Notes:
40: To see all options, run your program with the -help option.
42: Level: beginner
43: @*/
44: PetscErrorCode NEPSetFromOptions(NEP nep) 45: {
46: PetscErrorCode ierr;
47: char type[256],monfilename[PETSC_MAX_PATH_LEN];
48: PetscBool flg,flg1,flg2,flg3,flg4,flg5;
49: PetscReal r1,r2,r3;
50: PetscScalar s;
51: PetscInt i,j,k;
52: PetscViewer monviewer;
53: SlepcConvMonitor ctx;
57: NEPRegisterAll();
58: PetscObjectOptionsBegin((PetscObject)nep);
59: PetscOptionsFList("-nep_type","Nonlinear Eigenvalue Problem method","NEPSetType",NEPList,(char*)(((PetscObject)nep)->type_name?((PetscObject)nep)->type_name:NEPRII),type,256,&flg);
60: if (flg) {
61: NEPSetType(nep,type);
62: } else if (!((PetscObject)nep)->type_name) {
63: NEPSetType(nep,NEPRII);
64: }
66: PetscOptionsEnum("-nep_refine","Iterative refinement method","NEPSetRefine",NEPRefineTypes,(PetscEnum)nep->refine,(PetscEnum*)&nep->refine,NULL);
68: i = nep->npart;
69: PetscOptionsInt("-nep_refine_partitions","Number of partitions of the communicator for iterative refinement","NEPSetRefine",nep->npart,&i,&flg1);
70: r1 = nep->reftol;
71: PetscOptionsReal("-nep_refine_tol","Tolerance for iterative refinement","NEPSetRefine",nep->reftol,&r1,&flg2);
72: j = nep->rits;
73: PetscOptionsInt("-nep_refine_its","Maximum number of iterations for iterative refinement","NEPSetRefine",nep->rits,&j,&flg3);
74: if (flg1 || flg2 || flg3) {
75: NEPSetRefine(nep,nep->refine,i,r1,j);
76: }
78: i = nep->max_it? nep->max_it: PETSC_DEFAULT;
79: PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,&flg1);
80: j = nep->max_funcs? nep->max_funcs: PETSC_DEFAULT;
81: PetscOptionsInt("-nep_max_funcs","Maximum number of function evaluations","NEPSetTolerances",nep->max_funcs,&j,&flg2);
82: r1 = nep->abstol;
83: PetscOptionsReal("-nep_atol","Absolute tolerance for residual norm","NEPSetTolerances",nep->abstol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->abstol,&r1,&flg3);
84: r2 = nep->rtol;
85: PetscOptionsReal("-nep_rtol","Relative tolerance for residual norm","NEPSetTolerances",nep->rtol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->rtol,&r2,&flg4);
86: r3 = nep->stol;
87: PetscOptionsReal("-nep_stol","Relative tolerance for step length","NEPSetTolerances",nep->stol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->stol,&r3,&flg5);
88: if (flg1 || flg2 || flg3 || flg4 || flg5) {
89: NEPSetTolerances(nep,r1,r2,r3,i,j);
90: }
92: flg = PETSC_FALSE;
93: PetscOptionsBool("-nep_convergence_default","Default (relative error) convergence test","NEPSetConvergenceTest",flg,&flg,NULL);
94: if (flg) {
95: NEPSetConvergenceTest(nep,NEPConvergedDefault,NULL,NULL);
96: }
98: i = nep->nev;
99: PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,&flg1);
100: j = nep->ncv? nep->ncv: PETSC_DEFAULT;
101: PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,&flg2);
102: k = nep->mpd? nep->mpd: PETSC_DEFAULT;
103: PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,&flg3);
104: if (flg1 || flg2 || flg3) {
105: NEPSetDimensions(nep,i,j,k);
106: }
108: i = 0;
109: PetscOptionsInt("-nep_lag_preconditioner","Interval to rebuild preconditioner","NEPSetLagPreconditioner",nep->lag,&i,&flg);
110: if (flg) { NEPSetLagPreconditioner(nep,i); }
112: PetscOptionsBool("-nep_const_correction_tol","Constant correction tolerance for the linear solver","NEPSetConstCorrectionTol",nep->cctol,&nep->cctol,NULL);
114: PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg);
115: if (flg) {
116: NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE);
117: NEPSetTarget(nep,s);
118: }
120: /* -----------------------------------------------------------------------*/
121: /*
122: Cancels all monitors hardwired into code before call to NEPSetFromOptions()
123: */
124: flg = PETSC_FALSE;
125: PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",flg,&flg,NULL);
126: if (flg) {
127: NEPMonitorCancel(nep);
128: }
129: /*
130: Prints approximate eigenvalues and error estimates at each iteration
131: */
132: PetscOptionsString("-nep_monitor","Monitor first unconverged approximate eigenvalue and error estimate","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
133: if (flg) {
134: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
135: NEPMonitorSet(nep,NEPMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
136: }
137: PetscOptionsString("-nep_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
138: if (flg) {
139: PetscNew(&ctx);
140: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&ctx->viewer);
141: NEPMonitorSet(nep,NEPMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
142: }
143: PetscOptionsString("-nep_monitor_all","Monitor approximate eigenvalues and error estimates","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
144: if (flg) {
145: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
146: NEPMonitorSet(nep,NEPMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
147: NEPSetTrackAll(nep,PETSC_TRUE);
148: }
149: flg = PETSC_FALSE;
150: PetscOptionsBool("-nep_monitor_lg","Monitor first unconverged approximate error estimate graphically","NEPMonitorSet",flg,&flg,NULL);
151: if (flg) {
152: NEPMonitorSet(nep,NEPMonitorLG,NULL,NULL);
153: }
154: flg = PETSC_FALSE;
155: PetscOptionsBool("-nep_monitor_lg_all","Monitor error estimates graphically","NEPMonitorSet",flg,&flg,NULL);
156: if (flg) {
157: NEPMonitorSet(nep,NEPMonitorLGAll,NULL,NULL);
158: NEPSetTrackAll(nep,PETSC_TRUE);
159: }
160: /* -----------------------------------------------------------------------*/
162: PetscOptionsBoolGroupBegin("-nep_largest_magnitude","compute largest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
163: if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_MAGNITUDE); }
164: PetscOptionsBoolGroup("-nep_smallest_magnitude","compute smallest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
165: if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_MAGNITUDE); }
166: PetscOptionsBoolGroup("-nep_largest_real","compute largest real parts","NEPSetWhichEigenpairs",&flg);
167: if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_REAL); }
168: PetscOptionsBoolGroup("-nep_smallest_real","compute smallest real parts","NEPSetWhichEigenpairs",&flg);
169: if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_REAL); }
170: PetscOptionsBoolGroup("-nep_largest_imaginary","compute largest imaginary parts","NEPSetWhichEigenpairs",&flg);
171: if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_IMAGINARY); }
172: PetscOptionsBoolGroup("-nep_smallest_imaginary","compute smallest imaginary parts","NEPSetWhichEigenpairs",&flg);
173: if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_IMAGINARY); }
174: PetscOptionsBoolGroup("-nep_target_magnitude","compute nearest eigenvalues to target","NEPSetWhichEigenpairs",&flg);
175: if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE); }
176: PetscOptionsBoolGroup("-nep_target_real","compute eigenvalues with real parts close to target","NEPSetWhichEigenpairs",&flg);
177: if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_REAL); }
178: PetscOptionsBoolGroupEnd("-nep_target_imaginary","compute eigenvalues with imaginary parts close to target","NEPSetWhichEigenpairs",&flg);
179: if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_IMAGINARY); }
181: PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",0);
182: PetscOptionsName("-nep_view_vectors","View computed eigenvectors","NEPVectorsView",0);
183: PetscOptionsName("-nep_view_values","View computed eigenvalues","NEPValuesView",0);
184: PetscOptionsName("-nep_converged_reason","Print reason for convergence, and number of iterations","NEPReasonView",0);
185: PetscOptionsName("-nep_error_absolute","Print absolute errors of each eigenpair","NEPErrorView",0);
186: PetscOptionsName("-nep_error_relative","Print relative errors of each eigenpair","NEPErrorView",0);
188: if (nep->ops->setfromoptions) {
189: (*nep->ops->setfromoptions)(PetscOptionsObject,nep);
190: }
191: PetscObjectProcessOptionsHandlers((PetscObject)nep);
192: PetscOptionsEnd();
194: if (!nep->V) { NEPGetBV(nep,&nep->V); }
195: BVSetFromOptions(nep->V);
196: if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
197: RGSetFromOptions(nep->rg);
198: if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
199: DSSetFromOptions(nep->ds);
200: if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
201: KSPSetOperators(nep->ksp,nep->function,nep->function_pre);
202: KSPSetFromOptions(nep->ksp);
203: PetscRandomSetFromOptions(nep->rand);
204: return(0);
205: }
209: /*@
210: NEPGetTolerances - Gets the tolerance and maximum iteration count used
211: by the NEP convergence tests.
213: Not Collective
215: Input Parameter:
216: . nep - the nonlinear eigensolver context
218: Output Parameters:
219: + abstol - absolute convergence tolerance
220: . rtol - relative convergence tolerance
221: . stol - convergence tolerance in terms of the norm of the change in the
222: solution between steps, || delta x || < stol*|| x ||
223: . maxit - maximum number of iterations
224: - maxf - maximum number of function evaluations
226: Notes:
227: The user can specify NULL for any parameter that is not needed.
229: Level: intermediate
231: .seealso: NEPSetTolerances()
232: @*/
233: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *abstol,PetscReal *rtol,PetscReal *stol,PetscInt *maxit,PetscInt *maxf)234: {
237: if (abstol) *abstol = nep->abstol;
238: if (rtol) *rtol = nep->rtol;
239: if (stol) *stol = nep->stol;
240: if (maxit) *maxit = nep->max_it;
241: if (maxf) *maxf = nep->max_funcs;
242: return(0);
243: }
247: /*@
248: NEPSetTolerances - Sets various parameters used in convergence tests.
250: Logically Collective on NEP252: Input Parameters:
253: + nep - the nonlinear eigensolver context
254: . abstol - absolute convergence tolerance
255: . rtol - relative convergence tolerance
256: . stol - convergence tolerance in terms of the norm of the change in the
257: solution between steps, || delta x || < stol*|| x ||
258: . maxit - maximum number of iterations
259: - maxf - maximum number of function evaluations
261: Options Database Keys:
262: + -nep_atol <abstol> - Sets abstol
263: . -nep_rtol <rtol> - Sets rtol
264: . -nep_stol <stol> - Sets stol
265: . -nep_max_it <maxit> - Sets maxit
266: - -nep_max_funcs <maxf> - Sets maxf
268: Notes:
269: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
271: Level: intermediate
273: .seealso: NEPGetTolerances()
274: @*/
275: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal abstol,PetscReal rtol,PetscReal stol,PetscInt maxit,PetscInt maxf)276: {
284: if (abstol == PETSC_DEFAULT) {
285: nep->abstol = PETSC_DEFAULT;
286: } else {
287: if (abstol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Absolute tolerance %g must be non-negative",(double)abstol);
288: nep->abstol = abstol;
289: }
290: if (rtol == PETSC_DEFAULT) {
291: nep->rtol = PETSC_DEFAULT;
292: } else {
293: if (rtol < 0.0 || 1.0 <= rtol) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Relative tolerance %g must be non-negative and less than 1.0",(double)rtol);
294: nep->rtol = rtol;
295: }
296: if (stol == PETSC_DEFAULT) {
297: nep->stol = PETSC_DEFAULT;
298: } else {
299: if (stol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Step tolerance %g must be non-negative",(double)stol);
300: nep->stol = stol;
301: }
302: if (maxit == PETSC_DEFAULT || maxit == PETSC_DECIDE) {
303: nep->max_it = 0;
304: nep->state = NEP_STATE_INITIAL;
305: } else {
306: if (maxit < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of iterations %D must be non-negative",maxit);
307: nep->max_it = maxit;
308: }
309: if (maxf == PETSC_DEFAULT || maxf == PETSC_DECIDE) {
310: nep->max_it = 0;
311: nep->state = NEP_STATE_INITIAL;
312: } else {
313: if (maxf < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of function evaluations %D must be non-negative",maxf);
314: nep->max_funcs = maxf;
315: }
316: return(0);
317: }
321: /*@
322: NEPGetDimensions - Gets the number of eigenvalues to compute
323: and the dimension of the subspace.
325: Not Collective
327: Input Parameter:
328: . nep - the nonlinear eigensolver context
330: Output Parameters:
331: + nev - number of eigenvalues to compute
332: . ncv - the maximum dimension of the subspace to be used by the solver
333: - mpd - the maximum dimension allowed for the projected problem
335: Notes:
336: The user can specify NULL for any parameter that is not needed.
338: Level: intermediate
340: .seealso: NEPSetDimensions()
341: @*/
342: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)343: {
346: if (nev) *nev = nep->nev;
347: if (ncv) *ncv = nep->ncv;
348: if (mpd) *mpd = nep->mpd;
349: return(0);
350: }
354: /*@
355: NEPSetDimensions - Sets the number of eigenvalues to compute
356: and the dimension of the subspace.
358: Logically Collective on NEP360: Input Parameters:
361: + nep - the nonlinear eigensolver context
362: . nev - number of eigenvalues to compute
363: . ncv - the maximum dimension of the subspace to be used by the solver
364: - mpd - the maximum dimension allowed for the projected problem
366: Options Database Keys:
367: + -nep_nev <nev> - Sets the number of eigenvalues
368: . -nep_ncv <ncv> - Sets the dimension of the subspace
369: - -nep_mpd <mpd> - Sets the maximum projected dimension
371: Notes:
372: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
373: dependent on the solution method.
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 that
377: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
378: (b) in cases where nev is large, the user sets mpd.
380: The value of ncv should always be between nev and (nev+mpd), typically
381: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
382: a smaller value should be used.
384: Level: intermediate
386: .seealso: NEPGetDimensions()
387: @*/
388: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)389: {
395: if (nev<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
396: nep->nev = nev;
397: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
398: nep->ncv = 0;
399: } else {
400: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
401: nep->ncv = ncv;
402: }
403: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
404: nep->mpd = 0;
405: } else {
406: if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
407: nep->mpd = mpd;
408: }
409: nep->state = NEP_STATE_INITIAL;
410: return(0);
411: }
415: /*@
416: NEPSetWhichEigenpairs - Specifies which portion of the spectrum is
417: to be sought.
419: Logically Collective on NEP421: Input Parameters:
422: + nep - eigensolver context obtained from NEPCreate()
423: - which - the portion of the spectrum to be sought
425: Possible values:
426: The parameter 'which' can have one of these values
428: + NEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
429: . NEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
430: . NEP_LARGEST_REAL - largest real parts
431: . NEP_SMALLEST_REAL - smallest real parts
432: . NEP_LARGEST_IMAGINARY - largest imaginary parts
433: . NEP_SMALLEST_IMAGINARY - smallest imaginary parts
434: . NEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
435: . NEP_TARGET_REAL - eigenvalues with real part closest to target
436: - NEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
438: Options Database Keys:
439: + -nep_largest_magnitude - Sets largest eigenvalues in magnitude
440: . -nep_smallest_magnitude - Sets smallest eigenvalues in magnitude
441: . -nep_largest_real - Sets largest real parts
442: . -nep_smallest_real - Sets smallest real parts
443: . -nep_largest_imaginary - Sets largest imaginary parts
444: . -nep_smallest_imaginary - Sets smallest imaginary parts
445: . -nep_target_magnitude - Sets eigenvalues closest to target
446: . -nep_target_real - Sets real parts closest to target
447: - -nep_target_imaginary - Sets imaginary parts closest to target
449: Notes:
450: Not all eigensolvers implemented in NEP account for all the possible values
451: stated above. If SLEPc is compiled for real numbers NEP_LARGEST_IMAGINARY
452: and NEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
453: for eigenvalue selection.
455: Level: intermediate
457: .seealso: NEPGetWhichEigenpairs(), NEPWhich458: @*/
459: PetscErrorCode NEPSetWhichEigenpairs(NEP nep,NEPWhich which)460: {
464: switch (which) {
465: case NEP_LARGEST_MAGNITUDE:
466: case NEP_SMALLEST_MAGNITUDE:
467: case NEP_LARGEST_REAL:
468: case NEP_SMALLEST_REAL:
469: case NEP_LARGEST_IMAGINARY:
470: case NEP_SMALLEST_IMAGINARY:
471: case NEP_TARGET_MAGNITUDE:
472: case NEP_TARGET_REAL:
473: #if defined(PETSC_USE_COMPLEX)
474: case NEP_TARGET_IMAGINARY:
475: #endif
476: if (nep->which != which) {
477: nep->state = NEP_STATE_INITIAL;
478: nep->which = which;
479: }
480: break;
481: default:482: SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
483: }
484: return(0);
485: }
489: /*@
490: NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
491: sought.
493: Not Collective
495: Input Parameter:
496: . nep - eigensolver context obtained from NEPCreate()
498: Output Parameter:
499: . which - the portion of the spectrum to be sought
501: Notes:
502: See NEPSetWhichEigenpairs() for possible values of 'which'.
504: Level: intermediate
506: .seealso: NEPSetWhichEigenpairs(), NEPWhich507: @*/
508: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)509: {
513: *which = nep->which;
514: return(0);
515: }
519: /*@
520: NEPSetLagPreconditioner - Determines when the preconditioner is rebuilt in the
521: nonlinear solve.
523: Logically Collective on NEP525: Input Parameters:
526: + nep - the NEP context
527: - lag - 0 indicates NEVER rebuild, 1 means rebuild every time the Jacobian is
528: computed within the nonlinear iteration, 2 means every second time
529: the Jacobian is built, etc.
531: Options Database Keys:
532: . -nep_lag_preconditioner <lag>
534: Notes:
535: The default is 1.
536: The preconditioner is ALWAYS built in the first iteration of a nonlinear solve.
538: Level: intermediate
540: .seealso: NEPGetLagPreconditioner()
541: @*/
542: PetscErrorCode NEPSetLagPreconditioner(NEP nep,PetscInt lag)543: {
547: if (lag<0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Lag must be non-negative");
548: nep->lag = lag;
549: return(0);
550: }
554: /*@
555: NEPGetLagPreconditioner - Indicates how often the preconditioner is rebuilt.
557: Not Collective
559: Input Parameter:
560: . nep - the NEP context
562: Output Parameter:
563: . lag - the lag parameter
565: Level: intermediate
567: .seealso: NEPSetLagPreconditioner()
568: @*/
569: PetscErrorCode NEPGetLagPreconditioner(NEP nep,PetscInt *lag)570: {
574: *lag = nep->lag;
575: return(0);
576: }
580: /*@
581: NEPSetConstCorrectionTol - Sets a flag to keep the tolerance used
582: in the linear solver constant.
584: Logically Collective on NEP586: Input Parameters:
587: + nep - the NEP context
588: - cct - a boolean value
590: Options Database Keys:
591: . -nep_const_correction_tol <cct>
593: Notes:
594: By default, an exponentially decreasing tolerance is set in the KSP used
595: within the nonlinear iteration, so that each Newton iteration requests
596: better accuracy than the previous one. The constant correction tolerance
597: flag stops this behaviour.
599: Level: intermediate
601: .seealso: NEPGetConstCorrectionTol()
602: @*/
603: PetscErrorCode NEPSetConstCorrectionTol(NEP nep,PetscBool cct)604: {
608: nep->cctol = cct;
609: return(0);
610: }
614: /*@
615: NEPGetConstCorrectionTol - Returns the constant tolerance flag.
617: Not Collective
619: Input Parameter:
620: . nep - the NEP context
622: Output Parameter:
623: . cct - the value of the constant tolerance flag
625: Level: intermediate
627: .seealso: NEPSetConstCorrectionTol()
628: @*/
629: PetscErrorCode NEPGetConstCorrectionTol(NEP nep,PetscBool *cct)630: {
634: *cct = nep->cctol;
635: return(0);
636: }
640: /*@C
641: NEPSetConvergenceTest - Sets the function to be used to test convergence
642: of the nonlinear iterative solution.
644: Logically Collective on NEP646: Input Parameters:
647: + nep - the NEP context
648: . func - a pointer to the convergence test function
649: . ctx - [optional] context for private data for the convergence routine
650: (may be NULL)
651: - destroy - [optional] destructor for the context (may be NULL;
652: PETSC_NULL_FUNCTION in Fortran)
654: Calling Sequence of func:
655: $ func(NEP nep,PetscInt it,PetscReal xnorm,PetscReal snorm,PetscReal fnorm,NEPConvergedReason reason*,void *fctx)
657: + nep - the NEP context
658: . it - iteration number
659: . xnorm - norm of the current solution
660: . snorm - norm of the step (difference between two consecutive solutions)
661: . fnorm - norm of the function (residual)
662: . reason - (output) result of the convergence test
663: - fctx - optional context, as set by NEPSetConvergenceTest()
665: Level: advanced
667: .seealso: NEPSetTolerances()
668: @*/
669: PetscErrorCode NEPSetConvergenceTest(NEP nep,PetscErrorCode (*func)(NEP,PetscInt,PetscReal,PetscReal,PetscReal,NEPConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))670: {
675: if (nep->convergeddestroy) {
676: (*nep->convergeddestroy)(nep->convergedctx);
677: }
678: nep->converged = func;
679: nep->convergeddestroy = destroy;
680: nep->convergedctx = ctx;
681: return(0);
682: }
686: /*@
687: NEPSetTrackAll - Specifies if the solver must compute the residual of all
688: approximate eigenpairs or not.
690: Logically Collective on NEP692: Input Parameters:
693: + nep - the eigensolver context
694: - trackall - whether compute all residuals or not
696: Notes:
697: If the user sets trackall=PETSC_TRUE then the solver explicitly computes
698: the residual for each eigenpair approximation. Computing the residual is
699: usually an expensive operation and solvers commonly compute the associated
700: residual to the first unconverged eigenpair.
701: The options '-nep_monitor_all' and '-nep_monitor_lg_all' automatically
702: activate this option.
704: Level: developer
706: .seealso: NEPGetTrackAll()
707: @*/
708: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)709: {
713: nep->trackall = trackall;
714: return(0);
715: }
719: /*@
720: NEPGetTrackAll - Returns the flag indicating whether all residual norms must
721: be computed or not.
723: Not Collective
725: Input Parameter:
726: . nep - the eigensolver context
728: Output Parameter:
729: . trackall - the returned flag
731: Level: developer
733: .seealso: NEPSetTrackAll()
734: @*/
735: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)736: {
740: *trackall = nep->trackall;
741: return(0);
742: }
746: /*@
747: NEPSetRefine - Specifies the refinement type (and options) to be used
748: after the solve.
750: Logically Collective on NEP752: Input Parameters:
753: + nep - the nonlinear eigensolver context
754: . refine - refinement type
755: . npart - number of partitions of the communicator
756: . tol - the convergence tolerance
757: - its - maximum number of refinement iterations
759: Options Database Keys:
760: + -nep_refine <type> - refinement type, one of <none,simple,multiple>
761: . -nep_refine_partitions <n> - the number of partitions
762: . -nep_refine_tol <tol> - the tolerance
763: - -nep_refine_its <its> - number of iterations
765: Notes:
766: By default, iterative refinement is disabled, since it may be very
767: costly. There are two possible refinement strategies: simple and multiple.
768: The simple approach performs iterative refinement on each of the
769: converged eigenpairs individually, whereas the multiple strategy works
770: with the invariant pair as a whole, refining all eigenpairs simultaneously.
771: The latter may be required for the case of multiple eigenvalues.
773: In some cases, especially when using direct solvers within the
774: iterative refinement method, it may be helpful for improved scalability
775: to split the communicator in several partitions. The npart parameter
776: indicates how many partitions to use (defaults to 1).
778: The tol and its parameters specify the stopping criterion. In the simple
779: method, refinement continues until the residual of each eigenpair is
780: below the tolerance (tol defaults to the NEP tol, but may be set to a
781: different value). In contrast, the multiple method simply performs its
782: refinement iterations (just one by default).
784: Level: intermediate
786: .seealso: NEPGetRefine()
787: @*/
788: PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its)789: {
791: PetscMPIInt size;
799: nep->refine = refine;
800: if (refine) { /* process parameters only if not REFINE_NONE */
801: if (npart == PETSC_DEFAULT || npart == PETSC_DECIDE) {
802: nep->npart = 1;
803: } else {
804: MPI_Comm_size(PetscObjectComm((PetscObject)nep),&size);
805: if (npart<1 || npart>size) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
806: nep->npart = npart;
807: }
808: if (tol == PETSC_DEFAULT || tol == PETSC_DECIDE) {
809: nep->reftol = nep->rtol;
810: } else {
811: if (tol<=0.0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
812: nep->reftol = tol;
813: }
814: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
815: nep->rits = PETSC_DEFAULT;
816: } else {
817: if (its<0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
818: nep->rits = its;
819: }
820: }
821: nep->state = NEP_STATE_INITIAL;
822: return(0);
823: }
827: /*@
828: NEPGetRefine - Gets the refinement strategy used by the NEP object, and the
829: associated parameters.
831: Not Collective
833: Input Parameter:
834: . nep - the nonlinear eigensolver context
836: Output Parameters:
837: + refine - refinement type
838: . npart - number of partitions of the communicator
839: . tol - the convergence tolerance
840: - its - maximum number of refinement iterations
842: Level: intermediate
844: Note:
845: The user can specify NULL for any parameter that is not needed.
847: .seealso: NEPSetRefine()
848: @*/
849: PetscErrorCode NEPGetRefine(NEP nep,NEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its)850: {
853: if (refine) *refine = nep->refine;
854: if (npart) *npart = nep->npart;
855: if (tol) *tol = nep->reftol;
856: if (its) *its = nep->rits;
857: return(0);
858: }
862: /*@C
863: NEPSetOptionsPrefix - Sets the prefix used for searching for all
864: NEP options in the database.
866: Logically Collective on NEP868: Input Parameters:
869: + nep - the nonlinear eigensolver context
870: - prefix - the prefix string to prepend to all NEP option requests
872: Notes:
873: A hyphen (-) must NOT be given at the beginning of the prefix name.
874: The first character of all runtime options is AUTOMATICALLY the
875: hyphen.
877: For example, to distinguish between the runtime options for two
878: different NEP contexts, one could call
879: .vb
880: NEPSetOptionsPrefix(nep1,"neig1_")
881: NEPSetOptionsPrefix(nep2,"neig2_")
882: .ve
884: Level: advanced
886: .seealso: NEPAppendOptionsPrefix(), NEPGetOptionsPrefix()
887: @*/
888: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char *prefix)889: {
894: if (!nep->V) { NEPGetBV(nep,&nep->V); }
895: BVSetOptionsPrefix(nep->V,prefix);
896: if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
897: DSSetOptionsPrefix(nep->ds,prefix);
898: if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
899: RGSetOptionsPrefix(nep->rg,prefix);
900: if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
901: KSPSetOptionsPrefix(nep->ksp,prefix);
902: KSPAppendOptionsPrefix(nep->ksp,"nep_");
903: PetscObjectSetOptionsPrefix((PetscObject)nep,prefix);
904: return(0);
905: }
909: /*@C
910: NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
911: NEP options in the database.
913: Logically Collective on NEP915: Input Parameters:
916: + nep - the nonlinear eigensolver context
917: - prefix - the prefix string to prepend to all NEP option requests
919: Notes:
920: A hyphen (-) must NOT be given at the beginning of the prefix name.
921: The first character of all runtime options is AUTOMATICALLY the hyphen.
923: Level: advanced
925: .seealso: NEPSetOptionsPrefix(), NEPGetOptionsPrefix()
926: @*/
927: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char *prefix)928: {
933: if (!nep->V) { NEPGetBV(nep,&nep->V); }
934: BVSetOptionsPrefix(nep->V,prefix);
935: if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
936: DSSetOptionsPrefix(nep->ds,prefix);
937: if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
938: RGSetOptionsPrefix(nep->rg,prefix);
939: if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
940: KSPSetOptionsPrefix(nep->ksp,prefix);
941: KSPAppendOptionsPrefix(nep->ksp,"nep_");
942: PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix);
943: return(0);
944: }
948: /*@C
949: NEPGetOptionsPrefix - Gets the prefix used for searching for all
950: NEP options in the database.
952: Not Collective
954: Input Parameters:
955: . nep - the nonlinear eigensolver context
957: Output Parameters:
958: . prefix - pointer to the prefix string used is returned
960: Notes: On the fortran side, the user should pass in a string 'prefix' of
961: sufficient length to hold the prefix.
963: Level: advanced
965: .seealso: NEPSetOptionsPrefix(), NEPAppendOptionsPrefix()
966: @*/
967: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])968: {
974: PetscObjectGetOptionsPrefix((PetscObject)nep,prefix);
975: return(0);
976: }