Date: 2016-03-29T14:57:45+00:00

Actual source code: epsopts.c
slepc-3.6.3 2016-03-29
Report Typos and Errors

      1: /*
      2:       EPS routines related to options that can be set via the command-line
      3:       or procedurally.

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

      9:    This file is part of SLEPc.

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

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

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

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

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

     34:    Collective on EPS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    247:    Not Collective

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

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

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

    259:    Level: intermediate

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

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

    278:    Logically Collective on EPS

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

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

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

    292:    Level: intermediate

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

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

    325:    Not Collective

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

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

    335:    Level: intermediate

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

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

    355:    Logically Collective on EPS

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

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

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

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

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

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

    385:    Level: intermediate

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

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

    420:    Logically Collective on EPS

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

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

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

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

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

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

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

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

    470:    Level: intermediate

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

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

    511:    Not Collective

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

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

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

    522:    Level: intermediate

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

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

    541:    Logically Collective on EPS

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

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

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

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

    564:    Level: advanced

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

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

    585:    Logically Collective on EPS

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

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

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

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

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

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

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

    623:    Level: advanced

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

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

    643:    Logically Collective on EPS

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

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

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

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

    666:    Level: advanced

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

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

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

    695:    Logically Collective on EPS

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

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

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

    714:    Level: intermediate

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

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

    741:    Not Collective

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

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

    749:    Level: intermediate

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

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

    767:    Logically Collective on EPS

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

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

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

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

    794:    Level: intermediate

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

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

    846:    Not Collective

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

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

    854:    Level: intermediate

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

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

    873:    Logically Collective on EPS

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

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

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

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

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

    898:    Level: advanced

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

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

    916:    Not Collective

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

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

    924:    Level: advanced

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

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

    943:    Logically Collective on EPS

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

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

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

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

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

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

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

    977:    Level: intermediate

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

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

    1017:    Not Collective

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

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

    1027:    Level: intermediate

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

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

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

    1050:    Logically Collective on EPS

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

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

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

    1069:    Level: advanced

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

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

    1088:    Not Collective

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

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

    1096:    Level: advanced

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

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

    1115:    Logically Collective on EPS

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

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

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

    1130:    Level: developer

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

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

    1149:    Not Collective

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

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

    1157:    Level: developer

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

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

    1175:    Logically Collective on EPS

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

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

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

    1190:    Level: intermediate

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

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

    1209:    Not Collective

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

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

    1217:    Level: intermediate

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

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

    1236:    Logically Collective on EPS

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

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

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

    1254:    Level: advanced

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

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

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

    1282:    Logically Collective on EPS

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

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

    1292:    Level: advanced

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

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

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

    1320:    Not Collective

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

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

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

    1331:    Level: advanced

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

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