Date: 2013-09-02T10:02:48+00:00

Actual source code: opts.c

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

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

      9:    This file is part of SLEPc.

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

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

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

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

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

     34:    Collective on EPS

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

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

     42:    Level: beginner
     43: @*/
     44: PetscErrorCode EPSSetFromOptions(EPS eps)
     45: {
     46:   PetscErrorCode   ierr;
     47:   char             type[256],monfilename[PETSC_MAX_PATH_LEN];
     48:   PetscBool        flg,val;
     49:   PetscReal        r,nrma,nrmb,array[2]={0,0};
     50:   PetscScalar      s;
     51:   PetscInt         i,j,k;
     52:   const char       *bal_list[4] = {"none","oneside","twoside","user"};
     53:   PetscViewer      monviewer;
     54:   SlepcConvMonitor ctx;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    241:    Not Collective

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

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

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

    253:    Level: intermediate

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

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

    272:    Logically Collective on EPS

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

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

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

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

    289:    Level: intermediate

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

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

    325:    Not Collective

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

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

    335:    Notes:
    336:    The user can specify NULL for any parameter that is not needed.

    338:    Level: intermediate

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

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

    358:    Logically Collective on EPS

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

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

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

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

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

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

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

    393:    Level: intermediate

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

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

    435:    Logically Collective on EPS

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

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

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

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

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

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

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

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

    485:    Level: intermediate

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

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

    530:    Not Collective

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

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

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

    541:    Level: intermediate

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

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

    559:    Logically Collective on EPS

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

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

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

    573:    Level: intermediate

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

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

    595:    Not Collective

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

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

    603:    Level: intermediate

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

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

    622:    Logically Collective on EPS

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

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

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

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

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

    648:    Level: intermediate

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

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

    695:    Not Collective

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

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

    705:    Level: intermediate

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

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

    725:    Logically Collective on EPS

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

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

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

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

    748:    Level: advanced

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

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

    769:    Logically Collective on EPS

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

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

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

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

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

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

    803:    Level: advanced

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

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

    823:    Logically Collective on EPS

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

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

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

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

    844:    Level: advanced

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

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

    867:    Logically Collective on EPS

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

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

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

    885:    Level: intermediate

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

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

    912:    Not Collective

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

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

    920:    Level: intermediate

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

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

    938:    Logically Collective on EPS

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

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

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

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

    965:    Level: beginner

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

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

    1017:    Not Collective

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

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

    1025:    Level: intermediate

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

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

    1044:    Logically Collective on EPS

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

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

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

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

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

    1069:    Level: beginner

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

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

    1087:    Not Collective

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

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

    1095:    Level: intermediate

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

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

    1114:    Logically Collective on EPS

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

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

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

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

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

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

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

    1148:    Level: intermediate

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

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

    1189:    Not Collective

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

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

    1199:    Level: intermediate

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

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

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

    1222:    Logically Collective on EPS

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

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

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

    1241:    Level: intermediate

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

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

    1260:    Not Collective

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

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

    1268:    Level: intermediate

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

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

    1287:    Logically Collective on EPS

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

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

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

    1302:    Level: intermediate

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

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

    1321:    Not Collective

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

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

    1329:    Level: intermediate

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

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

    1348:    Logically Collective on EPS

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

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

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

    1366:    Level: advanced

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

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

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

    1392:    Logically Collective on EPS

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

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

    1402:    Level: advanced

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

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

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

    1428:    Not Collective

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

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

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

    1439:    Level: advanced

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

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