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 functionality for matrix functions.

 27:    Level: beginner

 29: .seealso: [](ch:mfn), `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: [](ch:mfn), `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: /*S
 79:    MFNMonitorFn - A function prototype for functions provided to `MFNMonitorSet()`.

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

 87:    Level: intermediate

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

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

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

102:    Level: advanced

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

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

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

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

121:    Level: advanced

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

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

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

134:    Level: advanced

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

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

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

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

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

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

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

171:    Level: intermediate

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

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

186: SLEPC_EXTERN PetscFunctionList MFNList;
187: SLEPC_EXTERN PetscFunctionList MFNMonitorList;
188: SLEPC_EXTERN PetscFunctionList MFNMonitorCreateList;
189: SLEPC_EXTERN PetscFunctionList MFNMonitorDestroyList;
190: SLEPC_EXTERN PetscErrorCode MFNRegister(const char[],PetscErrorCode(*)(MFN));
191: SLEPC_EXTERN PetscErrorCode MFNMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,MFNMonitorRegisterFn*,MFNMonitorRegisterCreateFn*,MFNMonitorRegisterDestroyFn*);

193: SLEPC_EXTERN PetscErrorCode MFNAllocateSolution(MFN,PetscInt);