Actual source code: mfnsolve.c

slepc-3.18.3 2023-03-24
Report Typos and Errors
  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: }