Actual source code: epsopts.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: EPS routines related to options that can be set via the command-line
12: or procedurally.
13: */
15: #include <slepc/private/epsimpl.h>
16: #include <petscdraw.h>
18: /*@C
19: EPSMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective
24: Input Parameters:
25: + eps - the 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: `EPSMonitorSet()`, `EPSSetTrackAll()`
34: @*/
35: PetscErrorCode EPSMonitorSetFromOptions(EPS eps,const char opt[],const char name[],void *ctx,PetscBool trackall)
36: {
37: PetscErrorCode (*mfunc)(EPS,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)eps),((PetscObject)eps)->options,((PetscObject)eps)->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(EPSMonitorList,key,&mfunc));
54: PetscCheck(mfunc,PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"Specified viewer and format not supported");
55: PetscCall(PetscFunctionListFind(EPSMonitorCreateList,key,&cfunc));
56: PetscCall(PetscFunctionListFind(EPSMonitorDestroyList,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(EPSMonitorSet(eps,mfunc,vf,(PetscCtxDestroyFn*)dfunc));
63: if (trackall) PetscCall(EPSSetTrackAll(eps,PETSC_TRUE));
64: PetscFunctionReturn(PETSC_SUCCESS);
65: }
67: /*@
68: EPSSetFromOptions - Sets EPS options from the options database.
69: This routine must be called before EPSSetUp() if the user is to be
70: allowed to set the solver type.
72: Collective
74: Input Parameters:
75: . eps - the eigensolver context
77: Notes:
78: To see all options, run your program with the -help option.
80: Level: beginner
82: .seealso: `EPSSetOptionsPrefix()`
83: @*/
84: PetscErrorCode EPSSetFromOptions(EPS eps)
85: {
86: char type[256];
87: PetscBool set,flg,flg1,flg2,flg3,bval;
88: PetscReal r,array[2]={0,0};
89: PetscScalar s;
90: PetscInt i,j,k;
91: EPSBalance bal;
93: PetscFunctionBegin;
95: PetscCall(EPSRegisterAll());
96: PetscObjectOptionsBegin((PetscObject)eps);
97: PetscCall(PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,sizeof(type),&flg));
98: if (flg) PetscCall(EPSSetType(eps,type));
99: else if (!((PetscObject)eps)->type_name) PetscCall(EPSSetType(eps,EPSKRYLOVSCHUR));
101: PetscCall(PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg));
102: if (flg) PetscCall(EPSSetProblemType(eps,EPS_HEP));
103: PetscCall(PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg));
104: if (flg) PetscCall(EPSSetProblemType(eps,EPS_GHEP));
105: PetscCall(PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg));
106: if (flg) PetscCall(EPSSetProblemType(eps,EPS_NHEP));
107: PetscCall(PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg));
108: if (flg) PetscCall(EPSSetProblemType(eps,EPS_GNHEP));
109: PetscCall(PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg));
110: if (flg) PetscCall(EPSSetProblemType(eps,EPS_PGNHEP));
111: PetscCall(PetscOptionsBoolGroup("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg));
112: if (flg) PetscCall(EPSSetProblemType(eps,EPS_GHIEP));
113: PetscCall(PetscOptionsBoolGroup("-eps_bse","Structured Bethe-Salpeter eigenvalue problem","EPSSetProblemType",&flg));
114: if (flg) PetscCall(EPSSetProblemType(eps,EPS_BSE));
115: PetscCall(PetscOptionsBoolGroupEnd("-eps_hamiltonian","Structured Hamiltonian eigenvalue problem","EPSSetProblemType",&flg));
116: if (flg) PetscCall(EPSSetProblemType(eps,EPS_HAMILT));
118: PetscCall(PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg));
119: if (flg) PetscCall(EPSSetExtraction(eps,EPS_RITZ));
120: PetscCall(PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg));
121: if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC));
122: PetscCall(PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg));
123: if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE));
124: PetscCall(PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg));
125: if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC_RIGHT));
126: PetscCall(PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg));
127: if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC_LARGEST));
128: PetscCall(PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg));
129: if (flg) PetscCall(EPSSetExtraction(eps,EPS_REFINED));
130: PetscCall(PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg));
131: if (flg) PetscCall(EPSSetExtraction(eps,EPS_REFINED_HARMONIC));
133: bal = eps->balance;
134: PetscCall(PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1));
135: j = eps->balance_its;
136: PetscCall(PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2));
137: r = eps->balance_cutoff;
138: PetscCall(PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3));
139: if (flg1 || flg2 || flg3) PetscCall(EPSSetBalance(eps,bal,j,r));
141: i = eps->max_it;
142: PetscCall(PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1));
143: r = eps->tol;
144: PetscCall(PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",SlepcDefaultTol(eps->tol),&r,&flg2));
145: if (flg1 || flg2) PetscCall(EPSSetTolerances(eps,r,i));
147: r = eps->thres;
148: PetscCall(PetscOptionsReal("-eps_threshold_absolute","Absolute threshold","EPSSetThreshold",r,&r,&flg));
149: if (flg) PetscCall(EPSSetThreshold(eps,r,PETSC_FALSE));
150: PetscCall(PetscOptionsReal("-eps_threshold_relative","Relative threshold","EPSSetThreshold",r,&r,&flg));
151: if (flg) PetscCall(EPSSetThreshold(eps,r,PETSC_TRUE));
153: PetscCall(PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg));
154: if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_REL));
155: PetscCall(PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg));
156: if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_NORM));
157: PetscCall(PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg));
158: if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_ABS));
159: PetscCall(PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg));
160: if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_USER));
162: PetscCall(PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg));
163: if (flg) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_BASIC));
164: PetscCall(PetscOptionsBoolGroup("-eps_stop_threshold","Stop iteration if a converged eigenvalue is below/above the threshold","EPSSetStoppingTest",&flg));
165: if (flg) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_THRESHOLD));
166: PetscCall(PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg));
167: if (flg) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_USER));
169: i = eps->nev;
170: PetscCall(PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1));
171: if (!flg1) i = PETSC_CURRENT;
172: j = eps->ncv;
173: PetscCall(PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2));
174: k = eps->mpd;
175: PetscCall(PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3));
176: if (flg1 || flg2 || flg3) PetscCall(EPSSetDimensions(eps,i,j,k));
178: PetscCall(PetscOptionsBoolGroupBegin("-eps_largest_magnitude","Compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg));
179: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE));
180: PetscCall(PetscOptionsBoolGroup("-eps_smallest_magnitude","Compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg));
181: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE));
182: PetscCall(PetscOptionsBoolGroup("-eps_largest_real","Compute eigenvalues with largest real parts","EPSSetWhichEigenpairs",&flg));
183: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL));
184: PetscCall(PetscOptionsBoolGroup("-eps_smallest_real","Compute eigenvalues with smallest real parts","EPSSetWhichEigenpairs",&flg));
185: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL));
186: PetscCall(PetscOptionsBoolGroup("-eps_largest_imaginary","Compute eigenvalues with largest imaginary parts","EPSSetWhichEigenpairs",&flg));
187: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY));
188: PetscCall(PetscOptionsBoolGroup("-eps_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","EPSSetWhichEigenpairs",&flg));
189: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY));
190: PetscCall(PetscOptionsBoolGroup("-eps_target_magnitude","Compute eigenvalues closest to target","EPSSetWhichEigenpairs",&flg));
191: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE));
192: PetscCall(PetscOptionsBoolGroup("-eps_target_real","Compute eigenvalues with real parts closest to target","EPSSetWhichEigenpairs",&flg));
193: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL));
194: PetscCall(PetscOptionsBoolGroup("-eps_target_imaginary","Compute eigenvalues with imaginary parts closest to target","EPSSetWhichEigenpairs",&flg));
195: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY));
196: PetscCall(PetscOptionsBoolGroupEnd("-eps_all","Compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg));
197: if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_ALL));
199: PetscCall(PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg));
200: if (flg) {
201: if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE));
202: PetscCall(EPSSetTarget(eps,s));
203: }
205: k = 2;
206: PetscCall(PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg));
207: if (flg) {
208: PetscCheck(k>1,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
209: PetscCall(EPSSetWhichEigenpairs(eps,EPS_ALL));
210: PetscCall(EPSSetInterval(eps,array[0],array[1]));
211: }
213: PetscCall(PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL));
214: PetscCall(PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&bval,&flg));
215: if (flg) PetscCall(EPSSetPurify(eps,bval));
216: PetscCall(PetscOptionsBool("-eps_two_sided","Use two-sided variant (to compute left eigenvectors)","EPSSetTwoSided",eps->twosided,&bval,&flg));
217: if (flg) PetscCall(EPSSetTwoSided(eps,bval));
219: /* -----------------------------------------------------------------------*/
220: /*
221: Cancels all monitors hardwired into code before call to EPSSetFromOptions()
222: */
223: PetscCall(PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set));
224: if (set && flg) PetscCall(EPSMonitorCancel(eps));
225: PetscCall(EPSMonitorSetFromOptions(eps,"-eps_monitor","first_approximation",NULL,PETSC_FALSE));
226: PetscCall(EPSMonitorSetFromOptions(eps,"-eps_monitor_all","all_approximations",NULL,PETSC_TRUE));
227: PetscCall(EPSMonitorSetFromOptions(eps,"-eps_monitor_conv","convergence_history",NULL,PETSC_FALSE));
229: /* -----------------------------------------------------------------------*/
230: PetscCall(PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",&set));
231: PetscCall(PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",&set));
232: PetscCall(PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",&set));
233: PetscCall(PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSConvergedReasonView",&set));
234: PetscCall(PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",&set));
235: PetscCall(PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",&set));
236: PetscCall(PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",&set));
238: PetscTryTypeMethod(eps,setfromoptions,PetscOptionsObject);
239: PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)eps,PetscOptionsObject));
240: PetscOptionsEnd();
242: if (!eps->V) PetscCall(EPSGetBV(eps,&eps->V));
243: PetscCall(BVSetFromOptions(eps->V));
244: if (!eps->rg) PetscCall(EPSGetRG(eps,&eps->rg));
245: PetscCall(RGSetFromOptions(eps->rg));
246: if (eps->useds) {
247: if (!eps->ds) PetscCall(EPSGetDS(eps,&eps->ds));
248: PetscCall(EPSSetDSType(eps));
249: PetscCall(DSSetFromOptions(eps->ds));
250: }
251: if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
252: PetscCall(EPSSetDefaultST(eps));
253: PetscCall(STSetFromOptions(eps->st));
254: PetscFunctionReturn(PETSC_SUCCESS);
255: }
257: /*@
258: EPSGetTolerances - Gets the tolerance and maximum iteration count used
259: by the EPS convergence tests.
261: Not Collective
263: Input Parameter:
264: . eps - the eigensolver context
266: Output Parameters:
267: + tol - the convergence tolerance
268: - maxits - maximum number of iterations
270: Notes:
271: The user can specify NULL for any parameter that is not needed.
273: Level: intermediate
275: .seealso: `EPSSetTolerances()`
276: @*/
277: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
278: {
279: PetscFunctionBegin;
281: if (tol) *tol = eps->tol;
282: if (maxits) *maxits = eps->max_it;
283: PetscFunctionReturn(PETSC_SUCCESS);
284: }
286: /*@
287: EPSSetTolerances - Sets the tolerance and maximum iteration count used
288: by the EPS convergence tests.
290: Logically Collective
292: Input Parameters:
293: + eps - the eigensolver context
294: . tol - the convergence tolerance
295: - maxits - maximum number of iterations to use
297: Options Database Keys:
298: + -eps_tol <tol> - Sets the convergence tolerance
299: - -eps_max_it <maxits> - Sets the maximum number of iterations allowed
301: Notes:
302: Use PETSC_CURRENT to retain the current value of any of the parameters.
303: Use PETSC_DETERMINE for either argument to assign a default value computed
304: internally (may be different in each solver).
305: For maxits use PETSC_UMLIMITED to indicate there is no upper bound on this value.
307: Level: intermediate
309: .seealso: `EPSGetTolerances()`
310: @*/
311: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
312: {
313: PetscFunctionBegin;
317: if (tol == (PetscReal)PETSC_DETERMINE) {
318: eps->tol = PETSC_DETERMINE;
319: eps->state = EPS_STATE_INITIAL;
320: } else if (tol != (PetscReal)PETSC_CURRENT) {
321: PetscCheck(tol>0.0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
322: eps->tol = tol;
323: }
324: if (maxits == PETSC_DETERMINE) {
325: eps->max_it = PETSC_DETERMINE;
326: eps->state = EPS_STATE_INITIAL;
327: } else if (maxits == PETSC_UNLIMITED) {
328: eps->max_it = PETSC_INT_MAX;
329: } else if (maxits != PETSC_CURRENT) {
330: PetscCheck(maxits>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
331: eps->max_it = maxits;
332: }
333: PetscFunctionReturn(PETSC_SUCCESS);
334: }
336: /*@
337: EPSGetDimensions - Gets the number of eigenvalues to compute
338: and the dimension of the subspace.
340: Not Collective
342: Input Parameter:
343: . eps - the eigensolver context
345: Output Parameters:
346: + nev - number of eigenvalues to compute
347: . ncv - the maximum dimension of the subspace to be used by the solver
348: - mpd - the maximum dimension allowed for the projected problem
350: Level: intermediate
352: .seealso: `EPSSetDimensions()`
353: @*/
354: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
355: {
356: PetscFunctionBegin;
358: if (nev) *nev = eps->nev? eps->nev: 1;
359: if (ncv) *ncv = eps->ncv;
360: if (mpd) *mpd = eps->mpd;
361: PetscFunctionReturn(PETSC_SUCCESS);
362: }
364: /*@
365: EPSSetDimensions - Sets the number of eigenvalues to compute
366: and the dimension of the subspace.
368: Logically Collective
370: Input Parameters:
371: + eps - the eigensolver context
372: . nev - number of eigenvalues to compute
373: . ncv - the maximum dimension of the subspace to be used by the solver
374: - mpd - the maximum dimension allowed for the projected problem
376: Options Database Keys:
377: + -eps_nev <nev> - Sets the number of eigenvalues
378: . -eps_ncv <ncv> - Sets the dimension of the subspace
379: - -eps_mpd <mpd> - Sets the maximum projected dimension
381: Notes:
382: Use PETSC_DETERMINE for ncv and mpd to assign a reasonably good value, which is
383: dependent on the solution method. For any of the arguments, use PETSC_CURRENT
384: to preserve the current value.
386: The parameters ncv and mpd are intimately related, so that the user is advised
387: to set one of them at most. Normal usage is that
388: (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
389: (b) in cases where nev is large, the user sets mpd.
391: The value of ncv should always be between nev and (nev+mpd), typically
392: ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
393: a smaller value should be used.
395: When computing all eigenvalues in an interval, see EPSSetInterval(), these
396: parameters lose relevance, and tuning must be done with
397: EPSKrylovSchurSetDimensions().
399: Level: intermediate
401: .seealso: `EPSGetDimensions()`, `EPSSetInterval()`, `EPSKrylovSchurSetDimensions()`
402: @*/
403: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
404: {
405: PetscFunctionBegin;
410: if (nev != PETSC_CURRENT) {
411: PetscCheck(nev>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
412: eps->nev = nev;
413: }
414: if (ncv == PETSC_DETERMINE) {
415: eps->ncv = PETSC_DETERMINE;
416: } else if (ncv != PETSC_CURRENT) {
417: PetscCheck(ncv>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
418: eps->ncv = ncv;
419: }
420: if (mpd == PETSC_DETERMINE) {
421: eps->mpd = PETSC_DETERMINE;
422: } else if (mpd != PETSC_CURRENT) {
423: PetscCheck(mpd>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
424: eps->mpd = mpd;
425: }
426: eps->state = EPS_STATE_INITIAL;
427: PetscFunctionReturn(PETSC_SUCCESS);
428: }
430: /*@
431: EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
432: to be sought.
434: Logically Collective
436: Input Parameters:
437: + eps - eigensolver context obtained from EPSCreate()
438: - which - the portion of the spectrum to be sought
440: Options Database Keys:
441: + -eps_largest_magnitude - Sets largest eigenvalues in magnitude
442: . -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
443: . -eps_largest_real - Sets largest real parts
444: . -eps_smallest_real - Sets smallest real parts
445: . -eps_largest_imaginary - Sets largest imaginary parts
446: . -eps_smallest_imaginary - Sets smallest imaginary parts
447: . -eps_target_magnitude - Sets eigenvalues closest to target
448: . -eps_target_real - Sets real parts closest to target
449: . -eps_target_imaginary - Sets imaginary parts closest to target
450: - -eps_all - Sets all eigenvalues in an interval or region
452: Notes:
453: The parameter 'which' can have one of these values
455: + EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
456: . EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
457: . EPS_LARGEST_REAL - largest real parts
458: . EPS_SMALLEST_REAL - smallest real parts
459: . EPS_LARGEST_IMAGINARY - largest imaginary parts
460: . EPS_SMALLEST_IMAGINARY - smallest imaginary parts
461: . EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
462: . EPS_TARGET_REAL - eigenvalues with real part closest to target
463: . EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
464: . EPS_ALL - all eigenvalues contained in a given interval or region
465: - EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()
467: Not all eigensolvers implemented in EPS account for all the possible values
468: stated above. Also, some values make sense only for certain types of
469: problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
470: and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
471: for eigenvalue selection.
473: The target is a scalar value provided with EPSSetTarget().
475: The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
476: SLEPc have been built with complex scalars.
478: EPS_ALL is intended for use in combination with an interval (see
479: EPSSetInterval()), when all eigenvalues within the interval are requested,
480: or in the context of the CISS solver for computing all eigenvalues in a region.
481: In those cases, the number of eigenvalues is unknown, so the nev parameter
482: has a different sense, see EPSSetDimensions().
484: Level: intermediate
486: .seealso: `EPSGetWhichEigenpairs()`, `EPSSetTarget()`, `EPSSetInterval()`,
487: `EPSSetDimensions()`, `EPSSetEigenvalueComparison()`, `EPSWhich`
488: @*/
489: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
490: {
491: PetscFunctionBegin;
494: switch (which) {
495: case EPS_LARGEST_MAGNITUDE:
496: case EPS_SMALLEST_MAGNITUDE:
497: case EPS_LARGEST_REAL:
498: case EPS_SMALLEST_REAL:
499: case EPS_LARGEST_IMAGINARY:
500: case EPS_SMALLEST_IMAGINARY:
501: case EPS_TARGET_MAGNITUDE:
502: case EPS_TARGET_REAL:
503: #if defined(PETSC_USE_COMPLEX)
504: case EPS_TARGET_IMAGINARY:
505: #endif
506: case EPS_ALL:
507: case EPS_WHICH_USER:
508: if (eps->which != which) {
509: eps->state = EPS_STATE_INITIAL;
510: eps->which = which;
511: }
512: break;
513: #if !defined(PETSC_USE_COMPLEX)
514: case EPS_TARGET_IMAGINARY:
515: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"EPS_TARGET_IMAGINARY can be used only with complex scalars");
516: #endif
517: default:
518: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
519: }
520: PetscFunctionReturn(PETSC_SUCCESS);
521: }
523: /*@
524: EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
525: sought.
527: Not Collective
529: Input Parameter:
530: . eps - eigensolver context obtained from EPSCreate()
532: Output Parameter:
533: . which - the portion of the spectrum to be sought
535: Notes:
536: See EPSSetWhichEigenpairs() for possible values of 'which'.
538: Level: intermediate
540: .seealso: `EPSSetWhichEigenpairs()`, `EPSWhich`
541: @*/
542: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
543: {
544: PetscFunctionBegin;
546: PetscAssertPointer(which,2);
547: *which = eps->which;
548: PetscFunctionReturn(PETSC_SUCCESS);
549: }
551: /*@
552: EPSSetThreshold - Sets the threshold used in the threshold stopping test.
554: Logically Collective
556: Input Parameters:
557: + eps - the eigenvalue solver context
558: . thres - the threshold value
559: - rel - whether the threshold is relative or not
561: Options Database Keys:
562: + -eps_threshold_absolute <thres> - Sets an absolute threshold
563: - -eps_threshold_relative <thres> - Sets a relative threshold
565: Notes:
566: This function internally calls EPSSetStoppingTest() to set a special stopping
567: test based on the threshold, where eigenvalues are computed in sequence until
568: one of the computed eigenvalues is below the threshold (in magnitude). This is
569: the interpretation in case of searching for largest eigenvalues in magnitude,
570: see EPSSetWhichEigenpairs().
572: If the solver is configured to compute smallest magnitude eigenvalues, then the
573: threshold must be interpreted in the opposite direction, i.e., the computation
574: will stop when one of the computed values is above the threshold (in magnitude).
576: The threshold can also be used when computing largest/smallest real eigenvalues
577: (i.e, rightmost or leftmost), in which case the threshold is allowed to be
578: negative. The solver will stop when one of the computed eigenvalues is above
579: or below the threshold (considering the real part of the eigenvalue). This mode
580: is allowed only in problem types whose eigenvalues are always real (e.g., HEP).
582: In the case of largest magnitude eigenvalues, the threshold can be made relative
583: with respect to the dominant eigenvalue. Otherwise, the argument rel should be
584: PETSC_FALSE.
586: An additional use case is with target magnitude selection of eigenvalues (e.g.,
587: with shift-and-invert), but this must be used with caution to avoid unexpected
588: behaviour. With an absolute threshold, the solver will assume that leftmost
589: eigenvalues are being computed (e.g., with target=0 for a problem with real
590: positive eigenvalues). In case of a relative threshold, a value of threshold<1
591: implies that the wanted eigenvalues are the largest ones, and otherwise the
592: solver assumes that smallest eigenvalues are being computed.
594: The test against the threshold is done for converged eigenvalues, which
595: implies that the final number of converged eigenvalues will be at least
596: one more than the actual number of values below/above the threshold.
598: Since the number of computed eigenvalues is not known a priori, the solver
599: will need to reallocate the basis of vectors internally, to have enough room
600: to accommodate all the eigenvectors. Hence, this option must be used with
601: caution to avoid out-of-memory problems. The recommendation is to set the value
602: of ncv to be larger than the estimated number of eigenvalues, to minimize the
603: number of reallocations.
605: If a number of wanted eigenvalues has been set with EPSSetDimensions()
606: it is also taken into account and the solver will stop when one of the two
607: conditions (threshold or number of converged values) is met.
609: Use EPSSetStoppingTest() to return to the usual computation of a fixed number
610: of eigenvalues.
612: Level: advanced
614: .seealso: `EPSGetThreshold()`, `EPSSetStoppingTest()`, `EPSSetDimensions()`, `EPSSetWhichEigenpairs()`, `EPSSetProblemType()`
615: @*/
616: PetscErrorCode EPSSetThreshold(EPS eps,PetscReal thres,PetscBool rel)
617: {
618: PetscFunctionBegin;
622: if (eps->thres != thres || eps->threlative != rel) {
623: eps->thres = thres;
624: eps->threlative = rel;
625: eps->state = EPS_STATE_INITIAL;
626: PetscCall(EPSSetStoppingTest(eps,EPS_STOP_THRESHOLD));
627: }
628: PetscFunctionReturn(PETSC_SUCCESS);
629: }
631: /*@
632: EPSGetThreshold - Gets the threshold used by the threshold stopping test.
634: Not Collective
636: Input Parameter:
637: . eps - the eigenvalue solver context
639: Output Parameters:
640: + thres - the threshold
641: - rel - whether the threshold is relative or not
643: Level: advanced
645: .seealso: `EPSSetThreshold()`
646: @*/
647: PetscErrorCode EPSGetThreshold(EPS eps,PetscReal *thres,PetscBool *rel)
648: {
649: PetscFunctionBegin;
651: if (thres) *thres = eps->thres;
652: if (rel) *rel = eps->threlative;
653: PetscFunctionReturn(PETSC_SUCCESS);
654: }
656: /*@C
657: EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
658: when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.
660: Logically Collective
662: Input Parameters:
663: + eps - eigensolver context obtained from EPSCreate()
664: . func - the comparison function, see EPSEigenvalueComparisonFn for the calling sequence
665: - ctx - a context pointer (the last parameter to the comparison function)
667: Note:
668: The returning parameter 'res' can be
669: + negative - if the 1st eigenvalue is preferred to the 2st one
670: . zero - if both eigenvalues are equally preferred
671: - positive - if the 2st eigenvalue is preferred to the 1st one
673: Level: advanced
675: .seealso: `EPSSetWhichEigenpairs()`, `EPSWhich`
676: @*/
677: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,SlepcEigenvalueComparisonFn *func,void *ctx)
678: {
679: PetscFunctionBegin;
681: eps->sc->comparison = func;
682: eps->sc->comparisonctx = ctx;
683: eps->which = EPS_WHICH_USER;
684: PetscFunctionReturn(PETSC_SUCCESS);
685: }
687: /*@C
688: EPSSetArbitrarySelection - Specifies a function intended to look for
689: eigenvalues according to an arbitrary selection criterion. This criterion
690: can be based on a computation involving the current eigenvector approximation.
692: Logically Collective
694: Input Parameters:
695: + eps - eigensolver context obtained from EPSCreate()
696: . func - the arbitrary selection function, see SlepcArbitrarySelectionFn for a calling sequence
697: - ctx - a context pointer (the last parameter to the arbitrary selection function)
699: Notes:
700: This provides a mechanism to select eigenpairs by evaluating a user-defined
701: function. When a function has been provided, the default selection based on
702: sorting the eigenvalues is replaced by the sorting of the results of this
703: function (with the same sorting criterion given in EPSSetWhichEigenpairs()).
705: For instance, suppose you want to compute those eigenvectors that maximize
706: a certain computable expression. Then implement the computation using
707: the arguments xr and xi, and return the result in rr. Then set the standard
708: sorting by magnitude so that the eigenpair with largest value of rr is
709: selected.
711: This evaluation function is collective, that is, all processes call it and
712: it can use collective operations; furthermore, the computed result must
713: be the same in all processes.
715: The result of func is expressed as a complex number so that it is possible to
716: use the standard eigenvalue sorting functions, but normally only rr is used.
717: Set ri to zero unless it is meaningful in your application.
719: Level: advanced
721: .seealso: `EPSSetWhichEigenpairs()`
722: @*/
723: PetscErrorCode EPSSetArbitrarySelection(EPS eps,SlepcArbitrarySelectionFn *func,void *ctx)
724: {
725: PetscFunctionBegin;
727: eps->arbitrary = func;
728: eps->arbitraryctx = ctx;
729: eps->state = EPS_STATE_INITIAL;
730: PetscFunctionReturn(PETSC_SUCCESS);
731: }
733: /*@C
734: EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
735: used in the convergence test.
737: Logically Collective
739: Input Parameters:
740: + eps - eigensolver context obtained from EPSCreate()
741: . func - convergence test function, see EPSConvergenceTestFn for the calling sequence
742: . ctx - context for private data for the convergence routine (may be NULL)
743: - destroy - a routine for destroying the context (may be NULL), see PetscCtxDestroyFn for the calling sequence
745: Note:
746: If the error estimate returned by the convergence test function is less than
747: the tolerance, then the eigenvalue is accepted as converged.
749: Level: advanced
751: .seealso: `EPSSetConvergenceTest()`, `EPSSetTolerances()`
752: @*/
753: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,EPSConvergenceTestFn *func,void *ctx,PetscCtxDestroyFn *destroy)
754: {
755: PetscFunctionBegin;
757: if (eps->convergeddestroy) PetscCall((*eps->convergeddestroy)(&eps->convergedctx));
758: eps->convergeduser = func;
759: eps->convergeddestroy = destroy;
760: eps->convergedctx = ctx;
761: if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
762: else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
763: else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
764: else {
765: eps->conv = EPS_CONV_USER;
766: eps->converged = eps->convergeduser;
767: }
768: PetscFunctionReturn(PETSC_SUCCESS);
769: }
771: /*@
772: EPSSetConvergenceTest - Specifies how to compute the error estimate
773: used in the convergence test.
775: Logically Collective
777: Input Parameters:
778: + eps - eigensolver context obtained from EPSCreate()
779: - conv - the type of convergence test
781: Options Database Keys:
782: + -eps_conv_abs - Sets the absolute convergence test
783: . -eps_conv_rel - Sets the convergence test relative to the eigenvalue
784: . -eps_conv_norm - Sets the convergence test relative to the matrix norms
785: - -eps_conv_user - Selects the user-defined convergence test
787: Note:
788: The parameter 'conv' can have one of these values
789: + EPS_CONV_ABS - absolute error ||r||
790: . EPS_CONV_REL - error relative to the eigenvalue l, ||r||/|l|
791: . EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
792: - EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()
794: Level: intermediate
796: .seealso: `EPSGetConvergenceTest()`, `EPSSetConvergenceTestFunction()`, `EPSSetStoppingTest()`, `EPSConv`
797: @*/
798: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
799: {
800: PetscFunctionBegin;
803: switch (conv) {
804: case EPS_CONV_ABS: eps->converged = EPSConvergedAbsolute; break;
805: case EPS_CONV_REL: eps->converged = EPSConvergedRelative; break;
806: case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
807: case EPS_CONV_USER:
808: PetscCheck(eps->convergeduser,PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetConvergenceTestFunction() first");
809: eps->converged = eps->convergeduser;
810: break;
811: default:
812: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
813: }
814: eps->conv = conv;
815: PetscFunctionReturn(PETSC_SUCCESS);
816: }
818: /*@
819: EPSGetConvergenceTest - Gets the method used to compute the error estimate
820: used in the convergence test.
822: Not Collective
824: Input Parameters:
825: . eps - eigensolver context obtained from EPSCreate()
827: Output Parameters:
828: . conv - the type of convergence test
830: Level: intermediate
832: .seealso: `EPSSetConvergenceTest()`, `EPSConv`
833: @*/
834: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
835: {
836: PetscFunctionBegin;
838: PetscAssertPointer(conv,2);
839: *conv = eps->conv;
840: PetscFunctionReturn(PETSC_SUCCESS);
841: }
843: /*@C
844: EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
845: iteration of the eigensolver.
847: Logically Collective
849: Input Parameters:
850: + eps - eigensolver context obtained from EPSCreate()
851: . func - stopping test function, see EPSStoppingTestFn for the calling sequence
852: . ctx - context for private data for the stopping routine (may be NULL)
853: - destroy - a routine for destroying the context (may be NULL), see PetscCtxDestroyFn for the calling sequence
855: Note:
856: Normal usage is to first call the default routine EPSStoppingBasic() and then
857: set reason to EPS_CONVERGED_USER if some user-defined conditions have been
858: met. To let the eigensolver continue iterating, the result must be left as
859: EPS_CONVERGED_ITERATING.
861: Level: advanced
863: .seealso: `EPSSetStoppingTest()`, `EPSStoppingBasic()`
864: @*/
865: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,EPSStoppingTestFn *func,void *ctx,PetscCtxDestroyFn *destroy)
866: {
867: PetscFunctionBegin;
869: if (eps->stoppingdestroy) PetscCall((*eps->stoppingdestroy)(&eps->stoppingctx));
870: eps->stoppinguser = func;
871: eps->stoppingdestroy = destroy;
872: eps->stoppingctx = ctx;
873: if (func == EPSStoppingBasic) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_BASIC));
874: else if (func == EPSStoppingThreshold) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_THRESHOLD));
875: else {
876: eps->stop = EPS_STOP_USER;
877: eps->stopping = eps->stoppinguser;
878: }
879: PetscFunctionReturn(PETSC_SUCCESS);
880: }
882: /*@
883: EPSSetStoppingTest - Specifies how to decide the termination of the outer
884: loop of the eigensolver.
886: Logically Collective
888: Input Parameters:
889: + eps - eigensolver context obtained from EPSCreate()
890: - stop - the type of stopping test
892: Options Database Keys:
893: + -eps_stop_basic - Sets the default stopping test
894: . -eps_stop_threshold - Sets the threshold stopping test
895: - -eps_stop_user - Selects the user-defined stopping test
897: Note:
898: The parameter 'stop' can have one of these values
899: + EPS_STOP_BASIC - default stopping test
900: . EPS_STOP_THRESHOLD - threshold stopping test)
901: - EPS_STOP_USER - function set by EPSSetStoppingTestFunction()
903: Level: advanced
905: .seealso: `EPSGetStoppingTest()`, `EPSSetStoppingTestFunction()`, `EPSSetConvergenceTest()`, `EPSStop`
906: @*/
907: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
908: {
909: PetscFunctionBegin;
912: switch (stop) {
913: case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
914: case EPS_STOP_THRESHOLD: eps->stopping = EPSStoppingThreshold; break;
915: case EPS_STOP_USER:
916: PetscCheck(eps->stoppinguser,PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetStoppingTestFunction() first");
917: eps->stopping = eps->stoppinguser;
918: break;
919: default:
920: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
921: }
922: eps->stop = stop;
923: PetscFunctionReturn(PETSC_SUCCESS);
924: }
926: /*@
927: EPSGetStoppingTest - Gets the method used to decide the termination of the outer
928: loop of the eigensolver.
930: Not Collective
932: Input Parameters:
933: . eps - eigensolver context obtained from EPSCreate()
935: Output Parameters:
936: . stop - the type of stopping test
938: Level: advanced
940: .seealso: `EPSSetStoppingTest()`, `EPSStop`
941: @*/
942: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
943: {
944: PetscFunctionBegin;
946: PetscAssertPointer(stop,2);
947: *stop = eps->stop;
948: PetscFunctionReturn(PETSC_SUCCESS);
949: }
951: /*@
952: EPSSetProblemType - Specifies the type of the eigenvalue problem.
954: Logically Collective
956: Input Parameters:
957: + eps - the eigensolver context
958: - type - a known type of eigenvalue problem
960: Options Database Keys:
961: + -eps_hermitian - Hermitian eigenvalue problem
962: . -eps_gen_hermitian - generalized Hermitian eigenvalue problem
963: . -eps_non_hermitian - non-Hermitian eigenvalue problem
964: . -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
965: . -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
966: with positive semi-definite B
967: . -eps_gen_indefinite - generalized Hermitian-indefinite eigenvalue problem
968: . -eps_bse - structured Bethe-Salpeter eigenvalue problem
969: - -eps_hamiltonian - structured Hamiltonian eigenvalue problem
971: Notes:
972: This function must be used to instruct SLEPc to exploit symmetry or other
973: kind of structure. If no
974: problem type is specified, by default a non-Hermitian problem is assumed
975: (either standard or generalized). If the user knows that the problem is
976: Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
977: B positive definite) then it is recommended to set the problem type so
978: that eigensolver can exploit these properties.
980: If the user does not call this function, the solver will use a reasonable
981: guess.
983: For structured problem types such as EPS_BSE, the matrices passed in via
984: EPSSetOperators() must have been created with the corresponding helper
985: function, i.e., MatCreateBSE().
987: Level: intermediate
989: .seealso: `EPSSetOperators()`, `EPSSetType()`, `EPSGetProblemType()`, `EPSProblemType`
990: @*/
991: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
992: {
993: PetscFunctionBegin;
996: if (type == eps->problem_type) PetscFunctionReturn(PETSC_SUCCESS);
997: switch (type) {
998: case EPS_HEP:
999: eps->isgeneralized = PETSC_FALSE;
1000: eps->ishermitian = PETSC_TRUE;
1001: eps->ispositive = PETSC_FALSE;
1002: eps->isstructured = PETSC_FALSE;
1003: break;
1004: case EPS_NHEP:
1005: eps->isgeneralized = PETSC_FALSE;
1006: eps->ishermitian = PETSC_FALSE;
1007: eps->ispositive = PETSC_FALSE;
1008: eps->isstructured = PETSC_FALSE;
1009: break;
1010: case EPS_GHEP:
1011: eps->isgeneralized = PETSC_TRUE;
1012: eps->ishermitian = PETSC_TRUE;
1013: eps->ispositive = PETSC_TRUE;
1014: eps->isstructured = PETSC_FALSE;
1015: break;
1016: case EPS_GNHEP:
1017: eps->isgeneralized = PETSC_TRUE;
1018: eps->ishermitian = PETSC_FALSE;
1019: eps->ispositive = PETSC_FALSE;
1020: eps->isstructured = PETSC_FALSE;
1021: break;
1022: case EPS_PGNHEP:
1023: eps->isgeneralized = PETSC_TRUE;
1024: eps->ishermitian = PETSC_FALSE;
1025: eps->ispositive = PETSC_TRUE;
1026: eps->isstructured = PETSC_FALSE;
1027: break;
1028: case EPS_GHIEP:
1029: eps->isgeneralized = PETSC_TRUE;
1030: eps->ishermitian = PETSC_TRUE;
1031: eps->ispositive = PETSC_FALSE;
1032: eps->isstructured = PETSC_FALSE;
1033: break;
1034: case EPS_BSE:
1035: eps->isgeneralized = PETSC_FALSE;
1036: eps->ishermitian = PETSC_FALSE;
1037: eps->ispositive = PETSC_FALSE;
1038: eps->isstructured = PETSC_TRUE;
1039: break;
1040: case EPS_HAMILT:
1041: eps->isgeneralized = PETSC_FALSE;
1042: eps->ishermitian = PETSC_FALSE;
1043: eps->ispositive = PETSC_FALSE;
1044: eps->isstructured = PETSC_TRUE;
1045: break;
1046: default:
1047: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
1048: }
1049: eps->problem_type = type;
1050: eps->state = EPS_STATE_INITIAL;
1051: PetscFunctionReturn(PETSC_SUCCESS);
1052: }
1054: /*@
1055: EPSGetProblemType - Gets the problem type from the EPS object.
1057: Not Collective
1059: Input Parameter:
1060: . eps - the eigensolver context
1062: Output Parameter:
1063: . type - the problem type
1065: Level: intermediate
1067: .seealso: `EPSSetProblemType()`, `EPSProblemType`
1068: @*/
1069: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
1070: {
1071: PetscFunctionBegin;
1073: PetscAssertPointer(type,2);
1074: *type = eps->problem_type;
1075: PetscFunctionReturn(PETSC_SUCCESS);
1076: }
1078: /*@
1079: EPSSetExtraction - Specifies the type of extraction technique to be employed
1080: by the eigensolver.
1082: Logically Collective
1084: Input Parameters:
1085: + eps - the eigensolver context
1086: - extr - a known type of extraction
1088: Options Database Keys:
1089: + -eps_ritz - Rayleigh-Ritz extraction
1090: . -eps_harmonic - harmonic Ritz extraction
1091: . -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
1092: . -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
1093: . -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
1094: (without target)
1095: . -eps_refined - refined Ritz extraction
1096: - -eps_refined_harmonic - refined harmonic Ritz extraction
1098: Notes:
1099: Not all eigensolvers support all types of extraction. See the SLEPc
1100: Users Manual for details.
1102: By default, a standard Rayleigh-Ritz extraction is used. Other extractions
1103: may be useful when computing interior eigenvalues.
1105: Harmonic-type extractions are used in combination with a 'target'.
1107: Level: advanced
1109: .seealso: `EPSSetTarget()`, `EPSGetExtraction()`, `EPSExtraction`
1110: @*/
1111: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
1112: {
1113: PetscFunctionBegin;
1116: if (eps->extraction != extr) {
1117: eps->state = EPS_STATE_INITIAL;
1118: eps->extraction = extr;
1119: }
1120: PetscFunctionReturn(PETSC_SUCCESS);
1121: }
1123: /*@
1124: EPSGetExtraction - Gets the extraction type used by the EPS object.
1126: Not Collective
1128: Input Parameter:
1129: . eps - the eigensolver context
1131: Output Parameter:
1132: . extr - name of extraction type
1134: Level: advanced
1136: .seealso: `EPSSetExtraction()`, `EPSExtraction`
1137: @*/
1138: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1139: {
1140: PetscFunctionBegin;
1142: PetscAssertPointer(extr,2);
1143: *extr = eps->extraction;
1144: PetscFunctionReturn(PETSC_SUCCESS);
1145: }
1147: /*@
1148: EPSSetBalance - Specifies the balancing technique to be employed by the
1149: eigensolver, and some parameters associated to it.
1151: Logically Collective
1153: Input Parameters:
1154: + eps - the eigensolver context
1155: . bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1156: EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1157: . its - number of iterations of the balancing algorithm
1158: - cutoff - cutoff value
1160: Options Database Keys:
1161: + -eps_balance <method> - the balancing method, where <method> is one of
1162: 'none', 'oneside', 'twoside', or 'user'
1163: . -eps_balance_its <its> - number of iterations
1164: - -eps_balance_cutoff <cutoff> - cutoff value
1166: Notes:
1167: When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1168: where D is an appropriate diagonal matrix. This improves the accuracy of
1169: the computed results in some cases. See the SLEPc Users Manual for details.
1171: Balancing makes sense only for non-Hermitian problems when the required
1172: precision is high (i.e. a small tolerance such as 1e-15).
1174: By default, balancing is disabled. The two-sided method is much more
1175: effective than the one-sided counterpart, but it requires the system
1176: matrices to have the MatMultTranspose operation defined.
1178: The parameter 'its' is the number of iterations performed by the method. The
1179: cutoff value is used only in the two-side variant. Use PETSC_DETERMINE to assign
1180: a reasonably good value, or PETSC_CURRENT to leave the value unchanged.
1182: User-defined balancing is allowed provided that the corresponding matrix
1183: is set via STSetBalanceMatrix.
1185: Level: intermediate
1187: .seealso: `EPSGetBalance()`, `EPSBalance`, `STSetBalanceMatrix()`
1188: @*/
1189: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1190: {
1191: PetscFunctionBegin;
1196: switch (bal) {
1197: case EPS_BALANCE_NONE:
1198: case EPS_BALANCE_ONESIDE:
1199: case EPS_BALANCE_TWOSIDE:
1200: case EPS_BALANCE_USER:
1201: if (eps->balance != bal) {
1202: eps->state = EPS_STATE_INITIAL;
1203: eps->balance = bal;
1204: }
1205: break;
1206: default:
1207: SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1208: }
1209: if (its==PETSC_DETERMINE) eps->balance_its = 5;
1210: else if (its!=PETSC_CURRENT) {
1211: PetscCheck(its>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1212: eps->balance_its = its;
1213: }
1214: if (cutoff==(PetscReal)PETSC_DETERMINE) eps->balance_cutoff = 1e-8;
1215: else if (cutoff!=(PetscReal)PETSC_CURRENT) {
1216: PetscCheck(cutoff>0.0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1217: eps->balance_cutoff = cutoff;
1218: }
1219: PetscFunctionReturn(PETSC_SUCCESS);
1220: }
1222: /*@
1223: EPSGetBalance - Gets the balancing type used by the EPS object, and the
1224: associated parameters.
1226: Not Collective
1228: Input Parameter:
1229: . eps - the eigensolver context
1231: Output Parameters:
1232: + bal - the balancing method
1233: . its - number of iterations of the balancing algorithm
1234: - cutoff - cutoff value
1236: Level: intermediate
1238: Note:
1239: The user can specify NULL for any parameter that is not needed.
1241: .seealso: `EPSSetBalance()`, `EPSBalance`
1242: @*/
1243: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1244: {
1245: PetscFunctionBegin;
1247: if (bal) *bal = eps->balance;
1248: if (its) *its = eps->balance_its;
1249: if (cutoff) *cutoff = eps->balance_cutoff;
1250: PetscFunctionReturn(PETSC_SUCCESS);
1251: }
1253: /*@
1254: EPSSetTwoSided - Sets the solver to use a two-sided variant so that left
1255: eigenvectors are also computed.
1257: Logically Collective
1259: Input Parameters:
1260: + eps - the eigensolver context
1261: - twosided - whether the two-sided variant is to be used or not
1263: Options Database Keys:
1264: . -eps_two_sided <boolean> - Sets/resets the twosided flag
1266: Notes:
1267: If the user sets twosided=PETSC_TRUE then the solver uses a variant of
1268: the algorithm that computes both right and left eigenvectors. This is
1269: usually much more costly. This option is not available in all solvers.
1271: When using two-sided solvers, the problem matrices must have both the
1272: MatMult and MatMultTranspose operations defined.
1274: Level: advanced
1276: .seealso: `EPSGetTwoSided()`, `EPSGetLeftEigenvector()`
1277: @*/
1278: PetscErrorCode EPSSetTwoSided(EPS eps,PetscBool twosided)
1279: {
1280: PetscFunctionBegin;
1283: if (twosided!=eps->twosided) {
1284: eps->twosided = twosided;
1285: eps->state = EPS_STATE_INITIAL;
1286: }
1287: PetscFunctionReturn(PETSC_SUCCESS);
1288: }
1290: /*@
1291: EPSGetTwoSided - Returns the flag indicating whether a two-sided variant
1292: of the algorithm is being used or not.
1294: Not Collective
1296: Input Parameter:
1297: . eps - the eigensolver context
1299: Output Parameter:
1300: . twosided - the returned flag
1302: Level: advanced
1304: .seealso: `EPSSetTwoSided()`
1305: @*/
1306: PetscErrorCode EPSGetTwoSided(EPS eps,PetscBool *twosided)
1307: {
1308: PetscFunctionBegin;
1310: PetscAssertPointer(twosided,2);
1311: *twosided = eps->twosided;
1312: PetscFunctionReturn(PETSC_SUCCESS);
1313: }
1315: /*@
1316: EPSSetTrueResidual - Specifies if the solver must compute the true residual
1317: explicitly or not.
1319: Logically Collective
1321: Input Parameters:
1322: + eps - the eigensolver context
1323: - trueres - whether true residuals are required or not
1325: Options Database Keys:
1326: . -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'
1328: Notes:
1329: If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1330: the true residual for each eigenpair approximation, and uses it for
1331: convergence testing. Computing the residual is usually an expensive
1332: operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1333: by using a cheap estimate of the residual norm, but this may sometimes
1334: give inaccurate results (especially if a spectral transform is being
1335: used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1336: do rely on computing the true residual, so this option is irrelevant for them.
1338: Level: advanced
1340: .seealso: `EPSGetTrueResidual()`
1341: @*/
1342: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1343: {
1344: PetscFunctionBegin;
1347: eps->trueres = trueres;
1348: PetscFunctionReturn(PETSC_SUCCESS);
1349: }
1351: /*@
1352: EPSGetTrueResidual - Returns the flag indicating whether true
1353: residuals must be computed explicitly or not.
1355: Not Collective
1357: Input Parameter:
1358: . eps - the eigensolver context
1360: Output Parameter:
1361: . trueres - the returned flag
1363: Level: advanced
1365: .seealso: `EPSSetTrueResidual()`
1366: @*/
1367: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1368: {
1369: PetscFunctionBegin;
1371: PetscAssertPointer(trueres,2);
1372: *trueres = eps->trueres;
1373: PetscFunctionReturn(PETSC_SUCCESS);
1374: }
1376: /*@
1377: EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1378: approximate eigenpairs or not.
1380: Logically Collective
1382: Input Parameters:
1383: + eps - the eigensolver context
1384: - trackall - whether to compute all residuals or not
1386: Notes:
1387: If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1388: the residual norm for each eigenpair approximation. Computing the residual is
1389: usually an expensive operation and solvers commonly compute only the residual
1390: associated to the first unconverged eigenpair.
1392: The option '-eps_monitor_all' automatically activates this option.
1394: Level: developer
1396: .seealso: `EPSGetTrackAll()`
1397: @*/
1398: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1399: {
1400: PetscFunctionBegin;
1403: eps->trackall = trackall;
1404: PetscFunctionReturn(PETSC_SUCCESS);
1405: }
1407: /*@
1408: EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1409: be computed or not.
1411: Not Collective
1413: Input Parameter:
1414: . eps - the eigensolver context
1416: Output Parameter:
1417: . trackall - the returned flag
1419: Level: developer
1421: .seealso: `EPSSetTrackAll()`
1422: @*/
1423: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1424: {
1425: PetscFunctionBegin;
1427: PetscAssertPointer(trackall,2);
1428: *trackall = eps->trackall;
1429: PetscFunctionReturn(PETSC_SUCCESS);
1430: }
1432: /*@
1433: EPSSetPurify - Deactivate eigenvector purification (which is activated by default).
1435: Logically Collective
1437: Input Parameters:
1438: + eps - the eigensolver context
1439: - purify - whether purification is required or not
1441: Options Database Keys:
1442: . -eps_purify <boolean> - Sets/resets the boolean flag 'purify'
1444: Notes:
1445: By default, eigenvectors of generalized symmetric eigenproblems are purified
1446: in order to purge directions in the nullspace of matrix B. If the user knows
1447: that B is non-singular, then purification can be safely deactivated and some
1448: computational cost is avoided (this is particularly important in interval computations).
1450: Level: intermediate
1452: .seealso: `EPSGetPurify()`, `EPSSetInterval()`
1453: @*/
1454: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1455: {
1456: PetscFunctionBegin;
1459: if (purify!=eps->purify) {
1460: eps->purify = purify;
1461: eps->state = EPS_STATE_INITIAL;
1462: }
1463: PetscFunctionReturn(PETSC_SUCCESS);
1464: }
1466: /*@
1467: EPSGetPurify - Returns the flag indicating whether purification is activated
1468: or not.
1470: Not Collective
1472: Input Parameter:
1473: . eps - the eigensolver context
1475: Output Parameter:
1476: . purify - the returned flag
1478: Level: intermediate
1480: .seealso: `EPSSetPurify()`
1481: @*/
1482: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1483: {
1484: PetscFunctionBegin;
1486: PetscAssertPointer(purify,2);
1487: *purify = eps->purify;
1488: PetscFunctionReturn(PETSC_SUCCESS);
1489: }
1491: /*@
1492: EPSSetOptionsPrefix - Sets the prefix used for searching for all
1493: EPS options in the database.
1495: Logically Collective
1497: Input Parameters:
1498: + eps - the eigensolver context
1499: - prefix - the prefix string to prepend to all EPS option requests
1501: Notes:
1502: A hyphen (-) must NOT be given at the beginning of the prefix name.
1503: The first character of all runtime options is AUTOMATICALLY the
1504: hyphen.
1506: For example, to distinguish between the runtime options for two
1507: different EPS contexts, one could call
1508: .vb
1509: EPSSetOptionsPrefix(eps1,"eig1_")
1510: EPSSetOptionsPrefix(eps2,"eig2_")
1511: .ve
1513: Level: advanced
1515: .seealso: `EPSAppendOptionsPrefix()`, `EPSGetOptionsPrefix()`
1516: @*/
1517: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1518: {
1519: PetscFunctionBegin;
1521: if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
1522: PetscCall(STSetOptionsPrefix(eps->st,prefix));
1523: if (!eps->V) PetscCall(EPSGetBV(eps,&eps->V));
1524: PetscCall(BVSetOptionsPrefix(eps->V,prefix));
1525: if (!eps->ds) PetscCall(EPSGetDS(eps,&eps->ds));
1526: PetscCall(DSSetOptionsPrefix(eps->ds,prefix));
1527: if (!eps->rg) PetscCall(EPSGetRG(eps,&eps->rg));
1528: PetscCall(RGSetOptionsPrefix(eps->rg,prefix));
1529: PetscCall(PetscObjectSetOptionsPrefix((PetscObject)eps,prefix));
1530: PetscFunctionReturn(PETSC_SUCCESS);
1531: }
1533: /*@
1534: EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1535: EPS options in the database.
1537: Logically Collective
1539: Input Parameters:
1540: + eps - the eigensolver context
1541: - prefix - the prefix string to prepend to all EPS option requests
1543: Notes:
1544: A hyphen (-) must NOT be given at the beginning of the prefix name.
1545: The first character of all runtime options is AUTOMATICALLY the hyphen.
1547: Level: advanced
1549: .seealso: `EPSSetOptionsPrefix()`, `EPSGetOptionsPrefix()`
1550: @*/
1551: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1552: {
1553: PetscFunctionBegin;
1555: if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
1556: PetscCall(STAppendOptionsPrefix(eps->st,prefix));
1557: if (!eps->V) PetscCall(EPSGetBV(eps,&eps->V));
1558: PetscCall(BVAppendOptionsPrefix(eps->V,prefix));
1559: if (!eps->ds) PetscCall(EPSGetDS(eps,&eps->ds));
1560: PetscCall(DSAppendOptionsPrefix(eps->ds,prefix));
1561: if (!eps->rg) PetscCall(EPSGetRG(eps,&eps->rg));
1562: PetscCall(RGAppendOptionsPrefix(eps->rg,prefix));
1563: PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix));
1564: PetscFunctionReturn(PETSC_SUCCESS);
1565: }
1567: /*@
1568: EPSGetOptionsPrefix - Gets the prefix used for searching for all
1569: EPS options in the database.
1571: Not Collective
1573: Input Parameters:
1574: . eps - the eigensolver context
1576: Output Parameters:
1577: . prefix - pointer to the prefix string used is returned
1579: Note:
1580: On the Fortran side, the user should pass in a string 'prefix' of
1581: sufficient length to hold the prefix.
1583: Level: advanced
1585: .seealso: `EPSSetOptionsPrefix()`, `EPSAppendOptionsPrefix()`
1586: @*/
1587: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1588: {
1589: PetscFunctionBegin;
1591: PetscAssertPointer(prefix,2);
1592: PetscCall(PetscObjectGetOptionsPrefix((PetscObject)eps,prefix));
1593: PetscFunctionReturn(PETSC_SUCCESS);
1594: }