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: VecLockPush(b);
83: (*mfn->ops->solve)(mfn,b,x);
84: 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: }