Date: 2023-01-26T12:19:38+00:00

Actual source code: mfnsolve.c
slepc-3.18.2 2023-01-26
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: }