Actual source code: mfnsolve.c

slepc-3.6.1 2015-09-03
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-2015, 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:   MFNMonitor(mfn,mfn->its,0);
 75:   MFNViewFromOptions(mfn,NULL,"-mfn_view_pre");

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

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

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

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

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

104:    Not Collective

106:    Input Parameter:
107: .  mfn - the matrix function context

109:    Output Parameter:
110: .  its - number of iterations

112:    Level: intermediate

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

121: .seealso: MFNGetConvergedReason(), MFNSetTolerances()
122: @*/
123: PetscErrorCode MFNGetIterationNumber(MFN mfn,PetscInt *its)
124: {
128:   *its = mfn->its;
129:   return(0);
130: }

134: /*@
135:    MFNGetConvergedReason - Gets the reason why the MFNSolve() iteration was
136:    stopped.

138:    Not Collective

140:    Input Parameter:
141: .  mfn - the matrix function context

143:    Output Parameter:
144: .  reason - negative value indicates diverged, positive value converged

146:    Possible values for reason:
147: +  MFN_CONVERGED_TOL - converged up to tolerance
148: .  MFN_DIVERGED_ITS - required more than its to reach convergence
149: -  MFN_DIVERGED_BREAKDOWN - generic breakdown in method

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

154:    Level: intermediate

156: .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
157: @*/
158: PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)
159: {
163:   *reason = mfn->reason;
164:   return(0);
165: }