Actual source code: slepcmfn.h

      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 the functionality for matrix functions,
     26:    more precisely the action of a matrix function on a vector, $y=f(A)v$.

     28:    Level: beginner

     30: .seealso: [](ch:mfn), `MFNCreate()`
     31: S*/
     32: typedef struct _p_MFN* MFN;

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

     37:    Level: beginner

     39: .seealso: [](ch:mfn), `MFNSetType()`, `MFN`
     40: J*/
     41: typedef const char *MFNType;
     42: #define MFNKRYLOV   "krylov"
     43: #define MFNEXPOKIT  "expokit"

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

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

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

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

     79: /*S
     80:    MFNMonitorFn - A function prototype for functions provided to `MFNMonitorSet()`.

     82:    Calling Sequence:
     83: +  mfn    - the matrix function solver context
     84: .  its    - iteration number
     85: .  errest - error estimate
     86: -  ctx    - optional monitoring context, as provided with `MFNMonitorSet()`

     88:    Level: intermediate

     90: .seealso: [](ch:mfn), `MFNMonitorSet()`
     91: S*/
     92: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode MFNMonitorFn(MFN mfn,PetscInt its,PetscReal errest,void *ctx);

     94: /*S
     95:    MFNMonitorRegisterFn - A function prototype for functions provided to `MFNMonitorRegister()`.

     97:    Calling Sequence:
     98: +  mfn    - the matrix function solver context
     99: .  its    - iteration number
    100: .  errest - error estimate
    101: -  ctx    - `PetscViewerAndFormat` object

    103:    Level: advanced

    105:    Note:
    106:    This is an `MFNMonitorFn` specialized for a context of `PetscViewerAndFormat`.

    108: .seealso: [](ch:mfn), `MFNMonitorSet()`, `MFNMonitorRegister()`, `MFNMonitorFn`, `MFNMonitorRegisterCreateFn`, `MFNMonitorRegisterDestroyFn`
    109: S*/
    110: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode MFNMonitorRegisterFn(MFN mfn,PetscInt its,PetscReal errest,PetscViewerAndFormat *ctx);

    112: /*S
    113:    MFNMonitorRegisterCreateFn - A function prototype for functions that do the
    114:    creation when provided to `MFNMonitorRegister()`.

    116:    Calling Sequence:
    117: +  viewer - the viewer to be used with the `MFNMonitorRegisterFn`
    118: .  format - the format of the viewer
    119: .  ctx    - a context for the monitor
    120: -  result - a `PetscViewerAndFormat` object

    122:    Level: advanced

    124: .seealso: [](ch:mfn), `MFNMonitorRegisterFn`, `MFNMonitorSet()`, `MFNMonitorRegister()`, `MFNMonitorFn`, `MFNMonitorRegisterDestroyFn`
    125: S*/
    126: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode MFNMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);

    128: /*S
    129:    MFNMonitorRegisterDestroyFn - A function prototype for functions that do the after
    130:    use destruction when provided to `MFNMonitorRegister()`.

    132:    Calling Sequence:
    133: .  vf - a `PetscViewerAndFormat` object to be destroyed, including any context

    135:    Level: advanced

    137: .seealso: [](ch:mfn), `MFNMonitorRegisterFn`, `MFNMonitorSet()`, `MFNMonitorRegister()`, `MFNMonitorFn`, `MFNMonitorRegisterCreateFn`
    138: S*/
    139: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode MFNMonitorRegisterDestroyFn(PetscViewerAndFormat **result);

    141: SLEPC_EXTERN PetscErrorCode MFNMonitor(MFN,PetscInt,PetscReal);
    142: SLEPC_EXTERN PetscErrorCode MFNMonitorSet(MFN,MFNMonitorFn,void*,PetscCtxDestroyFn*);
    143: SLEPC_EXTERN PetscErrorCode MFNMonitorCancel(MFN);
    144: SLEPC_EXTERN PetscErrorCode MFNGetMonitorContext(MFN,void*);

    146: SLEPC_EXTERN PetscErrorCode MFNMonitorSetFromOptions(MFN,const char[],const char[],void*);
    147: SLEPC_EXTERN MFNMonitorRegisterFn       MFNMonitorDefault;
    148: SLEPC_EXTERN MFNMonitorRegisterFn       MFNMonitorDefaultDrawLG;
    149: SLEPC_EXTERN MFNMonitorRegisterCreateFn MFNMonitorDefaultDrawLGCreate;

    151: SLEPC_EXTERN PetscErrorCode MFNSetOptionsPrefix(MFN,const char[]);
    152: SLEPC_EXTERN PetscErrorCode MFNAppendOptionsPrefix(MFN,const char[]);
    153: SLEPC_EXTERN PetscErrorCode MFNGetOptionsPrefix(MFN,const char*[]);

    155: /*E
    156:    MFNConvergedReason - Reason a matrix function iteration was determined to
    157:    have converged or diverged.

    159:    Values:
    160: +  `MFN_CONVERGED_TOL`       - converged up to tolerance
    161: .  `MFN_CONVERGED_ITS`       - solver completed the requested number of steps
    162: .  `MFN_DIVERGED_ITS`        - exceeded the maximum number of allowed iterations
    163: .  `MFN_DIVERGED_BREAKDOWN`  - generic breakdown in method
    164: -  `MFN_CONVERGED_ITERATING` - the solver is still running

    166:    Note:
    167:    Basic solvers (e.g., unrestarted Krylov iterations) cannot determine if the
    168:    computation is accurate up to the requested tolerance. In that case, the
    169:    converged reason is set to `MFN_CONVERGED_ITS` if the requested number of steps
    170:    (for instance, the `ncv` value in unrestarted Krylov methods) have been
    171:    completed successfully.

    173:    Level: intermediate

    175: .seealso: [](ch:mfn), `MFNSolve()`, `MFNGetConvergedReason()`, `MFNSetTolerances()`
    176: E*/
    177: typedef enum {/* converged */
    178:               MFN_CONVERGED_TOL                =  1,
    179:               MFN_CONVERGED_ITS                =  2,
    180:               /* diverged */
    181:               MFN_DIVERGED_ITS                 = -1,
    182:               MFN_DIVERGED_BREAKDOWN           = -2,
    183:               MFN_CONVERGED_ITERATING          =  0} MFNConvergedReason;
    184: SLEPC_EXTERN const char *const*MFNConvergedReasons;

    186: /*MC
    187:    MFN_CONVERGED_TOL - The computed error estimate is below the tolerance.

    189:    Level: intermediate

    191: .seealso: [](ch:mfn), `MFNSolve()`, `MFNGetConvergedReason()`, `MFNConvergedReason`
    192: M*/

    194: /*MC
    195:    MFN_CONVERGED_ITS - The solver completed the requested number of steps.

    197:    Note:
    198:    Basic solvers (e.g., unrestarted Krylov iterations) cannot determine if the
    199:    computation is accurate up to the requested tolerance. In that case, the
    200:    converged reason is set to `MFN_CONVERGED_ITS` if the requested number of steps
    201:    (for instance, the `ncv` value in unrestarted Krylov methods) have been
    202:    completed successfully.

    204:    Level: intermediate

    206: .seealso: [](ch:mfn), `MFNSolve()`, `MFNGetConvergedReason()`, `MFNConvergedReason`
    207: M*/

    209: /*MC
    210:    MFN_DIVERGED_ITS - Ran out of iterations before the convergence criterion was
    211:    reached.

    213:    Level: intermediate

    215: .seealso: [](ch:mfn), `MFNSolve()`, `MFNGetConvergedReason()`, `MFNConvergedReason`
    216: M*/

    218: /*MC
    219:    MFN_DIVERGED_BREAKDOWN - A breakdown in the solver was detected so the
    220:    method could not continue.

    222:    Level: intermediate

    224: .seealso: [](ch:mfn), `MFNSolve()`, `MFNGetConvergedReason()`, `MFNConvergedReason`
    225: M*/

    227: /*MC
    228:    MFN_CONVERGED_ITERATING - This flag is returned if `MFNGetConvergedReason()` is called
    229:    while `MFNSolve()` is still running..

    231:    Level: intermediate

    233: .seealso: [](ch:mfn), `MFNSolve()`, `MFNGetConvergedReason()`, `MFNConvergedReason`
    234: M*/

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

    238: SLEPC_EXTERN PetscFunctionList MFNList;
    239: SLEPC_EXTERN PetscFunctionList MFNMonitorList;
    240: SLEPC_EXTERN PetscFunctionList MFNMonitorCreateList;
    241: SLEPC_EXTERN PetscFunctionList MFNMonitorDestroyList;
    242: SLEPC_EXTERN PetscErrorCode MFNRegister(const char[],PetscErrorCode(*)(MFN));
    243: SLEPC_EXTERN PetscErrorCode MFNMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,MFNMonitorRegisterFn*,MFNMonitorRegisterCreateFn*,MFNMonitorRegisterDestroyFn*);

    245: SLEPC_EXTERN PetscErrorCode MFNAllocateSolution(MFN,PetscInt);