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: }