1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2019, Universitat Politecnica de Valencia, Spain
6: This file is part of SLEPc.
7: SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9: */
10: /*
11: MFN routines related to the solution process
12: */
14: #include <slepc/private/mfnimpl.h> /*I "slepcmfn.h" I*/
16: /*@
17: MFNSolve - Solves the matrix function problem. Given a vector b, the
18: vector x = f(A)*b is returned.
20: Collective on MFN 22: Input Parameters:
23: + mfn - matrix function context obtained from MFNCreate()
24: - b - the right hand side vector
26: Output Parameter:
27: . x - the solution (this may be the same vector as b, then b will be
28: overwritten with the answer)
30: Options Database Keys:
31: + -mfn_view - print information about the solver used
32: . -mfn_view_mat binary - save the matrix to the default binary viewer
33: . -mfn_view_rhs binary - save right hand side vector to the default binary viewer
34: . -mfn_view_solution binary - save computed solution vector to the default binary viewer
35: - -mfn_converged_reason - print reason for convergence, and number of iterations
37: Notes:
38: The matrix A is specified with MFNSetOperator().
39: The function f is specified with MFNSetFN().
41: Level: beginner
43: .seealso: MFNCreate(), MFNSetUp(), MFNDestroy(), MFNSetTolerances(),
44: MFNSetOperator(), MFNSetFN()
45: @*/
46: PetscErrorCode MFNSolve(MFN mfn,Vec b,Vec x) 47: {
56: VecSetErrorIfLocked(x,3);
58: /* call setup */
59: MFNSetUp(mfn);
60: mfn->its = 0;
62: MFNViewFromOptions(mfn,NULL,"-mfn_view_pre");
64: /* check nonzero right-hand side */
65: VecNorm(b,NORM_2,&mfn->bnorm);
66: if (!mfn->bnorm) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Cannot pass a zero b vector to MFNSolve()");
68: /* call solver */
69: PetscLogEventBegin(MFN_Solve,mfn,b,x,0);
70: if (b!=x) { VecLockReadPush(b); }
71: (*mfn->ops->solve)(mfn,b,x);
72: if (b!=x) { VecLockReadPop(b); }
73: PetscLogEventEnd(MFN_Solve,mfn,b,x,0);
75: if (!mfn->reason) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
77: if (mfn->errorifnotconverged && mfn->reason < 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_NOT_CONVERGED,"MFNSolve has not converged");
79: /* various viewers */
80: MFNViewFromOptions(mfn,NULL,"-mfn_view");
81: MFNReasonViewFromOptions(mfn);
82: MatViewFromOptions(mfn->A,(PetscObject)mfn,"-mfn_view_mat");
83: VecViewFromOptions(b,(PetscObject)mfn,"-mfn_view_rhs");
84: VecViewFromOptions(x,(PetscObject)mfn,"-mfn_view_solution");
85: return(0);
86: }
88: /*@
89: MFNGetIterationNumber - Gets the current iteration number. If the
90: call to MFNSolve() is complete, then it returns the number of iterations
91: carried out by the solution method.
93: Not Collective
95: Input Parameter:
96: . mfn - the matrix function context
98: Output Parameter:
99: . its - number of iterations
101: Note:
102: During the i-th iteration this call returns i-1. If MFNSolve() is
103: complete, then parameter "its" contains either the iteration number at
104: which convergence was successfully reached, or failure was detected.
105: Call MFNGetConvergedReason() to determine if the solver converged or
106: failed and why.
108: Level: intermediate
110: .seealso: MFNGetConvergedReason(), MFNSetTolerances()
111: @*/
112: PetscErrorCode MFNGetIterationNumber(MFN mfn,PetscInt *its)113: {
117: *its = mfn->its;
118: return(0);
119: }
121: /*@
122: MFNGetConvergedReason - Gets the reason why the MFNSolve() iteration was
123: stopped.
125: Not Collective
127: Input Parameter:
128: . mfn - the matrix function context
130: Output Parameter:
131: . reason - negative value indicates diverged, positive value converged
133: Notes:
135: Possible values for reason are
136: + MFN_CONVERGED_TOL - converged up to tolerance
137: . MFN_CONVERGED_ITS - solver completed the requested number of steps
138: . MFN_DIVERGED_ITS - required more than max_it iterations to reach convergence
139: - MFN_DIVERGED_BREAKDOWN - generic breakdown in method
141: Can only be called after the call to MFNSolve() is complete.
143: Basic solvers (e.g. unrestarted Krylov iterations) cannot determine if the
144: computation is accurate up to the requested tolerance. In that case, the
145: converged reason is set to MFN_CONVERGED_ITS if the requested number of steps
146: (for instance, the ncv value in unrestarted Krylov methods) have been
147: completed successfully.
149: Level: intermediate
151: .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
152: @*/
153: PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)154: {
158: *reason = mfn->reason;
159: return(0);
160: }