Actual source code: nepopts.c
slepc-3.21.0 2024-03-30
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: NEP routines related to options that can be set via the command-line
12: or procedurally
13: */
15: #include <slepc/private/nepimpl.h>
16: #include <petscdraw.h>
18: /*@C
19: NEPMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective
24: Input Parameters:
25: + nep - the nonlinear 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: NEPMonitorSet(), NEPSetTrackAll()
34: @*/
35: PetscErrorCode NEPMonitorSetFromOptions(NEP nep,const char opt[],const char name[],void *ctx,PetscBool trackall)
36: {
37: PetscErrorCode (*mfunc)(NEP,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(PetscOptionsGetViewer(PetscObjectComm((PetscObject)nep),((PetscObject)nep)->options,((PetscObject)nep)->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(NEPMonitorList,key,&mfunc));
54: PetscCheck(mfunc,PetscObjectComm((PetscObject)nep),PETSC_ERR_SUP,"Specified viewer and format not supported");
55: PetscCall(PetscFunctionListFind(NEPMonitorCreateList,key,&cfunc));
56: PetscCall(PetscFunctionListFind(NEPMonitorDestroyList,key,&dfunc));
57: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
58: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
60: PetscCall((*cfunc)(viewer,format,ctx,&vf));
61: PetscCall(PetscOptionsRestoreViewer(&viewer));
62: PetscCall(NEPMonitorSet(nep,mfunc,vf,(PetscErrorCode(*)(void **))dfunc));
63: if (trackall) PetscCall(NEPSetTrackAll(nep,PETSC_TRUE));
64: PetscFunctionReturn(PETSC_SUCCESS);
65: }
67: /*@
68: NEPSetFromOptions - Sets NEP options from the options database.
69: This routine must be called before NEPSetUp() if the user is to be
70: allowed to set the solver type.
72: Collective
74: Input Parameters:
75: . nep - the nonlinear eigensolver context
77: Notes:
78: To see all options, run your program with the -help option.
80: Level: beginner
82: .seealso: NEPSetOptionsPrefix()
83: @*/
84: PetscErrorCode NEPSetFromOptions(NEP nep)
85: {
86: char type[256];
87: PetscBool set,flg,flg1,flg2,flg3,flg4,flg5,bval;
88: PetscReal r;
89: PetscScalar s;
90: PetscInt i,j,k;
91: NEPRefine refine;
92: NEPRefineScheme scheme;
94: PetscFunctionBegin;
96: PetscCall(NEPRegisterAll());
97: PetscObjectOptionsBegin((PetscObject)nep);
98: PetscCall(PetscOptionsFList("-nep_type","Nonlinear eigensolver method","NEPSetType",NEPList,(char*)(((PetscObject)nep)->type_name?((PetscObject)nep)->type_name:NEPRII),type,sizeof(type),&flg));
99: if (flg) PetscCall(NEPSetType(nep,type));
100: else if (!((PetscObject)nep)->type_name) PetscCall(NEPSetType(nep,NEPRII));
102: PetscCall(PetscOptionsBoolGroupBegin("-nep_general","General nonlinear eigenvalue problem","NEPSetProblemType",&flg));
103: if (flg) PetscCall(NEPSetProblemType(nep,NEP_GENERAL));
104: PetscCall(PetscOptionsBoolGroupEnd("-nep_rational","Rational eigenvalue problem","NEPSetProblemType",&flg));
105: if (flg) PetscCall(NEPSetProblemType(nep,NEP_RATIONAL));
107: refine = nep->refine;
108: PetscCall(PetscOptionsEnum("-nep_refine","Iterative refinement method","NEPSetRefine",NEPRefineTypes,(PetscEnum)refine,(PetscEnum*)&refine,&flg1));
109: i = nep->npart;
110: PetscCall(PetscOptionsInt("-nep_refine_partitions","Number of partitions of the communicator for iterative refinement","NEPSetRefine",nep->npart,&i,&flg2));
111: r = nep->rtol;
112: PetscCall(PetscOptionsReal("-nep_refine_tol","Tolerance for iterative refinement","NEPSetRefine",nep->rtol==(PetscReal)PETSC_DEFAULT?SLEPC_DEFAULT_TOL/1000:nep->rtol,&r,&flg3));
113: j = nep->rits;
114: PetscCall(PetscOptionsInt("-nep_refine_its","Maximum number of iterations for iterative refinement","NEPSetRefine",nep->rits,&j,&flg4));
115: scheme = nep->scheme;
116: PetscCall(PetscOptionsEnum("-nep_refine_scheme","Scheme used for linear systems within iterative refinement","NEPSetRefine",NEPRefineSchemes,(PetscEnum)scheme,(PetscEnum*)&scheme,&flg5));
117: if (flg1 || flg2 || flg3 || flg4 || flg5) PetscCall(NEPSetRefine(nep,refine,i,r,j,scheme));
119: i = nep->max_it;
120: PetscCall(PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,&flg1));
121: r = nep->tol;
122: PetscCall(PetscOptionsReal("-nep_tol","Tolerance","NEPSetTolerances",SlepcDefaultTol(nep->tol),&r,&flg2));
123: if (flg1 || flg2) PetscCall(NEPSetTolerances(nep,r,i));
125: PetscCall(PetscOptionsBoolGroupBegin("-nep_conv_rel","Relative error convergence test","NEPSetConvergenceTest",&flg));
126: if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_REL));
127: PetscCall(PetscOptionsBoolGroup("-nep_conv_norm","Convergence test relative to the matrix norms","NEPSetConvergenceTest",&flg));
128: if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_NORM));
129: PetscCall(PetscOptionsBoolGroup("-nep_conv_abs","Absolute error convergence test","NEPSetConvergenceTest",&flg));
130: if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_ABS));
131: PetscCall(PetscOptionsBoolGroupEnd("-nep_conv_user","User-defined convergence test","NEPSetConvergenceTest",&flg));
132: if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_USER));
134: PetscCall(PetscOptionsBoolGroupBegin("-nep_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","NEPSetStoppingTest",&flg));
135: if (flg) PetscCall(NEPSetStoppingTest(nep,NEP_STOP_BASIC));
136: PetscCall(PetscOptionsBoolGroupEnd("-nep_stop_user","User-defined stopping test","NEPSetStoppingTest",&flg));
137: if (flg) PetscCall(NEPSetStoppingTest(nep,NEP_STOP_USER));
139: i = nep->nev;
140: PetscCall(PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,&flg1));
141: j = nep->ncv;
142: PetscCall(PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,&flg2));
143: k = nep->mpd;
144: PetscCall(PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,&flg3));
145: if (flg1 || flg2 || flg3) PetscCall(NEPSetDimensions(nep,i,j,k));
147: PetscCall(PetscOptionsBoolGroupBegin("-nep_largest_magnitude","Compute largest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg));
148: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_LARGEST_MAGNITUDE));
149: PetscCall(PetscOptionsBoolGroup("-nep_smallest_magnitude","Compute smallest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg));
150: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_SMALLEST_MAGNITUDE));
151: PetscCall(PetscOptionsBoolGroup("-nep_largest_real","Compute eigenvalues with largest real parts","NEPSetWhichEigenpairs",&flg));
152: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_LARGEST_REAL));
153: PetscCall(PetscOptionsBoolGroup("-nep_smallest_real","Compute eigenvalues with smallest real parts","NEPSetWhichEigenpairs",&flg));
154: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_SMALLEST_REAL));
155: PetscCall(PetscOptionsBoolGroup("-nep_largest_imaginary","Compute eigenvalues with largest imaginary parts","NEPSetWhichEigenpairs",&flg));
156: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_LARGEST_IMAGINARY));
157: PetscCall(PetscOptionsBoolGroup("-nep_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","NEPSetWhichEigenpairs",&flg));
158: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_SMALLEST_IMAGINARY));
159: PetscCall(PetscOptionsBoolGroup("-nep_target_magnitude","Compute eigenvalues closest to target","NEPSetWhichEigenpairs",&flg));
160: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE));
161: PetscCall(PetscOptionsBoolGroup("-nep_target_real","Compute eigenvalues with real parts closest to target","NEPSetWhichEigenpairs",&flg));
162: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_REAL));
163: PetscCall(PetscOptionsBoolGroup("-nep_target_imaginary","Compute eigenvalues with imaginary parts closest to target","NEPSetWhichEigenpairs",&flg));
164: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_IMAGINARY));
165: PetscCall(PetscOptionsBoolGroupEnd("-nep_all","Compute all eigenvalues in a region","NEPSetWhichEigenpairs",&flg));
166: if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_ALL));
168: PetscCall(PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg));
169: if (flg) {
170: if (nep->which!=NEP_TARGET_REAL && nep->which!=NEP_TARGET_IMAGINARY) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE));
171: PetscCall(NEPSetTarget(nep,s));
172: }
174: PetscCall(PetscOptionsBool("-nep_two_sided","Use two-sided variant (to compute left eigenvectors)","NEPSetTwoSided",nep->twosided,&bval,&flg));
175: if (flg) PetscCall(NEPSetTwoSided(nep,bval));
177: /* -----------------------------------------------------------------------*/
178: /*
179: Cancels all monitors hardwired into code before call to NEPSetFromOptions()
180: */
181: PetscCall(PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",PETSC_FALSE,&flg,&set));
182: if (set && flg) PetscCall(NEPMonitorCancel(nep));
183: PetscCall(NEPMonitorSetFromOptions(nep,"-nep_monitor","first_approximation",NULL,PETSC_FALSE));
184: PetscCall(NEPMonitorSetFromOptions(nep,"-nep_monitor_all","all_approximations",NULL,PETSC_TRUE));
185: PetscCall(NEPMonitorSetFromOptions(nep,"-nep_monitor_conv","convergence_history",NULL,PETSC_FALSE));
187: /* -----------------------------------------------------------------------*/
188: PetscCall(PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",&set));
189: PetscCall(PetscOptionsName("-nep_view_vectors","View computed eigenvectors","NEPVectorsView",&set));
190: PetscCall(PetscOptionsName("-nep_view_values","View computed eigenvalues","NEPValuesView",&set));
191: PetscCall(PetscOptionsName("-nep_converged_reason","Print reason for convergence, and number of iterations","NEPConvergedReasonView",&set));
192: PetscCall(PetscOptionsName("-nep_error_absolute","Print absolute errors of each eigenpair","NEPErrorView",&set));
193: PetscCall(PetscOptionsName("-nep_error_relative","Print relative errors of each eigenpair","NEPErrorView",&set));
195: PetscTryTypeMethod(nep,setfromoptions,PetscOptionsObject);
196: PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)nep,PetscOptionsObject));
197: PetscOptionsEnd();
199: if (!nep->V) PetscCall(NEPGetBV(nep,&nep->V));
200: PetscCall(BVSetFromOptions(nep->V));
201: if (!nep->rg) PetscCall(NEPGetRG(nep,&nep->rg));
202: PetscCall(RGSetFromOptions(nep->rg));
203: if (nep->useds) {
204: if (!nep->ds) PetscCall(NEPGetDS(nep,&nep->ds));
205: PetscCall(NEPSetDSType(nep));
206: PetscCall(DSSetFromOptions(nep->ds));
207: }
208: if (!nep->refineksp) PetscCall(NEPRefineGetKSP(nep,&nep->refineksp));
209: PetscCall(KSPSetFromOptions(nep->refineksp));
210: if (nep->fui==NEP_USER_INTERFACE_SPLIT) for (i=0;i<nep->nt;i++) PetscCall(FNSetFromOptions(nep->f[i]));
211: PetscFunctionReturn(PETSC_SUCCESS);
212: }
214: /*@C
215: NEPGetTolerances - Gets the tolerance and maximum iteration count used
216: by the NEP convergence tests.
218: Not Collective
220: Input Parameter:
221: . nep - the nonlinear eigensolver context
223: Output Parameters:
224: + tol - the convergence tolerance
225: - maxits - maximum number of iterations
227: Notes:
228: The user can specify NULL for any parameter that is not needed.
230: Level: intermediate
232: .seealso: NEPSetTolerances()
233: @*/
234: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *tol,PetscInt *maxits)
235: {
236: PetscFunctionBegin;
238: if (tol) *tol = nep->tol;
239: if (maxits) *maxits = nep->max_it;
240: PetscFunctionReturn(PETSC_SUCCESS);
241: }
243: /*@
244: NEPSetTolerances - Sets the tolerance and maximum iteration count used
245: by the NEP convergence tests.
247: Logically Collective
249: Input Parameters:
250: + nep - the nonlinear eigensolver context
251: . tol - the convergence tolerance
252: - maxits - maximum number of iterations to use
254: Options Database Keys:
255: + -nep_tol <tol> - Sets the convergence tolerance
256: - -nep_max_it <maxits> - Sets the maximum number of iterations allowed
258: Notes:
259: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
261: Level: intermediate
263: .seealso: NEPGetTolerances()
264: @*/
265: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal tol,PetscInt maxits)
266: {
267: PetscFunctionBegin;
271: if (tol == (PetscReal)PETSC_DEFAULT) {
272: nep->tol = PETSC_DEFAULT;
273: nep->state = NEP_STATE_INITIAL;
274: } else {
275: PetscCheck(tol>0.0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
276: nep->tol = tol;
277: }
278: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
279: nep->max_it = PETSC_DEFAULT;
280: nep->state = NEP_STATE_INITIAL;
281: } else {
282: PetscCheck(maxits>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
283: nep->max_it = maxits;
284: }
285: PetscFunctionReturn(PETSC_SUCCESS);
286: }
288: /*@C
289: NEPGetDimensions - Gets the number of eigenvalues to compute
290: and the dimension of the subspace.
292: Not Collective
294: Input Parameter:
295: . nep - the nonlinear eigensolver context
297: Output Parameters:
298: + nev - number of eigenvalues to compute
299: . ncv - the maximum dimension of the subspace to be used by the solver
300: - mpd - the maximum dimension allowed for the projected problem
302: Notes:
303: The user can specify NULL for any parameter that is not needed.
305: Level: intermediate
307: .seealso: NEPSetDimensions()
308: @*/
309: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
310: {
311: PetscFunctionBegin;
313: if (nev) *nev = nep->nev;
314: if (ncv) *ncv = nep->ncv;
315: if (mpd) *mpd = nep->mpd;
316: PetscFunctionReturn(PETSC_SUCCESS);
317: }
319: /*@
320: NEPSetDimensions - Sets the number of eigenvalues to compute
321: and the dimension of the subspace.
323: Logically Collective
325: Input Parameters:
326: + nep - the nonlinear eigensolver context
327: . nev - number of eigenvalues to compute
328: . ncv - the maximum dimension of the subspace to be used by the solver
329: - mpd - the maximum dimension allowed for the projected problem
331: Options Database Keys:
332: + -nep_nev <nev> - Sets the number of eigenvalues
333: . -nep_ncv <ncv> - Sets the dimension of the subspace
334: - -nep_mpd <mpd> - Sets the maximum projected dimension
336: Notes:
337: Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
338: dependent on the solution method.
340: The parameters ncv and mpd are intimately related, so that the user is advised
341: to set one of them at most. Normal usage is that
342: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
343: (b) in cases where nev is large, the user sets mpd.
345: The value of ncv should always be between nev and (nev+mpd), typically
346: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
347: a smaller value should be used.
349: Level: intermediate
351: .seealso: NEPGetDimensions()
352: @*/
353: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)
354: {
355: PetscFunctionBegin;
360: PetscCheck(nev>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
361: nep->nev = nev;
362: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
363: nep->ncv = PETSC_DEFAULT;
364: } else {
365: PetscCheck(ncv>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
366: nep->ncv = ncv;
367: }
368: if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
369: nep->mpd = PETSC_DEFAULT;
370: } else {
371: PetscCheck(mpd>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
372: nep->mpd = mpd;
373: }
374: nep->state = NEP_STATE_INITIAL;
375: PetscFunctionReturn(PETSC_SUCCESS);
376: }
378: /*@
379: NEPSetWhichEigenpairs - Specifies which portion of the spectrum is
380: to be sought.
382: Logically Collective
384: Input Parameters:
385: + nep - eigensolver context obtained from NEPCreate()
386: - which - the portion of the spectrum to be sought
388: Options Database Keys:
389: + -nep_largest_magnitude - Sets largest eigenvalues in magnitude
390: . -nep_smallest_magnitude - Sets smallest eigenvalues in magnitude
391: . -nep_largest_real - Sets largest real parts
392: . -nep_smallest_real - Sets smallest real parts
393: . -nep_largest_imaginary - Sets largest imaginary parts
394: . -nep_smallest_imaginary - Sets smallest imaginary parts
395: . -nep_target_magnitude - Sets eigenvalues closest to target
396: . -nep_target_real - Sets real parts closest to target
397: . -nep_target_imaginary - Sets imaginary parts closest to target
398: - -nep_all - Sets all eigenvalues in a region
400: Notes:
401: The parameter 'which' can have one of these values
403: + NEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
404: . NEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
405: . NEP_LARGEST_REAL - largest real parts
406: . NEP_SMALLEST_REAL - smallest real parts
407: . NEP_LARGEST_IMAGINARY - largest imaginary parts
408: . NEP_SMALLEST_IMAGINARY - smallest imaginary parts
409: . NEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
410: . NEP_TARGET_REAL - eigenvalues with real part closest to target
411: . NEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
412: . NEP_ALL - all eigenvalues contained in a given region
413: - NEP_WHICH_USER - user defined ordering set with NEPSetEigenvalueComparison()
415: Not all eigensolvers implemented in NEP account for all the possible values
416: stated above. If SLEPc is compiled for real numbers NEP_LARGEST_IMAGINARY
417: and NEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
418: for eigenvalue selection.
420: The target is a scalar value provided with NEPSetTarget().
422: NEP_ALL is intended for use in the context of the CISS solver for
423: computing all eigenvalues in a region.
425: Level: intermediate
427: .seealso: NEPGetWhichEigenpairs(), NEPSetTarget(), NEPSetEigenvalueComparison(), NEPWhich
428: @*/
429: PetscErrorCode NEPSetWhichEigenpairs(NEP nep,NEPWhich which)
430: {
431: PetscFunctionBegin;
434: switch (which) {
435: case NEP_LARGEST_MAGNITUDE:
436: case NEP_SMALLEST_MAGNITUDE:
437: case NEP_LARGEST_REAL:
438: case NEP_SMALLEST_REAL:
439: case NEP_LARGEST_IMAGINARY:
440: case NEP_SMALLEST_IMAGINARY:
441: case NEP_TARGET_MAGNITUDE:
442: case NEP_TARGET_REAL:
443: #if defined(PETSC_USE_COMPLEX)
444: case NEP_TARGET_IMAGINARY:
445: #endif
446: case NEP_ALL:
447: case NEP_WHICH_USER:
448: if (nep->which != which) {
449: nep->state = NEP_STATE_INITIAL;
450: nep->which = which;
451: }
452: break;
453: #if !defined(PETSC_USE_COMPLEX)
454: case NEP_TARGET_IMAGINARY:
455: SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_SUP,"NEP_TARGET_IMAGINARY can be used only with complex scalars");
456: #endif
457: default:
458: SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
459: }
460: PetscFunctionReturn(PETSC_SUCCESS);
461: }
463: /*@
464: NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
465: sought.
467: Not Collective
469: Input Parameter:
470: . nep - eigensolver context obtained from NEPCreate()
472: Output Parameter:
473: . which - the portion of the spectrum to be sought
475: Notes:
476: See NEPSetWhichEigenpairs() for possible values of 'which'.
478: Level: intermediate
480: .seealso: NEPSetWhichEigenpairs(), NEPWhich
481: @*/
482: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)
483: {
484: PetscFunctionBegin;
486: PetscAssertPointer(which,2);
487: *which = nep->which;
488: PetscFunctionReturn(PETSC_SUCCESS);
489: }
491: /*@C
492: NEPSetEigenvalueComparison - Specifies the eigenvalue comparison function
493: when NEPSetWhichEigenpairs() is set to NEP_WHICH_USER.
495: Logically Collective
497: Input Parameters:
498: + nep - eigensolver context obtained from NEPCreate()
499: . comp - a pointer to the comparison function
500: - ctx - a context pointer (the last parameter to the comparison function)
502: Calling sequence of comp:
503: $ PetscErrorCode comp(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)
504: + ar - real part of the 1st eigenvalue
505: . ai - imaginary part of the 1st eigenvalue
506: . br - real part of the 2nd eigenvalue
507: . bi - imaginary part of the 2nd eigenvalue
508: . res - result of comparison
509: - ctx - optional context, as set by NEPSetEigenvalueComparison()
511: Note:
512: The returning parameter 'res' can be
513: + negative - if the 1st eigenvalue is preferred to the 2st one
514: . zero - if both eigenvalues are equally preferred
515: - positive - if the 2st eigenvalue is preferred to the 1st one
517: Level: advanced
519: .seealso: NEPSetWhichEigenpairs(), NEPWhich
520: @*/
521: PetscErrorCode NEPSetEigenvalueComparison(NEP nep,PetscErrorCode (*comp)(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx),void* ctx)
522: {
523: PetscFunctionBegin;
525: nep->sc->comparison = comp;
526: nep->sc->comparisonctx = ctx;
527: nep->which = NEP_WHICH_USER;
528: PetscFunctionReturn(PETSC_SUCCESS);
529: }
531: /*@
532: NEPSetProblemType - Specifies the type of the nonlinear eigenvalue problem.
534: Logically Collective
536: Input Parameters:
537: + nep - the nonlinear eigensolver context
538: - type - a known type of nonlinear eigenvalue problem
540: Options Database Keys:
541: + -nep_general - general problem with no particular structure
542: - -nep_rational - a rational eigenvalue problem defined in split form with all f_i rational
544: Notes:
545: Allowed values for the problem type are general (NEP_GENERAL), and rational
546: (NEP_RATIONAL).
548: This function is used to provide a hint to the NEP solver to exploit certain
549: properties of the nonlinear eigenproblem. This hint may be used or not,
550: depending on the solver. By default, no particular structure is assumed.
552: Level: intermediate
554: .seealso: NEPSetType(), NEPGetProblemType(), NEPProblemType
555: @*/
556: PetscErrorCode NEPSetProblemType(NEP nep,NEPProblemType type)
557: {
558: PetscFunctionBegin;
561: PetscCheck(type==NEP_GENERAL || type==NEP_RATIONAL,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
562: if (type != nep->problem_type) {
563: nep->problem_type = type;
564: nep->state = NEP_STATE_INITIAL;
565: }
566: PetscFunctionReturn(PETSC_SUCCESS);
567: }
569: /*@
570: NEPGetProblemType - Gets the problem type from the NEP object.
572: Not Collective
574: Input Parameter:
575: . nep - the nonlinear eigensolver context
577: Output Parameter:
578: . type - the problem type
580: Level: intermediate
582: .seealso: NEPSetProblemType(), NEPProblemType
583: @*/
584: PetscErrorCode NEPGetProblemType(NEP nep,NEPProblemType *type)
585: {
586: PetscFunctionBegin;
588: PetscAssertPointer(type,2);
589: *type = nep->problem_type;
590: PetscFunctionReturn(PETSC_SUCCESS);
591: }
593: /*@
594: NEPSetTwoSided - Sets the solver to use a two-sided variant so that left
595: eigenvectors are also computed.
597: Logically Collective
599: Input Parameters:
600: + nep - the eigensolver context
601: - twosided - whether the two-sided variant is to be used or not
603: Options Database Keys:
604: . -nep_two_sided <boolean> - Sets/resets the twosided flag
606: Notes:
607: If the user sets twosided=PETSC_TRUE then the solver uses a variant of
608: the algorithm that computes both right and left eigenvectors. This is
609: usually much more costly. This option is not available in all solvers.
611: When using two-sided solvers, the problem matrices must have both the
612: MatMult and MatMultTranspose operations defined.
614: Level: advanced
616: .seealso: NEPGetTwoSided(), NEPGetLeftEigenvector()
617: @*/
618: PetscErrorCode NEPSetTwoSided(NEP nep,PetscBool twosided)
619: {
620: PetscFunctionBegin;
623: if (twosided!=nep->twosided) {
624: nep->twosided = twosided;
625: nep->state = NEP_STATE_INITIAL;
626: }
627: PetscFunctionReturn(PETSC_SUCCESS);
628: }
630: /*@
631: NEPGetTwoSided - Returns the flag indicating whether a two-sided variant
632: of the algorithm is being used or not.
634: Not Collective
636: Input Parameter:
637: . nep - the eigensolver context
639: Output Parameter:
640: . twosided - the returned flag
642: Level: advanced
644: .seealso: NEPSetTwoSided()
645: @*/
646: PetscErrorCode NEPGetTwoSided(NEP nep,PetscBool *twosided)
647: {
648: PetscFunctionBegin;
650: PetscAssertPointer(twosided,2);
651: *twosided = nep->twosided;
652: PetscFunctionReturn(PETSC_SUCCESS);
653: }
655: /*@C
656: NEPSetConvergenceTestFunction - Sets a function to compute the error estimate
657: used in the convergence test.
659: Logically Collective
661: Input Parameters:
662: + nep - nonlinear eigensolver context obtained from NEPCreate()
663: . conv - a pointer to the convergence test function
664: . ctx - context for private data for the convergence routine (may be null)
665: - destroy - a routine for destroying the context (may be null)
667: Calling sequence of conv:
668: $ PetscErrorCode conv(NEP nep,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)
669: + nep - nonlinear eigensolver context obtained from NEPCreate()
670: . eigr - real part of the eigenvalue
671: . eigi - imaginary part of the eigenvalue
672: . res - residual norm associated to the eigenpair
673: . errest - (output) computed error estimate
674: - ctx - optional context, as set by NEPSetConvergenceTestFunction()
676: Note:
677: If the error estimate returned by the convergence test function is less than
678: the tolerance, then the eigenvalue is accepted as converged.
680: Level: advanced
682: .seealso: NEPSetConvergenceTest(), NEPSetTolerances()
683: @*/
684: PetscErrorCode NEPSetConvergenceTestFunction(NEP nep,PetscErrorCode (*conv)(NEP nep,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx),void* ctx,PetscErrorCode (*destroy)(void*))
685: {
686: PetscFunctionBegin;
688: if (nep->convergeddestroy) PetscCall((*nep->convergeddestroy)(nep->convergedctx));
689: nep->convergeduser = conv;
690: nep->convergeddestroy = destroy;
691: nep->convergedctx = ctx;
692: if (conv == NEPConvergedRelative) nep->conv = NEP_CONV_REL;
693: else if (conv == NEPConvergedNorm) nep->conv = NEP_CONV_NORM;
694: else if (conv == NEPConvergedAbsolute) nep->conv = NEP_CONV_ABS;
695: else {
696: nep->conv = NEP_CONV_USER;
697: nep->converged = nep->convergeduser;
698: }
699: PetscFunctionReturn(PETSC_SUCCESS);
700: }
702: /*@
703: NEPSetConvergenceTest - Specifies how to compute the error estimate
704: used in the convergence test.
706: Logically Collective
708: Input Parameters:
709: + nep - nonlinear eigensolver context obtained from NEPCreate()
710: - conv - the type of convergence test
712: Options Database Keys:
713: + -nep_conv_abs - Sets the absolute convergence test
714: . -nep_conv_rel - Sets the convergence test relative to the eigenvalue
715: - -nep_conv_user - Selects the user-defined convergence test
717: Note:
718: The parameter 'conv' can have one of these values
719: + NEP_CONV_ABS - absolute error ||r||
720: . NEP_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
721: . NEP_CONV_NORM - error relative matrix norms, ||r||/sum_i(|f_i(l)|*||A_i||)
722: - NEP_CONV_USER - function set by NEPSetConvergenceTestFunction()
724: Level: intermediate
726: .seealso: NEPGetConvergenceTest(), NEPSetConvergenceTestFunction(), NEPSetStoppingTest(), NEPConv
727: @*/
728: PetscErrorCode NEPSetConvergenceTest(NEP nep,NEPConv conv)
729: {
730: PetscFunctionBegin;
733: switch (conv) {
734: case NEP_CONV_ABS: nep->converged = NEPConvergedAbsolute; break;
735: case NEP_CONV_REL: nep->converged = NEPConvergedRelative; break;
736: case NEP_CONV_NORM: nep->converged = NEPConvergedNorm; break;
737: case NEP_CONV_USER:
738: PetscCheck(nep->convergeduser,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetConvergenceTestFunction() first");
739: nep->converged = nep->convergeduser;
740: break;
741: default:
742: SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
743: }
744: nep->conv = conv;
745: PetscFunctionReturn(PETSC_SUCCESS);
746: }
748: /*@
749: NEPGetConvergenceTest - Gets the method used to compute the error estimate
750: used in the convergence test.
752: Not Collective
754: Input Parameters:
755: . nep - nonlinear eigensolver context obtained from NEPCreate()
757: Output Parameters:
758: . conv - the type of convergence test
760: Level: intermediate
762: .seealso: NEPSetConvergenceTest(), NEPConv
763: @*/
764: PetscErrorCode NEPGetConvergenceTest(NEP nep,NEPConv *conv)
765: {
766: PetscFunctionBegin;
768: PetscAssertPointer(conv,2);
769: *conv = nep->conv;
770: PetscFunctionReturn(PETSC_SUCCESS);
771: }
773: /*@C
774: NEPSetStoppingTestFunction - Sets a function to decide when to stop the outer
775: iteration of the eigensolver.
777: Logically Collective
779: Input Parameters:
780: + nep - nonlinear eigensolver context obtained from NEPCreate()
781: . stop - pointer to the stopping test function
782: . ctx - context for private data for the stopping routine (may be null)
783: - destroy - a routine for destroying the context (may be null)
785: Calling sequence of stop:
786: $ PetscErrorCode stop(NEP nep,PetscInt its,PetscInt max_its,PetscInt nconv,PetscInt nev,NEPConvergedReason *reason,void *ctx)
787: + nep - nonlinear eigensolver context obtained from NEPCreate()
788: . its - current number of iterations
789: . max_its - maximum number of iterations
790: . nconv - number of currently converged eigenpairs
791: . nev - number of requested eigenpairs
792: . reason - (output) result of the stopping test
793: - ctx - optional context, as set by NEPSetStoppingTestFunction()
795: Note:
796: Normal usage is to first call the default routine NEPStoppingBasic() and then
797: set reason to NEP_CONVERGED_USER if some user-defined conditions have been
798: met. To let the eigensolver continue iterating, the result must be left as
799: NEP_CONVERGED_ITERATING.
801: Level: advanced
803: .seealso: NEPSetStoppingTest(), NEPStoppingBasic()
804: @*/
805: PetscErrorCode NEPSetStoppingTestFunction(NEP nep,PetscErrorCode (*stop)(NEP nep,PetscInt its,PetscInt max_its,PetscInt nconv,PetscInt nev,NEPConvergedReason *reason,void *ctx),void* ctx,PetscErrorCode (*destroy)(void*))
806: {
807: PetscFunctionBegin;
809: if (nep->stoppingdestroy) PetscCall((*nep->stoppingdestroy)(nep->stoppingctx));
810: nep->stoppinguser = stop;
811: nep->stoppingdestroy = destroy;
812: nep->stoppingctx = ctx;
813: if (stop == NEPStoppingBasic) nep->stop = NEP_STOP_BASIC;
814: else {
815: nep->stop = NEP_STOP_USER;
816: nep->stopping = nep->stoppinguser;
817: }
818: PetscFunctionReturn(PETSC_SUCCESS);
819: }
821: /*@
822: NEPSetStoppingTest - Specifies how to decide the termination of the outer
823: loop of the eigensolver.
825: Logically Collective
827: Input Parameters:
828: + nep - nonlinear eigensolver context obtained from NEPCreate()
829: - stop - the type of stopping test
831: Options Database Keys:
832: + -nep_stop_basic - Sets the default stopping test
833: - -nep_stop_user - Selects the user-defined stopping test
835: Note:
836: The parameter 'stop' can have one of these values
837: + NEP_STOP_BASIC - default stopping test
838: - NEP_STOP_USER - function set by NEPSetStoppingTestFunction()
840: Level: advanced
842: .seealso: NEPGetStoppingTest(), NEPSetStoppingTestFunction(), NEPSetConvergenceTest(), NEPStop
843: @*/
844: PetscErrorCode NEPSetStoppingTest(NEP nep,NEPStop stop)
845: {
846: PetscFunctionBegin;
849: switch (stop) {
850: case NEP_STOP_BASIC: nep->stopping = NEPStoppingBasic; break;
851: case NEP_STOP_USER:
852: PetscCheck(nep->stoppinguser,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetStoppingTestFunction() first");
853: nep->stopping = nep->stoppinguser;
854: break;
855: default:
856: SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
857: }
858: nep->stop = stop;
859: PetscFunctionReturn(PETSC_SUCCESS);
860: }
862: /*@
863: NEPGetStoppingTest - Gets the method used to decide the termination of the outer
864: loop of the eigensolver.
866: Not Collective
868: Input Parameters:
869: . nep - nonlinear eigensolver context obtained from NEPCreate()
871: Output Parameters:
872: . stop - the type of stopping test
874: Level: advanced
876: .seealso: NEPSetStoppingTest(), NEPStop
877: @*/
878: PetscErrorCode NEPGetStoppingTest(NEP nep,NEPStop *stop)
879: {
880: PetscFunctionBegin;
882: PetscAssertPointer(stop,2);
883: *stop = nep->stop;
884: PetscFunctionReturn(PETSC_SUCCESS);
885: }
887: /*@
888: NEPSetTrackAll - Specifies if the solver must compute the residual of all
889: approximate eigenpairs or not.
891: Logically Collective
893: Input Parameters:
894: + nep - the eigensolver context
895: - trackall - whether compute all residuals or not
897: Notes:
898: If the user sets trackall=PETSC_TRUE then the solver explicitly computes
899: the residual for each eigenpair approximation. Computing the residual is
900: usually an expensive operation and solvers commonly compute the associated
901: residual to the first unconverged eigenpair.
903: The option '-nep_monitor_all' automatically activates this option.
905: Level: developer
907: .seealso: NEPGetTrackAll()
908: @*/
909: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)
910: {
911: PetscFunctionBegin;
914: nep->trackall = trackall;
915: PetscFunctionReturn(PETSC_SUCCESS);
916: }
918: /*@
919: NEPGetTrackAll - Returns the flag indicating whether all residual norms must
920: be computed or not.
922: Not Collective
924: Input Parameter:
925: . nep - the eigensolver context
927: Output Parameter:
928: . trackall - the returned flag
930: Level: developer
932: .seealso: NEPSetTrackAll()
933: @*/
934: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)
935: {
936: PetscFunctionBegin;
938: PetscAssertPointer(trackall,2);
939: *trackall = nep->trackall;
940: PetscFunctionReturn(PETSC_SUCCESS);
941: }
943: /*@
944: NEPSetRefine - Specifies the refinement type (and options) to be used
945: after the solve.
947: Logically Collective
949: Input Parameters:
950: + nep - the nonlinear eigensolver context
951: . refine - refinement type
952: . npart - number of partitions of the communicator
953: . tol - the convergence tolerance
954: . its - maximum number of refinement iterations
955: - scheme - which scheme to be used for solving the involved linear systems
957: Options Database Keys:
958: + -nep_refine <type> - refinement type, one of <none,simple,multiple>
959: . -nep_refine_partitions <n> - the number of partitions
960: . -nep_refine_tol <tol> - the tolerance
961: . -nep_refine_its <its> - number of iterations
962: - -nep_refine_scheme - to set the scheme for the linear solves
964: Notes:
965: By default, iterative refinement is disabled, since it may be very
966: costly. There are two possible refinement strategies, simple and multiple.
967: The simple approach performs iterative refinement on each of the
968: converged eigenpairs individually, whereas the multiple strategy works
969: with the invariant pair as a whole, refining all eigenpairs simultaneously.
970: The latter may be required for the case of multiple eigenvalues.
972: In some cases, especially when using direct solvers within the
973: iterative refinement method, it may be helpful for improved scalability
974: to split the communicator in several partitions. The npart parameter
975: indicates how many partitions to use (defaults to 1).
977: The tol and its parameters specify the stopping criterion. In the simple
978: method, refinement continues until the residual of each eigenpair is
979: below the tolerance (tol defaults to the NEP tol, but may be set to a
980: different value). In contrast, the multiple method simply performs its
981: refinement iterations (just one by default).
983: The scheme argument is used to change the way in which linear systems are
984: solved. Possible choices are explicit, mixed block elimination (MBE),
985: and Schur complement.
987: Level: intermediate
989: .seealso: NEPGetRefine()
990: @*/
991: PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its,NEPRefineScheme scheme)
992: {
993: PetscMPIInt size;
995: PetscFunctionBegin;
1002: nep->refine = refine;
1003: if (refine) { /* process parameters only if not REFINE_NONE */
1004: if (npart!=nep->npart) {
1005: PetscCall(PetscSubcommDestroy(&nep->refinesubc));
1006: PetscCall(KSPDestroy(&nep->refineksp));
1007: }
1008: if (npart == PETSC_DEFAULT || npart == PETSC_DECIDE) {
1009: nep->npart = 1;
1010: } else {
1011: PetscCallMPI(MPI_Comm_size(PetscObjectComm((PetscObject)nep),&size));
1012: PetscCheck(npart>0 && npart<=size,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
1013: nep->npart = npart;
1014: }
1015: if (tol == (PetscReal)PETSC_DEFAULT || tol == (PetscReal)PETSC_DECIDE) {
1016: nep->rtol = PETSC_DEFAULT;
1017: } else {
1018: PetscCheck(tol>0.0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
1019: nep->rtol = tol;
1020: }
1021: if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
1022: nep->rits = PETSC_DEFAULT;
1023: } else {
1024: PetscCheck(its>=0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
1025: nep->rits = its;
1026: }
1027: nep->scheme = scheme;
1028: }
1029: nep->state = NEP_STATE_INITIAL;
1030: PetscFunctionReturn(PETSC_SUCCESS);
1031: }
1033: /*@C
1034: NEPGetRefine - Gets the refinement strategy used by the NEP object, and the
1035: associated parameters.
1037: Not Collective
1039: Input Parameter:
1040: . nep - the nonlinear eigensolver context
1042: Output Parameters:
1043: + refine - refinement type
1044: . npart - number of partitions of the communicator
1045: . tol - the convergence tolerance
1046: . its - maximum number of refinement iterations
1047: - scheme - the scheme used for solving linear systems
1049: Level: intermediate
1051: Note:
1052: The user can specify NULL for any parameter that is not needed.
1054: .seealso: NEPSetRefine()
1055: @*/
1056: PetscErrorCode NEPGetRefine(NEP nep,NEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its,NEPRefineScheme *scheme)
1057: {
1058: PetscFunctionBegin;
1060: if (refine) *refine = nep->refine;
1061: if (npart) *npart = nep->npart;
1062: if (tol) *tol = nep->rtol;
1063: if (its) *its = nep->rits;
1064: if (scheme) *scheme = nep->scheme;
1065: PetscFunctionReturn(PETSC_SUCCESS);
1066: }
1068: /*@C
1069: NEPSetOptionsPrefix - Sets the prefix used for searching for all
1070: NEP options in the database.
1072: Logically Collective
1074: Input Parameters:
1075: + nep - the nonlinear eigensolver context
1076: - prefix - the prefix string to prepend to all NEP option requests
1078: Notes:
1079: A hyphen (-) must NOT be given at the beginning of the prefix name.
1080: The first character of all runtime options is AUTOMATICALLY the
1081: hyphen.
1083: For example, to distinguish between the runtime options for two
1084: different NEP contexts, one could call
1085: .vb
1086: NEPSetOptionsPrefix(nep1,"neig1_")
1087: NEPSetOptionsPrefix(nep2,"neig2_")
1088: .ve
1090: Level: advanced
1092: .seealso: NEPAppendOptionsPrefix(), NEPGetOptionsPrefix()
1093: @*/
1094: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char *prefix)
1095: {
1096: PetscFunctionBegin;
1098: if (!nep->V) PetscCall(NEPGetBV(nep,&nep->V));
1099: PetscCall(BVSetOptionsPrefix(nep->V,prefix));
1100: if (!nep->ds) PetscCall(NEPGetDS(nep,&nep->ds));
1101: PetscCall(DSSetOptionsPrefix(nep->ds,prefix));
1102: if (!nep->rg) PetscCall(NEPGetRG(nep,&nep->rg));
1103: PetscCall(RGSetOptionsPrefix(nep->rg,prefix));
1104: PetscCall(PetscObjectSetOptionsPrefix((PetscObject)nep,prefix));
1105: PetscFunctionReturn(PETSC_SUCCESS);
1106: }
1108: /*@C
1109: NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
1110: NEP options in the database.
1112: Logically Collective
1114: Input Parameters:
1115: + nep - the nonlinear eigensolver context
1116: - prefix - the prefix string to prepend to all NEP option requests
1118: Notes:
1119: A hyphen (-) must NOT be given at the beginning of the prefix name.
1120: The first character of all runtime options is AUTOMATICALLY the hyphen.
1122: Level: advanced
1124: .seealso: NEPSetOptionsPrefix(), NEPGetOptionsPrefix()
1125: @*/
1126: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char *prefix)
1127: {
1128: PetscFunctionBegin;
1130: if (!nep->V) PetscCall(NEPGetBV(nep,&nep->V));
1131: PetscCall(BVAppendOptionsPrefix(nep->V,prefix));
1132: if (!nep->ds) PetscCall(NEPGetDS(nep,&nep->ds));
1133: PetscCall(DSAppendOptionsPrefix(nep->ds,prefix));
1134: if (!nep->rg) PetscCall(NEPGetRG(nep,&nep->rg));
1135: PetscCall(RGAppendOptionsPrefix(nep->rg,prefix));
1136: PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix));
1137: PetscFunctionReturn(PETSC_SUCCESS);
1138: }
1140: /*@C
1141: NEPGetOptionsPrefix - Gets the prefix used for searching for all
1142: NEP options in the database.
1144: Not Collective
1146: Input Parameters:
1147: . nep - the nonlinear eigensolver context
1149: Output Parameters:
1150: . prefix - pointer to the prefix string used is returned
1152: Note:
1153: On the Fortran side, the user should pass in a string 'prefix' of
1154: sufficient length to hold the prefix.
1156: Level: advanced
1158: .seealso: NEPSetOptionsPrefix(), NEPAppendOptionsPrefix()
1159: @*/
1160: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])
1161: {
1162: PetscFunctionBegin;
1164: PetscAssertPointer(prefix,2);
1165: PetscCall(PetscObjectGetOptionsPrefix((PetscObject)nep,prefix));
1166: PetscFunctionReturn(PETSC_SUCCESS);
1167: }