Actual source code: mfnsolve.c
slepc-3.18.1 2022-11-02
1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-, 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>
16: static PetscErrorCode MFNSolve_Private(MFN mfn,Vec b,Vec x)
17: {
18: VecSetErrorIfLocked(x,3);
20: /* call setup */
21: MFNSetUp(mfn);
22: mfn->its = 0;
24: MFNViewFromOptions(mfn,NULL,"-mfn_view_pre");
26: /* check nonzero right-hand side */
27: VecNorm(b,NORM_2,&mfn->bnorm);
30: /* call solver */
31: PetscLogEventBegin(MFN_Solve,mfn,b,x,0);
32: if (b!=x) VecLockReadPush(b);
33: PetscUseTypeMethod(mfn,solve,b,x);
34: if (b!=x) VecLockReadPop(b);
35: PetscLogEventEnd(MFN_Solve,mfn,b,x,0);
41: /* various viewers */
42: MFNViewFromOptions(mfn,NULL,"-mfn_view");
43: MFNConvergedReasonViewFromOptions(mfn);
44: MatViewFromOptions(mfn->A,(PetscObject)mfn,"-mfn_view_mat");
45: VecViewFromOptions(b,(PetscObject)mfn,"-mfn_view_rhs");
46: VecViewFromOptions(x,(PetscObject)mfn,"-mfn_view_solution");
47: return 0;
48: }
50: /*@
51: MFNSolve - Solves the matrix function problem. Given a vector b, the
52: vector x = f(A)*b is returned.
54: Collective on mfn
56: Input Parameters:
57: + mfn - matrix function context obtained from MFNCreate()
58: - b - the right hand side vector
60: Output Parameter:
61: . x - the solution (this may be the same vector as b, then b will be
62: overwritten with the answer)
64: Options Database Keys:
65: + -mfn_view - print information about the solver used
66: . -mfn_view_mat binary - save the matrix to the default binary viewer
67: . -mfn_view_rhs binary - save right hand side vector to the default binary viewer
68: . -mfn_view_solution binary - save computed solution vector to the default binary viewer
69: - -mfn_converged_reason - print reason for convergence, and number of iterations
71: Notes:
72: The matrix A is specified with MFNSetOperator().
73: The function f is specified with MFNSetFN().
75: Level: beginner
77: .seealso: MFNCreate(), MFNSetUp(), MFNDestroy(), MFNSetTolerances(),
78: MFNSetOperator(), MFNSetFN()
79: @*/
80: PetscErrorCode MFNSolve(MFN mfn,Vec b,Vec x)
81: {
87: mfn->transpose_solve = PETSC_FALSE;
88: MFNSolve_Private(mfn,b,x);
89: return 0;
90: }
92: /*@
93: MFNSolveTranspose - Solves the transpose matrix function problem. Given a vector b,
94: the vector x = f(A^T)*b is returned.
96: Collective on mfn
98: Input Parameters:
99: + mfn - matrix function context obtained from MFNCreate()
100: - b - the right hand side vector
102: Output Parameter:
103: . x - the solution (this may be the same vector as b, then b will be
104: overwritten with the answer)
106: Note:
107: See available options at MFNSolve().
109: Level: beginner
111: .seealso: MFNSolve()
112: @*/
113: PetscErrorCode MFNSolveTranspose(MFN mfn,Vec b,Vec x)
114: {
120: mfn->transpose_solve = PETSC_TRUE;
121: if (!mfn->AT) MatCreateTranspose(mfn->A,&mfn->AT);
122: MFNSolve_Private(mfn,b,x);
123: return 0;
124: }
126: /*@
127: MFNGetIterationNumber - Gets the current iteration number. If the
128: call to MFNSolve() is complete, then it returns the number of iterations
129: carried out by the solution method.
131: Not Collective
133: Input Parameter:
134: . mfn - the matrix function context
136: Output Parameter:
137: . its - number of iterations
139: Note:
140: During the i-th iteration this call returns i-1. If MFNSolve() is
141: complete, then parameter "its" contains either the iteration number at
142: which convergence was successfully reached, or failure was detected.
143: Call MFNGetConvergedReason() to determine if the solver converged or
144: failed and why.
146: Level: intermediate
148: .seealso: MFNGetConvergedReason(), MFNSetTolerances()
149: @*/
150: PetscErrorCode MFNGetIterationNumber(MFN mfn,PetscInt *its)
151: {
154: *its = mfn->its;
155: return 0;
156: }
158: /*@
159: MFNGetConvergedReason - Gets the reason why the MFNSolve() iteration was
160: stopped.
162: Not Collective
164: Input Parameter:
165: . mfn - the matrix function context
167: Output Parameter:
168: . reason - negative value indicates diverged, positive value converged
170: Notes:
172: Possible values for reason are
173: + MFN_CONVERGED_TOL - converged up to tolerance
174: . MFN_CONVERGED_ITS - solver completed the requested number of steps
175: . MFN_DIVERGED_ITS - required more than max_it iterations to reach convergence
176: - MFN_DIVERGED_BREAKDOWN - generic breakdown in method
178: Can only be called after the call to MFNSolve() is complete.
180: Basic solvers (e.g. unrestarted Krylov iterations) cannot determine if the
181: computation is accurate up to the requested tolerance. In that case, the
182: converged reason is set to MFN_CONVERGED_ITS if the requested number of steps
183: (for instance, the ncv value in unrestarted Krylov methods) have been
184: completed successfully.
186: Level: intermediate
188: .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
189: @*/
190: PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)
191: {
194: *reason = mfn->reason;
195: return 0;
196: }