Actual source code: epssolve.c

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

      6:    This file is part of SLEPc.
      7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
      8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      9: */
     10: /*
     11:    EPS routines related to the solution process
     12: */

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

     18: PetscErrorCode EPSComputeVectors(EPS eps)
     19: {
     20:   PetscFunctionBegin;
     21:   EPSCheckSolved(eps,1);
     22:   if (eps->state==EPS_STATE_SOLVED) PetscTryTypeMethod(eps,computevectors);
     23:   eps->state = EPS_STATE_EIGENVECTORS;
     24:   PetscFunctionReturn(PETSC_SUCCESS);
     25: }

     27: static PetscErrorCode EPSComputeValues(EPS eps)
     28: {
     29:   PetscBool      injective,iscomp,isfilter;
     30:   PetscInt       i,n,aux,nconv0;
     31:   Mat            A,B=NULL,G,Z;

     33:   PetscFunctionBegin;
     34:   switch (eps->categ) {
     35:     case EPS_CATEGORY_KRYLOV:
     36:     case EPS_CATEGORY_OTHER:
     37:       PetscCall(STIsInjective(eps->st,&injective));
     38:       if (injective) {
     39:         /* one-to-one mapping: backtransform eigenvalues */
     40:         PetscUseTypeMethod(eps,backtransform);
     41:       } else {
     42:         /* compute eigenvalues from Rayleigh quotient */
     43:         PetscCall(DSGetDimensions(eps->ds,&n,NULL,NULL,NULL));
     44:         if (!n) break;
     45:         PetscCall(EPSGetOperators(eps,&A,&B));
     46:         PetscCall(BVSetActiveColumns(eps->V,0,n));
     47:         PetscCall(DSGetCompact(eps->ds,&iscomp));
     48:         PetscCall(DSSetCompact(eps->ds,PETSC_FALSE));
     49:         PetscCall(DSGetMat(eps->ds,DS_MAT_A,&G));
     50:         PetscCall(BVMatProject(eps->V,A,eps->V,G));
     51:         PetscCall(DSRestoreMat(eps->ds,DS_MAT_A,&G));
     52:         if (B) {
     53:           PetscCall(DSGetMat(eps->ds,DS_MAT_B,&G));
     54:           PetscCall(BVMatProject(eps->V,B,eps->V,G));
     55:           PetscCall(DSRestoreMat(eps->ds,DS_MAT_B,&G));
     56:         }
     57:         PetscCall(DSSolve(eps->ds,eps->eigr,eps->eigi));
     58:         PetscCall(DSSort(eps->ds,eps->eigr,eps->eigi,NULL,NULL,NULL));
     59:         PetscCall(DSSynchronize(eps->ds,eps->eigr,eps->eigi));
     60:         PetscCall(DSSetCompact(eps->ds,iscomp));
     61:         if (eps->ishermitian && (!eps->isgeneralized || eps->ispositive)) { /* V = V * Z */
     62:           PetscCall(DSVectors(eps->ds,DS_MAT_X,NULL,NULL));
     63:           PetscCall(DSGetMat(eps->ds,DS_MAT_X,&Z));
     64:           PetscCall(BVMultInPlace(eps->V,Z,0,n));
     65:           PetscCall(DSRestoreMat(eps->ds,DS_MAT_X,&Z));
     66:         }
     67:         /* in case of STFILTER discard computed eigenvalues that lie outside the wanted interval */
     68:         PetscCall(PetscObjectTypeCompare((PetscObject)eps->st,STFILTER,&isfilter));
     69:         if (isfilter) {
     70:           nconv0 = eps->nconv;
     71:           for (i=0;i<eps->nconv;i++) {
     72:             if (PetscRealPart(eps->eigr[eps->perm[i]])<eps->inta || PetscRealPart(eps->eigr[eps->perm[i]])>eps->intb) {
     73:               eps->nconv--;
     74:               if (i<eps->nconv) { SlepcSwap(eps->perm[i],eps->perm[eps->nconv],aux); i--; }
     75:             }
     76:           }
     77:           if (nconv0>eps->nconv) PetscCall(PetscInfo(eps,"Discarded %" PetscInt_FMT " computed eigenvalues lying outside the interval\n",nconv0-eps->nconv));
     78:         }
     79:       }
     80:       break;
     81:     case EPS_CATEGORY_PRECOND:
     82:     case EPS_CATEGORY_CONTOUR:
     83:       /* eigenvalues already available as an output of the solver */
     84:       break;
     85:   }
     86:   PetscFunctionReturn(PETSC_SUCCESS);
     87: }

     89: /*@
     90:    EPSSolve - Solves the eigensystem.

     92:    Collective

     94:    Input Parameter:
     95: .  eps - the linear eigensolver context

     97:    Options Database Keys:
     98: +  -eps_view             - print information about the solver once the solve is complete
     99: .  -eps_view_pre         - print information about the solver before the solve starts
    100: .  -eps_view_mat0        - view the first matrix ($A$)
    101: .  -eps_view_mat1        - view the second matrix ($B$)
    102: .  -eps_view_vectors     - view the computed eigenvectors
    103: .  -eps_view_values      - view the computed eigenvalues
    104: .  -eps_converged_reason - print reason for convergence/divergence, and number of iterations
    105: .  -eps_error_absolute   - print absolute errors of each eigenpair
    106: .  -eps_error_relative   - print relative errors of each eigenpair
    107: -  -eps_error_backward   - print backward errors of each eigenpair

    109:    Notes:
    110:    The problem matrices are specified with `EPSSetOperators()`.

    112:    `EPSSolve()` will return without generating an error regardless of whether
    113:    all requested solutions were computed or not. Call `EPSGetConverged()` to get the
    114:    actual number of computed solutions, and `EPSGetConvergedReason()` to determine if
    115:    the solver converged or failed and why.

    117:    All the command-line options listed above admit an optional argument specifying
    118:    the viewer type and options. For instance, use `-eps_view_mat0 binary:amatrix.bin`
    119:    to save the $A$ matrix to a binary file, `-eps_view_values draw` to draw the computed
    120:    eigenvalues graphically, or `-eps_error_relative :myerr.m:ascii_matlab` to save
    121:    the errors in a file that can be executed in Matlab.

    123:    Level: beginner

    125: .seealso: [](ch:eps), `EPSCreate()`, `EPSSetUp()`, `EPSDestroy()`, `EPSSetOperators()`, `EPSGetConverged()`, `EPSGetConvergedReason()`
    126: @*/
    127: PetscErrorCode EPSSolve(EPS eps)
    128: {
    129:   PetscInt       i;
    130:   PetscBool      hasname;
    131:   STMatMode      matmode;
    132:   Mat            A,B;

    134:   PetscFunctionBegin;
    136:   if (eps->state>=EPS_STATE_SOLVED) PetscFunctionReturn(PETSC_SUCCESS);
    137:   PetscCall(PetscLogEventBegin(EPS_Solve,eps,0,0,0));

    139:   /* Call setup */
    140:   PetscCall(EPSSetUp(eps));

    142:   /* Safeguard for matrices of size 0 */
    143:   if (eps->n == 0) {
    144:     eps->nconv  = 0;
    145:     eps->reason = EPS_CONVERGED_TOL;
    146:     eps->state  = EPS_STATE_SOLVED;
    147:     PetscFunctionReturn(PETSC_SUCCESS);
    148:   }

    150:   eps->nconv = 0;
    151:   eps->its   = 0;
    152:   for (i=0;i<eps->ncv;i++) {
    153:     eps->eigr[i]   = 0.0;
    154:     eps->eigi[i]   = 0.0;
    155:     eps->errest[i] = 0.0;
    156:     eps->perm[i]   = i;
    157:   }
    158:   PetscCall(EPSViewFromOptions(eps,NULL,"-eps_view_pre"));
    159:   PetscCall(RGViewFromOptions(eps->rg,NULL,"-rg_view"));

    161:   /* Call solver */
    162:   PetscUseTypeMethod(eps,solve);
    163:   PetscCheck(eps->reason,PetscObjectComm((PetscObject)eps),PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
    164:   eps->state = EPS_STATE_SOLVED;

    166:   /* Only the first nconv columns contain useful information (except in CISS) */
    167:   PetscCall(BVSetActiveColumns(eps->V,0,eps->nconv));
    168:   if (eps->twosided) PetscCall(BVSetActiveColumns(eps->W,0,eps->nconv));

    170:   /* If inplace, purify eigenvectors before reverting operator */
    171:   PetscCall(STGetMatMode(eps->st,&matmode));
    172:   if (matmode == ST_MATMODE_INPLACE && eps->ispositive) PetscCall(EPSComputeVectors(eps));
    173:   PetscCall(STPostSolve(eps->st));

    175:   /* Map eigenvalues back to the original problem if appropriate */
    176:   PetscCall(EPSComputeValues(eps));

    178: #if !defined(PETSC_USE_COMPLEX)
    179:   /* Reorder conjugate eigenvalues (positive imaginary first) */
    180:   for (i=0;i<eps->nconv-1;i++) {
    181:     if (eps->eigi[i] != 0 && (eps->problem_type!=EPS_HAMILT || eps->eigr[i]!=0)) {
    182:       /* conjugate eigenvalues */
    183:       if (eps->eigi[i] < 0) {
    184:         eps->eigi[i] = -eps->eigi[i];
    185:         eps->eigi[i+1] = -eps->eigi[i+1];
    186:         /* the next correction only works with eigenvectors */
    187:         PetscCall(EPSComputeVectors(eps));
    188:         PetscCall(BVScaleColumn(eps->V,i+1,-1.0));
    189:         if (eps->W) PetscCall(BVScaleColumn(eps->W,i+1,-1.0));
    190:       }
    191:       i++;
    192:     }
    193:   }
    194: #endif

    196:   /* Sort eigenvalues according to eps->which parameter */
    197:   if (eps->problem_type==EPS_HAMILT) PetscCall(SlepcSortEigenvaluesSpecial(eps->sc,eps->nconv,eps->eigr,eps->eigi,eps->perm));
    198:   else PetscCall(SlepcSortEigenvalues(eps->sc,eps->nconv,eps->eigr,eps->eigi,eps->perm));
    199:   PetscCall(PetscLogEventEnd(EPS_Solve,eps,0,0,0));

    201:   /* Various viewers */
    202:   PetscCall(EPSViewFromOptions(eps,NULL,"-eps_view"));
    203:   PetscCall(EPSConvergedReasonViewFromOptions(eps));
    204:   PetscCall(EPSErrorViewFromOptions(eps));
    205:   PetscCall(EPSValuesViewFromOptions(eps));
    206:   PetscCall(EPSVectorsViewFromOptions(eps));

    208:   PetscCall(PetscOptionsHasName(((PetscObject)eps)->options,((PetscObject)eps)->prefix,"-eps_view_mat0",&hasname));
    209:   if (hasname) {
    210:     PetscCall(EPSGetOperators(eps,&A,NULL));
    211:     PetscCall(MatViewFromOptions(A,(PetscObject)eps,"-eps_view_mat0"));
    212:   }
    213:   if (eps->isgeneralized) {
    214:     PetscCall(PetscOptionsHasName(((PetscObject)eps)->options,((PetscObject)eps)->prefix,"-eps_view_mat1",&hasname));
    215:     if (hasname) {
    216:       PetscCall(EPSGetOperators(eps,NULL,&B));
    217:       PetscCall(MatViewFromOptions(B,(PetscObject)eps,"-eps_view_mat1"));
    218:     }
    219:   }

    221:   /* Remove deflation and initial subspaces */
    222:   if (eps->nds) {
    223:     PetscCall(BVSetNumConstraints(eps->V,0));
    224:     eps->nds = 0;
    225:   }
    226:   eps->nini = 0;
    227:   PetscFunctionReturn(PETSC_SUCCESS);
    228: }

    230: /*@
    231:    EPSGetIterationNumber - Gets the current iteration number. If the
    232:    call to `EPSSolve()` is complete, then it returns the number of iterations
    233:    carried out by the solution method.

    235:    Not Collective

    237:    Input Parameter:
    238: .  eps - the linear eigensolver context

    240:    Output Parameter:
    241: .  its - number of iterations

    243:    Note:
    244:    During the $i$-th iteration this call returns $i-1$. If `EPSSolve()` is
    245:    complete, then parameter `its` contains either the iteration number at
    246:    which convergence was successfully reached, or failure was detected.
    247:    Call `EPSGetConvergedReason()` to determine if the solver converged or
    248:    failed and why.

    250:    Level: intermediate

    252: .seealso: [](ch:eps), `EPSGetConvergedReason()`, `EPSSetTolerances()`
    253: @*/
    254: PetscErrorCode EPSGetIterationNumber(EPS eps,PetscInt *its)
    255: {
    256:   PetscFunctionBegin;
    258:   PetscAssertPointer(its,2);
    259:   *its = eps->its;
    260:   PetscFunctionReturn(PETSC_SUCCESS);
    261: }

    263: /*@
    264:    EPSGetConverged - Gets the number of converged eigenpairs.

    266:    Not Collective

    268:    Input Parameter:
    269: .  eps - the linear eigensolver context

    271:    Output Parameter:
    272: .  nconv - number of converged eigenpairs

    274:    Notes:
    275:    This function should be called after `EPSSolve()` has finished.

    277:    The value `nconv` may be different from the number of requested solutions
    278:    `nev`, but not larger than `ncv`, see `EPSSetDimensions()`.

    280:    Level: beginner

    282: .seealso: [](ch:eps), `EPSSetDimensions()`, `EPSSolve()`, `EPSGetEigenpair()`
    283: @*/
    284: PetscErrorCode EPSGetConverged(EPS eps,PetscInt *nconv)
    285: {
    286:   PetscFunctionBegin;
    288:   PetscAssertPointer(nconv,2);
    289:   EPSCheckSolved(eps,1);
    290:   PetscCall(EPS_GetActualConverged(eps,nconv));
    291:   PetscFunctionReturn(PETSC_SUCCESS);
    292: }

    294: /*@
    295:    EPSGetConvergedReason - Gets the reason why the `EPSSolve()` iteration was
    296:    stopped.

    298:    Not Collective

    300:    Input Parameter:
    301: .  eps - the linear eigensolver context

    303:    Output Parameter:
    304: .  reason - negative value indicates diverged, positive value converged, see
    305:             `EPSConvergedReason` for the possible values

    307:    Options Database Key:
    308: .  -eps_converged_reason - print reason for convergence/divergence, and number of iterations

    310:    Note:
    311:    If this routine is called before or doing the `EPSSolve()` the value of
    312:    `EPS_CONVERGED_ITERATING` is returned.

    314:    Level: intermediate

    316: .seealso: [](ch:eps), `EPSSetTolerances()`, `EPSSolve()`, `EPSConvergedReason`
    317: @*/
    318: PetscErrorCode EPSGetConvergedReason(EPS eps,EPSConvergedReason *reason)
    319: {
    320:   PetscFunctionBegin;
    322:   PetscAssertPointer(reason,2);
    323:   EPSCheckSolved(eps,1);
    324:   *reason = eps->reason;
    325:   PetscFunctionReturn(PETSC_SUCCESS);
    326: }

    328: /*@
    329:    EPSGetInvariantSubspace - Gets an orthonormal basis of the computed invariant
    330:    subspace.

    332:    Collective

    334:    Input Parameter:
    335: .  eps - the linear eigensolver context

    337:    Output Parameter:
    338: .  v - an array of vectors

    340:    Notes:
    341:    This function should be called after `EPSSolve()` has finished.

    343:    The user should provide in `v` an array of `nconv` vectors, where `nconv`
    344:    is the value returned by `EPSGetConverged()`.

    346:    The first $k$ vectors returned in `v` span an invariant subspace associated
    347:    with the first $k$ computed eigenvalues (note that this is not true if the
    348:    $k$-th eigenvalue is complex and matrix $A$ is real; in this case the first
    349:    $k+1$ vectors should be used). An invariant subspace $X$ of $A$ satisfies
    350:    $Ax\in X, \forall x\in X$ (a similar definition applies for generalized
    351:    eigenproblems).

    353:    Level: intermediate

    355: .seealso: [](ch:eps), `EPSGetEigenpair()`, `EPSGetConverged()`, `EPSSolve()`
    356: @*/
    357: PetscErrorCode EPSGetInvariantSubspace(EPS eps,Vec v[])
    358: {
    359:   PetscInt       i;
    360:   BV             V=eps->V;
    361:   Vec            w;

    363:   PetscFunctionBegin;
    365:   PetscAssertPointer(v,2);
    367:   EPSCheckSolved(eps,1);
    368:   PetscCheck(eps->ishermitian || eps->state!=EPS_STATE_EIGENVECTORS,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONGSTATE,"EPSGetInvariantSubspace must be called before EPSGetEigenpair,EPSGetEigenvector or EPSComputeError");
    369:   if (eps->balance!=EPS_BALANCE_NONE && eps->D) {
    370:     PetscCall(BVDuplicateResize(eps->V,eps->nconv,&V));
    371:     PetscCall(BVSetActiveColumns(eps->V,0,eps->nconv));
    372:     PetscCall(BVCopy(eps->V,V));
    373:     for (i=0;i<eps->nconv;i++) {
    374:       PetscCall(BVGetColumn(V,i,&w));
    375:       PetscCall(VecPointwiseDivide(w,w,eps->D));
    376:       PetscCall(BVRestoreColumn(V,i,&w));
    377:     }
    378:     PetscCall(BVOrthogonalize(V,NULL));
    379:   }
    380:   for (i=0;i<eps->nconv;i++) PetscCall(BVCopyVec(V,i,v[i]));
    381:   if (eps->balance!=EPS_BALANCE_NONE && eps->D) PetscCall(BVDestroy(&V));
    382:   PetscFunctionReturn(PETSC_SUCCESS);
    383: }

    385: /*@
    386:    EPSGetEigenpair - Gets the `i`-th solution of the eigenproblem as computed by
    387:    `EPSSolve()`. The solution consists in both the eigenvalue and the eigenvector.

    389:    Collective

    391:    Input Parameters:
    392: +  eps - the linear eigensolver context
    393: -  i   - index of the solution

    395:    Output Parameters:
    396: +  eigr - real part of eigenvalue
    397: .  eigi - imaginary part of eigenvalue
    398: .  Vr   - real part of eigenvector
    399: -  Vi   - imaginary part of eigenvector

    401:    Notes:
    402:    It is allowed to pass `NULL` for `Vr` and `Vi`, if the eigenvector is not
    403:    required. Otherwise, the caller must provide valid `Vec` objects, i.e.,
    404:    they must be created by the calling program with e.g. `MatCreateVecs()`.

    406:    If the eigenvalue is real, then `eigi` and `Vi` are set to zero. If PETSc is
    407:    configured with complex scalars the eigenvalue is stored
    408:    directly in `eigr` (`eigi` is set to zero) and the eigenvector in `Vr` (`Vi` is
    409:    set to zero). In both cases, the user can pass `NULL` in `eigi` and `Vi`.

    411:    The index `i` should be a value between 0 and `nconv`-1 (see `EPSGetConverged()`).
    412:    Eigenpairs are indexed according to the ordering criterion established
    413:    with `EPSSetWhichEigenpairs()`.

    415:    The 2-norm of the eigenvector is one unless the problem is generalized
    416:    Hermitian. In this case the eigenvector is normalized with respect to the
    417:    norm defined by the $B$ matrix.

    419:    Level: beginner

    421: .seealso: [](ch:eps), `EPSGetEigenvalue()`, `EPSGetEigenvector()`, `EPSGetLeftEigenvector()`, `EPSSolve()`, `EPSGetConverged()`, `EPSSetWhichEigenpairs()`, `EPSGetInvariantSubspace()`
    422: @*/
    423: PetscErrorCode EPSGetEigenpair(EPS eps,PetscInt i,PetscScalar *eigr,PetscScalar *eigi,Vec Vr,Vec Vi)
    424: {
    425:   PetscInt nconv;

    427:   PetscFunctionBegin;
    430:   EPSCheckSolved(eps,1);
    431:   PetscCheck(i>=0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index cannot be negative");
    432:   PetscCall(EPS_GetActualConverged(eps,&nconv));
    433:   PetscCheck(i<nconv,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index can be nconv-1 at most, see EPSGetConverged()");
    434:   PetscCall(EPSGetEigenvalue(eps,i,eigr,eigi));
    435:   if (Vr || Vi) PetscCall(EPSGetEigenvector(eps,i,Vr,Vi));
    436:   PetscFunctionReturn(PETSC_SUCCESS);
    437: }

    439: /*@
    440:    EPSGetEigenvalue - Gets the `i`-th eigenvalue as computed by `EPSSolve()`.

    442:    Not Collective

    444:    Input Parameters:
    445: +  eps - the linear eigensolver context
    446: -  i   - index of the solution

    448:    Output Parameters:
    449: +  eigr - real part of eigenvalue
    450: -  eigi - imaginary part of eigenvalue

    452:    Notes:
    453:    If the eigenvalue is real, then `eigi` is set to zero. If PETSc is
    454:    configured with complex scalars the eigenvalue is stored
    455:    directly in `eigr` (`eigi` is set to zero).

    457:    The index `i` should be a value between 0 and `nconv`-1 (see `EPSGetConverged()`).
    458:    Eigenpairs are indexed according to the ordering criterion established
    459:    with `EPSSetWhichEigenpairs()`.

    461:    Level: beginner

    463: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConverged()`, `EPSSetWhichEigenpairs()`, `EPSGetEigenpair()`
    464: @*/
    465: PetscErrorCode EPSGetEigenvalue(EPS eps,PetscInt i,PetscScalar *eigr,PetscScalar *eigi)
    466: {
    467:   PetscInt  k,nconv;
    468: #if !defined(PETSC_USE_COMPLEX)
    469:   PetscInt  k2, iquad;
    470: #endif

    472:   PetscFunctionBegin;
    474:   EPSCheckSolved(eps,1);
    475:   PetscCheck(i>=0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index cannot be negative");
    476:   PetscCall(EPS_GetActualConverged(eps,&nconv));
    477:   PetscCheck(i<nconv,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index can be nconv-1 at most, see EPSGetConverged()");
    478:   if (nconv==eps->nconv) {
    479:     k = eps->perm[i];
    480: #if defined(PETSC_USE_COMPLEX)
    481:     if (eigr) *eigr = eps->eigr[k];
    482:     if (eigi) *eigi = 0;
    483: #else
    484:     if (eigr) *eigr = eps->eigr[k];
    485:     if (eigi) *eigi = eps->eigi[k];
    486: #endif
    487:   } else {
    488:     PetscCheck(eps->problem_type==EPS_BSE || eps->problem_type==EPS_HAMILT,PetscObjectComm((PetscObject)eps),PETSC_ERR_PLIB,"Problem type should be BSE or Hamiltonian");
    489:     if (eps->problem_type==EPS_BSE) {
    490:       /* BSE problem, even index is +lambda, odd index is -lambda */
    491:       k = eps->perm[i/2];
    492: #if defined(PETSC_USE_COMPLEX)
    493:       if (eigr) *eigr = (i%2)? -eps->eigr[k]: eps->eigr[k];
    494:       if (eigi) *eigi = 0;
    495: #else
    496:       if (eigr) *eigr = (i%2)? -eps->eigr[k]: eps->eigr[k];
    497:       if (eigi) *eigi = eps->eigi[k];
    498: #endif
    499:     } else if (eps->problem_type==EPS_HAMILT) {
    500:       /* Hamiltonian eigenproblem */
    501:       k = eps->perm[i/2];
    502: #if defined(PETSC_USE_COMPLEX)
    503:       if (eigr) *eigr = (i%2)? -eps->eigr[k]: eps->eigr[k];
    504:       if (eigi) *eigi = 0;
    505: #else
    506:       if (eps->eigi[k]==0.0) { /* real eigenvalue */
    507:         if (eigr) *eigr = (i%2)? -eps->eigr[k]: eps->eigr[k];
    508:         if (eigi) *eigi = 0.0;
    509:       } else if (eps->eigr[k]==0.0) { /* purely imaginary eigenvalue */
    510:         if (eigr) *eigr = 0.0;
    511:         if (eigi) *eigi = (i%2)? -eps->eigi[k]: eps->eigi[k];
    512:       } else { /* quadruple eigenvalue (-conj(lambda),-lambda,lambda,conj(lambda)) */
    513:         iquad = i%2;  /* index within the 4 values */
    514:         if (i>1) {
    515:           k2 = eps->perm[(i-2)/2];
    516:           if (eps->eigr[k]==eps->eigr[k2] && eps->eigi[k]==-eps->eigi[k2]) iquad += 2;
    517:         }
    518:         if (eigr) *eigr = (iquad<2)? -eps->eigr[k]: eps->eigr[k];
    519:         if (eigi) *eigi = (iquad%3)? -eps->eigi[k]: eps->eigi[k];
    520:       }
    521: #endif
    522:     }
    523:   }
    524:   PetscFunctionReturn(PETSC_SUCCESS);
    525: }

    527: /*@
    528:    EPSGetEigenvector - Gets the `i`-th right eigenvector as computed by `EPSSolve()`.

    530:    Collective

    532:    Input Parameters:
    533: +  eps - the linear eigensolver context
    534: -  i   - index of the solution

    536:    Output Parameters:
    537: +  Vr   - real part of eigenvector
    538: -  Vi   - imaginary part of eigenvector

    540:    Notes:
    541:    The caller must provide valid `Vec` objects, i.e., they must be created
    542:    by the calling program with e.g. `MatCreateVecs()`.

    544:    If the corresponding eigenvalue is real, then `Vi` is set to zero. If PETSc is
    545:    configured with complex scalars the eigenvector is stored
    546:    directly in `Vr` (`Vi` is set to zero). In any case, the user can pass `NULL` in `Vr`
    547:    or `Vi` if one of them is not required.

    549:    The index `i` should be a value between 0 and `nconv`-1 (see `EPSGetConverged()`).
    550:    Eigenpairs are indexed according to the ordering criterion established
    551:    with `EPSSetWhichEigenpairs()`.

    553:    The 2-norm of the eigenvector is one unless the problem is generalized
    554:    Hermitian. In this case the eigenvector is normalized with respect to the
    555:    norm defined by the $B$ matrix.

    557:    Level: beginner

    559: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConverged()`, `EPSSetWhichEigenpairs()`, `EPSGetEigenpair()`, `EPSGetLeftEigenvector()`
    560: @*/
    561: PetscErrorCode EPSGetEigenvector(EPS eps,PetscInt i,Vec Vr,Vec Vi)
    562: {
    563:   PetscInt nconv;

    565:   PetscFunctionBegin;
    570:   EPSCheckSolved(eps,1);
    571:   PetscCheck(i>=0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index cannot be negative");
    572:   PetscCall(EPS_GetActualConverged(eps,&nconv));
    573:   PetscCheck(i<nconv,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index can be nconv-1 at most, see EPSGetConverged()");
    574:   PetscCall(EPSComputeVectors(eps));
    575:   PetscCall(EPS_GetEigenvector(eps,eps->V,i,Vr,Vi));
    576:   PetscFunctionReturn(PETSC_SUCCESS);
    577: }

    579: /*@
    580:    EPSGetLeftEigenvector - Gets the `i`-th left eigenvector as computed by `EPSSolve()`.

    582:    Collective

    584:    Input Parameters:
    585: +  eps - the linear eigensolver context
    586: -  i   - index of the solution

    588:    Output Parameters:
    589: +  Wr   - real part of left eigenvector
    590: -  Wi   - imaginary part of left eigenvector

    592:    Notes:
    593:    The caller must provide valid `Vec` objects, i.e., they must be created
    594:    by the calling program with e.g. `MatCreateVecs()`.

    596:    If the corresponding eigenvalue is real, then `Wi` is set to zero. If PETSc is
    597:    configured with complex scalars the eigenvector is stored directly in `Wr`
    598:    (`Wi` is set to zero). In any case, the user can pass `NULL` in `Wr` or `Wi` if
    599:    one of them is not required.

    601:    The index `i` should be a value between 0 and `nconv`-1 (see `EPSGetConverged()`).
    602:    Eigensolutions are indexed according to the ordering criterion established
    603:    with `EPSSetWhichEigenpairs()`.

    605:    Left eigenvectors are available only if the `twosided` flag was set, see
    606:    `EPSSetTwoSided()`.

    608:    Level: intermediate

    610: .seealso: [](ch:eps), `EPSGetEigenvector()`, `EPSGetConverged()`, `EPSSetWhichEigenpairs()`, `EPSSetTwoSided()`
    611: @*/
    612: PetscErrorCode EPSGetLeftEigenvector(EPS eps,PetscInt i,Vec Wr,Vec Wi)
    613: {
    614:   PetscInt    nconv;
    615:   PetscBool   trivial;
    616:   Mat         H;
    617:   IS          is[2];
    618:   Vec         v;

    620:   PetscFunctionBegin;
    625:   EPSCheckSolved(eps,1);
    626:   PetscCheck(i>=0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index cannot be negative");
    627:   PetscCall(EPS_GetActualConverged(eps,&nconv));
    628:   PetscCheck(i<nconv,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index can be nconv-1 at most, see EPSGetConverged()");

    630:   trivial = (eps->problem_type==EPS_HEP || eps->problem_type==EPS_GHEP || eps->problem_type==EPS_BSE)? PETSC_TRUE: PETSC_FALSE;
    631:   if (!trivial) PetscCheck(eps->twosided,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONGSTATE,"Must request left vectors with EPSSetTwoSided");

    633:   PetscCall(EPSComputeVectors(eps));
    634:   if (trivial) {
    635:     PetscCall(EPS_GetEigenvector(eps,eps->V,i,Wr,Wi));
    636:     if (eps->problem_type==EPS_BSE) {   /* change sign of bottom part of the vector */
    637:       PetscCall(STGetMatrix(eps->st,0,&H));
    638:       PetscCall(MatNestGetISs(H,is,NULL));
    639:       if (Wr) {
    640:         PetscCall(VecGetSubVector(Wr,is[1],&v));
    641:         PetscCall(VecScale(v,-1.0));
    642:         PetscCall(VecRestoreSubVector(Wr,is[1],&v));
    643:       }
    644: #if !defined(PETSC_USE_COMPLEX)
    645:       if (Wi) {
    646:         PetscCall(VecGetSubVector(Wi,is[1],&v));
    647:         PetscCall(VecScale(v,-1.0));
    648:         PetscCall(VecRestoreSubVector(Wi,is[1],&v));
    649:       }
    650: #endif
    651:     }
    652:   } else {
    653:     PetscCall(EPS_GetEigenvector(eps,eps->W,i,Wr,Wi));
    654:   }
    655:   PetscFunctionReturn(PETSC_SUCCESS);
    656: }

    658: /*@
    659:    EPSGetErrorEstimate - Returns the error estimate associated to the `i`-th
    660:    computed eigenpair.

    662:    Not Collective

    664:    Input Parameters:
    665: +  eps - the linear eigensolver context
    666: -  i   - index of eigenpair

    668:    Output Parameter:
    669: .  errest - the error estimate

    671:    Note:
    672:    This is the error estimate used internally by the eigensolver. The actual
    673:    error bound can be computed with `EPSComputeError()`. See discussion at
    674:    section [](#sec:errbnd).

    676:    Level: advanced

    678: .seealso: [](ch:eps), [](#sec:errbnd), `EPSComputeError()`
    679: @*/
    680: PetscErrorCode EPSGetErrorEstimate(EPS eps,PetscInt i,PetscReal *errest)
    681: {
    682:   PetscInt nconv;

    684:   PetscFunctionBegin;
    686:   PetscAssertPointer(errest,3);
    687:   EPSCheckSolved(eps,1);
    688:   PetscCheck(i>=0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index cannot be negative");
    689:   PetscCall(EPS_GetActualConverged(eps,&nconv));
    690:   PetscCheck(i<nconv,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"The index can be nconv-1 at most, see EPSGetConverged()");
    691:   if (nconv==eps->nconv) {
    692:     *errest = eps->errest[eps->perm[i]];
    693:   } else {
    694:     PetscCheck(eps->problem_type==EPS_BSE,PetscObjectComm((PetscObject)eps),PETSC_ERR_PLIB,"Problem type should be BSE");
    695:     /* BSE problem, even index is +lambda, odd index is -lambda, assume both have same error */
    696:     *errest = eps->errest[eps->perm[i/2]];
    697:   }
    698:   PetscFunctionReturn(PETSC_SUCCESS);
    699: }

    701: /*
    702:    EPSComputeResidualNorm_Private - Computes the norm of the residual vector
    703:    associated with an eigenpair.

    705:    Input Parameters:
    706:      trans - whether A' must be used instead of A
    707:      kr,ki - eigenvalue
    708:      xr,xi - eigenvector
    709:      z     - three work vectors (the second one not referenced in complex scalars)
    710: */
    711: PetscErrorCode EPSComputeResidualNorm_Private(EPS eps,PetscBool trans,PetscScalar kr,PetscScalar ki,Vec xr,Vec xi,Vec *z,PetscReal *norm)
    712: {
    713:   PetscInt       nmat;
    714:   Mat            A,B;
    715:   Vec            u,w;
    716:   PetscScalar    alpha;
    717: #if !defined(PETSC_USE_COMPLEX)
    718:   Vec            v;
    719:   PetscReal      ni,nr;
    720: #endif
    721:   PetscErrorCode (*matmult)(Mat,Vec,Vec) = trans? MatMultHermitianTranspose: MatMult;

    723:   PetscFunctionBegin;
    724:   u = z[0]; w = z[2];
    725:   PetscCall(STGetNumMatrices(eps->st,&nmat));
    726:   PetscCall(STGetMatrix(eps->st,0,&A));
    727:   if (nmat>1) PetscCall(STGetMatrix(eps->st,1,&B));

    729: #if !defined(PETSC_USE_COMPLEX)
    730:   v = z[1];
    731:   if (ki == 0 || PetscAbsScalar(ki) < PetscAbsScalar(kr*PETSC_MACHINE_EPSILON)) {
    732: #endif
    733:     PetscCall((*matmult)(A,xr,u));                          /* u=A*x */
    734:     if (PetscAbsScalar(kr) > PETSC_MACHINE_EPSILON) {
    735:       if (nmat>1) PetscCall((*matmult)(B,xr,w));
    736:       else PetscCall(VecCopy(xr,w));                        /* w=B*x */
    737:       alpha = trans? -PetscConj(kr): -kr;
    738:       PetscCall(VecAXPY(u,alpha,w));                        /* u=A*x-k*B*x */
    739:     }
    740:     PetscCall(VecNorm(u,NORM_2,norm));
    741: #if !defined(PETSC_USE_COMPLEX)
    742:   } else {
    743:     PetscCall((*matmult)(A,xr,u));                          /* u=A*xr */
    744:     if (SlepcAbsEigenvalue(kr,ki) > PETSC_MACHINE_EPSILON) {
    745:       if (nmat>1) PetscCall((*matmult)(B,xr,v));
    746:       else PetscCall(VecCopy(xr,v));                        /* v=B*xr */
    747:       PetscCall(VecAXPY(u,-kr,v));                          /* u=A*xr-kr*B*xr */
    748:       if (nmat>1) PetscCall((*matmult)(B,xi,w));
    749:       else PetscCall(VecCopy(xi,w));                        /* w=B*xi */
    750:       PetscCall(VecAXPY(u,trans?-ki:ki,w));                 /* u=A*xr-kr*B*xr+ki*B*xi */
    751:     }
    752:     PetscCall(VecNorm(u,NORM_2,&nr));
    753:     PetscCall((*matmult)(A,xi,u));                          /* u=A*xi */
    754:     if (SlepcAbsEigenvalue(kr,ki) > PETSC_MACHINE_EPSILON) {
    755:       PetscCall(VecAXPY(u,-kr,w));                          /* u=A*xi-kr*B*xi */
    756:       PetscCall(VecAXPY(u,trans?ki:-ki,v));                 /* u=A*xi-kr*B*xi-ki*B*xr */
    757:     }
    758:     PetscCall(VecNorm(u,NORM_2,&ni));
    759:     *norm = SlepcAbsEigenvalue(nr,ni);
    760:   }
    761: #endif
    762:   PetscFunctionReturn(PETSC_SUCCESS);
    763: }

    765: /*@
    766:    EPSComputeError - Computes the error (based on the residual norm) associated
    767:    with the `i`-th computed eigenpair.

    769:    Collective

    771:    Input Parameters:
    772: +  eps  - the linear eigensolver context
    773: .  i    - the solution index
    774: -  type - the type of error to compute, see `EPSErrorType`

    776:    Output Parameter:
    777: .  error - the error

    779:    Notes:
    780:    The error can be computed in various ways, all of them based on the residual
    781:    norm $\|Ax-\lambda Bx\|_2$ where $(\lambda,x)$ is the approximate eigenpair.

    783:    If the computation of left eigenvectors was enabled with `EPSSetTwoSided()`,
    784:    then the error will be computed using the maximum of the value above and
    785:    the left residual norm $\|y^*A-\lambda y^*B\|_2$, where $y$ is the approximate left
    786:    eigenvector.

    788:    Level: beginner

    790: .seealso: [](ch:eps), `EPSErrorType`, `EPSSolve()`, `EPSGetErrorEstimate()`, `EPSSetTwoSided()`
    791: @*/
    792: PetscErrorCode EPSComputeError(EPS eps,PetscInt i,EPSErrorType type,PetscReal *error)
    793: {
    794:   Mat            A,B;
    795:   Vec            xr,xi,w[3];
    796:   PetscReal      t,vecnorm=1.0,errorl;
    797:   PetscScalar    kr,ki;
    798:   PetscBool      flg;

    800:   PetscFunctionBegin;
    804:   PetscAssertPointer(error,4);
    805:   EPSCheckSolved(eps,1);

    807:   /* allocate work vectors */
    808: #if defined(PETSC_USE_COMPLEX)
    809:   PetscCall(EPSSetWorkVecs(eps,3));
    810:   xi   = NULL;
    811:   w[1] = NULL;
    812: #else
    813:   PetscCall(EPSSetWorkVecs(eps,5));
    814:   xi   = eps->work[3];
    815:   w[1] = eps->work[4];
    816: #endif
    817:   xr   = eps->work[0];
    818:   w[0] = eps->work[1];
    819:   w[2] = eps->work[2];

    821:   /* compute residual norm */
    822:   PetscCall(EPSGetEigenpair(eps,i,&kr,&ki,xr,xi));
    823:   PetscCall(EPSComputeResidualNorm_Private(eps,PETSC_FALSE,kr,ki,xr,xi,w,error));

    825:   /* compute 2-norm of eigenvector */
    826:   if (eps->problem_type==EPS_GHEP) PetscCall(VecNorm(xr,NORM_2,&vecnorm));

    828:   /* if two-sided, compute left residual norm and take the maximum */
    829:   if (eps->twosided) {
    830:     PetscCall(EPSGetLeftEigenvector(eps,i,xr,xi));
    831:     PetscCall(EPSComputeResidualNorm_Private(eps,PETSC_TRUE,kr,ki,xr,xi,w,&errorl));
    832:     *error = PetscMax(*error,errorl);
    833:   }

    835:   /* compute error */
    836:   switch (type) {
    837:     case EPS_ERROR_ABSOLUTE:
    838:       break;
    839:     case EPS_ERROR_RELATIVE:
    840:       *error /= SlepcAbsEigenvalue(kr,ki)*vecnorm;
    841:       break;
    842:     case EPS_ERROR_BACKWARD:
    843:       /* initialization of matrix norms */
    844:       if (!eps->nrma) {
    845:         PetscCall(STGetMatrix(eps->st,0,&A));
    846:         PetscCall(MatHasOperation(A,MATOP_NORM,&flg));
    847:         PetscCheck(flg,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"The computation of backward errors requires a matrix norm operation");
    848:         PetscCall(MatNorm(A,NORM_INFINITY,&eps->nrma));
    849:       }
    850:       if (eps->isgeneralized) {
    851:         if (!eps->nrmb) {
    852:           PetscCall(STGetMatrix(eps->st,1,&B));
    853:           PetscCall(MatHasOperation(B,MATOP_NORM,&flg));
    854:           PetscCheck(flg,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"The computation of backward errors requires a matrix norm operation");
    855:           PetscCall(MatNorm(B,NORM_INFINITY,&eps->nrmb));
    856:         }
    857:       } else eps->nrmb = 1.0;
    858:       t = SlepcAbsEigenvalue(kr,ki);
    859:       *error /= (eps->nrma+t*eps->nrmb)*vecnorm;
    860:       break;
    861:     default:
    862:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid error type");
    863:   }
    864:   PetscFunctionReturn(PETSC_SUCCESS);
    865: }

    867: /*
    868:    EPSGetStartVector - Generate a suitable vector to be used as the starting vector
    869:    for the recurrence that builds the right subspace.

    871:    Collective

    873:    Input Parameters:
    874: +  eps - the linear eigensolver context
    875: -  i   - iteration number

    877:    Output Parameter:
    878: .  breakdown - flag indicating that a breakdown has occurred

    880:    Notes:
    881:    The start vector is computed from another vector: for the first step (i=0),
    882:    the first initial vector is used (see EPSSetInitialSpace()); otherwise a random
    883:    vector is created. Then this vector is forced to be in the range of OP (only
    884:    for generalized definite problems) and orthonormalized with respect to all
    885:    V-vectors up to i-1. The resulting vector is placed in V[i].

    887:    The flag breakdown is set to true if either i=0 and the vector belongs to the
    888:    deflation space, or i>0 and the vector is linearly dependent with respect
    889:    to the V-vectors.
    890: */
    891: PetscErrorCode EPSGetStartVector(EPS eps,PetscInt i,PetscBool *breakdown)
    892: {
    893:   PetscReal      norm;
    894:   PetscBool      lindep;
    895:   Vec            w,z;

    897:   PetscFunctionBegin;

    901:   /* For the first step, use the first initial vector, otherwise a random one */
    902:   if (i>0 || eps->nini==0) PetscCall(BVSetRandomColumn(eps->V,i));

    904:   /* Force the vector to be in the range of OP for generalized problems with B-inner product */
    905:   if (eps->ispositive || (eps->isgeneralized && eps->ishermitian)) {
    906:     PetscCall(BVCreateVec(eps->V,&w));
    907:     PetscCall(BVCopyVec(eps->V,i,w));
    908:     PetscCall(BVGetColumn(eps->V,i,&z));
    909:     PetscCall(STApply(eps->st,w,z));
    910:     PetscCall(BVRestoreColumn(eps->V,i,&z));
    911:     PetscCall(VecDestroy(&w));
    912:   }

    914:   /* Orthonormalize the vector with respect to previous vectors */
    915:   PetscCall(BVOrthogonalizeColumn(eps->V,i,NULL,&norm,&lindep));
    916:   if (breakdown) *breakdown = lindep;
    917:   else if (lindep || norm == 0.0) {
    918:     PetscCheck(i,PetscObjectComm((PetscObject)eps),PETSC_ERR_PLIB,"Initial vector is zero or belongs to the deflation space");
    919:     PetscCheck(!i,PetscObjectComm((PetscObject)eps),PETSC_ERR_CONV_FAILED,"Unable to generate more start vectors");
    920:   }
    921:   PetscCall(BVScaleColumn(eps->V,i,1.0/norm));
    922:   PetscFunctionReturn(PETSC_SUCCESS);
    923: }

    925: /*
    926:    EPSGetLeftStartVector - Generate a suitable vector to be used as the left starting
    927:    vector for the recurrence that builds the left subspace. See EPSGetStartVector().
    928: */
    929: PetscErrorCode EPSGetLeftStartVector(EPS eps,PetscInt i,PetscBool *breakdown)
    930: {
    931:   PetscReal      norm;
    932:   PetscBool      lindep;
    933:   Vec            w,z;

    935:   PetscFunctionBegin;

    939:   /* For the first step, use the first initial vector, otherwise a random one */
    940:   if (i>0 || eps->ninil==0) PetscCall(BVSetRandomColumn(eps->W,i));

    942:   /* Force the vector to be in the range of OP' for generalized problems with B-inner product */
    943:   if (eps->ispositive || (eps->isgeneralized && eps->ishermitian)) {
    944:     PetscCall(BVCreateVec(eps->W,&w));
    945:     PetscCall(BVCopyVec(eps->W,i,w));
    946:     PetscCall(BVGetColumn(eps->W,i,&z));
    947:     PetscCall(STApplyHermitianTranspose(eps->st,w,z));
    948:     PetscCall(BVRestoreColumn(eps->W,i,&z));
    949:     PetscCall(VecDestroy(&w));
    950:   }

    952:   /* Orthonormalize the vector with respect to previous vectors */
    953:   PetscCall(BVOrthogonalizeColumn(eps->W,i,NULL,&norm,&lindep));
    954:   if (breakdown) *breakdown = lindep;
    955:   else if (lindep || norm == 0.0) {
    956:     PetscCheck(i,PetscObjectComm((PetscObject)eps),PETSC_ERR_PLIB,"Left initial vector is zero");
    957:     PetscCheck(!i,PetscObjectComm((PetscObject)eps),PETSC_ERR_CONV_FAILED,"Unable to generate more left start vectors");
    958:   }
    959:   PetscCall(BVScaleColumn(eps->W,i,1.0/norm));
    960:   PetscFunctionReturn(PETSC_SUCCESS);
    961: }