Actual source code: slepcmfn.h
slepc-3.21.1 2024-04-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:    User interface for the SLEPc matrix function solver object
     12: */

     14: #pragma once

     16: #include <slepcbv.h>
     17: #include <slepcfn.h>

     19: /* SUBMANSEC = MFN */

     21: SLEPC_EXTERN PetscErrorCode MFNInitializePackage(void);
     22: SLEPC_EXTERN PetscErrorCode MFNFinalizePackage(void);

     24: /*S
     25:     MFN - SLEPc object that encapsulates functionality for matrix functions.

     27:     Level: beginner

     29: .seealso:  MFNCreate()
     30: S*/
     31: typedef struct _p_MFN* MFN;

     33: /*J
     34:     MFNType - String with the name of a method for computing matrix functions.

     36:     Level: beginner

     38: .seealso: MFNSetType(), MFN
     39: J*/
     40: typedef const char* MFNType;
     41: #define MFNKRYLOV   "krylov"
     42: #define MFNEXPOKIT  "expokit"

     44: /* Logging support */
     45: SLEPC_EXTERN PetscClassId MFN_CLASSID;

     47: SLEPC_EXTERN PetscErrorCode MFNCreate(MPI_Comm,MFN *);
     48: SLEPC_EXTERN PetscErrorCode MFNDestroy(MFN*);
     49: SLEPC_EXTERN PetscErrorCode MFNReset(MFN);
     50: SLEPC_EXTERN PetscErrorCode MFNSetType(MFN,MFNType);
     51: SLEPC_EXTERN PetscErrorCode MFNGetType(MFN,MFNType*);
     52: SLEPC_EXTERN PetscErrorCode MFNSetOperator(MFN,Mat);
     53: SLEPC_EXTERN PetscErrorCode MFNGetOperator(MFN,Mat*);
     54: SLEPC_EXTERN PetscErrorCode MFNSetFromOptions(MFN);
     55: SLEPC_EXTERN PetscErrorCode MFNSetUp(MFN);
     56: SLEPC_EXTERN PetscErrorCode MFNSolve(MFN,Vec,Vec);
     57: SLEPC_EXTERN PetscErrorCode MFNSolveTranspose(MFN,Vec,Vec);
     58: SLEPC_EXTERN PetscErrorCode MFNView(MFN,PetscViewer);
     59: SLEPC_EXTERN PetscErrorCode MFNViewFromOptions(MFN,PetscObject,const char[]);
     60: SLEPC_EXTERN PetscErrorCode MFNConvergedReasonView(MFN,PetscViewer);
     61: SLEPC_EXTERN PetscErrorCode MFNConvergedReasonViewFromOptions(MFN);
     62: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "MFNConvergedReasonView()", ) static inline PetscErrorCode MFNReasonView(MFN mfn,PetscViewer v) {return MFNConvergedReasonView(mfn,v);}
     63: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "MFNConvergedReasonViewFromOptions()", ) static inline PetscErrorCode MFNReasonViewFromOptions(MFN mfn) {return MFNConvergedReasonViewFromOptions(mfn);}

     65: SLEPC_EXTERN PetscErrorCode MFNSetBV(MFN,BV);
     66: SLEPC_EXTERN PetscErrorCode MFNGetBV(MFN,BV*);
     67: SLEPC_EXTERN PetscErrorCode MFNSetFN(MFN,FN);
     68: SLEPC_EXTERN PetscErrorCode MFNGetFN(MFN,FN*);
     69: SLEPC_EXTERN PetscErrorCode MFNSetTolerances(MFN,PetscReal,PetscInt);
     70: SLEPC_EXTERN PetscErrorCode MFNGetTolerances(MFN,PetscReal*,PetscInt*);
     71: SLEPC_EXTERN PetscErrorCode MFNSetDimensions(MFN,PetscInt);
     72: SLEPC_EXTERN PetscErrorCode MFNGetDimensions(MFN,PetscInt*);
     73: SLEPC_EXTERN PetscErrorCode MFNGetIterationNumber(MFN,PetscInt*);

     75: SLEPC_EXTERN PetscErrorCode MFNSetErrorIfNotConverged(MFN,PetscBool);
     76: SLEPC_EXTERN PetscErrorCode MFNGetErrorIfNotConverged(MFN,PetscBool*);

     78: SLEPC_EXTERN PetscErrorCode MFNMonitor(MFN,PetscInt,PetscReal);
     79: SLEPC_EXTERN PetscErrorCode MFNMonitorSet(MFN,PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*),void*,PetscErrorCode (*)(void**));
     80: SLEPC_EXTERN PetscErrorCode MFNMonitorCancel(MFN);
     81: SLEPC_EXTERN PetscErrorCode MFNGetMonitorContext(MFN,void*);

     83: SLEPC_EXTERN PetscErrorCode MFNMonitorSetFromOptions(MFN,const char[],const char[],void*);
     84: SLEPC_EXTERN PetscErrorCode MFNMonitorLGCreate(MPI_Comm,const char[],const char[],const char[],PetscInt,const char*[],int,int,int,int,PetscDrawLG*);
     85: SLEPC_EXTERN PetscErrorCode MFNMonitorDefault(MFN,PetscInt,PetscReal,PetscViewerAndFormat*);
     86: SLEPC_EXTERN PetscErrorCode MFNMonitorDefaultDrawLG(MFN,PetscInt,PetscReal,PetscViewerAndFormat*);
     87: SLEPC_EXTERN PetscErrorCode MFNMonitorDefaultDrawLGCreate(PetscViewer,PetscViewerFormat,void *,PetscViewerAndFormat**);

     89: SLEPC_EXTERN PetscErrorCode MFNSetOptionsPrefix(MFN,const char*);
     90: SLEPC_EXTERN PetscErrorCode MFNAppendOptionsPrefix(MFN,const char*);
     91: SLEPC_EXTERN PetscErrorCode MFNGetOptionsPrefix(MFN,const char*[]);

     93: /*E
     94:     MFNConvergedReason - reason a matrix function iteration was said to
     95:          have converged or diverged

     97:     Level: intermediate

     99: .seealso: MFNSolve(), MFNGetConvergedReason(), MFNSetTolerances()
    100: E*/
    101: typedef enum {/* converged */
    102:               MFN_CONVERGED_TOL                =  1,
    103:               MFN_CONVERGED_ITS                =  2,
    104:               /* diverged */
    105:               MFN_DIVERGED_ITS                 = -1,
    106:               MFN_DIVERGED_BREAKDOWN           = -2,
    107:               MFN_CONVERGED_ITERATING          =  0} MFNConvergedReason;
    108: SLEPC_EXTERN const char *const*MFNConvergedReasons;

    110: SLEPC_EXTERN PetscErrorCode MFNGetConvergedReason(MFN,MFNConvergedReason *);

    112: SLEPC_EXTERN PetscFunctionList MFNList;
    113: SLEPC_EXTERN PetscFunctionList MFNMonitorList;
    114: SLEPC_EXTERN PetscFunctionList MFNMonitorCreateList;
    115: SLEPC_EXTERN PetscFunctionList MFNMonitorDestroyList;
    116: SLEPC_EXTERN PetscErrorCode MFNRegister(const char[],PetscErrorCode(*)(MFN));
    117: SLEPC_EXTERN PetscErrorCode MFNMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,PetscErrorCode(*)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*),PetscErrorCode(*)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**),PetscErrorCode(*)(PetscViewerAndFormat**));

    119: SLEPC_EXTERN PetscErrorCode MFNAllocateSolution(MFN,PetscInt);