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: 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: /*S
79: MFNMonitorFn - A function prototype for functions provided to MFNMonitorSet()
81: Calling Sequence:
82: + mfn - matrix function context obtained from MFNCreate()
83: . its - iteration number
84: . errest - error estimate
85: - ctx - optional monitoring context, as provided with MFNMonitorSet()
87: Level: beginner
89: .seealso: 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 - matrix function context obtained from MFNCreate()
98: . its - iteration number
99: . errest - error estimate
100: - ctx - PetscViewerAndFormat object
102: Level: beginner
104: Note:
105: This is an MFNMonitorFn specialized for a context of PetscViewerAndFormat.
107: .seealso: 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 creation when provided to MFNMonitorRegister()
114: Calling Sequence:
115: + viewer - the viewer to be used with the MFNMonitorRegisterFn
116: . format - the format of the viewer
117: . ctx - a context for the monitor
118: - result - a PetscViewerAndFormat object
120: Level: beginner
122: .seealso: MFNMonitorRegisterFn, MFNMonitorSet(), MFNMonitorRegister(), MFNMonitorFn, MFNMonitorRegisterDestroyFn
123: S*/
124: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode MFNMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);
126: /*S
127: MFNMonitorRegisterDestroyFn - A function prototype for functions that do the after use destruction when provided to MFNMonitorRegister()
129: Calling Sequence:
130: . vf - a PetscViewerAndFormat object to be destroyed, including any context
132: Level: beginner
134: .seealso: MFNMonitorRegisterFn, MFNMonitorSet(), MFNMonitorRegister(), MFNMonitorFn, MFNMonitorRegisterCreateFn
135: S*/
136: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode MFNMonitorRegisterDestroyFn(PetscViewerAndFormat **result);
138: SLEPC_EXTERN PetscErrorCode MFNMonitor(MFN,PetscInt,PetscReal);
139: SLEPC_EXTERN PetscErrorCode MFNMonitorSet(MFN,MFNMonitorFn,void*,PetscCtxDestroyFn*);
140: SLEPC_EXTERN PetscErrorCode MFNMonitorCancel(MFN);
141: SLEPC_EXTERN PetscErrorCode MFNGetMonitorContext(MFN,void*);
143: SLEPC_EXTERN PetscErrorCode MFNMonitorSetFromOptions(MFN,const char[],const char[],void*);
144: SLEPC_EXTERN MFNMonitorRegisterFn MFNMonitorDefault;
145: SLEPC_EXTERN MFNMonitorRegisterFn MFNMonitorDefaultDrawLG;
146: SLEPC_EXTERN MFNMonitorRegisterCreateFn MFNMonitorDefaultDrawLGCreate;
148: SLEPC_EXTERN PetscErrorCode MFNSetOptionsPrefix(MFN,const char*);
149: SLEPC_EXTERN PetscErrorCode MFNAppendOptionsPrefix(MFN,const char*);
150: SLEPC_EXTERN PetscErrorCode MFNGetOptionsPrefix(MFN,const char*[]);
152: /*E
153: MFNConvergedReason - reason a matrix function iteration was said to
154: have converged or diverged
156: Level: intermediate
158: .seealso: MFNSolve(), MFNGetConvergedReason(), MFNSetTolerances()
159: E*/
160: typedef enum {/* converged */
161: MFN_CONVERGED_TOL = 1,
162: MFN_CONVERGED_ITS = 2,
163: /* diverged */
164: MFN_DIVERGED_ITS = -1,
165: MFN_DIVERGED_BREAKDOWN = -2,
166: MFN_CONVERGED_ITERATING = 0} MFNConvergedReason;
167: SLEPC_EXTERN const char *const*MFNConvergedReasons;
169: SLEPC_EXTERN PetscErrorCode MFNGetConvergedReason(MFN,MFNConvergedReason *);
171: SLEPC_EXTERN PetscFunctionList MFNList;
172: SLEPC_EXTERN PetscFunctionList MFNMonitorList;
173: SLEPC_EXTERN PetscFunctionList MFNMonitorCreateList;
174: SLEPC_EXTERN PetscFunctionList MFNMonitorDestroyList;
175: SLEPC_EXTERN PetscErrorCode MFNRegister(const char[],PetscErrorCode(*)(MFN));
176: SLEPC_EXTERN PetscErrorCode MFNMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,MFNMonitorRegisterFn*,MFNMonitorRegisterCreateFn*,MFNMonitorRegisterDestroyFn*);
178: SLEPC_EXTERN PetscErrorCode MFNAllocateSolution(MFN,PetscInt);