Date: 2021-09-20T09:43:50+00:00

Actual source code: epsopts.c
slepc-3.15.2 2021-09-20
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2021, 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;
     46:   PetscErrorCode       ierr;

     49:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->options,((PetscObject)eps)->prefix,opt,&viewer,&format,&flg);
     50:   if (!flg) return(0);

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

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

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

     74:    Collective on eps

     76:    Input Parameters:
     77: .  eps - the eigensolver context

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

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

     96:   EPSRegisterAll();
     97:   PetscObjectOptionsBegin((PetscObject)eps);
     98:     PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,sizeof(type),&flg);
     99:     if (flg) {
    100:       EPSSetType(eps,type);
    101:     } else if (!((PetscObject)eps)->type_name) {
    102:       EPSSetType(eps,EPSKRYLOVSCHUR);
    103:     }

    105:     PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg);
    106:     if (flg) { EPSSetProblemType(eps,EPS_HEP); }
    107:     PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg);
    108:     if (flg) { EPSSetProblemType(eps,EPS_GHEP); }
    109:     PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
    110:     if (flg) { EPSSetProblemType(eps,EPS_NHEP); }
    111:     PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg);
    112:     if (flg) { EPSSetProblemType(eps,EPS_GNHEP); }
    113:     PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
    114:     if (flg) { EPSSetProblemType(eps,EPS_PGNHEP); }
    115:     PetscOptionsBoolGroupEnd("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);
    116:     if (flg) { EPSSetProblemType(eps,EPS_GHIEP); }

    118:     PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
    119:     if (flg) { EPSSetExtraction(eps,EPS_RITZ); }
    120:     PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg);
    121:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC); }
    122:     PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg);
    123:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE); }
    124:     PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg);
    125:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_RIGHT); }
    126:     PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg);
    127:     if (flg) { EPSSetExtraction(eps,EPS_HARMONIC_LARGEST); }
    128:     PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg);
    129:     if (flg) { EPSSetExtraction(eps,EPS_REFINED); }
    130:     PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg);
    131:     if (flg) { EPSSetExtraction(eps,EPS_REFINED_HARMONIC); }

    133:     bal = eps->balance;
    134:     PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1);
    135:     j = eps->balance_its;
    136:     PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2);
    137:     r = eps->balance_cutoff;
    138:     PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3);
    139:     if (flg1 || flg2 || flg3) { EPSSetBalance(eps,bal,j,r); }

    141:     i = eps->max_it;
    142:     PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1);
    143:     r = eps->tol;
    144:     PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:eps->tol,&r,&flg2);
    145:     if (flg1 || flg2) { EPSSetTolerances(eps,r,i); }

    147:     PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg);
    148:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_REL); }
    149:     PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);
    150:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_NORM); }
    151:     PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);
    152:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_ABS); }
    153:     PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg);
    154:     if (flg) { EPSSetConvergenceTest(eps,EPS_CONV_USER); }

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

    161:     i = eps->nev;
    162:     PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1);
    163:     j = eps->ncv;
    164:     PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2);
    165:     k = eps->mpd;
    166:     PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3);
    167:     if (flg1 || flg2 || flg3) { EPSSetDimensions(eps,i,j,k); }

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

    190:     PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
    191:     if (flg) {
    192:       if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) {
    193:         EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);
    194:       }
    195:       EPSSetTarget(eps,s);
    196:     }

    198:     k = 2;
    199:     PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);
    200:     if (flg) {
    201:       if (k<2) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
    202:       EPSSetWhichEigenpairs(eps,EPS_ALL);
    203:       EPSSetInterval(eps,array[0],array[1]);
    204:     }

    206:     PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL);
    207:     PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&bval,&flg);
    208:     if (flg) { EPSSetPurify(eps,bval); }
    209:     PetscOptionsBool("-eps_two_sided","Use two-sided variant (to compute left eigenvectors)","EPSSetTwoSided",eps->twosided,&bval,&flg);
    210:     if (flg) { EPSSetTwoSided(eps,bval); }

    212:     /* -----------------------------------------------------------------------*/
    213:     /*
    214:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
    215:     */
    216:     PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set);
    217:     if (set && flg) { EPSMonitorCancel(eps); }
    218:     EPSMonitorSetFromOptions(eps,"-eps_monitor","first_approximation",NULL,PETSC_FALSE);
    219:     EPSMonitorSetFromOptions(eps,"-eps_monitor_all","all_approximations",NULL,PETSC_TRUE);
    220:     EPSMonitorSetFromOptions(eps,"-eps_monitor_conv","convergence_history",NULL,PETSC_FALSE);

    222:     /* -----------------------------------------------------------------------*/
    223:     PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",NULL);
    224:     PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",NULL);
    225:     PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",NULL);
    226:     PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSConvergedReasonView",NULL);
    227:     PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",NULL);
    228:     PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",NULL);
    229:     PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",NULL);

    231:     if (eps->ops->setfromoptions) {
    232:       (*eps->ops->setfromoptions)(PetscOptionsObject,eps);
    233:     }
    234:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)eps);
    235:   PetscOptionsEnd();

    237:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
    238:   BVSetFromOptions(eps->V);
    239:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
    240:   RGSetFromOptions(eps->rg);
    241:   if (eps->useds) {
    242:     if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
    243:     DSSetFromOptions(eps->ds);
    244:   }
    245:   if (!eps->st) { EPSGetST(eps,&eps->st); }
    246:   EPSSetDefaultST(eps);
    247:   STSetFromOptions(eps->st);
    248:   return(0);
    249: }

    251: /*@C
    252:    EPSGetTolerances - Gets the tolerance and maximum iteration count used
    253:    by the EPS convergence tests.

    255:    Not Collective

    257:    Input Parameter:
    258: .  eps - the eigensolver context

    260:    Output Parameters:
    261: +  tol - the convergence tolerance
    262: -  maxits - maximum number of iterations

    264:    Notes:
    265:    The user can specify NULL for any parameter that is not needed.

    267:    Level: intermediate

    269: .seealso: EPSSetTolerances()
    270: @*/
    271: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
    272: {
    275:   if (tol)    *tol    = eps->tol;
    276:   if (maxits) *maxits = eps->max_it;
    277:   return(0);
    278: }

    280: /*@
    281:    EPSSetTolerances - Sets the tolerance and maximum iteration count used
    282:    by the EPS convergence tests.

    284:    Logically Collective on eps

    286:    Input Parameters:
    287: +  eps - the eigensolver context
    288: .  tol - the convergence tolerance
    289: -  maxits - maximum number of iterations to use

    291:    Options Database Keys:
    292: +  -eps_tol <tol> - Sets the convergence tolerance
    293: -  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

    295:    Notes:
    296:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

    298:    Level: intermediate

    300: .seealso: EPSGetTolerances()
    301: @*/
    302: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
    303: {
    308:   if (tol == PETSC_DEFAULT) {
    309:     eps->tol   = PETSC_DEFAULT;
    310:     eps->state = EPS_STATE_INITIAL;
    311:   } else {
    312:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    313:     eps->tol = tol;
    314:   }
    315:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    316:     eps->max_it = PETSC_DEFAULT;
    317:     eps->state  = EPS_STATE_INITIAL;
    318:   } else {
    319:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
    320:     eps->max_it = maxits;
    321:   }
    322:   return(0);
    323: }

    325: /*@C
    326:    EPSGetDimensions - Gets the number of eigenvalues to compute
    327:    and the dimension of the subspace.

    329:    Not Collective

    331:    Input Parameter:
    332: .  eps - the eigensolver context

    334:    Output Parameters:
    335: +  nev - number of eigenvalues to compute
    336: .  ncv - the maximum dimension of the subspace to be used by the solver
    337: -  mpd - the maximum dimension allowed for the projected problem

    339:    Level: intermediate

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

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

    357:    Logically Collective on eps

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

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

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

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

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

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

    387:    Level: intermediate

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

    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 or region
    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 or region

    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:    or in the context of the CISS solver for computing all eigenvalues in a region.
    468:    In those cases, the number of eigenvalues is unknown, so the nev parameter
    469:    has a different sense, see EPSSetDimensions().

    471:    Level: intermediate

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

    510: /*@
    511:    EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
    512:    sought.

    514:    Not Collective

    516:    Input Parameter:
    517: .  eps - eigensolver context obtained from EPSCreate()

    519:    Output Parameter:
    520: .  which - the portion of the spectrum to be sought

    522:    Notes:
    523:    See EPSSetWhichEigenpairs() for possible values of 'which'.

    525:    Level: intermediate

    527: .seealso: EPSSetWhichEigenpairs(), EPSWhich
    528: @*/
    529: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
    530: {
    534:   *which = eps->which;
    535:   return(0);
    536: }

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

    542:    Logically Collective on eps

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

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

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

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

    565:    Level: advanced

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

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

    584:    Logically Collective on eps

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

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

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

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

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

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

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

    622:    Level: advanced

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

    636: /*@C
    637:    EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
    638:    used in the convergence test.

    640:    Logically Collective on eps

    642:    Input Parameters:
    643: +  eps     - eigensolver context obtained from EPSCreate()
    644: .  func    - a pointer to the convergence test function
    645: .  ctx     - context for private data for the convergence routine (may be null)
    646: -  destroy - a routine for destroying the context (may be null)

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

    651: +   eps    - eigensolver context obtained from EPSCreate()
    652: .   eigr   - real part of the eigenvalue
    653: .   eigi   - imaginary part of the eigenvalue
    654: .   res    - residual norm associated to the eigenpair
    655: .   errest - (output) computed error estimate
    656: -   ctx    - optional context, as set by EPSSetConvergenceTestFunction()

    658:    Note:
    659:    If the error estimate returned by the convergence test function is less than
    660:    the tolerance, then the eigenvalue is accepted as converged.

    662:    Level: advanced

    664: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
    665: @*/
    666: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
    667: {

    672:   if (eps->convergeddestroy) {
    673:     (*eps->convergeddestroy)(eps->convergedctx);
    674:   }
    675:   eps->convergeduser    = func;
    676:   eps->convergeddestroy = destroy;
    677:   eps->convergedctx     = ctx;
    678:   if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
    679:   else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
    680:   else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
    681:   else {
    682:     eps->conv      = EPS_CONV_USER;
    683:     eps->converged = eps->convergeduser;
    684:   }
    685:   return(0);
    686: }

    688: /*@
    689:    EPSSetConvergenceTest - Specifies how to compute the error estimate
    690:    used in the convergence test.

    692:    Logically Collective on eps

    694:    Input Parameters:
    695: +  eps  - eigensolver context obtained from EPSCreate()
    696: -  conv - the type of convergence test

    698:    Options Database Keys:
    699: +  -eps_conv_abs  - Sets the absolute convergence test
    700: .  -eps_conv_rel  - Sets the convergence test relative to the eigenvalue
    701: .  -eps_conv_norm - Sets the convergence test relative to the matrix norms
    702: -  -eps_conv_user - Selects the user-defined convergence test

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

    711:    Level: intermediate

    713: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
    714: @*/
    715: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
    716: {
    720:   switch (conv) {
    721:     case EPS_CONV_ABS:  eps->converged = EPSConvergedAbsolute; break;
    722:     case EPS_CONV_REL:  eps->converged = EPSConvergedRelative; break;
    723:     case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
    724:     case EPS_CONV_USER:
    725:       if (!eps->convergeduser) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetConvergenceTestFunction() first");
    726:       eps->converged = eps->convergeduser;
    727:       break;
    728:     default:
    729:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
    730:   }
    731:   eps->conv = conv;
    732:   return(0);
    733: }

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

    739:    Not Collective

    741:    Input Parameters:
    742: .  eps   - eigensolver context obtained from EPSCreate()

    744:    Output Parameters:
    745: .  conv  - the type of convergence test

    747:    Level: intermediate

    749: .seealso: EPSSetConvergenceTest(), EPSConv
    750: @*/
    751: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
    752: {
    756:   *conv = eps->conv;
    757:   return(0);
    758: }

    760: /*@C
    761:    EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
    762:    iteration of the eigensolver.

    764:    Logically Collective on eps

    766:    Input Parameters:
    767: +  eps     - eigensolver context obtained from EPSCreate()
    768: .  func    - pointer to the stopping test function
    769: .  ctx     - context for private data for the stopping routine (may be null)
    770: -  destroy - a routine for destroying the context (may be null)

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

    775: +   eps    - eigensolver context obtained from EPSCreate()
    776: .   its    - current number of iterations
    777: .   max_it - maximum number of iterations
    778: .   nconv  - number of currently converged eigenpairs
    779: .   nev    - number of requested eigenpairs
    780: .   reason - (output) result of the stopping test
    781: -   ctx    - optional context, as set by EPSSetStoppingTestFunction()

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

    789:    Level: advanced

    791: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
    792: @*/
    793: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,PetscErrorCode (*func)(EPS,PetscInt,PetscInt,PetscInt,PetscInt,EPSConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
    794: {

    799:   if (eps->stoppingdestroy) {
    800:     (*eps->stoppingdestroy)(eps->stoppingctx);
    801:   }
    802:   eps->stoppinguser    = func;
    803:   eps->stoppingdestroy = destroy;
    804:   eps->stoppingctx     = ctx;
    805:   if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
    806:   else {
    807:     eps->stop     = EPS_STOP_USER;
    808:     eps->stopping = eps->stoppinguser;
    809:   }
    810:   return(0);
    811: }

    813: /*@
    814:    EPSSetStoppingTest - Specifies how to decide the termination of the outer
    815:    loop of the eigensolver.

    817:    Logically Collective on eps

    819:    Input Parameters:
    820: +  eps  - eigensolver context obtained from EPSCreate()
    821: -  stop - the type of stopping test

    823:    Options Database Keys:
    824: +  -eps_stop_basic - Sets the default stopping test
    825: -  -eps_stop_user  - Selects the user-defined stopping test

    827:    Note:
    828:    The parameter 'stop' can have one of these values
    829: +     EPS_STOP_BASIC - default stopping test
    830: -     EPS_STOP_USER  - function set by EPSSetStoppingTestFunction()

    832:    Level: advanced

    834: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
    835: @*/
    836: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
    837: {
    841:   switch (stop) {
    842:     case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
    843:     case EPS_STOP_USER:
    844:       if (!eps->stoppinguser) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetStoppingTestFunction() first");
    845:       eps->stopping = eps->stoppinguser;
    846:       break;
    847:     default:
    848:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
    849:   }
    850:   eps->stop = stop;
    851:   return(0);
    852: }

    854: /*@
    855:    EPSGetStoppingTest - Gets the method used to decide the termination of the outer
    856:    loop of the eigensolver.

    858:    Not Collective

    860:    Input Parameters:
    861: .  eps   - eigensolver context obtained from EPSCreate()

    863:    Output Parameters:
    864: .  stop  - the type of stopping test

    866:    Level: advanced

    868: .seealso: EPSSetStoppingTest(), EPSStop
    869: @*/
    870: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
    871: {
    875:   *stop = eps->stop;
    876:   return(0);
    877: }

    879: /*@
    880:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

    882:    Logically Collective on eps

    884:    Input Parameters:
    885: +  eps      - the eigensolver context
    886: -  type     - a known type of eigenvalue problem

    888:    Options Database Keys:
    889: +  -eps_hermitian - Hermitian eigenvalue problem
    890: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
    891: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
    892: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
    893: .  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
    894:    with positive semi-definite B
    895: -  -eps_gen_indefinite - generalized Hermitian-indefinite eigenvalue problem

    897:    Notes:
    898:    Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
    899:    (EPS_NHEP), generalized Hermitian (EPS_GHEP), generalized non-Hermitian
    900:    (EPS_GNHEP), generalized non-Hermitian with positive semi-definite B
    901:    (EPS_PGNHEP), and generalized Hermitian-indefinite (EPS_GHIEP).

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

    910:    Level: intermediate

    912: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
    913: @*/
    914: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
    915: {
    919:   if (type == eps->problem_type) return(0);
    920:   switch (type) {
    921:     case EPS_HEP:
    922:       eps->isgeneralized = PETSC_FALSE;
    923:       eps->ishermitian = PETSC_TRUE;
    924:       eps->ispositive = PETSC_FALSE;
    925:       break;
    926:     case EPS_NHEP:
    927:       eps->isgeneralized = PETSC_FALSE;
    928:       eps->ishermitian = PETSC_FALSE;
    929:       eps->ispositive = PETSC_FALSE;
    930:       break;
    931:     case EPS_GHEP:
    932:       eps->isgeneralized = PETSC_TRUE;
    933:       eps->ishermitian = PETSC_TRUE;
    934:       eps->ispositive = PETSC_TRUE;
    935:       break;
    936:     case EPS_GNHEP:
    937:       eps->isgeneralized = PETSC_TRUE;
    938:       eps->ishermitian = PETSC_FALSE;
    939:       eps->ispositive = PETSC_FALSE;
    940:       break;
    941:     case EPS_PGNHEP:
    942:       eps->isgeneralized = PETSC_TRUE;
    943:       eps->ishermitian = PETSC_FALSE;
    944:       eps->ispositive = PETSC_TRUE;
    945:       break;
    946:     case EPS_GHIEP:
    947:       eps->isgeneralized = PETSC_TRUE;
    948:       eps->ishermitian = PETSC_TRUE;
    949:       eps->ispositive = PETSC_FALSE;
    950:       break;
    951:     default:
    952:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
    953:   }
    954:   eps->problem_type = type;
    955:   eps->state = EPS_STATE_INITIAL;
    956:   return(0);
    957: }

    959: /*@
    960:    EPSGetProblemType - Gets the problem type from the EPS object.

    962:    Not Collective

    964:    Input Parameter:
    965: .  eps - the eigensolver context

    967:    Output Parameter:
    968: .  type - the problem type

    970:    Level: intermediate

    972: .seealso: EPSSetProblemType(), EPSProblemType
    973: @*/
    974: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
    975: {
    979:   *type = eps->problem_type;
    980:   return(0);
    981: }

    983: /*@
    984:    EPSSetExtraction - Specifies the type of extraction technique to be employed
    985:    by the eigensolver.

    987:    Logically Collective on eps

    989:    Input Parameters:
    990: +  eps  - the eigensolver context
    991: -  extr - a known type of extraction

    993:    Options Database Keys:
    994: +  -eps_ritz - Rayleigh-Ritz extraction
    995: .  -eps_harmonic - harmonic Ritz extraction
    996: .  -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
    997: .  -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
    998: .  -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
    999:    (without target)
    1000: .  -eps_refined - refined Ritz extraction
    1001: -  -eps_refined_harmonic - refined harmonic Ritz extraction

    1003:    Notes:
    1004:    Not all eigensolvers support all types of extraction. See the SLEPc
    1005:    Users Manual for details.

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

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

    1012:    Level: advanced

    1014: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
    1015: @*/
    1016: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
    1017: {
    1021:   eps->extraction = extr;
    1022:   return(0);
    1023: }

    1025: /*@
    1026:    EPSGetExtraction - Gets the extraction type used by the EPS object.

    1028:    Not Collective

    1030:    Input Parameter:
    1031: .  eps - the eigensolver context

    1033:    Output Parameter:
    1034: .  extr - name of extraction type

    1036:    Level: advanced

    1038: .seealso: EPSSetExtraction(), EPSExtraction
    1039: @*/
    1040: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
    1041: {
    1045:   *extr = eps->extraction;
    1046:   return(0);
    1047: }

    1049: /*@
    1050:    EPSSetBalance - Specifies the balancing technique to be employed by the
    1051:    eigensolver, and some parameters associated to it.

    1053:    Logically Collective on eps

    1055:    Input Parameters:
    1056: +  eps    - the eigensolver context
    1057: .  bal    - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
    1058:             EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
    1059: .  its    - number of iterations of the balancing algorithm
    1060: -  cutoff - cutoff value

    1062:    Options Database Keys:
    1063: +  -eps_balance <method> - the balancing method, where <method> is one of
    1064:                            'none', 'oneside', 'twoside', or 'user'
    1065: .  -eps_balance_its <its> - number of iterations
    1066: -  -eps_balance_cutoff <cutoff> - cutoff value

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

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

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

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

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

    1087:    Level: intermediate

    1089: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
    1090: @*/
    1091: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
    1092: {
    1098:   switch (bal) {
    1099:     case EPS_BALANCE_NONE:
    1100:     case EPS_BALANCE_ONESIDE:
    1101:     case EPS_BALANCE_TWOSIDE:
    1102:     case EPS_BALANCE_USER:
    1103:       if (eps->balance != bal) {
    1104:         eps->state = EPS_STATE_INITIAL;
    1105:         eps->balance = bal;
    1106:       }
    1107:       break;
    1108:     default:
    1109:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
    1110:   }
    1111:   if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
    1112:   else {
    1113:     if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
    1114:     eps->balance_its = its;
    1115:   }
    1116:   if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
    1117:   else {
    1118:     if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
    1119:     eps->balance_cutoff = cutoff;
    1120:   }
    1121:   return(0);
    1122: }

    1124: /*@C
    1125:    EPSGetBalance - Gets the balancing type used by the EPS object, and the
    1126:    associated parameters.

    1128:    Not Collective

    1130:    Input Parameter:
    1131: .  eps - the eigensolver context

    1133:    Output Parameters:
    1134: +  bal    - the balancing method
    1135: .  its    - number of iterations of the balancing algorithm
    1136: -  cutoff - cutoff value

    1138:    Level: intermediate

    1140:    Note:
    1141:    The user can specify NULL for any parameter that is not needed.

    1143: .seealso: EPSSetBalance(), EPSBalance
    1144: @*/
    1145: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
    1146: {
    1149:   if (bal)    *bal = eps->balance;
    1150:   if (its)    *its = eps->balance_its;
    1151:   if (cutoff) *cutoff = eps->balance_cutoff;
    1152:   return(0);
    1153: }

    1155: /*@
    1156:    EPSSetTwoSided - Sets the solver to use a two-sided variant so that left
    1157:    eigenvectors are also computed.

    1159:    Logically Collective on eps

    1161:    Input Parameters:
    1162: +  eps      - the eigensolver context
    1163: -  twosided - whether the two-sided variant is to be used or not

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

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

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

    1176:    Level: advanced

    1178: .seealso: EPSGetTwoSided(), EPSGetLeftEigenvector()
    1179: @*/
    1180: PetscErrorCode EPSSetTwoSided(EPS eps,PetscBool twosided)
    1181: {
    1185:   if (twosided!=eps->twosided) {
    1186:     eps->twosided = twosided;
    1187:     eps->state    = EPS_STATE_INITIAL;
    1188:   }
    1189:   return(0);
    1190: }

    1192: /*@
    1193:    EPSGetTwoSided - Returns the flag indicating whether a two-sided variant
    1194:    of the algorithm is being used or not.

    1196:    Not Collective

    1198:    Input Parameter:
    1199: .  eps - the eigensolver context

    1201:    Output Parameter:
    1202: .  twosided - the returned flag

    1204:    Level: advanced

    1206: .seealso: EPSSetTwoSided()
    1207: @*/
    1208: PetscErrorCode EPSGetTwoSided(EPS eps,PetscBool *twosided)
    1209: {
    1213:   *twosided = eps->twosided;
    1214:   return(0);
    1215: }

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

    1221:    Logically Collective on eps

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

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

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

    1240:    Level: advanced

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

    1253: /*@
    1254:    EPSGetTrueResidual - Returns the flag indicating whether true
    1255:    residuals must be computed explicitly or not.

    1257:    Not Collective

    1259:    Input Parameter:
    1260: .  eps - the eigensolver context

    1262:    Output Parameter:
    1263: .  trueres - the returned flag

    1265:    Level: advanced

    1267: .seealso: EPSSetTrueResidual()
    1268: @*/
    1269: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
    1270: {
    1274:   *trueres = eps->trueres;
    1275:   return(0);
    1276: }

    1278: /*@
    1279:    EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
    1280:    approximate eigenpairs or not.

    1282:    Logically Collective on eps

    1284:    Input Parameters:
    1285: +  eps      - the eigensolver context
    1286: -  trackall - whether to compute all residuals or not

    1288:    Notes:
    1289:    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
    1290:    the residual norm for each eigenpair approximation. Computing the residual is
    1291:    usually an expensive operation and solvers commonly compute only the residual
    1292:    associated to the first unconverged eigenpair.

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

    1296:    Level: developer

    1298: .seealso: EPSGetTrackAll()
    1299: @*/
    1300: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
    1301: {
    1305:   eps->trackall = trackall;
    1306:   return(0);
    1307: }

    1309: /*@
    1310:    EPSGetTrackAll - Returns the flag indicating whether all residual norms must
    1311:    be computed or not.

    1313:    Not Collective

    1315:    Input Parameter:
    1316: .  eps - the eigensolver context

    1318:    Output Parameter:
    1319: .  trackall - the returned flag

    1321:    Level: developer

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

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

    1337:    Logically Collective on eps

    1339:    Input Parameters:
    1340: +  eps    - the eigensolver context
    1341: -  purify - whether purification is required or not

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

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

    1352:    Level: intermediate

    1354: .seealso: EPSGetPurify(), EPSSetInterval()
    1355: @*/
    1356: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
    1357: {
    1361:   if (purify!=eps->purify) {
    1362:     eps->purify = purify;
    1363:     eps->state  = EPS_STATE_INITIAL;
    1364:   }
    1365:   return(0);
    1366: }

    1368: /*@
    1369:    EPSGetPurify - Returns the flag indicating whether purification is activated
    1370:    or not.

    1372:    Not Collective

    1374:    Input Parameter:
    1375: .  eps - the eigensolver context

    1377:    Output Parameter:
    1378: .  purify - the returned flag

    1380:    Level: intermediate

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

    1393: /*@C
    1394:    EPSSetOptionsPrefix - Sets the prefix used for searching for all
    1395:    EPS options in the database.

    1397:    Logically Collective on eps

    1399:    Input Parameters:
    1400: +  eps - the eigensolver context
    1401: -  prefix - the prefix string to prepend to all EPS option requests

    1403:    Notes:
    1404:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1405:    The first character of all runtime options is AUTOMATICALLY the
    1406:    hyphen.

    1408:    For example, to distinguish between the runtime options for two
    1409:    different EPS contexts, one could call
    1410: .vb
    1411:       EPSSetOptionsPrefix(eps1,"eig1_")
    1412:       EPSSetOptionsPrefix(eps2,"eig2_")
    1413: .ve

    1415:    Level: advanced

    1417: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
    1418: @*/
    1419: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
    1420: {

    1425:   if (!eps->st) { EPSGetST(eps,&eps->st); }
    1426:   STSetOptionsPrefix(eps->st,prefix);
    1427:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
    1428:   BVSetOptionsPrefix(eps->V,prefix);
    1429:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
    1430:   DSSetOptionsPrefix(eps->ds,prefix);
    1431:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
    1432:   RGSetOptionsPrefix(eps->rg,prefix);
    1433:   PetscObjectSetOptionsPrefix((PetscObject)eps,prefix);
    1434:   return(0);
    1435: }

    1437: /*@C
    1438:    EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
    1439:    EPS options in the database.

    1441:    Logically Collective on eps

    1443:    Input Parameters:
    1444: +  eps - the eigensolver context
    1445: -  prefix - the prefix string to prepend to all EPS option requests

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

    1451:    Level: advanced

    1453: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
    1454: @*/
    1455: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
    1456: {

    1461:   if (!eps->st) { EPSGetST(eps,&eps->st); }
    1462:   STAppendOptionsPrefix(eps->st,prefix);
    1463:   if (!eps->V) { EPSGetBV(eps,&eps->V); }
    1464:   BVAppendOptionsPrefix(eps->V,prefix);
    1465:   if (!eps->ds) { EPSGetDS(eps,&eps->ds); }
    1466:   DSAppendOptionsPrefix(eps->ds,prefix);
    1467:   if (!eps->rg) { EPSGetRG(eps,&eps->rg); }
    1468:   RGAppendOptionsPrefix(eps->rg,prefix);
    1469:   PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix);
    1470:   return(0);
    1471: }

    1473: /*@C
    1474:    EPSGetOptionsPrefix - Gets the prefix used for searching for all
    1475:    EPS options in the database.

    1477:    Not Collective

    1479:    Input Parameters:
    1480: .  eps - the eigensolver context

    1482:    Output Parameters:
    1483: .  prefix - pointer to the prefix string used is returned

    1485:    Note:
    1486:    On the Fortran side, the user should pass in a string 'prefix' of
    1487:    sufficient length to hold the prefix.

    1489:    Level: advanced

    1491: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
    1492: @*/
    1493: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
    1494: {

    1500:   PetscObjectGetOptionsPrefix((PetscObject)eps,prefix);
    1501:   return(0);
    1502: }