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);