LCOV - code coverage report
Current view: top level - mfn/interface - mfnsolve.c (source / functions) Hit Total Coverage
Test: SLEPc Lines: 54 54 100.0 %
Date: 2024-03-29 00:34:52 Functions: 5 5 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : /*
       2             :    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       3             :    SLEPc - Scalable Library for Eigenvalue Problem Computations
       4             :    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
       5             : 
       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             : */
      13             : 
      14             : #include <slepc/private/mfnimpl.h>   /*I "slepcmfn.h" I*/
      15             : 
      16         104 : static PetscErrorCode MFNSolve_Private(MFN mfn,Vec b,Vec x)
      17             : {
      18         104 :   PetscFunctionBegin;
      19         104 :   PetscCall(VecSetErrorIfLocked(x,3));
      20             : 
      21             :   /* call setup */
      22         104 :   PetscCall(MFNSetUp(mfn));
      23         104 :   mfn->its = 0;
      24             : 
      25         104 :   PetscCall(MFNViewFromOptions(mfn,NULL,"-mfn_view_pre"));
      26             : 
      27             :   /* check nonzero right-hand side */
      28         104 :   PetscCall(VecNorm(b,NORM_2,&mfn->bnorm));
      29         104 :   PetscCheck(mfn->bnorm,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Cannot pass a zero b vector to MFNSolve()");
      30             : 
      31             :   /* call solver */
      32         104 :   PetscCall(PetscLogEventBegin(MFN_Solve,mfn,b,x,0));
      33         104 :   if (b!=x) PetscCall(VecLockReadPush(b));
      34         104 :   PetscUseTypeMethod(mfn,solve,b,x);
      35         104 :   if (b!=x) PetscCall(VecLockReadPop(b));
      36         104 :   PetscCall(PetscLogEventEnd(MFN_Solve,mfn,b,x,0));
      37             : 
      38         104 :   PetscCheck(mfn->reason,PetscObjectComm((PetscObject)mfn),PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
      39             : 
      40         104 :   PetscCheck(!mfn->errorifnotconverged || mfn->reason>=0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_NOT_CONVERGED,"MFNSolve has not converged");
      41             : 
      42             :   /* various viewers */
      43         104 :   PetscCall(MFNViewFromOptions(mfn,NULL,"-mfn_view"));
      44         104 :   PetscCall(MFNConvergedReasonViewFromOptions(mfn));
      45         104 :   PetscCall(MatViewFromOptions(mfn->A,(PetscObject)mfn,"-mfn_view_mat"));
      46         104 :   PetscCall(VecViewFromOptions(b,(PetscObject)mfn,"-mfn_view_rhs"));
      47         104 :   PetscCall(VecViewFromOptions(x,(PetscObject)mfn,"-mfn_view_solution"));
      48         104 :   PetscFunctionReturn(PETSC_SUCCESS);
      49             : }
      50             : 
      51             : /*@
      52             :    MFNSolve - Solves the matrix function problem. Given a vector b, the
      53             :    vector x = f(A)*b is returned.
      54             : 
      55             :    Collective
      56             : 
      57             :    Input Parameters:
      58             : +  mfn - matrix function context obtained from MFNCreate()
      59             : -  b   - the right hand side vector
      60             : 
      61             :    Output Parameter:
      62             : .  x   - the solution (this may be the same vector as b, then b will be
      63             :          overwritten with the answer)
      64             : 
      65             :    Options Database Keys:
      66             : +  -mfn_view - print information about the solver used
      67             : .  -mfn_view_mat binary - save the matrix to the default binary viewer
      68             : .  -mfn_view_rhs binary - save right hand side vector to the default binary viewer
      69             : .  -mfn_view_solution binary - save computed solution vector to the default binary viewer
      70             : -  -mfn_converged_reason - print reason for convergence, and number of iterations
      71             : 
      72             :    Notes:
      73             :    The matrix A is specified with MFNSetOperator().
      74             :    The function f is specified with MFNSetFN().
      75             : 
      76             :    Level: beginner
      77             : 
      78             : .seealso: MFNCreate(), MFNSetUp(), MFNDestroy(), MFNSetTolerances(),
      79             :           MFNSetOperator(), MFNSetFN()
      80             : @*/
      81         102 : PetscErrorCode MFNSolve(MFN mfn,Vec b,Vec x)
      82             : {
      83         102 :   PetscFunctionBegin;
      84         102 :   PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
      85         102 :   PetscValidHeaderSpecific(b,VEC_CLASSID,2);
      86         102 :   PetscCheckSameComm(mfn,1,b,2);
      87         102 :   if (b!=x) PetscValidHeaderSpecific(x,VEC_CLASSID,3);
      88         102 :   if (b!=x) PetscCheckSameComm(mfn,1,x,3);
      89         102 :   mfn->transpose_solve = PETSC_FALSE;
      90         102 :   PetscCall(MFNSolve_Private(mfn,b,x));
      91         102 :   PetscFunctionReturn(PETSC_SUCCESS);
      92             : }
      93             : 
      94             : /*@
      95             :    MFNSolveTranspose - Solves the transpose matrix function problem. Given a vector b,
      96             :    the vector x = f(A^T)*b is returned.
      97             : 
      98             :    Collective
      99             : 
     100             :    Input Parameters:
     101             : +  mfn - matrix function context obtained from MFNCreate()
     102             : -  b   - the right hand side vector
     103             : 
     104             :    Output Parameter:
     105             : .  x   - the solution (this may be the same vector as b, then b will be
     106             :          overwritten with the answer)
     107             : 
     108             :    Note:
     109             :    See available options at MFNSolve().
     110             : 
     111             :    Level: beginner
     112             : 
     113             : .seealso: MFNSolve()
     114             : @*/
     115           2 : PetscErrorCode MFNSolveTranspose(MFN mfn,Vec b,Vec x)
     116             : {
     117           2 :   PetscFunctionBegin;
     118           2 :   PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
     119           2 :   PetscValidHeaderSpecific(b,VEC_CLASSID,2);
     120           2 :   PetscCheckSameComm(mfn,1,b,2);
     121           2 :   if (b!=x) PetscValidHeaderSpecific(x,VEC_CLASSID,3);
     122           2 :   if (b!=x) PetscCheckSameComm(mfn,1,x,3);
     123           2 :   mfn->transpose_solve = PETSC_TRUE;
     124           2 :   if (!mfn->AT) PetscCall(MatCreateTranspose(mfn->A,&mfn->AT));
     125           2 :   PetscCall(MFNSolve_Private(mfn,b,x));
     126           2 :   PetscFunctionReturn(PETSC_SUCCESS);
     127             : }
     128             : 
     129             : /*@
     130             :    MFNGetIterationNumber - Gets the current iteration number. If the
     131             :    call to MFNSolve() is complete, then it returns the number of iterations
     132             :    carried out by the solution method.
     133             : 
     134             :    Not Collective
     135             : 
     136             :    Input Parameter:
     137             : .  mfn - the matrix function context
     138             : 
     139             :    Output Parameter:
     140             : .  its - number of iterations
     141             : 
     142             :    Note:
     143             :    During the i-th iteration this call returns i-1. If MFNSolve() is
     144             :    complete, then parameter "its" contains either the iteration number at
     145             :    which convergence was successfully reached, or failure was detected.
     146             :    Call MFNGetConvergedReason() to determine if the solver converged or
     147             :    failed and why.
     148             : 
     149             :    Level: intermediate
     150             : 
     151             : .seealso: MFNGetConvergedReason(), MFNSetTolerances()
     152             : @*/
     153           9 : PetscErrorCode MFNGetIterationNumber(MFN mfn,PetscInt *its)
     154             : {
     155           9 :   PetscFunctionBegin;
     156           9 :   PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
     157           9 :   PetscAssertPointer(its,2);
     158           9 :   *its = mfn->its;
     159           9 :   PetscFunctionReturn(PETSC_SUCCESS);
     160             : }
     161             : 
     162             : /*@
     163             :    MFNGetConvergedReason - Gets the reason why the MFNSolve() iteration was
     164             :    stopped.
     165             : 
     166             :    Not Collective
     167             : 
     168             :    Input Parameter:
     169             : .  mfn - the matrix function context
     170             : 
     171             :    Output Parameter:
     172             : .  reason - negative value indicates diverged, positive value converged
     173             : 
     174             :    Notes:
     175             : 
     176             :    Possible values for reason are
     177             : +  MFN_CONVERGED_TOL - converged up to tolerance
     178             : .  MFN_CONVERGED_ITS - solver completed the requested number of steps
     179             : .  MFN_DIVERGED_ITS - required more than max_it iterations to reach convergence
     180             : -  MFN_DIVERGED_BREAKDOWN - generic breakdown in method
     181             : 
     182             :    Can only be called after the call to MFNSolve() is complete.
     183             : 
     184             :    Basic solvers (e.g. unrestarted Krylov iterations) cannot determine if the
     185             :    computation is accurate up to the requested tolerance. In that case, the
     186             :    converged reason is set to MFN_CONVERGED_ITS if the requested number of steps
     187             :    (for instance, the ncv value in unrestarted Krylov methods) have been
     188             :    completed successfully.
     189             : 
     190             :    Level: intermediate
     191             : 
     192             : .seealso: MFNSetTolerances(), MFNSolve(), MFNConvergedReason, MFNSetErrorIfNotConverged()
     193             : @*/
     194          14 : PetscErrorCode MFNGetConvergedReason(MFN mfn,MFNConvergedReason *reason)
     195             : {
     196          14 :   PetscFunctionBegin;
     197          14 :   PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
     198          14 :   PetscAssertPointer(reason,2);
     199          14 :   *reason = mfn->reason;
     200          14 :   PetscFunctionReturn(PETSC_SUCCESS);
     201             : }

Generated by: LCOV version 1.14