Actual source code: opts.c

  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-2013, 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,val;
 49:   PetscReal        r,nrma,nrmb,array[2]={0,0};
 50:   PetscScalar      s;
 51:   PetscInt         i,j,k;
 52:   const char       *bal_list[4] = {"none","oneside","twoside","user"};
 53:   PetscViewer      monviewer;
 54:   SlepcConvMonitor ctx;

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

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

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

 99:     if (!eps->balance) eps->balance = EPS_BALANCE_NONE;
100:     PetscOptionsEList("-eps_balance","Balancing method","EPSSetBalance",bal_list,4,bal_list[eps->balance-EPS_BALANCE_NONE],&i,&flg);
101:     if (flg) eps->balance = (EPSBalance)(i+EPS_BALANCE_NONE);
102:     r = j = 0;
103:     PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,NULL);
104:     PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,NULL);
105:     EPSSetBalance(eps,(EPSBalance)0,j,r);

107:     r = i = 0;
108:     PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,NULL);
109:     PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,NULL);
110:     EPSSetTolerances(eps,r,i);
111:     PetscOptionsBoolGroupBegin("-eps_conv_eig","Relative error convergence test","EPSSetConvergenceTest",&flg);
112:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_EIG); }
113:     PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
114:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
115:     PetscOptionsBoolGroupEnd("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
116:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }

118:     i = j = k = 0;
119:     PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,NULL);
120:     PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,NULL);
121:     PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,NULL);
122:     EPSSetDimensions(eps,i,j,k);

124:     /* -----------------------------------------------------------------------*/
125:     /*
126:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
127:     */
128:     flg  = PETSC_FALSE;
129:     PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",flg,&flg,NULL);
130:     if (flg) {
131:       EPSMonitorCancel(eps);
132:     }
133:     /*
134:       Prints approximate eigenvalues and error estimates at each iteration
135:     */
136:     PetscOptionsString("-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
137:     if (flg) {
138:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
139:       EPSMonitorSet(eps,EPSMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
140:     }
141:     PetscOptionsString("-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
142:     if (flg) {
143:       PetscNew(struct _n_SlepcConvMonitor,&ctx);
144:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&ctx->viewer);
145:       EPSMonitorSet(eps,EPSMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
146:     }
147:     PetscOptionsString("-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
148:     if (flg) {
149:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)eps),monfilename,&monviewer);
150:       EPSMonitorSet(eps,EPSMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
151:       EPSSetTrackAll(eps,PETSC_TRUE);
152:     }
153:     flg = PETSC_FALSE;
154:     PetscOptionsBool("-eps_monitor_lg","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",flg,&flg,NULL);
155:     if (flg) {
156:       EPSMonitorSet(eps,EPSMonitorLG,NULL,NULL);
157:     }
158:     flg = PETSC_FALSE;
159:     PetscOptionsBool("-eps_monitor_lg_all","Monitor error estimates graphically","EPSMonitorSet",flg,&flg,NULL);
160:     if (flg) {
161:       EPSMonitorSet(eps,EPSMonitorLGAll,NULL,NULL);
162:       EPSSetTrackAll(eps,PETSC_TRUE);
163:     }
164:   /* -----------------------------------------------------------------------*/
165:     PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
166:     if (flg) {
167:       EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
168:       EPSSetTarget(eps,s);
169:     }
170:     k = 2;
171:     PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
172:     if (flg) {
173:       if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
174:       EPSSetWhichEigenpairs(eps,EPS_ALL);
175:       EPSSetInterval(eps,array[0],array[1]);
176:     }

178:     PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
179:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE); }
180:     PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
181:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE); }
182:     PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
183:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL); }
184:     PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
185:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL); }
186:     PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
187:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY); }
188:     PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
189:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY); }
190:     PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);
191:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE); }
192:     PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);
193:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL); }
194:     PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);
195:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY); }
196:     PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval","EPSSetWhichEigenpairs",&flg);
197:     if (flg) { EPSSetWhichEigenpairs(eps,EPS_ALL); }

199:     PetscOptionsBool("-eps_left_vectors","Compute left eigenvectors also","EPSSetLeftVectorsWanted",eps->leftvecs,&val,&flg);
200:     if (flg) {
201:       EPSSetLeftVectorsWanted(eps,val);
202:     }
203:     PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&val,&flg);
204:     if (flg) {
205:       EPSSetTrueResidual(eps,val);
206:     }

208:     nrma = nrmb = 0;
209:     PetscOptionsReal("-eps_norm_a","Norm of matrix A","EPSSetMatrixNorms",eps->nrma,&nrma,NULL);
210:     PetscOptionsReal("-eps_norm_b","Norm of matrix B","EPSSetMatrixNorms",eps->nrmb,&nrmb,NULL);
211:     EPSSetMatrixNorms(eps,nrma,nrmb,eps->adaptive);
212:     PetscOptionsBool("-eps_norms_adaptive","Update the value of matrix norms adaptively","EPSSetMatrixNorms",eps->adaptive,&val,&flg);
213:     if (flg) {
214:       EPSSetMatrixNorms(eps,0,0,val);
215:     }

217:     PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",0);
218:     PetscOptionsName("-eps_plot_eigs","Make a plot of the computed eigenvalues","EPSSolve",0);

220:     if (eps->ops->setfromoptions) {
221:       (*eps->ops->setfromoptions)(eps);
222:     }
223:     PetscObjectProcessOptionsHandlers((PetscObject)eps);
224:   PetscOptionsEnd();

226:   if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
227:   IPSetFromOptions(eps->ip);
228:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
229:   DSSetFromOptions(eps->ds);
230:   STSetFromOptions(eps->st);
231:   PetscRandomSetFromOptions(eps->rand);
232:   return(0);
233: }

237: /*@
238:    EPSGetTolerances - Gets the tolerance and maximum iteration count used
239:    by the EPS convergence tests.

241:    Not Collective

243:    Input Parameter:
244: .  eps - the eigensolver context

246:    Output Parameters:
247: +  tol - the convergence tolerance
248: -  maxits - maximum number of iterations

250:    Notes:
251:    The user can specify NULL for any parameter that is not needed.

253:    Level: intermediate

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

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

272:    Logically Collective on EPS

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

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

283:    Notes:
284:    Pass 0 for an argument that need not be changed.

286:    Use PETSC_DECIDE for maxits to assign a reasonably good value, which is
287:    dependent on the solution method.

289:    Level: intermediate

291: .seealso: EPSGetTolerances()
292: @*/
293: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
294: {
299:   if (tol) {
300:     if (tol == PETSC_DEFAULT) {
301:       eps->tol = PETSC_DEFAULT;
302:     } else {
303:       if (tol < 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
304:       eps->tol = tol;
305:     }
306:   }
307:   if (maxits) {
308:     if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
309:       eps->max_it = 0;
310:       eps->setupcalled = 0;
311:     } else {
312:       if (maxits < 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
313:       eps->max_it = maxits;
314:     }
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:    Notes:
336:    The user can specify NULL for any parameter that is not needed.

338:    Level: intermediate

340: .seealso: EPSSetDimensions()
341: @*/
342: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
343: {
346:   if (nev) *nev = eps->nev;
347:   if (ncv) *ncv = eps->ncv;
348:   if (mpd) *mpd = eps->mpd;
349:   return(0);
350: }

354: /*@
355:    EPSSetDimensions - Sets the number of eigenvalues to compute
356:    and the dimension of the subspace.

358:    Logically Collective on EPS

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

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

371:    Notes:
372:    Pass 0 to retain the previous value of any parameter.

374:    Use PETSC_DECIDE for ncv and mpd to assign a reasonably good value, which is
375:    dependent on the solution method.

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

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

386:    When computing all eigenvalues in an interval, see EPSSetInterval(), the
387:    meaning of nev changes. In that case, the number of eigenvalues in the
388:    interval is not known a priori; the meaning of nev is then the number of
389:    eigenvalues that are computed at a time when sweeping the interval from one
390:    end to the other. The value of nev in this case may have an impact on overall
391:    performance. The value of ncv should not be assigned in this case.

393:    Level: intermediate

395: .seealso: EPSGetDimensions(), EPSSetInterval()
396: @*/
397: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
398: {
404:   if (nev) {
405:     if (nev<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
406:     eps->nev = nev;
407:     eps->setupcalled = 0;
408:   }
409:   if (ncv) {
410:     if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
411:       eps->ncv = 0;
412:     } else {
413:       if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
414:       eps->ncv = ncv;
415:     }
416:     eps->setupcalled = 0;
417:   }
418:   if (mpd) {
419:     if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
420:       eps->mpd = 0;
421:     } else {
422:       if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
423:       eps->mpd = mpd;
424:     }
425:   }
426:   return(0);
427: }

431: /*@
432:    EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
433:    to be sought.

435:    Logically Collective on EPS

437:    Input Parameters:
438: +  eps   - eigensolver context obtained from EPSCreate()
439: -  which - the portion of the spectrum to be sought

441:    Possible values:
442:    The parameter 'which' can have one of these values

444: +     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
445: .     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
446: .     EPS_LARGEST_REAL - largest real parts
447: .     EPS_SMALLEST_REAL - smallest real parts
448: .     EPS_LARGEST_IMAGINARY - largest imaginary parts
449: .     EPS_SMALLEST_IMAGINARY - smallest imaginary parts
450: .     EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
451: .     EPS_TARGET_REAL - eigenvalues with real part closest to target
452: .     EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
453: .     EPS_ALL - all eigenvalues contained in a given interval
454: -     EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()

456:    Options Database Keys:
457: +   -eps_largest_magnitude - Sets largest eigenvalues in magnitude
458: .   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
459: .   -eps_largest_real - Sets largest real parts
460: .   -eps_smallest_real - Sets smallest real parts
461: .   -eps_largest_imaginary - Sets largest imaginary parts
462: .   -eps_smallest_imaginary - Sets smallest imaginary parts
463: .   -eps_target_magnitude - Sets eigenvalues closest to target
464: .   -eps_target_real - Sets real parts closest to target
465: .   -eps_target_imaginary - Sets imaginary parts closest to target
466: -   -eps_all - Sets all eigenvalues in an interval

468:    Notes:
469:    Not all eigensolvers implemented in EPS account for all the possible values
470:    stated above. Also, some values make sense only for certain types of
471:    problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
472:    and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
473:    for eigenvalue selection.

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

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

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

485:    Level: intermediate

487: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
488:           EPSSetDimensions(), EPSSetEigenvalueComparison(),
489:           EPSSortEigenvalues(), EPSWhich
490: @*/
491: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
492: {
496:   if (which) {
497:     if (which==PETSC_DECIDE || which==PETSC_DEFAULT) eps->which = (EPSWhich)0;
498:     else switch (which) {
499:       case EPS_LARGEST_MAGNITUDE:
500:       case EPS_SMALLEST_MAGNITUDE:
501:       case EPS_LARGEST_REAL:
502:       case EPS_SMALLEST_REAL:
503:       case EPS_LARGEST_IMAGINARY:
504:       case EPS_SMALLEST_IMAGINARY:
505:       case EPS_TARGET_MAGNITUDE:
506:       case EPS_TARGET_REAL:
507: #if defined(PETSC_USE_COMPLEX)
508:       case EPS_TARGET_IMAGINARY:
509: #endif
510:       case EPS_ALL:
511:       case EPS_WHICH_USER:
512:         if (eps->which != which) {
513:           eps->setupcalled = 0;
514:           eps->which = which;
515:         }
516:         break;
517:       default:
518:         SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
519:     }
520:   }
521:   return(0);
522: }

526: /*@C
527:    EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
528:    sought.

530:    Not Collective

532:    Input Parameter:
533: .  eps - eigensolver context obtained from EPSCreate()

535:    Output Parameter:
536: .  which - the portion of the spectrum to be sought

538:    Notes:
539:    See EPSSetWhichEigenpairs() for possible values of 'which'.

541:    Level: intermediate

543: .seealso: EPSSetWhichEigenpairs(), EPSWhich
544: @*/
545: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
546: {
550:   *which = eps->which;
551:   return(0);
552: }

556: /*@
557:    EPSSetLeftVectorsWanted - Specifies which eigenvectors are required.

559:    Logically Collective on EPS

561:    Input Parameters:
562: +  eps      - the eigensolver context
563: -  leftvecs - whether left eigenvectors are required or not

565:    Options Database Keys:
566: .  -eps_left_vectors <boolean> - Sets/resets the boolean flag 'leftvecs'

568:    Notes:
569:    If the user sets leftvecs=PETSC_TRUE then the solver uses a variant of
570:    the algorithm that computes both right and left eigenvectors. This is
571:    usually much more costly. This option is not available in all solvers.

573:    Level: intermediate

575: .seealso: EPSGetLeftVectorsWanted(), EPSGetEigenvectorLeft()
576: @*/
577: PetscErrorCode EPSSetLeftVectorsWanted(EPS eps,PetscBool leftvecs)
578: {
582:   if (eps->leftvecs != leftvecs) {
583:     eps->leftvecs = leftvecs;
584:     eps->setupcalled = 0;
585:   }
586:   return(0);
587: }

591: /*@
592:    EPSGetLeftVectorsWanted - Returns the flag indicating whether left
593:    eigenvectors are required or not.

595:    Not Collective

597:    Input Parameter:
598: .  eps - the eigensolver context

600:    Output Parameter:
601: .  leftvecs - the returned flag

603:    Level: intermediate

605: .seealso: EPSSetLeftVectorsWanted(), EPSWhich
606: @*/
607: PetscErrorCode EPSGetLeftVectorsWanted(EPS eps,PetscBool *leftvecs)
608: {
612:   *leftvecs = eps->leftvecs;
613:   return(0);
614: }

618: /*@
619:    EPSSetMatrixNorms - Gives the reference values of the matrix norms
620:    and specifies whether these values should be improved adaptively.

622:    Logically Collective on EPS

624:    Input Parameters:
625: +  eps      - the eigensolver context
626: .  nrma     - a reference value for the norm of matrix A
627: .  nrmb     - a reference value for the norm of matrix B
628: -  adaptive - whether matrix norms are improved adaptively

630:    Options Database Keys:
631: +  -eps_norm_a <nrma> - norm of A
632: .  -eps_norm_b <nrma> - norm of B
633: -  -eps_norms_adaptive <boolean> - Sets/resets the boolean flag 'adaptive'

635:    Notes:
636:    If the user sets adaptive=PETSC_FALSE then the solver uses the values
637:    of nrma and nrmb for the matrix norms, and these values do not change
638:    throughout the iteration.

640:    If the user sets adaptive=PETSC_TRUE then the solver tries to adaptively
641:    improve the supplied values, with the numerical information generated
642:    during the iteration. This option is not available in all solvers.

644:    If a passed value is PETSC_DEFAULT, the corresponding norm will be set to 1.
645:    If a passed value is PETSC_DETERMINE, the corresponding norm will be computed
646:    as the NORM_INFINITY with MatNorm().

648:    Level: intermediate

650: .seealso: EPSGetMatrixNorms()
651: @*/
652: PetscErrorCode EPSSetMatrixNorms(EPS eps,PetscReal nrma,PetscReal nrmb,PetscBool adaptive)
653: {
659:   if (nrma) {
660:     if (nrma == PETSC_DEFAULT) eps->nrma = 1.0;
661:     else if (nrma == PETSC_DETERMINE) {
662:       eps->nrma = nrma;
663:       eps->setupcalled = 0;
664:     } else {
665:       if (nrma < 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nrma. Must be > 0");
666:       eps->nrma = nrma;
667:     }
668:   }
669:   if (nrmb) {
670:     if (!eps->isgeneralized) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Norm of B only allowed in generalized problems");
671:     if (nrmb == PETSC_DEFAULT) eps->nrmb = 1.0;
672:     else if (nrmb == PETSC_DETERMINE) {
673:       eps->nrmb = nrmb;
674:       eps->setupcalled = 0;
675:     } else {
676:       if (nrmb < 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nrmb. Must be > 0");
677:       eps->nrmb = nrmb;
678:     }
679:   }
680:   if (eps->adaptive != adaptive) {
681:     eps->adaptive = adaptive;
682:     eps->setupcalled = 0;
683:     if (adaptive) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"Sorry, adaptive norms are not implemented in this release");
684:   }
685:   return(0);
686: }

690: /*@
691:    EPSGetMatrixNorms - Returns the value of the matrix norms (either set
692:    by the user or estimated by the solver) and the flag indicating whether
693:    the norms are being adaptively improved.

695:    Not Collective

697:    Input Parameter:
698: .  eps - the eigensolver context

700:    Output Parameters:
701: +  nrma     - the norm of matrix A
702: .  nrmb     - the norm of matrix B
703: -  adaptive - whether matrix norms are improved adaptively

705:    Level: intermediate

707: .seealso: EPSSetMatrixNorms()
708: @*/
709: PetscErrorCode EPSGetMatrixNorms(EPS eps,PetscReal *nrma,PetscReal *nrmb,PetscBool *adaptive)
710: {
713:   if (nrma) *nrma = eps->nrma;
714:   if (nrmb) *nrmb = eps->nrmb;
715:   if (adaptive) *adaptive = eps->adaptive;
716:   return(0);
717: }

721: /*@C
722:    EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
723:    when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.

725:    Logically Collective on EPS

727:    Input Parameters:
728: +  eps  - eigensolver context obtained from EPSCreate()
729: .  func - a pointer to the comparison function
730: -  ctx  - a context pointer (the last parameter to the comparison function)

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

735: +   ar     - real part of the 1st eigenvalue
736: .   ai     - imaginary part of the 1st eigenvalue
737: .   br     - real part of the 2nd eigenvalue
738: .   bi     - imaginary part of the 2nd eigenvalue
739: .   res    - result of comparison
740: -   ctx    - optional context, as set by EPSSetEigenvalueComparison()

742:    Note:
743:    The returning parameter 'res' can be:
744: +  negative - if the 1st eigenvalue is preferred to the 2st one
745: .  zero     - if both eigenvalues are equally preferred
746: -  positive - if the 2st eigenvalue is preferred to the 1st one

748:    Level: advanced

750: .seealso: EPSSetWhichEigenpairs(), EPSSortEigenvalues(), EPSWhich
751: @*/
752: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
753: {
756:   eps->comparison    = func;
757:   eps->comparisonctx = ctx;
758:   eps->which         = EPS_WHICH_USER;
759:   return(0);
760: }

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

769:    Logically Collective on EPS

771:    Input Parameters:
772: +  eps  - eigensolver context obtained from EPSCreate()
773: .  func - a pointer to the evaluation function
774: -  ctx  - a context pointer (the last parameter to the evaluation function)

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

779: +   er     - real part of the current eigenvalue approximation
780: .   ei     - imaginary part of the current eigenvalue approximation
781: .   xr     - real part of the current eigenvector approximation
782: .   xi     - imaginary part of the current eigenvector approximation
783: .   rr     - result of evaluation (real part)
784: .   ri     - result of evaluation (imaginary part)
785: -   ctx    - optional context, as set by EPSSetArbitrarySelection()

787:    Note:
788:    This provides a mechanism to select eigenpairs by evaluating a user-defined
789:    function. When a function has been provided, the default selection based on
790:    sorting the eigenvalues is replaced by the sorting of the results of this
791:    function (with the same sorting criterion given in EPSSortEigenvalues()).

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

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

803:    Level: advanced

805: .seealso: EPSSetWhichEigenpairs(), EPSSortEigenvalues()
806: @*/
807: PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar,PetscScalar,Vec,Vec,PetscScalar*,PetscScalar*,void*),void* ctx)
808: {
811:   eps->arbitrary    = func;
812:   eps->arbitraryctx = ctx;
813:   eps->setupcalled  = 0;
814:   return(0);
815: }

819: /*@C
820:    EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
821:    used in the convergence test.

823:    Logically Collective on EPS

825:    Input Parameters:
826: +  eps  - eigensolver context obtained from EPSCreate()
827: .  func - a pointer to the convergence test function
828: -  ctx  - a context pointer (the last parameter to the convergence test function)

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

833: +   eps    - eigensolver context obtained from EPSCreate()
834: .   eigr   - real part of the eigenvalue
835: .   eigi   - imaginary part of the eigenvalue
836: .   res    - residual norm associated to the eigenpair
837: .   errest - (output) computed error estimate
838: -   ctx    - optional context, as set by EPSSetConvergenceTest()

840:    Note:
841:    If the error estimate returned by the convergence test function is less than
842:    the tolerance, then the eigenvalue is accepted as converged.

844:    Level: advanced

846: .seealso: EPSSetConvergenceTest(),EPSSetTolerances()
847: @*/
848: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx)
849: {
852:   eps->converged    = func;
853:   eps->convergedctx = ctx;
854:   if (func == EPSConvergedEigRelative) eps->conv = EPS_CONV_EIG;
855:   else if (func == EPSConvergedNormRelative) eps->conv = EPS_CONV_NORM;
856:   else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
857:   else eps->conv = EPS_CONV_USER;
858:   return(0);
859: }

863: /*@
864:    EPSSetConvergenceTest - Specifies how to compute the error estimate
865:    used in the convergence test.

867:    Logically Collective on EPS

869:    Input Parameters:
870: +  eps   - eigensolver context obtained from EPSCreate()
871: -  conv  - the type of convergence test

873:    Options Database Keys:
874: +  -eps_conv_abs - Sets the absolute convergence test
875: .  -eps_conv_eig - Sets the convergence test relative to the eigenvalue
876: -  -eps_conv_norm - Sets the convergence test relative to the matrix norms

878:    Note:
879:    The parameter 'conv' can have one of these values
880: +     EPS_CONV_ABS - absolute error ||r||
881: .     EPS_CONV_EIG - error relative to the eigenvalue l, ||r||/|l|
882: .     EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
883: -     EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()

885:    Level: intermediate

887: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSConv
888: @*/
889: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
890: {
894:   switch (conv) {
895:     case EPS_CONV_EIG:  eps->converged = EPSConvergedEigRelative; break;
896:     case EPS_CONV_NORM: eps->converged = EPSConvergedNormRelative; break;
897:     case EPS_CONV_ABS:  eps->converged = EPSConvergedAbsolute; break;
898:     case EPS_CONV_USER: break;
899:     default:
900:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
901:   }
902:   eps->conv = conv;
903:   return(0);
904: }

908: /*@
909:    EPSGetConvergenceTest - Gets the method used to compute the error estimate
910:    used in the convergence test.

912:    Not Collective

914:    Input Parameters:
915: .  eps   - eigensolver context obtained from EPSCreate()

917:    Output Parameters:
918: .  conv  - the type of convergence test

920:    Level: intermediate

922: .seealso: EPSSetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSConv
923: @*/
924: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
925: {
929:   *conv = eps->conv;
930:   return(0);
931: }

935: /*@
936:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

938:    Logically Collective on EPS

940:    Input Parameters:
941: +  eps      - the eigensolver context
942: -  type     - a known type of eigenvalue problem

944:    Options Database Keys:
945: +  -eps_hermitian - Hermitian eigenvalue problem
946: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
947: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
948: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
949: -  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
950:    with positive semi-definite B

952:    Notes:
953:    Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
954:    (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
955:    (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
956:    (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).

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

965:    Level: beginner

967: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
968: @*/
969: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
970: {
974:   switch (type) {
975:     case EPS_HEP:
976:       eps->isgeneralized = PETSC_FALSE;
977:       eps->ishermitian = PETSC_TRUE;
978:       eps->ispositive = PETSC_FALSE;
979:       break;
980:     case EPS_NHEP:
981:       eps->isgeneralized = PETSC_FALSE;
982:       eps->ishermitian = PETSC_FALSE;
983:       eps->ispositive = PETSC_FALSE;
984:       break;
985:     case EPS_GHEP:
986:       eps->isgeneralized = PETSC_TRUE;
987:       eps->ishermitian = PETSC_TRUE;
988:       eps->ispositive = PETSC_TRUE;
989:       break;
990:     case EPS_GNHEP:
991:       eps->isgeneralized = PETSC_TRUE;
992:       eps->ishermitian = PETSC_FALSE;
993:       eps->ispositive = PETSC_FALSE;
994:       break;
995:     case EPS_PGNHEP:
996:       eps->isgeneralized = PETSC_TRUE;
997:       eps->ishermitian = PETSC_FALSE;
998:       eps->ispositive = PETSC_TRUE;
999:       break;
1000:     case EPS_GHIEP:
1001:       eps->isgeneralized = PETSC_TRUE;
1002:       eps->ishermitian = PETSC_TRUE;
1003:       eps->ispositive = PETSC_FALSE;
1004:       break;
1005:     default:
1006:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
1007:   }
1008:   eps->problem_type = type;
1009:   return(0);
1010: }

1014: /*@C
1015:    EPSGetProblemType - Gets the problem type from the EPS object.

1017:    Not Collective

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

1022:    Output Parameter:
1023: .  type - name of EPS problem type

1025:    Level: intermediate

1027: .seealso: EPSSetProblemType(), EPSProblemType
1028: @*/
1029: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
1030: {
1034:   *type = eps->problem_type;
1035:   return(0);
1036: }

1040: /*@
1041:    EPSSetExtraction - Specifies the type of extraction technique to be employed
1042:    by the eigensolver.

1044:    Logically Collective on EPS

1046:    Input Parameters:
1047: +  eps  - the eigensolver context
1048: -  extr - a known type of extraction

1050:    Options Database Keys:
1051: +  -eps_ritz - Rayleigh-Ritz extraction
1052: .  -eps_harmonic - harmonic Ritz extraction
1053: .  -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
1054: .  -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
1055: .  -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
1056:    (without target)
1057: .  -eps_refined - refined Ritz extraction
1058: -  -eps_refined_harmonic - refined harmonic Ritz extraction

1060:    Notes:
1061:    Not all eigensolvers support all types of extraction. See the SLEPc
1062:    Users Manual for details.

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

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

1069:    Level: beginner

1071: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
1072: @*/
1073: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
1074: {
1078:   eps->extraction = extr;
1079:   return(0);
1080: }

1084: /*@C
1085:    EPSGetExtraction - Gets the extraction type used by the EPS object.

1087:    Not Collective

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

1092:    Output Parameter:
1093: .  extr - name of extraction type

1095:    Level: intermediate

1097: .seealso: EPSSetExtraction(), EPSExtraction
1098: @*/
1099: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1100: {
1104:   *extr = eps->extraction;
1105:   return(0);
1106: }

1110: /*@
1111:    EPSSetBalance - Specifies the balancing technique to be employed by the
1112:    eigensolver, and some parameters associated to it.

1114:    Logically Collective on EPS

1116:    Input Parameters:
1117: +  eps    - the eigensolver context
1118: .  bal    - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1119:             EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1120: .  its    - number of iterations of the balancing algorithm
1121: -  cutoff - cutoff value

1123:    Options Database Keys:
1124: +  -eps_balance <method> - the balancing method, where <method> is one of
1125:                            'none', 'oneside', 'twoside', or 'user'
1126: .  -eps_balance_its <its> - number of iterations
1127: -  -eps_balance_cutoff <cutoff> - cutoff value

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

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

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

1141:    The parameter 'its' is the number of iterations performed by the method. The
1142:    cutoff value is used only in the two-side variant. Pass 0 for an argument
1143:    that need not be changed. Use PETSC_DECIDE to assign a reasonably good value.

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

1148:    Level: intermediate

1150: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1151: @*/
1152: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1153: {
1159:   if (bal) {
1160:     if (bal==PETSC_DECIDE || bal==PETSC_DEFAULT) eps->balance = EPS_BALANCE_TWOSIDE;
1161:     else switch (bal) {
1162:       case EPS_BALANCE_NONE:
1163:       case EPS_BALANCE_ONESIDE:
1164:       case EPS_BALANCE_TWOSIDE:
1165:       case EPS_BALANCE_USER:
1166:         eps->balance = bal;
1167:         break;
1168:       default:
1169:         SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1170:     }
1171:   }
1172:   if (its) {
1173:     if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
1174:     else eps->balance_its = its;
1175:   }
1176:   if (cutoff) {
1177:     if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
1178:     else eps->balance_cutoff = cutoff;
1179:   }
1180:   return(0);
1181: }

1185: /*@
1186:    EPSGetBalance - Gets the balancing type used by the EPS object, and the associated
1187:    parameters.

1189:    Not Collective

1191:    Input Parameter:
1192: .  eps - the eigensolver context

1194:    Output Parameters:
1195: +  bal    - the balancing method
1196: .  its    - number of iterations of the balancing algorithm
1197: -  cutoff - cutoff value

1199:    Level: intermediate

1201:    Note:
1202:    The user can specify NULL for any parameter that is not needed.

1204: .seealso: EPSSetBalance(), EPSBalance
1205: @*/
1206: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1207: {
1210:   if (bal)    *bal = eps->balance;
1211:   if (its)    *its = eps->balance_its;
1212:   if (cutoff) *cutoff = eps->balance_cutoff;
1213:   return(0);
1214: }

1218: /*@
1219:    EPSSetTrueResidual - Specifies if the solver must compute the true residual
1220:    explicitly or not.

1222:    Logically Collective on EPS

1224:    Input Parameters:
1225: +  eps     - the eigensolver context
1226: -  trueres - whether true residuals are required or not

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

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

1241:    Level: intermediate

1243: .seealso: EPSGetTrueResidual()
1244: @*/
1245: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1246: {
1250:   eps->trueres = trueres;
1251:   return(0);
1252: }

1256: /*@C
1257:    EPSGetTrueResidual - Returns the flag indicating whether true
1258:    residuals must be computed explicitly or not.

1260:    Not Collective

1262:    Input Parameter:
1263: .  eps - the eigensolver context

1265:    Output Parameter:
1266: .  trueres - the returned flag

1268:    Level: intermediate

1270: .seealso: EPSSetTrueResidual()
1271: @*/
1272: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1273: {
1277:   *trueres = eps->trueres;
1278:   return(0);
1279: }

1283: /*@
1284:    EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1285:    approximate eigenpairs or not.

1287:    Logically Collective on EPS

1289:    Input Parameters:
1290: +  eps      - the eigensolver context
1291: -  trackall - whether to compute all residuals or not

1293:    Notes:
1294:    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1295:    the residual norm for each eigenpair approximation. Computing the residual is
1296:    usually an expensive operation and solvers commonly compute only the residual
1297:    associated to the first unconverged eigenpair.

1299:    The options '-eps_monitor_all' and '-eps_monitor_lg_all' automatically
1300:    activate this option.

1302:    Level: intermediate

1304: .seealso: EPSGetTrackAll()
1305: @*/
1306: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1307: {
1311:   eps->trackall = trackall;
1312:   return(0);
1313: }

1317: /*@
1318:    EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1319:    be computed or not.

1321:    Not Collective

1323:    Input Parameter:
1324: .  eps - the eigensolver context

1326:    Output Parameter:
1327: .  trackall - the returned flag

1329:    Level: intermediate

1331: .seealso: EPSSetTrackAll()
1332: @*/
1333: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1334: {
1338:   *trackall = eps->trackall;
1339:   return(0);
1340: }

1344: /*@C
1345:    EPSSetOptionsPrefix - Sets the prefix used for searching for all
1346:    EPS options in the database.

1348:    Logically Collective on EPS

1350:    Input Parameters:
1351: +  eps - the eigensolver context
1352: -  prefix - the prefix string to prepend to all EPS option requests

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

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

1366:    Level: advanced

1368: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1369: @*/
1370: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1371: {

1376:   if (!eps->st) { EPSGetST(eps,&eps->st); }
1377:   STSetOptionsPrefix(eps->st,prefix);
1378:   if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
1379:   IPSetOptionsPrefix(eps->ip,prefix);
1380:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1381:   DSSetOptionsPrefix(eps->ds,prefix);
1382:   PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
1383:   return(0);
1384: }

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

1392:    Logically Collective on EPS

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

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

1402:    Level: advanced

1404: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1405: @*/
1406: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1407: {

1412:   if (!eps->st) { EPSGetST(eps,&eps->st); }
1413:   STAppendOptionsPrefix(eps->st,prefix);
1414:   if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
1415:   IPSetOptionsPrefix(eps->ip,prefix);
1416:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
1417:   DSSetOptionsPrefix(eps->ds,prefix);
1418:   PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
1419:   return(0);
1420: }

1424: /*@C
1425:    EPSGetOptionsPrefix - Gets the prefix used for searching for all
1426:    EPS options in the database.

1428:    Not Collective

1430:    Input Parameters:
1431: .  eps - the eigensolver context

1433:    Output Parameters:
1434: .  prefix - pointer to the prefix string used is returned

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

1439:    Level: advanced

1441: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1442: @*/
1443: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1444: {

1450:   PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
1451:   return(0);
1452: }