Actual source code: epsopts.c

slepc-3.7.4 2017-05-17
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-2016, 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*/
 26: #include <petscdraw.h>

 30: /*@C
 31:    EPSMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
 32:    indicated by the user.

 34:    Collective on EPS

 36:    Input Parameters:
 37: +  eps      - the eigensolver context
 38: .  name     - the monitor option name
 39: .  help     - message indicating what monitoring is done
 40: .  manual   - manual page for the monitor
 41: .  monitor  - the monitor function, whose context is a PetscViewerAndFormat
 42: -  trackall - whether this monitor tracks all eigenvalues or not

 44:    Level: developer

 46: .seealso: EPSMonitorSet(), EPSSetTrackAll(), EPSConvMonitorSetFromOptions()
 47: @*/
 48: PetscErrorCode EPSMonitorSetFromOptions(EPS eps,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*),PetscBool trackall)
 49: {
 50:   PetscErrorCode       ierr;
 51:   PetscBool            flg;
 52:   PetscViewer          viewer;
 53:   PetscViewerFormat    format;
 54:   PetscViewerAndFormat *vf;

 57:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->prefix,name,&viewer,&format,&flg);
 58:   if (flg) {
 59:     PetscViewerAndFormatCreate(viewer,format,&vf);
 60:     PetscObjectDereference((PetscObject)viewer);
 61:     EPSMonitorSet(eps,(PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
 62:     if (trackall) {
 63:       EPSSetTrackAll(eps,PETSC_TRUE);
 64:     }
 65:   }
 66:   return(0);
 67: }

 71: /*@C
 72:    EPSConvMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
 73:    indicated by the user (for monitors that only show iteration numbers of convergence).

 75:    Collective on EPS

 77:    Input Parameters:
 78: +  eps      - the eigensolver context
 79: .  name     - the monitor option name
 80: .  help     - message indicating what monitoring is done
 81: .  manual   - manual page for the monitor
 82: -  monitor  - the monitor function, whose context is a SlepcConvMonitor

 84:    Level: developer

 86: .seealso: EPSMonitorSet(), EPSMonitorSetFromOptions()
 87: @*/
 88: PetscErrorCode EPSConvMonitorSetFromOptions(EPS eps,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor))
 89: {
 90:   PetscErrorCode    ierr;
 91:   PetscBool         flg;
 92:   PetscViewer       viewer;
 93:   PetscViewerFormat format;
 94:   SlepcConvMonitor  ctx;

 97:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->prefix,name,&viewer,&format,&flg);
 98:   if (flg) {
 99:     SlepcConvMonitorCreate(viewer,format,&ctx);
100:     PetscObjectDereference((PetscObject)viewer);
101:     EPSMonitorSet(eps,(PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*))monitor,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
102:   }
103:   return(0);
104: }

108: /*@
109:    EPSSetFromOptions - Sets EPS options from the options database.
110:    This routine must be called before EPSSetUp() if the user is to be
111:    allowed to set the solver type.

113:    Collective on EPS

115:    Input Parameters:
116: .  eps - the eigensolver context

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

121:    Level: beginner
122: @*/
123: PetscErrorCode EPSSetFromOptions(EPS eps)
124: {
126:   char           type[256];
127:   PetscBool      set,flg,flg1,flg2,flg3;
128:   PetscReal      r,array[2]={0,0};
129:   PetscScalar    s;
130:   PetscInt       i,j,k;
131:   PetscDrawLG    lg;

135:   EPSRegisterAll();
136:   PetscObjectOptionsBegin((PetscObject)eps);
137:     PetscOptionsFList("-eps_type","Eigenvalue Problem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
138:     if (flg) {
139:       EPSSetType(eps,type);
140:     }
141:     /*
142:       Set the type if it was never set.
143:     */
144:     if (!((PetscObject)eps)->type_name) {
145:       EPSSetType(eps,EPSKRYLOVSCHUR);
146:     }

148:     PetscOptionsBoolGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);
149:     if (flg) { EPSSetProblemType(eps,EPS_HEP); }
150:     PetscOptionsBoolGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);
151:     if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
152:     PetscOptionsBoolGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
153:     if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
154:     PetscOptionsBoolGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
155:     if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
156:     PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
157:     if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
158:     PetscOptionsBoolGroupEnd("-eps_gen_indefinite","generalized hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
159:     if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }

161:     PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
162:     if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
163:     PetscOptionsBoolGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);
164:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
165:     PetscOptionsBoolGroup("-eps_harmonic_relative","relative harmonic Ritz extraction","EPSSetExtraction",&flg);
166:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
167:     PetscOptionsBoolGroup("-eps_harmonic_right","right harmonic Ritz extraction","EPSSetExtraction",&flg);
168:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
169:     PetscOptionsBoolGroup("-eps_harmonic_largest","largest harmonic Ritz extraction","EPSSetExtraction",&flg);
170:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
171:     PetscOptionsBoolGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);
172:     if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
173:     PetscOptionsBoolGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);
174:     if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }

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

178:     j = eps->balance_its;
179:     PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg1);
180:     r = eps->balance_cutoff;
181:     PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg2);
182:     if (flg1 || flg2) {
183:       EPSSetBalance(eps,eps->balance,j,r);
184:     }

186:     i = eps->max_it? eps->max_it: PETSC_DEFAULT;
187:     PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
188:     r = eps->tol;
189:     PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,&flg2);
190:     if (flg1 || flg2) {
191:       EPSSetTolerances(eps,r,i);
192:     }

194:     PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
195:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_REL); }
196:     PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
197:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
198:     PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
199:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
200:     PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
201:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_USER); }

203:     PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg);
204:     if (flg) { EPSSetStoppingTest(eps,EPS_STOP_BASIC); }
205:     PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg);
206:     if (flg) { EPSSetStoppingTest(eps,EPS_STOP_USER); }

208:     i = eps->nev;
209:     PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
210:     j = eps->ncv? eps->ncv: PETSC_DEFAULT;
211:     PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
212:     k = eps->mpd? eps->mpd: PETSC_DEFAULT;
213:     PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
214:     if (flg1 || flg2 || flg3) {
215:       EPSSetDimensions(eps,i,j,k);
216:     }

218:     /* -----------------------------------------------------------------------*/
219:     /*
220:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
221:     */
222:     PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
223:     if (set && flg) {
224:       EPSMonitorCancel(eps);
225:     }
226:     /*
227:       Text monitors
228:     */
229:     EPSMonitorSetFromOptions(eps,"-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorFirst",EPSMonitorFirst,PETSC_FALSE);
230:     EPSConvMonitorSetFromOptions(eps,"-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorConverged",EPSMonitorConverged);
231:     EPSMonitorSetFromOptions(eps,"-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorAll",EPSMonitorAll,PETSC_TRUE);
232:     /*
233:       Line graph monitors
234:     */
235:     PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",PETSC_FALSE,&flg,&set);
236:     if (set && flg) {
237:       EPSMonitorLGCreate(PetscObjectComm((PetscObject)eps),NULL,"Error estimates",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
238:       EPSMonitorSet(eps,EPSMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
239:     }
240:     PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",PETSC_FALSE,&flg,&set);
241:     if (set && flg) {
242:       EPSMonitorLGCreate(PetscObjectComm((PetscObject)eps),NULL,"Error estimates",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
243:       EPSMonitorSet(eps,EPSMonitorLGAll,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
244:       EPSSetTrackAll(eps,PETSC_TRUE);
245:     }
246:   /* -----------------------------------------------------------------------*/
247:     PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
248:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
249:     PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
250:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
251:     PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
252:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
253:     PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
254:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
255:     PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
256:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
257:     PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
258:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
259:     PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);
260:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
261:     PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);
262:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
263:     PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);
264:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
265:     PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg);
266:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }

268:     PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
269:     if (flg) {
270:       if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) {
271:         EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
272:       }
273:       EPSSetTarget(eps,s);
274:     }
275:     k = 2;
276:     PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
277:     if (flg) {
278:       if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
279:       EPSSetWhichEigenpairs(eps,EPS_ALL);
280:       EPSSetInterval(eps,array[0],array[1]);
281:     }

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

286:     PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
287:     PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
288:     PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
289:     PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSReasonView",NULL);
290:     PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
291:     PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
292:     PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);

294:     if (eps->ops->setfromoptions) {
295:       (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
296:     }
297:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)eps);
298:   PetscOptionsEnd();

300:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
301:   BVSetFromOptions(eps->V);
302:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
303:   RGSetFromOptions(eps->rg);
304:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
305:   DSSetFromOptions(eps->ds);
306:   if (!eps->st) { EPSGetST(eps,&eps->st); }
307:   STSetFromOptions(eps->st);
308:   return(0);
309: }

313: /*@
314:    EPSGetTolerances - Gets the tolerance and maximum iteration count used
315:    by the EPS convergence tests.

317:    Not Collective

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

322:    Output Parameters:
323: +  tol - the convergence tolerance
324: -  maxits - maximum number of iterations

326:    Notes:
327:    The user can specify NULL for any parameter that is not needed.

329:    Level: intermediate

331: .seealso: EPSSetTolerances()
332: @*/
333: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
334: {
337:   if (tol)    *tol    = eps->tol;
338:   if (maxits) *maxits = eps->max_it;
339:   return(0);
340: }

344: /*@
345:    EPSSetTolerances - Sets the tolerance and maximum iteration count used
346:    by the EPS convergence tests.

348:    Logically Collective on EPS

350:    Input Parameters:
351: +  eps - the eigensolver context
352: .  tol - the convergence tolerance
353: -  maxits - maximum number of iterations to use

355:    Options Database Keys:
356: +  -eps_tol <tol> - Sets the convergence tolerance
357: -  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

359:    Notes:
360:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

362:    Level: intermediate

364: .seealso: EPSGetTolerances()
365: @*/
366: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
367: {
372:   if (tol == PETSC_DEFAULT) {
373:     eps->tol   = PETSC_DEFAULT;
374:     eps->state = EPS_STATE_INITIAL;
375:   } else {
376:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
377:     eps->tol = tol;
378:   }
379:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
380:     eps->max_it = 0;
381:     eps->state  = EPS_STATE_INITIAL;
382:   } else {
383:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
384:     eps->max_it = maxits;
385:   }
386:   return(0);
387: }

391: /*@
392:    EPSGetDimensions - Gets the number of eigenvalues to compute
393:    and the dimension of the subspace.

395:    Not Collective

397:    Input Parameter:
398: .  eps - the eigensolver context

400:    Output Parameters:
401: +  nev - number of eigenvalues to compute
402: .  ncv - the maximum dimension of the subspace to be used by the solver
403: -  mpd - the maximum dimension allowed for the projected problem

405:    Level: intermediate

407: .seealso: EPSSetDimensions()
408: @*/
409: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
410: {
413:   if (nev) *nev = eps->nev;
414:   if (ncv) *ncv = eps->ncv;
415:   if (mpd) *mpd = eps->mpd;
416:   return(0);
417: }

421: /*@
422:    EPSSetDimensions - Sets the number of eigenvalues to compute
423:    and the dimension of the subspace.

425:    Logically Collective on EPS

427:    Input Parameters:
428: +  eps - the eigensolver context
429: .  nev - number of eigenvalues to compute
430: .  ncv - the maximum dimension of the subspace to be used by the solver
431: -  mpd - the maximum dimension allowed for the projected problem

433:    Options Database Keys:
434: +  -eps_nev <nev> - Sets the number of eigenvalues
435: .  -eps_ncv <ncv> - Sets the dimension of the subspace
436: -  -eps_mpd <mpd> - Sets the maximum projected dimension

438:    Notes:
439:    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
440:    dependent on the solution method.

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

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

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

455:    Level: intermediate

457: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
458: @*/
459: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
460: {
466:   if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
467:   eps->nev = nev;
468:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
469:     eps->ncv = 0;
470:   } else {
471:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
472:     eps->ncv = ncv;
473:   }
474:   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
475:     eps->mpd = 0;
476:   } else {
477:     if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
478:     eps->mpd = mpd;
479:   }
480:   eps->state = EPS_STATE_INITIAL;
481:   return(0);
482: }

486: /*@
487:    EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
488:    to be sought.

490:    Logically Collective on EPS

492:    Input Parameters:
493: +  eps   - eigensolver context obtained from EPSCreate()
494: -  which - the portion of the spectrum to be sought

496:    Possible values:
497:    The parameter 'which' can have one of these values

499: +     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
500: .     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
501: .     EPS_LARGEST_REAL - largest real parts
502: .     EPS_SMALLEST_REAL - smallest real parts
503: .     EPS_LARGEST_IMAGINARY - largest imaginary parts
504: .     EPS_SMALLEST_IMAGINARY - smallest imaginary parts
505: .     EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
506: .     EPS_TARGET_REAL - eigenvalues with real part closest to target
507: .     EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
508: .     EPS_ALL - all eigenvalues contained in a given interval or region
509: -     EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()

511:    Options Database Keys:
512: +   -eps_largest_magnitude - Sets largest eigenvalues in magnitude
513: .   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
514: .   -eps_largest_real - Sets largest real parts
515: .   -eps_smallest_real - Sets smallest real parts
516: .   -eps_largest_imaginary - Sets largest imaginary parts
517: .   -eps_smallest_imaginary - Sets smallest imaginary parts
518: .   -eps_target_magnitude - Sets eigenvalues closest to target
519: .   -eps_target_real - Sets real parts closest to target
520: .   -eps_target_imaginary - Sets imaginary parts closest to target
521: -   -eps_all - Sets all eigenvalues in an interval or region

523:    Notes:
524:    Not all eigensolvers implemented in EPS account for all the possible values
525:    stated above. Also, some values make sense only for certain types of
526:    problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
527:    and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
528:    for eigenvalue selection.

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

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

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

541:    Level: intermediate

543: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
544:           EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
545: @*/
546: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
547: {
551:   switch (which) {
552:     case EPS_LARGEST_MAGNITUDE:
553:     case EPS_SMALLEST_MAGNITUDE:
554:     case EPS_LARGEST_REAL:
555:     case EPS_SMALLEST_REAL:
556:     case EPS_LARGEST_IMAGINARY:
557:     case EPS_SMALLEST_IMAGINARY:
558:     case EPS_TARGET_MAGNITUDE:
559:     case EPS_TARGET_REAL:
560: #if defined(PETSC_USE_COMPLEX)
561:     case EPS_TARGET_IMAGINARY:
562: #endif
563:     case EPS_ALL:
564:     case EPS_WHICH_USER:
565:       if (eps->which != which) {
566:         eps->state = EPS_STATE_INITIAL;
567:         eps->which = which;
568:       }
569:       break;
570:     default:
571:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
572:   }
573:   return(0);
574: }

578: /*@
579:    EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
580:    sought.

582:    Not Collective

584:    Input Parameter:
585: .  eps - eigensolver context obtained from EPSCreate()

587:    Output Parameter:
588: .  which - the portion of the spectrum to be sought

590:    Notes:
591:    See EPSSetWhichEigenpairs() for possible values of 'which'.

593:    Level: intermediate

595: .seealso: EPSSetWhichEigenpairs(), EPSWhich
596: @*/
597: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
598: {
602:   *which = eps->which;
603:   return(0);
604: }

608: /*@C
609:    EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
610:    when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.

612:    Logically Collective on EPS

614:    Input Parameters:
615: +  eps  - eigensolver context obtained from EPSCreate()
616: .  func - a pointer to the comparison function
617: -  ctx  - a context pointer (the last parameter to the comparison function)

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

622: +   ar     - real part of the 1st eigenvalue
623: .   ai     - imaginary part of the 1st eigenvalue
624: .   br     - real part of the 2nd eigenvalue
625: .   bi     - imaginary part of the 2nd eigenvalue
626: .   res    - result of comparison
627: -   ctx    - optional context, as set by EPSSetEigenvalueComparison()

629:    Note:
630:    The returning parameter 'res' can be
631: +  negative - if the 1st eigenvalue is preferred to the 2st one
632: .  zero     - if both eigenvalues are equally preferred
633: -  positive - if the 2st eigenvalue is preferred to the 1st one

635:    Level: advanced

637: .seealso: EPSSetWhichEigenpairs(), EPSWhich
638: @*/
639: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
640: {
643:   eps->sc->comparison    = func;
644:   eps->sc->comparisonctx = ctx;
645:   eps->which             = EPS_WHICH_USER;
646:   return(0);
647: }

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

656:    Logically Collective on EPS

658:    Input Parameters:
659: +  eps  - eigensolver context obtained from EPSCreate()
660: .  func - a pointer to the evaluation function
661: -  ctx  - a context pointer (the last parameter to the evaluation function)

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

666: +   er     - real part of the current eigenvalue approximation
667: .   ei     - imaginary part of the current eigenvalue approximation
668: .   xr     - real part of the current eigenvector approximation
669: .   xi     - imaginary part of the current eigenvector approximation
670: .   rr     - result of evaluation (real part)
671: .   ri     - result of evaluation (imaginary part)
672: -   ctx    - optional context, as set by EPSSetArbitrarySelection()

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

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

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

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

694:    Level: advanced

696: .seealso: EPSSetWhichEigenpairs()
697: @*/
698: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
699: {
702:   eps->arbitrary    = func;
703:   eps->arbitraryctx = ctx;
704:   eps->state        = EPS_STATE_INITIAL;
705:   return(0);
706: }

710: /*@C
711:    EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
712:    used in the convergence test.

714:    Logically Collective on EPS

716:    Input Parameters:
717: +  eps     - eigensolver context obtained from EPSCreate()
718: .  func    - a pointer to the convergence test function
719: .  ctx     - context for private data for the convergence routine (may be null)
720: -  destroy - a routine for destroying the context (may be null)

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

725: +   eps    - eigensolver context obtained from EPSCreate()
726: .   eigr   - real part of the eigenvalue
727: .   eigi   - imaginary part of the eigenvalue
728: .   res    - residual norm associated to the eigenpair
729: .   errest - (output) computed error estimate
730: -   ctx    - optional context, as set by EPSSetConvergenceTestFunction()

732:    Note:
733:    If the error estimate returned by the convergence test function is less than
734:    the tolerance, then the eigenvalue is accepted as converged.

736:    Level: advanced

738: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
739: @*/
740: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
741: {

746:   if (eps->convergeddestroy) {
747:     (*eps->convergeddestroy)(eps->convergedctx);
748:   }
749:   eps->converged        = func;
750:   eps->convergeddestroy = destroy;
751:   eps->convergedctx     = ctx;
752:   if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
753:   else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
754:   else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
755:   else eps->conv = EPS_CONV_USER;
756:   return(0);
757: }

761: /*@
762:    EPSSetConvergenceTest - Specifies how to compute the error estimate
763:    used in the convergence test.

765:    Logically Collective on EPS

767:    Input Parameters:
768: +  eps  - eigensolver context obtained from EPSCreate()
769: -  conv - the type of convergence test

771:    Options Database Keys:
772: +  -eps_conv_abs  - Sets the absolute convergence test
773: .  -eps_conv_rel  - Sets the convergence test relative to the eigenvalue
774: .  -eps_conv_norm - Sets the convergence test relative to the matrix norms
775: -  -eps_conv_user - Selects the user-defined convergence test

777:    Note:
778:    The parameter 'conv' can have one of these values
779: +     EPS_CONV_ABS  - absolute error ||r||
780: .     EPS_CONV_REL  - error relative to the eigenvalue l, ||r||/|l|
781: .     EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
782: -     EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()

784:    Level: intermediate

786: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
787: @*/
788: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
789: {
793:   switch (conv) {
794:     case EPS_CONV_ABS:  eps->converged = EPSConvergedAbsolute; break;
795:     case EPS_CONV_REL:  eps->converged = EPSConvergedRelative; break;
796:     case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
797:     case EPS_CONV_USER: break;
798:     default:
799:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
800:   }
801:   eps->conv = conv;
802:   return(0);
803: }

807: /*@
808:    EPSGetConvergenceTest - Gets the method used to compute the error estimate
809:    used in the convergence test.

811:    Not Collective

813:    Input Parameters:
814: .  eps   - eigensolver context obtained from EPSCreate()

816:    Output Parameters:
817: .  conv  - the type of convergence test

819:    Level: intermediate

821: .seealso: EPSSetConvergenceTest(), EPSConv
822: @*/
823: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
824: {
828:   *conv = eps->conv;
829:   return(0);
830: }

834: /*@C
835:    EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
836:    iteration of the eigensolver.

838:    Logically Collective on EPS

840:    Input Parameters:
841: +  eps     - eigensolver context obtained from EPSCreate()
842: .  func    - pointer to the stopping test function
843: .  ctx     - context for private data for the stopping routine (may be null)
844: -  destroy - a routine for destroying the context (may be null)

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

849: +   eps    - eigensolver context obtained from EPSCreate()
850: .   its    - current number of iterations
851: .   max_it - maximum number of iterations
852: .   nconv  - number of currently converged eigenpairs
853: .   nev    - number of requested eigenpairs
854: .   reason - (output) result of the stopping test
855: -   ctx    - optional context, as set by EPSSetStoppingTestFunction()

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

863:    Level: advanced

865: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
866: @*/
867: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
868: {

873:   if (eps->stoppingdestroy) {
874:     (*eps->stoppingdestroy)(eps->stoppingctx);
875:   }
876:   eps->stopping        = func;
877:   eps->stoppingdestroy = destroy;
878:   eps->stoppingctx     = ctx;
879:   if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
880:   else eps->stop = EPS_STOP_USER;
881:   return(0);
882: }

886: /*@
887:    EPSSetStoppingTest - Specifies how to decide the termination of the outer
888:    loop of the eigensolver.

890:    Logically Collective on EPS

892:    Input Parameters:
893: +  eps  - eigensolver context obtained from EPSCreate()
894: -  stop - the type of stopping test

896:    Options Database Keys:
897: +  -eps_stop_basic - Sets the default stopping test
898: -  -eps_stop_user  - Selects the user-defined stopping test

900:    Note:
901:    The parameter 'stop' can have one of these values
902: +     EPS_STOP_BASIC - default stopping test
903: -     EPS_STOP_USER  - function set by EPSSetStoppingTestFunction()

905:    Level: advanced

907: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
908: @*/
909: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
910: {
914:   switch (stop) {
915:     case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
916:     case EPS_STOP_USER:  break;
917:     default:
918:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
919:   }
920:   eps->stop = stop;
921:   return(0);
922: }

926: /*@
927:    EPSGetStoppingTest - Gets the method used to decide the termination of the outer
928:    loop of the eigensolver.

930:    Not Collective

932:    Input Parameters:
933: .  eps   - eigensolver context obtained from EPSCreate()

935:    Output Parameters:
936: .  stop  - the type of stopping test

938:    Level: advanced

940: .seealso: EPSSetStoppingTest(), EPSStop
941: @*/
942: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
943: {
947:   *stop = eps->stop;
948:   return(0);
949: }

953: /*@
954:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

956:    Logically Collective on EPS

958:    Input Parameters:
959: +  eps      - the eigensolver context
960: -  type     - a known type of eigenvalue problem

962:    Options Database Keys:
963: +  -eps_hermitian - Hermitian eigenvalue problem
964: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
965: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
966: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
967: -  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
968:    with positive semi-definite B

970:    Notes:
971:    Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
972:    (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
973:    (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
974:    (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).

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

983:    Level: intermediate

985: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
986: @*/
987: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
988: {
992:   if (type == eps->problem_type) return(0);
993:   switch (type) {
994:     case EPS_HEP:
995:       eps->isgeneralized = PETSC_FALSE;
996:       eps->ishermitian = PETSC_TRUE;
997:       eps->ispositive = PETSC_FALSE;
998:       break;
999:     case EPS_NHEP:
1000:       eps->isgeneralized = PETSC_FALSE;
1001:       eps->ishermitian = PETSC_FALSE;
1002:       eps->ispositive = PETSC_FALSE;
1003:       break;
1004:     case EPS_GHEP:
1005:       eps->isgeneralized = PETSC_TRUE;
1006:       eps->ishermitian = PETSC_TRUE;
1007:       eps->ispositive = PETSC_TRUE;
1008:       break;
1009:     case EPS_GNHEP:
1010:       eps->isgeneralized = PETSC_TRUE;
1011:       eps->ishermitian = PETSC_FALSE;
1012:       eps->ispositive = PETSC_FALSE;
1013:       break;
1014:     case EPS_PGNHEP:
1015:       eps->isgeneralized = PETSC_TRUE;
1016:       eps->ishermitian = PETSC_FALSE;
1017:       eps->ispositive = PETSC_TRUE;
1018:       break;
1019:     case EPS_GHIEP:
1020:       eps->isgeneralized = PETSC_TRUE;
1021:       eps->ishermitian = PETSC_TRUE;
1022:       eps->ispositive = PETSC_FALSE;
1023:       break;
1024:     default:
1025:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
1026:   }
1027:   eps->problem_type = type;
1028:   eps->state = EPS_STATE_INITIAL;
1029:   return(0);
1030: }

1034: /*@
1035:    EPSGetProblemType - Gets the problem type from the EPS object.

1037:    Not Collective

1039:    Input Parameter:
1040: .  eps - the eigensolver context

1042:    Output Parameter:
1043: .  type - name of EPS problem type

1045:    Level: intermediate

1047: .seealso: EPSSetProblemType(), EPSProblemType
1048: @*/
1049: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
1050: {
1054:   *type = eps->problem_type;
1055:   return(0);
1056: }

1060: /*@
1061:    EPSSetExtraction - Specifies the type of extraction technique to be employed
1062:    by the eigensolver.

1064:    Logically Collective on EPS

1066:    Input Parameters:
1067: +  eps  - the eigensolver context
1068: -  extr - a known type of extraction

1070:    Options Database Keys:
1071: +  -eps_ritz - Rayleigh-Ritz extraction
1072: .  -eps_harmonic - harmonic Ritz extraction
1073: .  -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
1074: .  -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
1075: .  -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
1076:    (without target)
1077: .  -eps_refined - refined Ritz extraction
1078: -  -eps_refined_harmonic - refined harmonic Ritz extraction

1080:    Notes:
1081:    Not all eigensolvers support all types of extraction. See the SLEPc
1082:    Users Manual for details.

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

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

1089:    Level: advanced

1091: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
1092: @*/
1093: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
1094: {
1098:   eps->extraction = extr;
1099:   return(0);
1100: }

1104: /*@
1105:    EPSGetExtraction - Gets the extraction type used by the EPS object.

1107:    Not Collective

1109:    Input Parameter:
1110: .  eps - the eigensolver context

1112:    Output Parameter:
1113: .  extr - name of extraction type

1115:    Level: advanced

1117: .seealso: EPSSetExtraction(), EPSExtraction
1118: @*/
1119: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1120: {
1124:   *extr = eps->extraction;
1125:   return(0);
1126: }

1130: /*@
1131:    EPSSetBalance - Specifies the balancing technique to be employed by the
1132:    eigensolver, and some parameters associated to it.

1134:    Logically Collective on EPS

1136:    Input Parameters:
1137: +  eps    - the eigensolver context
1138: .  bal    - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1139:             EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1140: .  its    - number of iterations of the balancing algorithm
1141: -  cutoff - cutoff value

1143:    Options Database Keys:
1144: +  -eps_balance <method> - the balancing method, where <method> is one of
1145:                            'none', 'oneside', 'twoside', or 'user'
1146: .  -eps_balance_its <its> - number of iterations
1147: -  -eps_balance_cutoff <cutoff> - cutoff value

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

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

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

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

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

1168:    Level: intermediate

1170: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1171: @*/
1172: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1173: {
1179:   switch (bal) {
1180:     case EPS_BALANCE_NONE:
1181:     case EPS_BALANCE_ONESIDE:
1182:     case EPS_BALANCE_TWOSIDE:
1183:     case EPS_BALANCE_USER:
1184:       eps->balance = bal;
1185:       break;
1186:     default:
1187:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1188:   }
1189:   if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1190:   else {
1191:     if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1192:     eps->balance_its = its;
1193:   }
1194:   if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1195:   else {
1196:     if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1197:     eps->balance_cutoff = cutoff;
1198:   }
1199:   return(0);
1200: }

1204: /*@
1205:    EPSGetBalance - Gets the balancing type used by the EPS object, and the
1206:    associated parameters.

1208:    Not Collective

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

1213:    Output Parameters:
1214: +  bal    - the balancing method
1215: .  its    - number of iterations of the balancing algorithm
1216: -  cutoff - cutoff value

1218:    Level: intermediate

1220:    Note:
1221:    The user can specify NULL for any parameter that is not needed.

1223: .seealso: EPSSetBalance(), EPSBalance
1224: @*/
1225: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1226: {
1229:   if (bal)    *bal = eps->balance;
1230:   if (its)    *its = eps->balance_its;
1231:   if (cutoff) *cutoff = eps->balance_cutoff;
1232:   return(0);
1233: }

1237: /*@
1238:    EPSSetTrueResidual - Specifies if the solver must compute the true residual
1239:    explicitly or not.

1241:    Logically Collective on EPS

1243:    Input Parameters:
1244: +  eps     - the eigensolver context
1245: -  trueres - whether true residuals are required or not

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

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

1260:    Level: advanced

1262: .seealso: EPSGetTrueResidual()
1263: @*/
1264: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1265: {
1269:   eps->trueres = trueres;
1270:   return(0);
1271: }

1275: /*@
1276:    EPSGetTrueResidual - Returns the flag indicating whether true
1277:    residuals must be computed explicitly or not.

1279:    Not Collective

1281:    Input Parameter:
1282: .  eps - the eigensolver context

1284:    Output Parameter:
1285: .  trueres - the returned flag

1287:    Level: advanced

1289: .seealso: EPSSetTrueResidual()
1290: @*/
1291: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1292: {
1296:   *trueres = eps->trueres;
1297:   return(0);
1298: }

1302: /*@
1303:    EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1304:    approximate eigenpairs or not.

1306:    Logically Collective on EPS

1308:    Input Parameters:
1309: +  eps      - the eigensolver context
1310: -  trackall - whether to compute all residuals or not

1312:    Notes:
1313:    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1314:    the residual norm for each eigenpair approximation. Computing the residual is
1315:    usually an expensive operation and solvers commonly compute only the residual
1316:    associated to the first unconverged eigenpair.

1318:    The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1319:    activate this option.

1321:    Level: developer

1323: .seealso: EPSGetTrackAll()
1324: @*/
1325: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1326: {
1330:   eps->trackall = trackall;
1331:   return(0);
1332: }

1336: /*@
1337:    EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1338:    be computed or not.

1340:    Not Collective

1342:    Input Parameter:
1343: .  eps - the eigensolver context

1345:    Output Parameter:
1346: .  trackall - the returned flag

1348:    Level: developer

1350: .seealso: EPSSetTrackAll()
1351: @*/
1352: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1353: {
1357:   *trackall = eps->trackall;
1358:   return(0);
1359: }

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

1366:    Logically Collective on EPS

1368:    Input Parameters:
1369: +  eps    - the eigensolver context
1370: -  purify - whether purification is required or not

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

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

1381:    Level: intermediate

1383: .seealso: EPSGetPurify(), EPSSetInterval()
1384: @*/
1385: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1386: {
1390:   eps->purify = purify;
1391:   return(0);
1392: }

1396: /*@
1397:    EPSGetPurify - Returns the flag indicating whether purification is activated
1398:    or not.

1400:    Not Collective

1402:    Input Parameter:
1403: .  eps - the eigensolver context

1405:    Output Parameter:
1406: .  purify - the returned flag

1408:    Level: intermediate

1410: .seealso: EPSSetPurify()
1411: @*/
1412: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1413: {
1417:   *purify = eps->purify;
1418:   return(0);
1419: }

1423: /*@C
1424:    EPSSetOptionsPrefix - Sets the prefix used for searching for all
1425:    EPS options in the database.

1427:    Logically Collective on EPS

1429:    Input Parameters:
1430: +  eps - the eigensolver context
1431: -  prefix - the prefix string to prepend to all EPS option requests

1433:    Notes:
1434:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1435:    The first character of all runtime options is AUTOMATICALLY the
1436:    hyphen.

1438:    For example, to distinguish between the runtime options for two
1439:    different EPS contexts, one could call
1440: .vb
1441:       EPSSetOptionsPrefix(eps1,"eig1_")
1442:       EPSSetOptionsPrefix(eps2,"eig2_")
1443: .ve

1445:    Level: advanced

1447: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1448: @*/
1449: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1450: {

1455:   if (!eps->st) { EPSGetST(eps,&eps->st); }
1456:   STSetOptionsPrefix(eps->st,prefix);
1457:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
1458:   BVSetOptionsPrefix(eps->V,prefix);
1459:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1460:   DSSetOptionsPrefix(eps->ds,prefix);
1461:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1462:   RGSetOptionsPrefix(eps->rg,prefix);
1463:   PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1464:   return(0);
1465: }

1469: /*@C
1470:    EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1471:    EPS options in the database.

1473:    Logically Collective on EPS

1475:    Input Parameters:
1476: +  eps - the eigensolver context
1477: -  prefix - the prefix string to prepend to all EPS option requests

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

1483:    Level: advanced

1485: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1486: @*/
1487: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1488: {

1493:   if (!eps->st) { EPSGetST(eps,&eps->st); }
1494:   STAppendOptionsPrefix(eps->st,prefix);
1495:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
1496:   BVSetOptionsPrefix(eps->V,prefix);
1497:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1498:   DSSetOptionsPrefix(eps->ds,prefix);
1499:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
1500:   RGSetOptionsPrefix(eps->rg,prefix);
1501:   PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1502:   return(0);
1503: }

1507: /*@C
1508:    EPSGetOptionsPrefix - Gets the prefix used for searching for all
1509:    EPS options in the database.

1511:    Not Collective

1513:    Input Parameters:
1514: .  eps - the eigensolver context

1516:    Output Parameters:
1517: .  prefix - pointer to the prefix string used is returned

1519:    Note:
1520:    On the Fortran side, the user should pass in a string 'prefix' of
1521:    sufficient length to hold the prefix.

1523:    Level: advanced

1525: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1526: @*/
1527: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1528: {

1534:   PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1535:   return(0);
1536: }