Date: 2020-01-13T12:02:10+00:00

Actual source code: mfnsolve.c
slepc-3.12.2 2020-01-13
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2019, 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:    MFN routines related to the solution process
     12: */

     14: #include <slepc/private/mfnimpl.h>   /*I "slepcmfn.h" I*/

     16: /*@
     17:    MFNSolve - Solves the matrix function problem. Given a vector b, the
     18:    vector x = f(A)*b is returned.

     20:    Collective on mfn

     22:    Input Parameters:
     23: +  mfn - matrix function context obtained from MFNCreate()
     24: -  b   - the right hand side vector

     26:    Output Parameter:
     27: .  x   - the solution (this may be the same vector as b, then b will be
     28:          overwritten with the answer)

     30:    Options Database Keys:
     31: +  -mfn_view - print information about the solver used
     32: .  -mfn_view_mat binary - save the matrix to the default binary viewer
     33: .  -mfn_view_rhs binary - save right hand side vector to the default binary viewer
     34: .  -mfn_view_solution binary - save computed solution vector to the default binary viewer
     35: -  -mfn_converged_reason - print reason for convergence, and number of iterations

     37:    Notes:
     38:    The matrix A is specified with MFNSetOperator().
     39:    The function f is specified with MFNSetFN().

     41:    Level: beginner

     43: .seealso: MFNCreate(), MFNSetUp(), MFNDestroy(), MFNSetTolerances(),
     44:           MFNSetOperator(), MFNSetFN()
     45: @*/
     46: PetscErrorCode MFNSolve(MFN mfn,Vec b,Vec x)
     47: {

     56:   VecSetErrorIfLocked(x,3);

     58:   /* call setup */
     59:   MFNSetUp(mfn);
     60:   mfn->its = 0;

     62:   MFNViewFromOptions(mfn,NULL,"-mfn_view_pre");

     64:   /* check nonzero right-hand side */
     65:   VecNorm(b,NORM_2,&mfn->bnorm);
     66:   if (!mfn->bnorm) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Cannot pass a zero b vector to MFNSolve()");

     68:   /* call solver */
     69:   PetscLogEventBegin(MFN_Solve,mfn,b,x,0);
     70:   if (b!=x) { VecLockReadPush(b); }
     71:   (*mfn->ops->solve)(mfn,b,x);
     72:   if (b!=x) { VecLockReadPop(b); }
     73:   PetscLogEventEnd(MFN_Solve,mfn,b,x,0);

     75:   if (!mfn->reason) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");

     77:   if (mfn->errorifnotconverged && mfn->reason < 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_NOT_CONVERGED,"MFNSolve has not converged");

     79:   /* various viewers */
     80:   MFNViewFromOptions(mfn,NULL,"-mfn_view");
     81:   MFNReasonViewFromOptions(mfn);
     82:   MatViewFromOptions(mfn->A,(PetscObject)mfn,"-mfn_view_mat");
     83:   VecViewFromOptions(b,(PetscObject)mfn,"-mfn_view_rhs");
     84:   VecViewFromOptions(x,(PetscObject)mfn,"-mfn_view_solution");
     85:   return(0);
     86: }

     88: /*@
     89:    MFNGetIterationNumber - Gets the current iteration number. If the
     90:    call to MFNSolve() is complete, then it returns the number of iterations
     91:    carried out by the solution method.

     93:    Not Collective

     95:    Input Parameter:
     96: .  mfn - the matrix function context

     98:    Output Parameter:
     99: .  its - number of iterations

    101:    Note:
    102:    During the i-th iteration this call returns i-1. If MFNSolve() is
    103:    complete, then parameter "its" contains either the iteration number at
    104:    which convergence was successfully reached, or failure was detected.
    105:    Call MFNGetConvergedReason() to determine if the solver converged or
    106:    failed and why.

    108:    Level: intermediate

    110: .seealso: MFNGetConvergedReason(), MFNSetTolerances()
    111: @*/
    112: PetscErrorCode MFNGetIterationNumber(MFN mfn,PetscInt *its)
    113: {
    117:   *its = mfn->its;
    118:   return(0);
    119: }

    121: /*@
    122:    MFNGetConvergedReason - Gets the reason why the MFNSolve() iteration was
    123:    stopped.

    125:    Not Collective

    127:    Input Parameter:
    128: .  mfn - the matrix function context

    130:    Output Parameter:
    131: .  reason - negative value indicates diverged, positive value converged

    133:    Notes:

    135:    Possible values for reason are
    136: +  MFN_CONVERGED_TOL - converged up to tolerance
    137: .  MFN_CONVERGED_ITS - solver completed the requested number of steps
    138: .  MFN_DIVERGED_ITS - required more than max_it iterations to reach convergence
    139: -  MFN_DIVERGED_BREAKDOWN - generic breakdown in method

    141:    Can only be called after the call to MFNSolve() is complete.

    143:    Basic solvers (e.g. unrestarted Krylov iterations) cannot determine if the
    144:    computation is accurate up to the requested tolerance. In that case, the
    145:    converged reason is set to MFN_CONVERGED_ITS if the requested number of steps
    146:    (for instance, the ncv value in unrestarted Krylov methods) have been
    147:    completed successfully.

    149:    Level: intermediate

    151: .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
    152: @*/
    153: PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)
    154: {
    158:   *reason = mfn->reason;
    159:   return(0);
    160: }