Actual source code: epsopts.c

slepc-3.18.0 2022-10-01
Report Typos and Errors
  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 on eps

 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:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->options,((PetscObject)eps)->prefix,opt,&viewer,&format,&flg);
 48:   if (!flg) return 0;

 50:   PetscViewerGetType(viewer,&vtype);
 51:   SlepcMonitorMakeKey_Internal(name,vtype,format,key);
 52:   PetscFunctionListFind(EPSMonitorList,key,&mfunc);
 54:   PetscFunctionListFind(EPSMonitorCreateList,key,&cfunc);
 55:   PetscFunctionListFind(EPSMonitorDestroyList,key,&dfunc);
 56:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
 57:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

 59:   (*cfunc)(viewer,format,ctx,&vf);
 60:   PetscObjectDereference((PetscObject)viewer);
 61:   EPSMonitorSet(eps,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
 62:   if (trackall) EPSSetTrackAll(eps,PETSC_TRUE);
 63:   return 0;
 64: }

 66: /*@
 67:    EPSSetFromOptions - Sets EPS options from the options database.
 68:    This routine must be called before EPSSetUp() if the user is to be
 69:    allowed to set the solver type.

 71:    Collective on eps

 73:    Input Parameters:
 74: .  eps - the eigensolver context

 76:    Notes:
 77:    To see all options, run your program with the -help option.

 79:    Level: beginner

 81: .seealso: EPSSetOptionsPrefix()
 82: @*/
 83: PetscErrorCode EPSSetFromOptions(EPS eps)
 84: {
 85:   char           type[256];
 86:   PetscBool      set,flg,flg1,flg2,flg3,bval;
 87:   PetscReal      r,array[2]={0,0};
 88:   PetscScalar    s;
 89:   PetscInt       i,j,k;
 90:   EPSBalance     bal;

 93:   EPSRegisterAll();
 94:   PetscObjectOptionsBegin((PetscObject)eps);
 95:     PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,sizeof(type),&flg);
 96:     if (flg) EPSSetType(eps,type);
 97:     else if (!((PetscObject)eps)->type_name) EPSSetType(eps,EPSKRYLOVSCHUR);

 99:     PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg);
100:     if (flg) EPSSetProblemType(eps,EPS_HEP);
101:     PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg);
102:     if (flg) EPSSetProblemType(eps,EPS_GHEP);
103:     PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
104:     if (flg) EPSSetProblemType(eps,EPS_NHEP);
105:     PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
106:     if (flg) EPSSetProblemType(eps,EPS_GNHEP);
107:     PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
108:     if (flg) EPSSetProblemType(eps,EPS_PGNHEP);
109:     PetscOptionsBoolGroupEnd("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
110:     if (flg) EPSSetProblemType(eps,EPS_GHIEP);

112:     PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
113:     if (flg) EPSSetExtraction(eps,EPS_RITZ);
114:     PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg);
115:     if (flg) EPSSetExtraction(eps,EPS_HARMONIC);
116:     PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg);
117:     if (flg) EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE);
118:     PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg);
119:     if (flg) EPSSetExtraction(eps,EPS_HARMONIC_RIGHT);
120:     PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg);
121:     if (flg) EPSSetExtraction(eps,EPS_HARMONIC_LARGEST);
122:     PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg);
123:     if (flg) EPSSetExtraction(eps,EPS_REFINED);
124:     PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg);
125:     if (flg) EPSSetExtraction(eps,EPS_REFINED_HARMONIC);

127:     bal = eps->balance;
128:     PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1);
129:     j = eps->balance_its;
130:     PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2);
131:     r = eps->balance_cutoff;
132:     PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3);
133:     if (flg1 || flg2 || flg3) EPSSetBalance(eps,bal,j,r);

135:     i = eps->max_it;
136:     PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
137:     r = eps->tol;
138:     PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",SlepcDefaultTol(eps->tol),&r,&flg2);
139:     if (flg1 || flg2) EPSSetTolerances(eps,r,i);

141:     PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
142:     if (flg) EPSSetConvergenceTest(eps,EPS_CONV_REL);
143:     PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
144:     if (flg) EPSSetConvergenceTest(eps,EPS_CONV_NORM);
145:     PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
146:     if (flg) EPSSetConvergenceTest(eps,EPS_CONV_ABS);
147:     PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
148:     if (flg) EPSSetConvergenceTest(eps,EPS_CONV_USER);

150:     PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg);
151:     if (flg) EPSSetStoppingTest(eps,EPS_STOP_BASIC);
152:     PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg);
153:     if (flg) EPSSetStoppingTest(eps,EPS_STOP_USER);

155:     i = eps->nev;
156:     PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
157:     j = eps->ncv;
158:     PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
159:     k = eps->mpd;
160:     PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
161:     if (flg1 || flg2 || flg3) EPSSetDimensions(eps,i,j,k);

163:     PetscOptionsBoolGroupBegin("-eps_largest_magnitude","Compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
164:     if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE);
165:     PetscOptionsBoolGroup("-eps_smallest_magnitude","Compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
166:     if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE);
167:     PetscOptionsBoolGroup("-eps_largest_real","Compute eigenvalues with largest real parts","EPSSetWhichEigenpairs",&flg);
168:     if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL);
169:     PetscOptionsBoolGroup("-eps_smallest_real","Compute eigenvalues with smallest real parts","EPSSetWhichEigenpairs",&flg);
170:     if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL);
171:     PetscOptionsBoolGroup("-eps_largest_imaginary","Compute eigenvalues with largest imaginary parts","EPSSetWhichEigenpairs",&flg);
172:     if (flg) EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY);
173:     PetscOptionsBoolGroup("-eps_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
174:     if (flg) EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY);
175:     PetscOptionsBoolGroup("-eps_target_magnitude","Compute eigenvalues closest to target","EPSSetWhichEigenpairs",&flg);
176:     if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
177:     PetscOptionsBoolGroup("-eps_target_real","Compute eigenvalues with real parts closest to target","EPSSetWhichEigenpairs",&flg);
178:     if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL);
179:     PetscOptionsBoolGroup("-eps_target_imaginary","Compute eigenvalues with imaginary parts closest to target","EPSSetWhichEigenpairs",&flg);
180:     if (flg) EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY);
181:     PetscOptionsBoolGroupEnd("-eps_all","Compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg);
182:     if (flg) EPSSetWhichEigenpairs(eps,EPS_ALL);

184:     PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
185:     if (flg) {
186:       if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
187:       EPSSetTarget(eps,s);
188:     }

190:     k = 2;
191:     PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
192:     if (flg) {
194:       EPSSetWhichEigenpairs(eps,EPS_ALL);
195:       EPSSetInterval(eps,array[0],array[1]);
196:     }

198:     PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
199:     PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&bval,&flg);
200:     if (flg) EPSSetPurify(eps,bval);
201:     PetscOptionsBool("-eps_two_sided","Use two-sided variant (to compute left eigenvectors)","EPSSetTwoSided",eps->twosided,&bval,&flg);
202:     if (flg) EPSSetTwoSided(eps,bval);

204:     /* -----------------------------------------------------------------------*/
205:     /*
206:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
207:     */
208:     PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
209:     if (set && flg) EPSMonitorCancel(eps);
210:     EPSMonitorSetFromOptions(eps,"-eps_monitor","first_approximation",NULL,PETSC_FALSE);
211:     EPSMonitorSetFromOptions(eps,"-eps_monitor_all","all_approximations",NULL,PETSC_TRUE);
212:     EPSMonitorSetFromOptions(eps,"-eps_monitor_conv","convergence_history",NULL,PETSC_FALSE);

214:     /* -----------------------------------------------------------------------*/
215:     PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
216:     PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
217:     PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
218:     PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSConvergedReasonView",NULL);
219:     PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
220:     PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
221:     PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);

223:     PetscTryTypeMethod(eps,setfromoptions,PetscOptionsObject);
224:     PetscObjectProcessOptionsHandlers((PetscObject)eps,PetscOptionsObject);
225:   PetscOptionsEnd();

227:   if (!eps->V) EPSGetBV(eps,&eps->V);
228:   BVSetFromOptions(eps->V);
229:   if (!eps->rg) EPSGetRG(eps,&eps->rg);
230:   RGSetFromOptions(eps->rg);
231:   if (eps->useds) {
232:     if (!eps->ds) EPSGetDS(eps,&eps->ds);
233:     DSSetFromOptions(eps->ds);
234:   }
235:   if (!eps->st) EPSGetST(eps,&eps->st);
236:   EPSSetDefaultST(eps);
237:   STSetFromOptions(eps->st);
238:   return 0;
239: }

241: /*@C
242:    EPSGetTolerances - Gets the tolerance and maximum iteration count used
243:    by the EPS convergence tests.

245:    Not Collective

247:    Input Parameter:
248: .  eps - the eigensolver context

250:    Output Parameters:
251: +  tol - the convergence tolerance
252: -  maxits - maximum number of iterations

254:    Notes:
255:    The user can specify NULL for any parameter that is not needed.

257:    Level: intermediate

259: .seealso: EPSSetTolerances()
260: @*/
261: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
262: {
264:   if (tol)    *tol    = eps->tol;
265:   if (maxits) *maxits = eps->max_it;
266:   return 0;
267: }

269: /*@
270:    EPSSetTolerances - Sets the tolerance and maximum iteration count used
271:    by the EPS convergence tests.

273:    Logically Collective on eps

275:    Input Parameters:
276: +  eps - the eigensolver context
277: .  tol - the convergence tolerance
278: -  maxits - maximum number of iterations to use

280:    Options Database Keys:
281: +  -eps_tol <tol> - Sets the convergence tolerance
282: -  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

284:    Notes:
285:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

287:    Level: intermediate

289: .seealso: EPSGetTolerances()
290: @*/
291: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
292: {
296:   if (tol == PETSC_DEFAULT) {
297:     eps->tol   = PETSC_DEFAULT;
298:     eps->state = EPS_STATE_INITIAL;
299:   } else {
301:     eps->tol = tol;
302:   }
303:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
304:     eps->max_it = PETSC_DEFAULT;
305:     eps->state  = EPS_STATE_INITIAL;
306:   } else {
308:     eps->max_it = maxits;
309:   }
310:   return 0;
311: }

313: /*@C
314:    EPSGetDimensions - Gets the number of eigenvalues to compute
315:    and the dimension of the subspace.

317:    Not Collective

319:    Input Parameter:
320: .  eps - the eigensolver context

322:    Output Parameters:
323: +  nev - number of eigenvalues to compute
324: .  ncv - the maximum dimension of the subspace to be used by the solver
325: -  mpd - the maximum dimension allowed for the projected problem

327:    Level: intermediate

329: .seealso: EPSSetDimensions()
330: @*/
331: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
332: {
334:   if (nev) *nev = eps->nev;
335:   if (ncv) *ncv = eps->ncv;
336:   if (mpd) *mpd = eps->mpd;
337:   return 0;
338: }

340: /*@
341:    EPSSetDimensions - Sets the number of eigenvalues to compute
342:    and the dimension of the subspace.

344:    Logically Collective on eps

346:    Input Parameters:
347: +  eps - the eigensolver context
348: .  nev - number of eigenvalues to compute
349: .  ncv - the maximum dimension of the subspace to be used by the solver
350: -  mpd - the maximum dimension allowed for the projected problem

352:    Options Database Keys:
353: +  -eps_nev <nev> - Sets the number of eigenvalues
354: .  -eps_ncv <ncv> - Sets the dimension of the subspace
355: -  -eps_mpd <mpd> - Sets the maximum projected dimension

357:    Notes:
358:    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
359:    dependent on the solution method.

361:    The parameters ncv and mpd are intimately related, so that the user is advised
362:    to set one of them at most. Normal usage is that
363:    (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
364:    (b) in cases where nev is large, the user sets mpd.

366:    The value of ncv should always be between nev and (nev+mpd), typically
367:    ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
368:    a smaller value should be used.

370:    When computing all eigenvalues in an interval, see EPSSetInterval(), these
371:    parameters lose relevance, and tuning must be done with
372:    EPSKrylovSchurSetDimensions().

374:    Level: intermediate

376: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
377: @*/
378: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
379: {
385:   eps->nev = nev;
386:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
387:     eps->ncv = PETSC_DEFAULT;
388:   } else {
390:     eps->ncv = ncv;
391:   }
392:   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
393:     eps->mpd = PETSC_DEFAULT;
394:   } else {
396:     eps->mpd = mpd;
397:   }
398:   eps->state = EPS_STATE_INITIAL;
399:   return 0;
400: }

402: /*@
403:    EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
404:    to be sought.

406:    Logically Collective on eps

408:    Input Parameters:
409: +  eps   - eigensolver context obtained from EPSCreate()
410: -  which - the portion of the spectrum to be sought

412:    Possible values:
413:    The parameter 'which' can have one of these values

415: +     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
416: .     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
417: .     EPS_LARGEST_REAL - largest real parts
418: .     EPS_SMALLEST_REAL - smallest real parts
419: .     EPS_LARGEST_IMAGINARY - largest imaginary parts
420: .     EPS_SMALLEST_IMAGINARY - smallest imaginary parts
421: .     EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
422: .     EPS_TARGET_REAL - eigenvalues with real part closest to target
423: .     EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
424: .     EPS_ALL - all eigenvalues contained in a given interval or region
425: -     EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()

427:    Options Database Keys:
428: +   -eps_largest_magnitude - Sets largest eigenvalues in magnitude
429: .   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
430: .   -eps_largest_real - Sets largest real parts
431: .   -eps_smallest_real - Sets smallest real parts
432: .   -eps_largest_imaginary - Sets largest imaginary parts
433: .   -eps_smallest_imaginary - Sets smallest imaginary parts
434: .   -eps_target_magnitude - Sets eigenvalues closest to target
435: .   -eps_target_real - Sets real parts closest to target
436: .   -eps_target_imaginary - Sets imaginary parts closest to target
437: -   -eps_all - Sets all eigenvalues in an interval or region

439:    Notes:
440:    Not all eigensolvers implemented in EPS account for all the possible values
441:    stated above. Also, some values make sense only for certain types of
442:    problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
443:    and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
444:    for eigenvalue selection.

446:    The target is a scalar value provided with EPSSetTarget().

448:    The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
449:    SLEPc have been built with complex scalars.

451:    EPS_ALL is intended for use in combination with an interval (see
452:    EPSSetInterval()), when all eigenvalues within the interval are requested,
453:    or in the context of the CISS solver for computing all eigenvalues in a region.
454:    In those cases, the number of eigenvalues is unknown, so the nev parameter
455:    has a different sense, see EPSSetDimensions().

457:    Level: intermediate

459: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
460:           EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
461: @*/
462: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
463: {
466:   switch (which) {
467:     case EPS_LARGEST_MAGNITUDE:
468:     case EPS_SMALLEST_MAGNITUDE:
469:     case EPS_LARGEST_REAL:
470:     case EPS_SMALLEST_REAL:
471:     case EPS_LARGEST_IMAGINARY:
472:     case EPS_SMALLEST_IMAGINARY:
473:     case EPS_TARGET_MAGNITUDE:
474:     case EPS_TARGET_REAL:
475: #if defined(PETSC_USE_COMPLEX)
476:     case EPS_TARGET_IMAGINARY:
477: #endif
478:     case EPS_ALL:
479:     case EPS_WHICH_USER:
480:       if (eps->which != which) {
481:         eps->state = EPS_STATE_INITIAL;
482:         eps->which = which;
483:       }
484:       break;
485: #if !defined(PETSC_USE_COMPLEX)
486:     case EPS_TARGET_IMAGINARY:
487:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"EPS_TARGET_IMAGINARY can be used only with complex scalars");
488: #endif
489:     default:
490:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
491:   }
492:   return 0;
493: }

495: /*@
496:    EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
497:    sought.

499:    Not Collective

501:    Input Parameter:
502: .  eps - eigensolver context obtained from EPSCreate()

504:    Output Parameter:
505: .  which - the portion of the spectrum to be sought

507:    Notes:
508:    See EPSSetWhichEigenpairs() for possible values of 'which'.

510:    Level: intermediate

512: .seealso: EPSSetWhichEigenpairs(), EPSWhich
513: @*/
514: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
515: {
518:   *which = eps->which;
519:   return 0;
520: }

522: /*@C
523:    EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
524:    when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.

526:    Logically Collective on eps

528:    Input Parameters:
529: +  eps  - eigensolver context obtained from EPSCreate()
530: .  func - a pointer to the comparison function
531: -  ctx  - a context pointer (the last parameter to the comparison function)

533:    Calling Sequence of func:
534: $   func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)

536: +   ar     - real part of the 1st eigenvalue
537: .   ai     - imaginary part of the 1st eigenvalue
538: .   br     - real part of the 2nd eigenvalue
539: .   bi     - imaginary part of the 2nd eigenvalue
540: .   res    - result of comparison
541: -   ctx    - optional context, as set by EPSSetEigenvalueComparison()

543:    Note:
544:    The returning parameter 'res' can be
545: +  negative - if the 1st eigenvalue is preferred to the 2st one
546: .  zero     - if both eigenvalues are equally preferred
547: -  positive - if the 2st eigenvalue is preferred to the 1st one

549:    Level: advanced

551: .seealso: EPSSetWhichEigenpairs(), EPSWhich
552: @*/
553: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
554: {
556:   eps->sc->comparison    = func;
557:   eps->sc->comparisonctx = ctx;
558:   eps->which             = EPS_WHICH_USER;
559:   return 0;
560: }

562: /*@C
563:    EPSSetArbitrarySelection - Specifies a function intended to look for
564:    eigenvalues according to an arbitrary selection criterion. This criterion
565:    can be based on a computation involving the current eigenvector approximation.

567:    Logically Collective on eps

569:    Input Parameters:
570: +  eps  - eigensolver context obtained from EPSCreate()
571: .  func - a pointer to the evaluation function
572: -  ctx  - a context pointer (the last parameter to the evaluation function)

574:    Calling Sequence of func:
575: $   func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)

577: +   er     - real part of the current eigenvalue approximation
578: .   ei     - imaginary part of the current eigenvalue approximation
579: .   xr     - real part of the current eigenvector approximation
580: .   xi     - imaginary part of the current eigenvector approximation
581: .   rr     - result of evaluation (real part)
582: .   ri     - result of evaluation (imaginary part)
583: -   ctx    - optional context, as set by EPSSetArbitrarySelection()

585:    Notes:
586:    This provides a mechanism to select eigenpairs by evaluating a user-defined
587:    function. When a function has been provided, the default selection based on
588:    sorting the eigenvalues is replaced by the sorting of the results of this
589:    function (with the same sorting criterion given in EPSSetWhichEigenpairs()).

591:    For instance, suppose you want to compute those eigenvectors that maximize
592:    a certain computable expression. Then implement the computation using
593:    the arguments xr and xi, and return the result in rr. Then set the standard
594:    sorting by magnitude so that the eigenpair with largest value of rr is
595:    selected.

597:    This evaluation function is collective, that is, all processes call it and
598:    it can use collective operations; furthermore, the computed result must
599:    be the same in all processes.

601:    The result of func is expressed as a complex number so that it is possible to
602:    use the standard eigenvalue sorting functions, but normally only rr is used.
603:    Set ri to zero unless it is meaningful in your application.

605:    Level: advanced

607: .seealso: EPSSetWhichEigenpairs()
608: @*/
609: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
610: {
612:   eps->arbitrary    = func;
613:   eps->arbitraryctx = ctx;
614:   eps->state        = EPS_STATE_INITIAL;
615:   return 0;
616: }

618: /*@C
619:    EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
620:    used in the convergence test.

622:    Logically Collective on eps

624:    Input Parameters:
625: +  eps     - eigensolver context obtained from EPSCreate()
626: .  func    - a pointer to the convergence test function
627: .  ctx     - context for private data for the convergence routine (may be null)
628: -  destroy - a routine for destroying the context (may be null)

630:    Calling Sequence of func:
631: $   func(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)

633: +   eps    - eigensolver context obtained from EPSCreate()
634: .   eigr   - real part of the eigenvalue
635: .   eigi   - imaginary part of the eigenvalue
636: .   res    - residual norm associated to the eigenpair
637: .   errest - (output) computed error estimate
638: -   ctx    - optional context, as set by EPSSetConvergenceTestFunction()

640:    Note:
641:    If the error estimate returned by the convergence test function is less than
642:    the tolerance, then the eigenvalue is accepted as converged.

644:    Level: advanced

646: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
647: @*/
648: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
649: {
651:   if (eps->convergeddestroy) (*eps->convergeddestroy)(eps->convergedctx);
652:   eps->convergeduser    = func;
653:   eps->convergeddestroy = destroy;
654:   eps->convergedctx     = ctx;
655:   if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
656:   else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
657:   else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
658:   else {
659:     eps->conv      = EPS_CONV_USER;
660:     eps->converged = eps->convergeduser;
661:   }
662:   return 0;
663: }

665: /*@
666:    EPSSetConvergenceTest - Specifies how to compute the error estimate
667:    used in the convergence test.

669:    Logically Collective on eps

671:    Input Parameters:
672: +  eps  - eigensolver context obtained from EPSCreate()
673: -  conv - the type of convergence test

675:    Options Database Keys:
676: +  -eps_conv_abs  - Sets the absolute convergence test
677: .  -eps_conv_rel  - Sets the convergence test relative to the eigenvalue
678: .  -eps_conv_norm - Sets the convergence test relative to the matrix norms
679: -  -eps_conv_user - Selects the user-defined convergence test

681:    Note:
682:    The parameter 'conv' can have one of these values
683: +     EPS_CONV_ABS  - absolute error ||r||
684: .     EPS_CONV_REL  - error relative to the eigenvalue l, ||r||/|l|
685: .     EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
686: -     EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()

688:    Level: intermediate

690: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
691: @*/
692: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
693: {
696:   switch (conv) {
697:     case EPS_CONV_ABS:  eps->converged = EPSConvergedAbsolute; break;
698:     case EPS_CONV_REL:  eps->converged = EPSConvergedRelative; break;
699:     case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
700:     case EPS_CONV_USER:
702:       eps->converged = eps->convergeduser;
703:       break;
704:     default:
705:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
706:   }
707:   eps->conv = conv;
708:   return 0;
709: }

711: /*@
712:    EPSGetConvergenceTest - Gets the method used to compute the error estimate
713:    used in the convergence test.

715:    Not Collective

717:    Input Parameters:
718: .  eps   - eigensolver context obtained from EPSCreate()

720:    Output Parameters:
721: .  conv  - the type of convergence test

723:    Level: intermediate

725: .seealso: EPSSetConvergenceTest(), EPSConv
726: @*/
727: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
728: {
731:   *conv = eps->conv;
732:   return 0;
733: }

735: /*@C
736:    EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
737:    iteration of the eigensolver.

739:    Logically Collective on eps

741:    Input Parameters:
742: +  eps     - eigensolver context obtained from EPSCreate()
743: .  func    - pointer to the stopping test function
744: .  ctx     - context for private data for the stopping routine (may be null)
745: -  destroy - a routine for destroying the context (may be null)

747:    Calling Sequence of func:
748: $   func(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx)

750: +   eps    - eigensolver context obtained from EPSCreate()
751: .   its    - current number of iterations
752: .   max_it - maximum number of iterations
753: .   nconv  - number of currently converged eigenpairs
754: .   nev    - number of requested eigenpairs
755: .   reason - (output) result of the stopping test
756: -   ctx    - optional context, as set by EPSSetStoppingTestFunction()

758:    Note:
759:    Normal usage is to first call the default routine EPSStoppingBasic() and then
760:    set reason to EPS_CONVERGED_USER if some user-defined conditions have been
761:    met. To let the eigensolver continue iterating, the result must be left as
762:    EPS_CONVERGED_ITERATING.

764:    Level: advanced

766: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
767: @*/
768: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
769: {
771:   if (eps->stoppingdestroy) (*eps->stoppingdestroy)(eps->stoppingctx);
772:   eps->stoppinguser    = func;
773:   eps->stoppingdestroy = destroy;
774:   eps->stoppingctx     = ctx;
775:   if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
776:   else {
777:     eps->stop     = EPS_STOP_USER;
778:     eps->stopping = eps->stoppinguser;
779:   }
780:   return 0;
781: }

783: /*@
784:    EPSSetStoppingTest - Specifies how to decide the termination of the outer
785:    loop of the eigensolver.

787:    Logically Collective on eps

789:    Input Parameters:
790: +  eps  - eigensolver context obtained from EPSCreate()
791: -  stop - the type of stopping test

793:    Options Database Keys:
794: +  -eps_stop_basic - Sets the default stopping test
795: -  -eps_stop_user  - Selects the user-defined stopping test

797:    Note:
798:    The parameter 'stop' can have one of these values
799: +     EPS_STOP_BASIC - default stopping test
800: -     EPS_STOP_USER  - function set by EPSSetStoppingTestFunction()

802:    Level: advanced

804: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
805: @*/
806: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
807: {
810:   switch (stop) {
811:     case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
812:     case EPS_STOP_USER:
814:       eps->stopping = eps->stoppinguser;
815:       break;
816:     default:
817:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
818:   }
819:   eps->stop = stop;
820:   return 0;
821: }

823: /*@
824:    EPSGetStoppingTest - Gets the method used to decide the termination of the outer
825:    loop of the eigensolver.

827:    Not Collective

829:    Input Parameters:
830: .  eps   - eigensolver context obtained from EPSCreate()

832:    Output Parameters:
833: .  stop  - the type of stopping test

835:    Level: advanced

837: .seealso: EPSSetStoppingTest(), EPSStop
838: @*/
839: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
840: {
843:   *stop = eps->stop;
844:   return 0;
845: }

847: /*@
848:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

850:    Logically Collective on eps

852:    Input Parameters:
853: +  eps      - the eigensolver context
854: -  type     - a known type of eigenvalue problem

856:    Options Database Keys:
857: +  -eps_hermitian - Hermitian eigenvalue problem
858: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
859: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
860: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
861: .  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
862:    with positive semi-definite B
863: -  -eps_gen_indefinite - generalized Hermitian-indefinite eigenvalue problem

865:    Notes:
866:    Allowed values for the problem type are Hermitian (EPS_HEP), non-Hermitian
867:    (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
868:    (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
869:    (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).

871:    This function must be used to instruct SLEPc to exploit symmetry. If no
872:    problem type is specified, by default a non-Hermitian problem is assumed
873:    (either standard or generalized). If the user knows that the problem is
874:    Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
875:    B positive definite) then it is recommended to set the problem type so
876:    that eigensolver can exploit these properties.

878:    Level: intermediate

880: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
881: @*/
882: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
883: {
886:   if (type == eps->problem_type) return 0;
887:   switch (type) {
888:     case EPS_HEP:
889:       eps->isgeneralized = PETSC_FALSE;
890:       eps->ishermitian = PETSC_TRUE;
891:       eps->ispositive = PETSC_FALSE;
892:       break;
893:     case EPS_NHEP:
894:       eps->isgeneralized = PETSC_FALSE;
895:       eps->ishermitian = PETSC_FALSE;
896:       eps->ispositive = PETSC_FALSE;
897:       break;
898:     case EPS_GHEP:
899:       eps->isgeneralized = PETSC_TRUE;
900:       eps->ishermitian = PETSC_TRUE;
901:       eps->ispositive = PETSC_TRUE;
902:       break;
903:     case EPS_GNHEP:
904:       eps->isgeneralized = PETSC_TRUE;
905:       eps->ishermitian = PETSC_FALSE;
906:       eps->ispositive = PETSC_FALSE;
907:       break;
908:     case EPS_PGNHEP:
909:       eps->isgeneralized = PETSC_TRUE;
910:       eps->ishermitian = PETSC_FALSE;
911:       eps->ispositive = PETSC_TRUE;
912:       break;
913:     case EPS_GHIEP:
914:       eps->isgeneralized = PETSC_TRUE;
915:       eps->ishermitian = PETSC_TRUE;
916:       eps->ispositive = PETSC_FALSE;
917:       break;
918:     default:
919:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
920:   }
921:   eps->problem_type = type;
922:   eps->state = EPS_STATE_INITIAL;
923:   return 0;
924: }

926: /*@
927:    EPSGetProblemType - Gets the problem type from the EPS object.

929:    Not Collective

931:    Input Parameter:
932: .  eps - the eigensolver context

934:    Output Parameter:
935: .  type - the problem type

937:    Level: intermediate

939: .seealso: EPSSetProblemType(), EPSProblemType
940: @*/
941: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
942: {
945:   *type = eps->problem_type;
946:   return 0;
947: }

949: /*@
950:    EPSSetExtraction - Specifies the type of extraction technique to be employed
951:    by the eigensolver.

953:    Logically Collective on eps

955:    Input Parameters:
956: +  eps  - the eigensolver context
957: -  extr - a known type of extraction

959:    Options Database Keys:
960: +  -eps_ritz - Rayleigh-Ritz extraction
961: .  -eps_harmonic - harmonic Ritz extraction
962: .  -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
963: .  -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
964: .  -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
965:    (without target)
966: .  -eps_refined - refined Ritz extraction
967: -  -eps_refined_harmonic - refined harmonic Ritz extraction

969:    Notes:
970:    Not all eigensolvers support all types of extraction. See the SLEPc
971:    Users Manual for details.

973:    By default, a standard Rayleigh-Ritz extraction is used. Other extractions
974:    may be useful when computing interior eigenvalues.

976:    Harmonic-type extractions are used in combination with a 'target'.

978:    Level: advanced

980: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
981: @*/
982: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
983: {
986:   eps->extraction = extr;
987:   return 0;
988: }

990: /*@
991:    EPSGetExtraction - Gets the extraction type used by the EPS object.

993:    Not Collective

995:    Input Parameter:
996: .  eps - the eigensolver context

998:    Output Parameter:
999: .  extr - name of extraction type

1001:    Level: advanced

1003: .seealso: EPSSetExtraction(), EPSExtraction
1004: @*/
1005: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1006: {
1009:   *extr = eps->extraction;
1010:   return 0;
1011: }

1013: /*@
1014:    EPSSetBalance - Specifies the balancing technique to be employed by the
1015:    eigensolver, and some parameters associated to it.

1017:    Logically Collective on eps

1019:    Input Parameters:
1020: +  eps    - the eigensolver context
1021: .  bal    - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1022:             EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1023: .  its    - number of iterations of the balancing algorithm
1024: -  cutoff - cutoff value

1026:    Options Database Keys:
1027: +  -eps_balance <method> - the balancing method, where <method> is one of
1028:                            'none', 'oneside', 'twoside', or 'user'
1029: .  -eps_balance_its <its> - number of iterations
1030: -  -eps_balance_cutoff <cutoff> - cutoff value

1032:    Notes:
1033:    When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1034:    where D is an appropriate diagonal matrix. This improves the accuracy of
1035:    the computed results in some cases. See the SLEPc Users Manual for details.

1037:    Balancing makes sense only for non-Hermitian problems when the required
1038:    precision is high (i.e. a small tolerance such as 1e-15).

1040:    By default, balancing is disabled. The two-sided method is much more
1041:    effective than the one-sided counterpart, but it requires the system
1042:    matrices to have the MatMultTranspose operation defined.

1044:    The parameter 'its' is the number of iterations performed by the method. The
1045:    cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
1046:    a reasonably good value.

1048:    User-defined balancing is allowed provided that the corresponding matrix
1049:    is set via STSetBalanceMatrix.

1051:    Level: intermediate

1053: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1054: @*/
1055: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1056: {
1061:   switch (bal) {
1062:     case EPS_BALANCE_NONE:
1063:     case EPS_BALANCE_ONESIDE:
1064:     case EPS_BALANCE_TWOSIDE:
1065:     case EPS_BALANCE_USER:
1066:       if (eps->balance != bal) {
1067:         eps->state = EPS_STATE_INITIAL;
1068:         eps->balance = bal;
1069:       }
1070:       break;
1071:     default:
1072:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1073:   }
1074:   if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1075:   else {
1077:     eps->balance_its = its;
1078:   }
1079:   if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1080:   else {
1082:     eps->balance_cutoff = cutoff;
1083:   }
1084:   return 0;
1085: }

1087: /*@C
1088:    EPSGetBalance - Gets the balancing type used by the EPS object, and the
1089:    associated parameters.

1091:    Not Collective

1093:    Input Parameter:
1094: .  eps - the eigensolver context

1096:    Output Parameters:
1097: +  bal    - the balancing method
1098: .  its    - number of iterations of the balancing algorithm
1099: -  cutoff - cutoff value

1101:    Level: intermediate

1103:    Note:
1104:    The user can specify NULL for any parameter that is not needed.

1106: .seealso: EPSSetBalance(), EPSBalance
1107: @*/
1108: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1109: {
1111:   if (bal)    *bal = eps->balance;
1112:   if (its)    *its = eps->balance_its;
1113:   if (cutoff) *cutoff = eps->balance_cutoff;
1114:   return 0;
1115: }

1117: /*@
1118:    EPSSetTwoSided - Sets the solver to use a two-sided variant so that left
1119:    eigenvectors are also computed.

1121:    Logically Collective on eps

1123:    Input Parameters:
1124: +  eps      - the eigensolver context
1125: -  twosided - whether the two-sided variant is to be used or not

1127:    Options Database Keys:
1128: .  -eps_two_sided <boolean> - Sets/resets the twosided flag

1130:    Notes:
1131:    If the user sets twosided=PETSC_TRUE then the solver uses a variant of
1132:    the algorithm that computes both right and left eigenvectors. This is
1133:    usually much more costly. This option is not available in all solvers.

1135:    When using two-sided solvers, the problem matrices must have both the
1136:    MatMult and MatMultTranspose operations defined.

1138:    Level: advanced

1140: .seealso: EPSGetTwoSided(), EPSGetLeftEigenvector()
1141: @*/
1142: PetscErrorCode EPSSetTwoSided(EPS eps,PetscBool twosided)
1143: {
1146:   if (twosided!=eps->twosided) {
1147:     eps->twosided = twosided;
1148:     eps->state    = EPS_STATE_INITIAL;
1149:   }
1150:   return 0;
1151: }

1153: /*@
1154:    EPSGetTwoSided - Returns the flag indicating whether a two-sided variant
1155:    of the algorithm is being used or not.

1157:    Not Collective

1159:    Input Parameter:
1160: .  eps - the eigensolver context

1162:    Output Parameter:
1163: .  twosided - the returned flag

1165:    Level: advanced

1167: .seealso: EPSSetTwoSided()
1168: @*/
1169: PetscErrorCode EPSGetTwoSided(EPS eps,PetscBool *twosided)
1170: {
1173:   *twosided = eps->twosided;
1174:   return 0;
1175: }

1177: /*@
1178:    EPSSetTrueResidual - Specifies if the solver must compute the true residual
1179:    explicitly or not.

1181:    Logically Collective on eps

1183:    Input Parameters:
1184: +  eps     - the eigensolver context
1185: -  trueres - whether true residuals are required or not

1187:    Options Database Keys:
1188: .  -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'

1190:    Notes:
1191:    If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1192:    the true residual for each eigenpair approximation, and uses it for
1193:    convergence testing. Computing the residual is usually an expensive
1194:    operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1195:    by using a cheap estimate of the residual norm, but this may sometimes
1196:    give inaccurate results (especially if a spectral transform is being
1197:    used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1198:    do rely on computing the true residual, so this option is irrelevant for them.

1200:    Level: advanced

1202: .seealso: EPSGetTrueResidual()
1203: @*/
1204: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1205: {
1208:   eps->trueres = trueres;
1209:   return 0;
1210: }

1212: /*@
1213:    EPSGetTrueResidual - Returns the flag indicating whether true
1214:    residuals must be computed explicitly or not.

1216:    Not Collective

1218:    Input Parameter:
1219: .  eps - the eigensolver context

1221:    Output Parameter:
1222: .  trueres - the returned flag

1224:    Level: advanced

1226: .seealso: EPSSetTrueResidual()
1227: @*/
1228: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1229: {
1232:   *trueres = eps->trueres;
1233:   return 0;
1234: }

1236: /*@
1237:    EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1238:    approximate eigenpairs or not.

1240:    Logically Collective on eps

1242:    Input Parameters:
1243: +  eps      - the eigensolver context
1244: -  trackall - whether to compute all residuals or not

1246:    Notes:
1247:    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1248:    the residual norm for each eigenpair approximation. Computing the residual is
1249:    usually an expensive operation and solvers commonly compute only the residual
1250:    associated to the first unconverged eigenpair.

1252:    The option '-eps_monitor_all' automatically activates this option.

1254:    Level: developer

1256: .seealso: EPSGetTrackAll()
1257: @*/
1258: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1259: {
1262:   eps->trackall = trackall;
1263:   return 0;
1264: }

1266: /*@
1267:    EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1268:    be computed or not.

1270:    Not Collective

1272:    Input Parameter:
1273: .  eps - the eigensolver context

1275:    Output Parameter:
1276: .  trackall - the returned flag

1278:    Level: developer

1280: .seealso: EPSSetTrackAll()
1281: @*/
1282: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1283: {
1286:   *trackall = eps->trackall;
1287:   return 0;
1288: }

1290: /*@
1291:    EPSSetPurify - Deactivate eigenvector purification (which is activated by default).

1293:    Logically Collective on eps

1295:    Input Parameters:
1296: +  eps    - the eigensolver context
1297: -  purify - whether purification is required or not

1299:    Options Database Keys:
1300: .  -eps_purify <boolean> - Sets/resets the boolean flag 'purify'

1302:    Notes:
1303:    By default, eigenvectors of generalized symmetric eigenproblems are purified
1304:    in order to purge directions in the nullspace of matrix B. If the user knows
1305:    that B is non-singular, then purification can be safely deactivated and some
1306:    computational cost is avoided (this is particularly important in interval computations).

1308:    Level: intermediate

1310: .seealso: EPSGetPurify(), EPSSetInterval()
1311: @*/
1312: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1313: {
1316:   if (purify!=eps->purify) {
1317:     eps->purify = purify;
1318:     eps->state  = EPS_STATE_INITIAL;
1319:   }
1320:   return 0;
1321: }

1323: /*@
1324:    EPSGetPurify - Returns the flag indicating whether purification is activated
1325:    or not.

1327:    Not Collective

1329:    Input Parameter:
1330: .  eps - the eigensolver context

1332:    Output Parameter:
1333: .  purify - the returned flag

1335:    Level: intermediate

1337: .seealso: EPSSetPurify()
1338: @*/
1339: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1340: {
1343:   *purify = eps->purify;
1344:   return 0;
1345: }

1347: /*@C
1348:    EPSSetOptionsPrefix - Sets the prefix used for searching for all
1349:    EPS options in the database.

1351:    Logically Collective on eps

1353:    Input Parameters:
1354: +  eps - the eigensolver context
1355: -  prefix - the prefix string to prepend to all EPS option requests

1357:    Notes:
1358:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1359:    The first character of all runtime options is AUTOMATICALLY the
1360:    hyphen.

1362:    For example, to distinguish between the runtime options for two
1363:    different EPS contexts, one could call
1364: .vb
1365:       EPSSetOptionsPrefix(eps1,"eig1_")
1366:       EPSSetOptionsPrefix(eps2,"eig2_")
1367: .ve

1369:    Level: advanced

1371: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1372: @*/
1373: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1374: {
1376:   if (!eps->st) EPSGetST(eps,&eps->st);
1377:   STSetOptionsPrefix(eps->st,prefix);
1378:   if (!eps->V) EPSGetBV(eps,&eps->V);
1379:   BVSetOptionsPrefix(eps->V,prefix);
1380:   if (!eps->ds) EPSGetDS(eps,&eps->ds);
1381:   DSSetOptionsPrefix(eps->ds,prefix);
1382:   if (!eps->rg) EPSGetRG(eps,&eps->rg);
1383:   RGSetOptionsPrefix(eps->rg,prefix);
1384:   PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1385:   return 0;
1386: }

1388: /*@C
1389:    EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1390:    EPS options in the database.

1392:    Logically Collective on eps

1394:    Input Parameters:
1395: +  eps - the eigensolver context
1396: -  prefix - the prefix string to prepend to all EPS option requests

1398:    Notes:
1399:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1400:    The first character of all runtime options is AUTOMATICALLY the hyphen.

1402:    Level: advanced

1404: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1405: @*/
1406: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1407: {
1409:   if (!eps->st) EPSGetST(eps,&eps->st);
1410:   STAppendOptionsPrefix(eps->st,prefix);
1411:   if (!eps->V) EPSGetBV(eps,&eps->V);
1412:   BVAppendOptionsPrefix(eps->V,prefix);
1413:   if (!eps->ds) EPSGetDS(eps,&eps->ds);
1414:   DSAppendOptionsPrefix(eps->ds,prefix);
1415:   if (!eps->rg) EPSGetRG(eps,&eps->rg);
1416:   RGAppendOptionsPrefix(eps->rg,prefix);
1417:   PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1418:   return 0;
1419: }

1421: /*@C
1422:    EPSGetOptionsPrefix - Gets the prefix used for searching for all
1423:    EPS options in the database.

1425:    Not Collective

1427:    Input Parameters:
1428: .  eps - the eigensolver context

1430:    Output Parameters:
1431: .  prefix - pointer to the prefix string used is returned

1433:    Note:
1434:    On the Fortran side, the user should pass in a string 'prefix' of
1435:    sufficient length to hold the prefix.

1437:    Level: advanced

1439: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1440: @*/
1441: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1442: {
1445:   PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1446:   return 0;
1447: }