Date: 2022-03-31T15:29:06+00:00

Actual source code: epsopts.c
slepc-3.17.0 2022-03-31
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

      6:    This file is part of SLEPc.
      7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
      8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      9: */
     10: /*
     11:    EPS routines related to options that can be set via the command-line
     12:    or procedurally.
     13: */

     15: #include <slepc/private/epsimpl.h>
     16: #include <petscdraw.h>

     18: /*@C
     19:    EPSMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
     20:    indicated by the user.

     22:    Collective on eps

     24:    Input Parameters:
     25: +  eps      - the eigensolver context
     26: .  opt      - the command line option for this monitor
     27: .  name     - the monitor type one is seeking
     28: .  ctx      - an optional user context for the monitor, or NULL
     29: -  trackall - whether this monitor tracks all eigenvalues or not

     31:    Level: developer

     33: .seealso: EPSMonitorSet(), EPSSetTrackAll()
     34: @*/
     35: PetscErrorCode EPSMonitorSetFromOptions(EPS eps,const char opt[],const char name[],void *ctx,PetscBool trackall)
     36: {
     37:   PetscErrorCode       (*mfunc)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
     38:   PetscErrorCode       (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
     39:   PetscErrorCode       (*dfunc)(PetscViewerAndFormat**);
     40:   PetscViewerAndFormat *vf;
     41:   PetscViewer          viewer;
     42:   PetscViewerFormat    format;
     43:   PetscViewerType      vtype;
     44:   char                 key[PETSC_MAX_PATH_LEN];
     45:   PetscBool            flg;

     47:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->options,((PetscObject)eps)->prefix,opt,&viewer,&format,&flg);
     48:   if (!flg) PetscFunctionReturn(0);

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

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

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

     71:    Collective on eps

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

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

     79:    Level: beginner

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    224:     if (eps->ops->setfromoptions) (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
    225:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)eps);
    226:   ierr = PetscOptionsEnd();

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

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

    246:    Not Collective

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

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

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

    258:    Level: intermediate

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

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

    274:    Logically Collective on eps

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

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

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

    288:    Level: intermediate

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

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

    318:    Not Collective

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

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

    328:    Level: intermediate

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

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

    345:    Logically Collective on eps

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

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

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

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

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

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

    375:    Level: intermediate

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

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

    407:    Logically Collective on eps

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

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

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

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

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

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

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

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

    458:    Level: intermediate

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

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

    500:    Not Collective

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

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

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

    511:    Level: intermediate

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

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

    527:    Logically Collective on eps

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

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

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

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

    550:    Level: advanced

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

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

    568:    Logically Collective on eps

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

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

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

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

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

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

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

    606:    Level: advanced

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

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

    623:    Logically Collective on eps

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

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

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

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

    645:    Level: advanced

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

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

    670:    Logically Collective on eps

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

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

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

    689:    Level: intermediate

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

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

    716:    Not Collective

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

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

    724:    Level: intermediate

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

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

    740:    Logically Collective on eps

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

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

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

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

    765:    Level: advanced

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

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

    788:    Logically Collective on eps

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

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

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

    803:    Level: advanced

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

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

    828:    Not Collective

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

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

    836:    Level: advanced

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

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

    851:    Logically Collective on eps

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

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

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

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

    879:    Level: intermediate

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

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

    930:    Not Collective

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

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

    938:    Level: intermediate

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

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

    954:    Logically Collective on eps

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

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

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

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

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

    979:    Level: advanced

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

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

    994:    Not Collective

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

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

    1002:    Level: advanced

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

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

    1018:    Logically Collective on eps

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

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

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

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

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

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

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

    1052:    Level: intermediate

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

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

    1092:    Not Collective

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

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

    1102:    Level: intermediate

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

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

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

    1122:    Logically Collective on eps

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

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

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

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

    1139:    Level: advanced

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

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

    1158:    Not Collective

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

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

    1166:    Level: advanced

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

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

    1182:    Logically Collective on eps

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

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

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

    1201:    Level: advanced

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

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

    1217:    Not Collective

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

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

    1225:    Level: advanced

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

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

    1241:    Logically Collective on eps

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

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

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

    1255:    Level: developer

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

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

    1271:    Not Collective

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

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

    1279:    Level: developer

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

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

    1294:    Logically Collective on eps

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

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

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

    1309:    Level: intermediate

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

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

    1328:    Not Collective

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

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

    1336:    Level: intermediate

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

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

    1352:    Logically Collective on eps

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

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

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

    1370:    Level: advanced

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

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

    1393:    Logically Collective on eps

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

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

    1403:    Level: advanced

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

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

    1426:    Not Collective

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

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

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

    1438:    Level: advanced

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