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

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

      1: /*
      2:       MFN routines related to the solution process.

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

      8:    This file is part of SLEPc.

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

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

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

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

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

     32:    Collective on MFN

     34:    Input Parameters:
     35: +  mfn - matrix function context obtained from MFNCreate()
     36: -  b   - the right hand side vector

     38:    Output Parameter:
     39: .  x   - the solution (this may be the same vector as b, then b will be
     40:          overwritten with the answer)

     42:    Options Database Keys:
     43: +  -mfn_view - print information about the solver used
     44: .  -mfn_view_mat binary - save the matrix to the default binary viewer
     45: .  -mfn_view_rhs binary - save right hand side vector to the default binary viewer
     46: .  -mfn_view_solution binary - save computed solution vector to the default binary viewer
     47: -  -mfn_converged_reason - print reason for convergence, and number of iterations

     49:    Notes:
     50:    The matrix A is specified with MFNSetOperator().
     51:    The function f is specified with MFNSetFN().

     53:    Level: beginner

     55: .seealso: MFNCreate(), MFNSetUp(), MFNDestroy(), MFNSetTolerances(),
     56:           MFNSetOperator(), MFNSetFN()
     57: @*/
     58: PetscErrorCode MFNSolve(MFN mfn,Vec b,Vec x)
     59: {

     68:   VecLocked(x,3);

     70:   /* call setup */
     71:   MFNSetUp(mfn);
     72:   mfn->its = 0;

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

     76:   /* check nonzero right-hand side */
     77:   VecNorm(b,NORM_2,&mfn->bnorm);
     78:   if (!mfn->bnorm) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Cannot pass a zero b vector to MFNSolve()");

     80:   /* call solver */
     81:   PetscLogEventBegin(MFN_Solve,mfn,b,x,0);
     82:   if (b!=x) { VecLockPush(b); }
     83:   (*mfn->ops->solve)(mfn,b,x);
     84:   if (b!=x) { VecLockPop(b); }
     85:   PetscLogEventEnd(MFN_Solve,mfn,b,x,0);

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

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

     91:   /* various viewers */
     92:   MFNViewFromOptions(mfn,NULL,"-mfn_view");
     93:   MFNReasonViewFromOptions(mfn);
     94:   MatViewFromOptions(mfn->A,(PetscObject)mfn,"-mfn_view_mat");
     95:   VecViewFromOptions(b,(PetscObject)mfn,"-mfn_view_rhs");
     96:   VecViewFromOptions(x,(PetscObject)mfn,"-mfn_view_solution");
     97:   return(0);
     98: }

    102: /*@
    103:    MFNGetIterationNumber - Gets the current iteration number. If the
    104:    call to MFNSolve() is complete, then it returns the number of iterations
    105:    carried out by the solution method.

    107:    Not Collective

    109:    Input Parameter:
    110: .  mfn - the matrix function context

    112:    Output Parameter:
    113: .  its - number of iterations

    115:    Level: intermediate

    117:    Note:
    118:    During the i-th iteration this call returns i-1. If MFNSolve() is
    119:    complete, then parameter "its" contains either the iteration number at
    120:    which convergence was successfully reached, or failure was detected.
    121:    Call MFNGetConvergedReason() to determine if the solver converged or
    122:    failed and why.

    124: .seealso: MFNGetConvergedReason(), MFNSetTolerances()
    125: @*/
    126: PetscErrorCode MFNGetIterationNumber(MFN mfn,PetscInt *its)
    127: {
    131:   *its = mfn->its;
    132:   return(0);
    133: }

    137: /*@
    138:    MFNGetConvergedReason - Gets the reason why the MFNSolve() iteration was
    139:    stopped.

    141:    Not Collective

    143:    Input Parameter:
    144: .  mfn - the matrix function context

    146:    Output Parameter:
    147: .  reason - negative value indicates diverged, positive value converged

    149:    Notes:

    151:    Possible values for reason are
    152: +  MFN_CONVERGED_TOL - converged up to tolerance
    153: .  MFN_CONVERGED_ITS - solver completed the requested number of steps
    154: .  MFN_DIVERGED_ITS - required more than max_it iterations to reach convergence
    155: -  MFN_DIVERGED_BREAKDOWN - generic breakdown in method

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

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

    165:    Level: intermediate

    167: .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
    168: @*/
    169: PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)
    170: {
    174:   *reason = mfn->reason;
    175:   return(0);
    176: }