Date: 2013-09-02T10:08:24+00:00

Actual source code: mfnsolve.c

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

      4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      6:    Copyright (c) 2002-2013, 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(alpha*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

     41:    Options Database Keys:
     42: +  -mfn_view - print information about the solver used
     43: .  -mfn_view_mat binary - save the matrix to the default binary viewer
     44: .  -mfn_view_rhs binary - save right hand side vector to the default binary viewer
     45: -  -mfn_view_solution binary - save computed solution vector to the default binary viewer

     47:    Notes:
     48:    The matrix A is specified with MFNSetOperator().
     49:    The function f is specified with MFNSetFunction().
     50:    The scalar alpha is specified with MFNSetScaleFactor().

     52:    Level: beginner

     54: .seealso: MFNCreate(), MFNSetUp(), MFNDestroy(), MFNSetTolerances(),
     55:           MFNSetOperator(), MFNSetFunction(), MFNSetScaleFactor()
     56: @*/
     57: PetscErrorCode MFNSolve(MFN mfn,Vec b,Vec x)
     58: {
     59:   PetscErrorCode    ierr;
     60:   PetscBool         flg;
     61:   PetscViewer       viewer;
     62:   PetscViewerFormat format;

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

     75:   MFNMonitor(mfn,mfn->its,0);

     77:   /* call solver */
     78:   PetscLogEventBegin(MFN_Solve,mfn,b,x,0);
     79:   (*mfn->ops->solve)(mfn,b,x);
     80:   PetscLogEventEnd(MFN_Solve,mfn,b,x,0);

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

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

     86:   /* various viewers */
     87:   MatViewFromOptions(mfn->A,((PetscObject)mfn)->prefix,"-mfn_view_mat");
     88:   VecViewFromOptions(b,((PetscObject)mfn)->prefix,"-mfn_view_rhs");
     89:   VecViewFromOptions(x,((PetscObject)mfn)->prefix,"-mfn_view_solution");

     91:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,"-mfn_view",&viewer,&format,&flg);
     92:   if (flg && !PetscPreLoadingOn) {
     93:     PetscViewerPushFormat(viewer,format);
     94:     MFNView(mfn,viewer);
     95:     PetscViewerPopFormat(viewer);
     96:     PetscViewerDestroy(&viewer);
     97:   }
     98:   return(0);
     99: }

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

    108:    Not Collective

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

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

    116:    Level: intermediate

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

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

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

    142:    Not Collective

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

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

    150:    Possible values for reason:
    151: +  MFN_CONVERGED_TOL - converged up to tolerance
    152: .  MFN_DIVERGED_ITS - required more than its to reach convergence
    153: -  MFN_DIVERGED_BREAKDOWN - generic breakdown in method

    155:    Note:
    156:    Can only be called after the call to MFNSolve() is complete.

    158:    Level: intermediate

    160: .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
    161: @*/
    162: PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)
    163: {
    167:   *reason = mfn->reason;
    168:   return(0);
    169: }