Actual source code: epsopts.c

slepc-3.6.1 2015-09-03
Report Typos and Errors
  1: /*
  2:       EPS routines related to options that can be set via the command-line
  3:       or procedurally.

  5:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  7:    Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain

  9:    This file is part of SLEPc.

 11:    SLEPc is free software: you can redistribute it and/or modify it under  the
 12:    terms of version 3 of the GNU Lesser General Public License as published by
 13:    the Free Software Foundation.

 15:    SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY
 16:    WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS
 17:    FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for
 18:    more details.

 20:    You  should have received a copy of the GNU Lesser General  Public  License
 21:    along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
 22:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 23: */

 25: #include <slepc/private/epsimpl.h>   /*I "slepceps.h" I*/

 29: /*@
 30:    EPSSetFromOptions - Sets EPS options from the options database.
 31:    This routine must be called before EPSSetUp() if the user is to be
 32:    allowed to set the solver type.

 34:    Collective on EPS

 36:    Input Parameters:
 37: .  eps - the eigensolver context

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

 42:    Level: beginner
 43: @*/
 44: PetscErrorCode EPSSetFromOptions(EPS eps)
 45: {
 46:   PetscErrorCode   ierr;
 47:   char             type[256],monfilename[PETSC_MAX_PATH_LEN];
 48:   PetscBool        flg,flg1,flg2,flg3;
 49:   PetscReal        r,array[2]={0,0};
 50:   PetscScalar      s;
 51:   PetscInt         i,j,k;
 52:   PetscViewer      monviewer;
 53:   SlepcConvMonitor ctx;

 57:   EPSRegisterAll();
 58:   PetscObjectOptionsBegin((PetscObject)eps);
 59:     PetscOptionsFList("-eps_type","Eigenvalue Problem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
 60:     if (flg) {
 61:       EPSSetType(eps,type);
 62:     }
 63:     /*
 64:       Set the type if it was never set.
 65:     */
 66:     if (!((PetscObject)eps)->type_name) {
 67:       EPSSetType(eps,EPSKRYLOVSCHUR);
 68:     }

 70:     PetscOptionsBoolGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);
 71:     if (flg) { EPSSetProblemType(eps,EPS_HEP); }
 72:     PetscOptionsBoolGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);
 73:     if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
 74:     PetscOptionsBoolGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
 75:     if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
 76:     PetscOptionsBoolGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
 77:     if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
 78:     PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
 79:     if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
 80:     PetscOptionsBoolGroupEnd("-eps_gen_indefinite","generalized hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
 81:     if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }

 83:     PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
 84:     if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
 85:     PetscOptionsBoolGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);
 86:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
 87:     PetscOptionsBoolGroup("-eps_harmonic_relative","relative harmonic Ritz extraction","EPSSetExtraction",&flg);
 88:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
 89:     PetscOptionsBoolGroup("-eps_harmonic_right","right harmonic Ritz extraction","EPSSetExtraction",&flg);
 90:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
 91:     PetscOptionsBoolGroup("-eps_harmonic_largest","largest harmonic Ritz extraction","EPSSetExtraction",&flg);
 92:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
 93:     PetscOptionsBoolGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);
 94:     if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
 95:     PetscOptionsBoolGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);
 96:     if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }

 98:     PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)eps->balance,(PetscEnum*)&eps->balance,NULL);

100:     j = eps->balance_its;
101:     PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg1);
102:     r = eps->balance_cutoff;
103:     PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg2);
104:     if (flg1 || flg2) {
105:       EPSSetBalance(eps,eps->balance,j,r);
106:     }

108:     i = eps->max_it? eps->max_it: PETSC_DEFAULT;
109:     PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
110:     r = eps->tol;
111:     PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,&flg2);
112:     if (flg1 || flg2) {
113:       EPSSetTolerances(eps,r,i);
114:     }

116:     PetscOptionsBoolGroupBegin("-eps_conv_eig","Relative error convergence test","EPSSetConvergenceTest",&flg);
117:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_EIG); }
118:     PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
119:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
120:     PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
121:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
122:     PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
123:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_USER); }

125:     i = eps->nev;
126:     PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
127:     j = eps->ncv? eps->ncv: PETSC_DEFAULT;
128:     PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
129:     k = eps->mpd? eps->mpd: PETSC_DEFAULT;
130:     PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
131:     if (flg1 || flg2 || flg3) {
132:       EPSSetDimensions(eps,i,j,k);
133:     }

135:     /* -----------------------------------------------------------------------*/
136:     /*
137:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
138:     */
139:     flg = PETSC_FALSE;
140:     PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",flg,&flg,NULL);
141:     if (flg) {
142:       EPSMonitorCancel(eps);
143:     }
144:     /*
145:       Prints approximate eigenvalues and error estimates at each iteration
146:     */
147:     PetscOptionsString("-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
148:     if (flg) {
149:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
150:       EPSMonitorSet(eps,EPSMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
151:     }
152:     PetscOptionsString("-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
153:     if (flg) {
154:       PetscNew(&ctx);
155:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&ctx->viewer);
156:       EPSMonitorSet(eps,EPSMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
157:     }
158:     PetscOptionsString("-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
159:     if (flg) {
160:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
161:       EPSMonitorSet(eps,EPSMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
162:       EPSSetTrackAll(eps,PETSC_TRUE);
163:     }
164:     flg = PETSC_FALSE;
165:     PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",flg,&flg,NULL);
166:     if (flg) {
167:       EPSMonitorSet(eps,EPSMonitorLG,NULL,NULL);
168:     }
169:     flg = PETSC_FALSE;
170:     PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",flg,&flg,NULL);
171:     if (flg) {
172:       EPSMonitorSet(eps,EPSMonitorLGAll,NULL,NULL);
173:       EPSSetTrackAll(eps,PETSC_TRUE);
174:     }
175:   /* -----------------------------------------------------------------------*/
176:     PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
177:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
178:     PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
179:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
180:     PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
181:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
182:     PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
183:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
184:     PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
185:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
186:     PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
187:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
188:     PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);
189:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
190:     PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);
191:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
192:     PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);
193:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
194:     PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval","EPSSetWhichEigenpairs",&flg);
195:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }

197:     PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
198:     if (flg) {
199:       if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) {
200:         EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
201:       }
202:       EPSSetTarget(eps,s);
203:     }
204:     k = 2;
205:     PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
206:     if (flg) {
207:       if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
208:       EPSSetWhichEigenpairs(eps,EPS_ALL);
209:       EPSSetInterval(eps,array[0],array[1]);
210:     }

212:     PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
213:     PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&eps->purify,NULL);

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

223:     if (eps->ops->setfromoptions) {
224:       (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
225:     }
226:     PetscObjectProcessOptionsHandlers((PetscObject)eps);
227:   PetscOptionsEnd();

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

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

247:    Not Collective

249:    Input Parameter:
250: .  eps - the eigensolver context

252:    Output Parameters:
253: +  tol - the convergence tolerance
254: -  maxits - maximum number of iterations

256:    Notes:
257:    The user can specify NULL for any parameter that is not needed.

259:    Level: intermediate

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

274: /*@
275:    EPSSetTolerances - Sets the tolerance and maximum iteration count used
276:    by the EPS convergence tests.

278:    Logically Collective on EPS

280:    Input Parameters:
281: +  eps - the eigensolver context
282: .  tol - the convergence tolerance
283: -  maxits - maximum number of iterations to use

285:    Options Database Keys:
286: +  -eps_tol <tol> - Sets the convergence tolerance
287: -  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

289:    Notes:
290:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

292:    Level: intermediate

294: .seealso: EPSGetTolerances()
295: @*/
296: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
297: {
302:   if (tol == PETSC_DEFAULT) {
303:     eps->tol   = PETSC_DEFAULT;
304:     eps->state = EPS_STATE_INITIAL;
305:   } else {
306:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
307:     eps->tol = tol;
308:   }
309:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
310:     eps->max_it = 0;
311:     eps->state  = EPS_STATE_INITIAL;
312:   } else {
313:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
314:     eps->max_it = maxits;
315:   }
316:   return(0);
317: }

321: /*@
322:    EPSGetDimensions - Gets the number of eigenvalues to compute
323:    and the dimension of the subspace.

325:    Not Collective

327:    Input Parameter:
328: .  eps - the eigensolver context

330:    Output Parameters:
331: +  nev - number of eigenvalues to compute
332: .  ncv - the maximum dimension of the subspace to be used by the solver
333: -  mpd - the maximum dimension allowed for the projected problem

335:    Level: intermediate

337: .seealso: EPSSetDimensions()
338: @*/
339: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
340: {
343:   if (nev) *nev = eps->nev;
344:   if (ncv) *ncv = eps->ncv;
345:   if (mpd) *mpd = eps->mpd;
346:   return(0);
347: }

351: /*@
352:    EPSSetDimensions - Sets the number of eigenvalues to compute
353:    and the dimension of the subspace.

355:    Logically Collective on EPS

357:    Input Parameters:
358: +  eps - the eigensolver context
359: .  nev - number of eigenvalues to compute
360: .  ncv - the maximum dimension of the subspace to be used by the solver
361: -  mpd - the maximum dimension allowed for the projected problem

363:    Options Database Keys:
364: +  -eps_nev <nev> - Sets the number of eigenvalues
365: .  -eps_ncv <ncv> - Sets the dimension of the subspace
366: -  -eps_mpd <mpd> - Sets the maximum projected dimension

368:    Notes:
369:    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
370:    dependent on the solution method.

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

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

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

385:    Level: intermediate

387: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
388: @*/
389: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
390: {
396:   if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
397:   eps->nev = nev;
398:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
399:     eps->ncv = 0;
400:   } else {
401:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
402:     eps->ncv = ncv;
403:   }
404:   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
405:     eps->mpd = 0;
406:   } else {
407:     if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
408:     eps->mpd = mpd;
409:   }
410:   eps->state = EPS_STATE_INITIAL;
411:   return(0);
412: }

416: /*@
417:    EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
418:    to be sought.

420:    Logically Collective on EPS

422:    Input Parameters:
423: +  eps   - eigensolver context obtained from EPSCreate()
424: -  which - the portion of the spectrum to be sought

426:    Possible values:
427:    The parameter 'which' can have one of these values

429: +     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
430: .     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
431: .     EPS_LARGEST_REAL - largest real parts
432: .     EPS_SMALLEST_REAL - smallest real parts
433: .     EPS_LARGEST_IMAGINARY - largest imaginary parts
434: .     EPS_SMALLEST_IMAGINARY - smallest imaginary parts
435: .     EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
436: .     EPS_TARGET_REAL - eigenvalues with real part closest to target
437: .     EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
438: .     EPS_ALL - all eigenvalues contained in a given interval
439: -     EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()

441:    Options Database Keys:
442: +   -eps_largest_magnitude - Sets largest eigenvalues in magnitude
443: .   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
444: .   -eps_largest_real - Sets largest real parts
445: .   -eps_smallest_real - Sets smallest real parts
446: .   -eps_largest_imaginary - Sets largest imaginary parts
447: .   -eps_smallest_imaginary - Sets smallest imaginary parts
448: .   -eps_target_magnitude - Sets eigenvalues closest to target
449: .   -eps_target_real - Sets real parts closest to target
450: .   -eps_target_imaginary - Sets imaginary parts closest to target
451: -   -eps_all - Sets all eigenvalues in an interval

453:    Notes:
454:    Not all eigensolvers implemented in EPS account for all the possible values
455:    stated above. Also, some values make sense only for certain types of
456:    problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
457:    and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
458:    for eigenvalue selection.

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

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

465:    EPS_ALL is intended for use in combination with an interval (see
466:    EPSSetInterval()), when all eigenvalues within the interval are requested.
467:    In that case, the number of eigenvalues is unknown, so the nev parameter
468:    has a different sense, see EPSSetDimensions().

470:    Level: intermediate

472: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
473:           EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
474: @*/
475: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
476: {
480:   switch (which) {
481:     case EPS_LARGEST_MAGNITUDE:
482:     case EPS_SMALLEST_MAGNITUDE:
483:     case EPS_LARGEST_REAL:
484:     case EPS_SMALLEST_REAL:
485:     case EPS_LARGEST_IMAGINARY:
486:     case EPS_SMALLEST_IMAGINARY:
487:     case EPS_TARGET_MAGNITUDE:
488:     case EPS_TARGET_REAL:
489: #if defined(PETSC_USE_COMPLEX)
490:     case EPS_TARGET_IMAGINARY:
491: #endif
492:     case EPS_ALL:
493:     case EPS_WHICH_USER:
494:       if (eps->which != which) {
495:         eps->state = EPS_STATE_INITIAL;
496:         eps->which = which;
497:       }
498:       break;
499:     default:
500:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
501:   }
502:   return(0);
503: }

507: /*@
508:    EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
509:    sought.

511:    Not Collective

513:    Input Parameter:
514: .  eps - eigensolver context obtained from EPSCreate()

516:    Output Parameter:
517: .  which - the portion of the spectrum to be sought

519:    Notes:
520:    See EPSSetWhichEigenpairs() for possible values of 'which'.

522:    Level: intermediate

524: .seealso: EPSSetWhichEigenpairs(), EPSWhich
525: @*/
526: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
527: {
531:   *which = eps->which;
532:   return(0);
533: }

537: /*@C
538:    EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
539:    when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.

541:    Logically Collective on EPS

543:    Input Parameters:
544: +  eps  - eigensolver context obtained from EPSCreate()
545: .  func - a pointer to the comparison function
546: -  ctx  - a context pointer (the last parameter to the comparison function)

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

551: +   ar     - real part of the 1st eigenvalue
552: .   ai     - imaginary part of the 1st eigenvalue
553: .   br     - real part of the 2nd eigenvalue
554: .   bi     - imaginary part of the 2nd eigenvalue
555: .   res    - result of comparison
556: -   ctx    - optional context, as set by EPSSetEigenvalueComparison()

558:    Note:
559:    The returning parameter 'res' can be:
560: +  negative - if the 1st eigenvalue is preferred to the 2st one
561: .  zero     - if both eigenvalues are equally preferred
562: -  positive - if the 2st eigenvalue is preferred to the 1st one

564:    Level: advanced

566: .seealso: EPSSetWhichEigenpairs(), EPSWhich
567: @*/
568: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
569: {
572:   eps->sc->comparison    = func;
573:   eps->sc->comparisonctx = ctx;
574:   eps->which             = EPS_WHICH_USER;
575:   return(0);
576: }

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

585:    Logically Collective on EPS

587:    Input Parameters:
588: +  eps  - eigensolver context obtained from EPSCreate()
589: .  func - a pointer to the evaluation function
590: -  ctx  - a context pointer (the last parameter to the evaluation function)

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

595: +   er     - real part of the current eigenvalue approximation
596: .   ei     - imaginary part of the current eigenvalue approximation
597: .   xr     - real part of the current eigenvector approximation
598: .   xi     - imaginary part of the current eigenvector approximation
599: .   rr     - result of evaluation (real part)
600: .   ri     - result of evaluation (imaginary part)
601: -   ctx    - optional context, as set by EPSSetArbitrarySelection()

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

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

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

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

623:    Level: advanced

625: .seealso: EPSSetWhichEigenpairs()
626: @*/
627: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
628: {
631:   eps->arbitrary    = func;
632:   eps->arbitraryctx = ctx;
633:   eps->state        = EPS_STATE_INITIAL;
634:   return(0);
635: }

639: /*@C
640:    EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
641:    used in the convergence test.

643:    Logically Collective on EPS

645:    Input Parameters:
646: +  eps     - eigensolver context obtained from EPSCreate()
647: .  func    - a pointer to the convergence test function
648: .  ctx     - [optional] context for private data for the convergence routine
649: -  destroy - [optional] destructor for the context (may be NULL;
650:              PETSC_NULL_FUNCTION in Fortran)

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

655: +   eps    - eigensolver context obtained from EPSCreate()
656: .   eigr   - real part of the eigenvalue
657: .   eigi   - imaginary part of the eigenvalue
658: .   res    - residual norm associated to the eigenpair
659: .   errest - (output) computed error estimate
660: -   ctx    - optional context, as set by EPSSetConvergenceTest()

662:    Note:
663:    If the error estimate returned by the convergence test function is less than
664:    the tolerance, then the eigenvalue is accepted as converged.

666:    Level: advanced

668: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
669: @*/
670: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
671: {

676:   if (eps->convergeddestroy) {
677:     (*eps->convergeddestroy)(eps->convergedctx);
678:   }
679:   eps->converged        = func;
680:   eps->convergeddestroy = destroy;
681:   eps->convergedctx     = ctx;
682:   if (func == EPSConvergedEigRelative) eps->conv = EPS_CONV_EIG;
683:   else if (func == EPSConvergedNormRelative) eps->conv = EPS_CONV_NORM;
684:   else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
685:   else eps->conv = EPS_CONV_USER;
686:   return(0);
687: }

691: /*@
692:    EPSSetConvergenceTest - Specifies how to compute the error estimate
693:    used in the convergence test.

695:    Logically Collective on EPS

697:    Input Parameters:
698: +  eps  - eigensolver context obtained from EPSCreate()
699: -  conv - the type of convergence test

701:    Options Database Keys:
702: +  -eps_conv_abs  - Sets the absolute convergence test
703: .  -eps_conv_eig  - Sets the convergence test relative to the eigenvalue
704: .  -eps_conv_norm - Sets the convergence test relative to the matrix norms
705: -  -eps_conv_user - Selects the user-defined convergence test

707:    Note:
708:    The parameter 'conv' can have one of these values
709: +     EPS_CONV_ABS  - absolute error ||r||
710: .     EPS_CONV_EIG  - error relative to the eigenvalue l, ||r||/|l|
711: .     EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
712: -     EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()

714:    Level: intermediate

716: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSConv
717: @*/
718: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
719: {
723:   switch (conv) {
724:     case EPS_CONV_ABS:  eps->converged = EPSConvergedAbsolute; break;
725:     case EPS_CONV_EIG:  eps->converged = EPSConvergedEigRelative; break;
726:     case EPS_CONV_NORM: eps->converged = EPSConvergedNormRelative; break;
727:     case EPS_CONV_USER: break;
728:     default:
729:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
730:   }
731:   eps->conv = conv;
732:   return(0);
733: }

737: /*@
738:    EPSGetConvergenceTest - Gets the method used to compute the error estimate
739:    used in the convergence test.

741:    Not Collective

743:    Input Parameters:
744: .  eps   - eigensolver context obtained from EPSCreate()

746:    Output Parameters:
747: .  conv  - the type of convergence test

749:    Level: intermediate

751: .seealso: EPSSetConvergenceTest(), EPSConv
752: @*/
753: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
754: {
758:   *conv = eps->conv;
759:   return(0);
760: }

764: /*@
765:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

767:    Logically Collective on EPS

769:    Input Parameters:
770: +  eps      - the eigensolver context
771: -  type     - a known type of eigenvalue problem

773:    Options Database Keys:
774: +  -eps_hermitian - Hermitian eigenvalue problem
775: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
776: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
777: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
778: -  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
779:    with positive semi-definite B

781:    Notes:
782:    Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
783:    (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
784:    (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
785:    (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).

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

794:    Level: intermediate

796: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
797: @*/
798: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
799: {
803:   switch (type) {
804:     case EPS_HEP:
805:       eps->isgeneralized = PETSC_FALSE;
806:       eps->ishermitian = PETSC_TRUE;
807:       eps->ispositive = PETSC_FALSE;
808:       break;
809:     case EPS_NHEP:
810:       eps->isgeneralized = PETSC_FALSE;
811:       eps->ishermitian = PETSC_FALSE;
812:       eps->ispositive = PETSC_FALSE;
813:       break;
814:     case EPS_GHEP:
815:       eps->isgeneralized = PETSC_TRUE;
816:       eps->ishermitian = PETSC_TRUE;
817:       eps->ispositive = PETSC_TRUE;
818:       break;
819:     case EPS_GNHEP:
820:       eps->isgeneralized = PETSC_TRUE;
821:       eps->ishermitian = PETSC_FALSE;
822:       eps->ispositive = PETSC_FALSE;
823:       break;
824:     case EPS_PGNHEP:
825:       eps->isgeneralized = PETSC_TRUE;
826:       eps->ishermitian = PETSC_FALSE;
827:       eps->ispositive = PETSC_TRUE;
828:       break;
829:     case EPS_GHIEP:
830:       eps->isgeneralized = PETSC_TRUE;
831:       eps->ishermitian = PETSC_TRUE;
832:       eps->ispositive = PETSC_FALSE;
833:       break;
834:     default:
835:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
836:   }
837:   eps->problem_type = type;
838:   return(0);
839: }

843: /*@
844:    EPSGetProblemType - Gets the problem type from the EPS object.

846:    Not Collective

848:    Input Parameter:
849: .  eps - the eigensolver context

851:    Output Parameter:
852: .  type - name of EPS problem type

854:    Level: intermediate

856: .seealso: EPSSetProblemType(), EPSProblemType
857: @*/
858: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
859: {
863:   *type = eps->problem_type;
864:   return(0);
865: }

869: /*@
870:    EPSSetExtraction - Specifies the type of extraction technique to be employed
871:    by the eigensolver.

873:    Logically Collective on EPS

875:    Input Parameters:
876: +  eps  - the eigensolver context
877: -  extr - a known type of extraction

879:    Options Database Keys:
880: +  -eps_ritz - Rayleigh-Ritz extraction
881: .  -eps_harmonic - harmonic Ritz extraction
882: .  -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
883: .  -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
884: .  -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
885:    (without target)
886: .  -eps_refined - refined Ritz extraction
887: -  -eps_refined_harmonic - refined harmonic Ritz extraction

889:    Notes:
890:    Not all eigensolvers support all types of extraction. See the SLEPc
891:    Users Manual for details.

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

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

898:    Level: advanced

900: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
901: @*/
902: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
903: {
907:   eps->extraction = extr;
908:   return(0);
909: }

913: /*@
914:    EPSGetExtraction - Gets the extraction type used by the EPS object.

916:    Not Collective

918:    Input Parameter:
919: .  eps - the eigensolver context

921:    Output Parameter:
922: .  extr - name of extraction type

924:    Level: advanced

926: .seealso: EPSSetExtraction(), EPSExtraction
927: @*/
928: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
929: {
933:   *extr = eps->extraction;
934:   return(0);
935: }

939: /*@
940:    EPSSetBalance - Specifies the balancing technique to be employed by the
941:    eigensolver, and some parameters associated to it.

943:    Logically Collective on EPS

945:    Input Parameters:
946: +  eps    - the eigensolver context
947: .  bal    - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
948:             EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
949: .  its    - number of iterations of the balancing algorithm
950: -  cutoff - cutoff value

952:    Options Database Keys:
953: +  -eps_balance <method> - the balancing method, where <method> is one of
954:                            'none', 'oneside', 'twoside', or 'user'
955: .  -eps_balance_its <its> - number of iterations
956: -  -eps_balance_cutoff <cutoff> - cutoff value

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

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

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

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

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

977:    Level: intermediate

979: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
980: @*/
981: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
982: {
988:   switch (bal) {
989:     case EPS_BALANCE_NONE:
990:     case EPS_BALANCE_ONESIDE:
991:     case EPS_BALANCE_TWOSIDE:
992:     case EPS_BALANCE_USER:
993:       eps->balance = bal;
994:       break;
995:     default:
996:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
997:   }
998:   if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
999:   else {
1000:     if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1001:     eps->balance_its = its;
1002:   }
1003:   if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1004:   else {
1005:     if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1006:     eps->balance_cutoff = cutoff;
1007:   }
1008:   return(0);
1009: }

1013: /*@
1014:    EPSGetBalance - Gets the balancing type used by the EPS object, and the
1015:    associated parameters.

1017:    Not Collective

1019:    Input Parameter:
1020: .  eps - the eigensolver context

1022:    Output Parameters:
1023: +  bal    - the balancing method
1024: .  its    - number of iterations of the balancing algorithm
1025: -  cutoff - cutoff value

1027:    Level: intermediate

1029:    Note:
1030:    The user can specify NULL for any parameter that is not needed.

1032: .seealso: EPSSetBalance(), EPSBalance
1033: @*/
1034: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1035: {
1038:   if (bal)    *bal = eps->balance;
1039:   if (its)    *its = eps->balance_its;
1040:   if (cutoff) *cutoff = eps->balance_cutoff;
1041:   return(0);
1042: }

1046: /*@
1047:    EPSSetTrueResidual - Specifies if the solver must compute the true residual
1048:    explicitly or not.

1050:    Logically Collective on EPS

1052:    Input Parameters:
1053: +  eps     - the eigensolver context
1054: -  trueres - whether true residuals are required or not

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

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

1069:    Level: advanced

1071: .seealso: EPSGetTrueResidual()
1072: @*/
1073: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1074: {
1078:   eps->trueres = trueres;
1079:   return(0);
1080: }

1084: /*@
1085:    EPSGetTrueResidual - Returns the flag indicating whether true
1086:    residuals must be computed explicitly or not.

1088:    Not Collective

1090:    Input Parameter:
1091: .  eps - the eigensolver context

1093:    Output Parameter:
1094: .  trueres - the returned flag

1096:    Level: advanced

1098: .seealso: EPSSetTrueResidual()
1099: @*/
1100: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1101: {
1105:   *trueres = eps->trueres;
1106:   return(0);
1107: }

1111: /*@
1112:    EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1113:    approximate eigenpairs or not.

1115:    Logically Collective on EPS

1117:    Input Parameters:
1118: +  eps      - the eigensolver context
1119: -  trackall - whether to compute all residuals or not

1121:    Notes:
1122:    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1123:    the residual norm for each eigenpair approximation. Computing the residual is
1124:    usually an expensive operation and solvers commonly compute only the residual
1125:    associated to the first unconverged eigenpair.

1127:    The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1128:    activate this option.

1130:    Level: developer

1132: .seealso: EPSGetTrackAll()
1133: @*/
1134: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1135: {
1139:   eps->trackall = trackall;
1140:   return(0);
1141: }

1145: /*@
1146:    EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1147:    be computed or not.

1149:    Not Collective

1151:    Input Parameter:
1152: .  eps - the eigensolver context

1154:    Output Parameter:
1155: .  trackall - the returned flag

1157:    Level: developer

1159: .seealso: EPSSetTrackAll()
1160: @*/
1161: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1162: {
1166:   *trackall = eps->trackall;
1167:   return(0);
1168: }

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

1175:    Logically Collective on EPS

1177:    Input Parameters:
1178: +  eps    - the eigensolver context
1179: -  purify - whether purification is required or not

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

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

1190:    Level: intermediate

1192: .seealso: EPSGetPurify(), EPSSetInterval()
1193: @*/
1194: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1195: {
1199:   eps->purify = purify;
1200:   return(0);
1201: }

1205: /*@
1206:    EPSGetPurify - Returns the flag indicating whether purification is activated
1207:    or not.

1209:    Not Collective

1211:    Input Parameter:
1212: .  eps - the eigensolver context

1214:    Output Parameter:
1215: .  purify - the returned flag

1217:    Level: intermediate

1219: .seealso: EPSSetPurify()
1220: @*/
1221: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1222: {
1226:   *purify = eps->purify;
1227:   return(0);
1228: }

1232: /*@C
1233:    EPSSetOptionsPrefix - Sets the prefix used for searching for all
1234:    EPS options in the database.

1236:    Logically Collective on EPS

1238:    Input Parameters:
1239: +  eps - the eigensolver context
1240: -  prefix - the prefix string to prepend to all EPS option requests

1242:    Notes:
1243:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1244:    The first character of all runtime options is AUTOMATICALLY the
1245:    hyphen.

1247:    For example, to distinguish between the runtime options for two
1248:    different EPS contexts, one could call
1249: .vb
1250:       EPSSetOptionsPrefix(eps1,"eig1_")
1251:       EPSSetOptionsPrefix(eps2,"eig2_")
1252: .ve

1254:    Level: advanced

1256: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1257: @*/
1258: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1259: {

1264:   if (!eps->st) { EPSGetST(eps,&eps->st); }
1265:   STSetOptionsPrefix(eps->st,prefix);
1266:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
1267:   BVSetOptionsPrefix(eps->V,prefix);
1268:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1269:   DSSetOptionsPrefix(eps->ds,prefix);
1270:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1271:   RGSetOptionsPrefix(eps->rg,prefix);
1272:   PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1273:   return(0);
1274: }

1278: /*@C
1279:    EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1280:    EPS options in the database.

1282:    Logically Collective on EPS

1284:    Input Parameters:
1285: +  eps - the eigensolver context
1286: -  prefix - the prefix string to prepend to all EPS option requests

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

1292:    Level: advanced

1294: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1295: @*/
1296: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1297: {

1302:   if (!eps->st) { EPSGetST(eps,&eps->st); }
1303:   STAppendOptionsPrefix(eps->st,prefix);
1304:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
1305:   BVSetOptionsPrefix(eps->V,prefix);
1306:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1307:   DSSetOptionsPrefix(eps->ds,prefix);
1308:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1309:   RGSetOptionsPrefix(eps->rg,prefix);
1310:   PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1311:   return(0);
1312: }

1316: /*@C
1317:    EPSGetOptionsPrefix - Gets the prefix used for searching for all
1318:    EPS options in the database.

1320:    Not Collective

1322:    Input Parameters:
1323: .  eps - the eigensolver context

1325:    Output Parameters:
1326: .  prefix - pointer to the prefix string used is returned

1328:    Notes: On the fortran side, the user should pass in a string 'prefix' of
1329:    sufficient length to hold the prefix.

1331:    Level: advanced

1333: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1334: @*/
1335: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1336: {

1342:   PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1343:   return(0);
1344: }