Date: 2016-09-29T11:11:12+00:00

Actual source code: epsopts.c
slepc-3.7.3 2016-09-29
Report Typos and Errors

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

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

      9:    This file is part of SLEPc.

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

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

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

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

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

     34:    Collective on EPS

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

     44:    Level: developer

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

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

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

     75:    Collective on EPS

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

     84:    Level: developer

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

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

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

    113:    Collective on EPS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    317:    Not Collective

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

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

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

    329:    Level: intermediate

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

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

    348:    Logically Collective on EPS

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

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

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

    362:    Level: intermediate

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

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

    395:    Not Collective

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

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

    405:    Level: intermediate

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

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

    425:    Logically Collective on EPS

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

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

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

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

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

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

    455:    Level: intermediate

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

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

    490:    Logically Collective on EPS

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

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

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

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

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

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

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

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

    541:    Level: intermediate

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

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

    582:    Not Collective

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

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

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

    593:    Level: intermediate

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

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

    612:    Logically Collective on EPS

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

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

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

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

    635:    Level: advanced

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

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

    656:    Logically Collective on EPS

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

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

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

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

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

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

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

    694:    Level: advanced

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

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

    714:    Logically Collective on EPS

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

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

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

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

    736:    Level: advanced

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

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

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

    765:    Logically Collective on EPS

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

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

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

    784:    Level: intermediate

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

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

    811:    Not Collective

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

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

    819:    Level: intermediate

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

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

    838:    Logically Collective on EPS

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

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

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

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

    863:    Level: advanced

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

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

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

    890:    Logically Collective on EPS

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

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

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

    905:    Level: advanced

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

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

    930:    Not Collective

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

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

    938:    Level: advanced

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

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

    956:    Logically Collective on EPS

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

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

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

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

    983:    Level: intermediate

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

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

    1037:    Not Collective

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

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

    1045:    Level: intermediate

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

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

    1064:    Logically Collective on EPS

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

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

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

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

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

    1089:    Level: advanced

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

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

    1107:    Not Collective

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

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

    1115:    Level: advanced

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

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

    1134:    Logically Collective on EPS

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

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

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

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

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

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

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

    1168:    Level: intermediate

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

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

    1208:    Not Collective

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

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

    1218:    Level: intermediate

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

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

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

    1241:    Logically Collective on EPS

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

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

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

    1260:    Level: advanced

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

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

    1279:    Not Collective

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

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

    1287:    Level: advanced

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

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

    1306:    Logically Collective on EPS

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

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

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

    1321:    Level: developer

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

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

    1340:    Not Collective

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

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

    1348:    Level: developer

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

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

    1366:    Logically Collective on EPS

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

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

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

    1381:    Level: intermediate

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

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

    1400:    Not Collective

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

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

    1408:    Level: intermediate

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

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

    1427:    Logically Collective on EPS

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

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

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

    1445:    Level: advanced

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

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

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

    1473:    Logically Collective on EPS

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

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

    1483:    Level: advanced

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

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

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

    1511:    Not Collective

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

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

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

    1523:    Level: advanced

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

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