Actual source code: slepcpep.h
slepc-3.8.3 2018-04-03
1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2017, 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 SLEPc's polynomial eigenvalue solvers
12: */
16: #include <slepceps.h>
18: PETSC_EXTERN PetscErrorCode PEPInitializePackage(void);
20: /*S
21: PEP - Abstract SLEPc object that manages all the polynomial eigenvalue
22: problem solvers.
24: Level: beginner
26: .seealso: PEPCreate()
27: S*/
28: typedef struct _p_PEP* PEP;
30: /*J
31: PEPType - String with the name of a polynomial eigensolver
33: Level: beginner
35: .seealso: PEPSetType(), PEP
36: J*/
37: typedef const char* PEPType;
38: #define PEPLINEAR "linear"
39: #define PEPQARNOLDI "qarnoldi"
40: #define PEPTOAR "toar"
41: #define PEPSTOAR "stoar"
42: #define PEPJD "jd"
44: /* Logging support */
45: PETSC_EXTERN PetscClassId PEP_CLASSID;
47: /*E
48: PEPProblemType - Determines the type of the polynomial eigenproblem
50: Level: intermediate
52: .seealso: PEPSetProblemType(), PEPGetProblemType()
53: E*/
54: typedef enum { PEP_GENERAL=1,
55: PEP_HERMITIAN, /* All A_i Hermitian */
56: PEP_GYROSCOPIC /* QEP with M, K Hermitian, M>0, C skew-Hermitian */
57: } PEPProblemType;
59: /*E
60: PEPWhich - Determines which part of the spectrum is requested
62: Level: intermediate
64: .seealso: PEPSetWhichEigenpairs(), PEPGetWhichEigenpairs()
65: E*/
66: typedef enum { PEP_LARGEST_MAGNITUDE=1,
67: PEP_SMALLEST_MAGNITUDE,
68: PEP_LARGEST_REAL,
69: PEP_SMALLEST_REAL,
70: PEP_LARGEST_IMAGINARY,
71: PEP_SMALLEST_IMAGINARY,
72: PEP_TARGET_MAGNITUDE,
73: PEP_TARGET_REAL,
74: PEP_TARGET_IMAGINARY,
75: PEP_WHICH_USER } PEPWhich;
77: /*E
78: PEPBasis - The type of polynomial basis used to represent the polynomial
79: eigenproblem
81: Level: intermediate
83: .seealso: PEPSetBasis()
84: E*/
85: typedef enum { PEP_BASIS_MONOMIAL,
86: PEP_BASIS_CHEBYSHEV1,
87: PEP_BASIS_CHEBYSHEV2,
88: PEP_BASIS_LEGENDRE,
89: PEP_BASIS_LAGUERRE,
90: PEP_BASIS_HERMITE } PEPBasis;
91: PETSC_EXTERN const char *PEPBasisTypes[];
93: /*E
94: PEPScale - The scaling strategy
96: Level: intermediate
98: .seealso: PEPSetScale()
99: E*/
100: typedef enum { PEP_SCALE_NONE,
101: PEP_SCALE_SCALAR,
102: PEP_SCALE_DIAGONAL,
103: PEP_SCALE_BOTH } PEPScale;
104: PETSC_EXTERN const char *PEPScaleTypes[];
106: /*E
107: PEPRefine - The refinement type
109: Level: intermediate
111: .seealso: PEPSetRefine()
112: E*/
113: typedef enum { PEP_REFINE_NONE,
114: PEP_REFINE_SIMPLE,
115: PEP_REFINE_MULTIPLE } PEPRefine;
116: PETSC_EXTERN const char *PEPRefineTypes[];
118: /*E
119: PEPRefineScheme - The scheme used for solving linear systems during iterative refinement
121: Level: intermediate
123: .seealso: PEPSetRefine()
124: E*/
125: typedef enum { PEP_REFINE_SCHEME_SCHUR=1,
126: PEP_REFINE_SCHEME_MBE,
127: PEP_REFINE_SCHEME_EXPLICIT } PEPRefineScheme;
128: PETSC_EXTERN const char *PEPRefineSchemes[];
130: /*E
131: PEPExtract - The extraction type
133: Level: intermediate
135: .seealso: PEPSetExtract()
136: E*/
137: typedef enum { PEP_EXTRACT_NONE=1,
138: PEP_EXTRACT_NORM,
139: PEP_EXTRACT_RESIDUAL,
140: PEP_EXTRACT_STRUCTURED } PEPExtract;
141: PETSC_EXTERN const char *PEPExtractTypes[];
143: /*E
144: PEPErrorType - The error type used to assess accuracy of computed solutions
146: Level: intermediate
148: .seealso: PEPComputeError()
149: E*/
150: typedef enum { PEP_ERROR_ABSOLUTE,
151: PEP_ERROR_RELATIVE,
152: PEP_ERROR_BACKWARD } PEPErrorType;
153: PETSC_EXTERN const char *PEPErrorTypes[];
155: /*E
156: PEPConv - Determines the convergence test
158: Level: intermediate
160: .seealso: PEPSetConvergenceTest(), PEPSetConvergenceTestFunction()
161: E*/
162: typedef enum { PEP_CONV_ABS,
163: PEP_CONV_REL,
164: PEP_CONV_NORM,
165: PEP_CONV_USER } PEPConv;
167: /*E
168: PEPStop - Determines the stopping test
170: Level: advanced
172: .seealso: PEPSetStoppingTest(), PEPSetStoppingTestFunction()
173: E*/
174: typedef enum { PEP_STOP_BASIC,
175: PEP_STOP_USER } PEPStop;
177: /*E
178: PEPConvergedReason - Reason an eigensolver was said to
179: have converged or diverged
181: Level: intermediate
183: .seealso: PEPSolve(), PEPGetConvergedReason(), PEPSetTolerances()
184: E*/
185: typedef enum {/* converged */
186: PEP_CONVERGED_TOL = 1,
187: PEP_CONVERGED_USER = 2,
188: /* diverged */
189: PEP_DIVERGED_ITS = -1,
190: PEP_DIVERGED_BREAKDOWN = -2,
191: PEP_DIVERGED_SYMMETRY_LOST = -3,
192: PEP_CONVERGED_ITERATING = 0} PEPConvergedReason;
193: PETSC_EXTERN const char *const*PEPConvergedReasons;
195: PETSC_EXTERN PetscErrorCode PEPCreate(MPI_Comm,PEP*);
196: PETSC_EXTERN PetscErrorCode PEPDestroy(PEP*);
197: PETSC_EXTERN PetscErrorCode PEPReset(PEP);
198: PETSC_EXTERN PetscErrorCode PEPSetType(PEP,PEPType);
199: PETSC_EXTERN PetscErrorCode PEPGetType(PEP,PEPType*);
200: PETSC_EXTERN PetscErrorCode PEPSetProblemType(PEP,PEPProblemType);
201: PETSC_EXTERN PetscErrorCode PEPGetProblemType(PEP,PEPProblemType*);
202: PETSC_EXTERN PetscErrorCode PEPSetOperators(PEP,PetscInt,Mat[]);
203: PETSC_EXTERN PetscErrorCode PEPGetOperators(PEP,PetscInt,Mat*);
204: PETSC_EXTERN PetscErrorCode PEPGetNumMatrices(PEP,PetscInt*);
205: PETSC_EXTERN PetscErrorCode PEPSetTarget(PEP,PetscScalar);
206: PETSC_EXTERN PetscErrorCode PEPGetTarget(PEP,PetscScalar*);
207: PETSC_EXTERN PetscErrorCode PEPSetFromOptions(PEP);
208: PETSC_EXTERN PetscErrorCode PEPSetUp(PEP);
209: PETSC_EXTERN PetscErrorCode PEPSolve(PEP);
210: PETSC_EXTERN PetscErrorCode PEPView(PEP,PetscViewer);
211: PETSC_STATIC_INLINE PetscErrorCode PEPViewFromOptions(PEP pep,PetscObject obj,const char name[]) {return PetscObjectViewFromOptions((PetscObject)pep,obj,name);}
212: PETSC_EXTERN PetscErrorCode PEPErrorView(PEP,PEPErrorType,PetscViewer);
213: PETSC_DEPRECATED("Use PEPErrorView()") PETSC_STATIC_INLINE PetscErrorCode PEPPrintSolution(PEP pep,PetscViewer v) {return PEPErrorView(pep,PEP_ERROR_BACKWARD,v);}
214: PETSC_EXTERN PetscErrorCode PEPErrorViewFromOptions(PEP);
215: PETSC_EXTERN PetscErrorCode PEPReasonView(PEP,PetscViewer);
216: PETSC_EXTERN PetscErrorCode PEPReasonViewFromOptions(PEP);
217: PETSC_EXTERN PetscErrorCode PEPValuesView(PEP,PetscViewer);
218: PETSC_EXTERN PetscErrorCode PEPValuesViewFromOptions(PEP);
219: PETSC_EXTERN PetscErrorCode PEPVectorsView(PEP,PetscViewer);
220: PETSC_EXTERN PetscErrorCode PEPVectorsViewFromOptions(PEP);
221: PETSC_EXTERN PetscErrorCode PEPSetBV(PEP,BV);
222: PETSC_EXTERN PetscErrorCode PEPGetBV(PEP,BV*);
223: PETSC_EXTERN PetscErrorCode PEPSetRG(PEP,RG);
224: PETSC_EXTERN PetscErrorCode PEPGetRG(PEP,RG*);
225: PETSC_EXTERN PetscErrorCode PEPSetDS(PEP,DS);
226: PETSC_EXTERN PetscErrorCode PEPGetDS(PEP,DS*);
227: PETSC_EXTERN PetscErrorCode PEPSetST(PEP,ST);
228: PETSC_EXTERN PetscErrorCode PEPGetST(PEP,ST*);
229: PETSC_EXTERN PetscErrorCode PEPRefineGetKSP(PEP,KSP*);
231: PETSC_EXTERN PetscErrorCode PEPSetTolerances(PEP,PetscReal,PetscInt);
232: PETSC_EXTERN PetscErrorCode PEPGetTolerances(PEP,PetscReal*,PetscInt*);
233: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTestFunction(PEP,PetscErrorCode (*)(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*,PetscErrorCode (*)(void*));
234: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTest(PEP,PEPConv);
235: PETSC_EXTERN PetscErrorCode PEPGetConvergenceTest(PEP,PEPConv*);
236: PETSC_EXTERN PetscErrorCode PEPConvergedAbsolute(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
237: PETSC_EXTERN PetscErrorCode PEPConvergedRelative(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
238: PETSC_EXTERN PetscErrorCode PEPConvergedNorm(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
239: PETSC_EXTERN PetscErrorCode PEPSetStoppingTestFunction(PEP,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscInt,PetscInt,PEPConvergedReason*,void*),void*,PetscErrorCode (*)(void*));
240: PETSC_EXTERN PetscErrorCode PEPSetStoppingTest(PEP,PEPStop);
241: PETSC_EXTERN PetscErrorCode PEPGetStoppingTest(PEP,PEPStop*);
242: PETSC_EXTERN PetscErrorCode PEPStoppingBasic(PEP,PetscInt,PetscInt,PetscInt,PetscInt,PEPConvergedReason*,void*);
243: PETSC_EXTERN PetscErrorCode PEPGetConvergedReason(PEP,PEPConvergedReason *);
245: PETSC_EXTERN PetscErrorCode PEPSetDimensions(PEP,PetscInt,PetscInt,PetscInt);
246: PETSC_EXTERN PetscErrorCode PEPGetDimensions(PEP,PetscInt*,PetscInt*,PetscInt*);
247: PETSC_EXTERN PetscErrorCode PEPSetScale(PEP,PEPScale,PetscReal,Vec,Vec,PetscInt,PetscReal);
248: PETSC_EXTERN PetscErrorCode PEPGetScale(PEP,PEPScale*,PetscReal*,Vec*,Vec*,PetscInt*,PetscReal*);
249: PETSC_EXTERN PetscErrorCode PEPSetRefine(PEP,PEPRefine,PetscInt,PetscReal,PetscInt,PEPRefineScheme);
250: PETSC_EXTERN PetscErrorCode PEPGetRefine(PEP,PEPRefine*,PetscInt*,PetscReal*,PetscInt*,PEPRefineScheme*);
251: PETSC_EXTERN PetscErrorCode PEPSetExtract(PEP,PEPExtract);
252: PETSC_EXTERN PetscErrorCode PEPGetExtract(PEP,PEPExtract*);
253: PETSC_EXTERN PetscErrorCode PEPSetBasis(PEP,PEPBasis);
254: PETSC_EXTERN PetscErrorCode PEPGetBasis(PEP,PEPBasis*);
256: PETSC_EXTERN PetscErrorCode PEPGetConverged(PEP,PetscInt*);
257: PETSC_EXTERN PetscErrorCode PEPGetEigenpair(PEP,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
258: PETSC_EXTERN PetscErrorCode PEPComputeError(PEP,PetscInt,PEPErrorType,PetscReal*);
259: PETSC_DEPRECATED("Use PEPComputeError()") PETSC_STATIC_INLINE PetscErrorCode PEPComputeRelativeError(PEP pep,PetscInt i,PetscReal *r) {return PEPComputeError(pep,i,PEP_ERROR_BACKWARD,r);}
260: PETSC_DEPRECATED("Use PEPComputeError() with PEP_ERROR_ABSOLUTE") PETSC_STATIC_INLINE PetscErrorCode PEPComputeResidualNorm(PEP pep,PetscInt i,PetscReal *r) {return PEPComputeError(pep,i,PEP_ERROR_ABSOLUTE,r);}
261: PETSC_EXTERN PetscErrorCode PEPGetErrorEstimate(PEP,PetscInt,PetscReal*);
263: PETSC_EXTERN PetscErrorCode PEPMonitor(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt);
264: PETSC_EXTERN PetscErrorCode PEPMonitorSet(PEP,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),void*,PetscErrorCode (*)(void**));
265: PETSC_EXTERN PetscErrorCode PEPMonitorSetFromOptions(PEP,const char*,const char*,const char*,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*),PetscBool);
266: PETSC_EXTERN PetscErrorCode PEPConvMonitorSetFromOptions(PEP,const char*,const char*,const char*,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor));
267: PETSC_EXTERN PetscErrorCode PEPMonitorCancel(PEP);
268: PETSC_EXTERN PetscErrorCode PEPGetMonitorContext(PEP,void **);
269: PETSC_EXTERN PetscErrorCode PEPGetIterationNumber(PEP,PetscInt*);
271: PETSC_EXTERN PetscErrorCode PEPSetInitialSpace(PEP,PetscInt,Vec*);
272: PETSC_EXTERN PetscErrorCode PEPSetWhichEigenpairs(PEP,PEPWhich);
273: PETSC_EXTERN PetscErrorCode PEPGetWhichEigenpairs(PEP,PEPWhich*);
274: PETSC_EXTERN PetscErrorCode PEPSetEigenvalueComparison(PEP,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);
276: PETSC_EXTERN PetscErrorCode PEPMonitorAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*);
277: PETSC_EXTERN PetscErrorCode PEPMonitorFirst(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*);
278: PETSC_EXTERN PetscErrorCode PEPMonitorConverged(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor);
279: PETSC_EXTERN PetscErrorCode PEPMonitorLGCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
280: PETSC_EXTERN PetscErrorCode PEPMonitorLG(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
281: PETSC_EXTERN PetscErrorCode PEPMonitorLGAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
283: PETSC_EXTERN PetscErrorCode PEPSetTrackAll(PEP,PetscBool);
284: PETSC_EXTERN PetscErrorCode PEPGetTrackAll(PEP,PetscBool*);
286: PETSC_EXTERN PetscErrorCode PEPSetOptionsPrefix(PEP,const char*);
287: PETSC_EXTERN PetscErrorCode PEPAppendOptionsPrefix(PEP,const char*);
288: PETSC_EXTERN PetscErrorCode PEPGetOptionsPrefix(PEP,const char*[]);
290: PETSC_EXTERN PetscFunctionList PEPList;
291: PETSC_EXTERN PetscErrorCode PEPRegister(const char[],PetscErrorCode(*)(PEP));
293: PETSC_EXTERN PetscErrorCode PEPSetWorkVecs(PEP,PetscInt);
294: PETSC_EXTERN PetscErrorCode PEPAllocateSolution(PEP,PetscInt);
296: /* --------- options specific to particular eigensolvers -------- */
298: PETSC_EXTERN PetscErrorCode PEPLinearSetCompanionForm(PEP,PetscInt);
299: PETSC_EXTERN PetscErrorCode PEPLinearGetCompanionForm(PEP,PetscInt*);
300: PETSC_EXTERN PetscErrorCode PEPLinearSetExplicitMatrix(PEP,PetscBool);
301: PETSC_EXTERN PetscErrorCode PEPLinearGetExplicitMatrix(PEP,PetscBool*);
302: PETSC_EXTERN PetscErrorCode PEPLinearSetEPS(PEP,EPS);
303: PETSC_EXTERN PetscErrorCode PEPLinearGetEPS(PEP,EPS*);
305: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetRestart(PEP,PetscReal);
306: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetRestart(PEP,PetscReal*);
307: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetLocking(PEP,PetscBool);
308: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetLocking(PEP,PetscBool*);
310: PETSC_EXTERN PetscErrorCode PEPTOARSetRestart(PEP,PetscReal);
311: PETSC_EXTERN PetscErrorCode PEPTOARGetRestart(PEP,PetscReal*);
312: PETSC_EXTERN PetscErrorCode PEPTOARSetLocking(PEP,PetscBool);
313: PETSC_EXTERN PetscErrorCode PEPTOARGetLocking(PEP,PetscBool*);
315: PETSC_EXTERN PetscErrorCode PEPSTOARSetLocking(PEP,PetscBool);
316: PETSC_EXTERN PetscErrorCode PEPSTOARGetLocking(PEP,PetscBool*);
318: PETSC_EXTERN PetscErrorCode PEPJDSetRestart(PEP,PetscReal);
319: PETSC_EXTERN PetscErrorCode PEPJDGetRestart(PEP,PetscReal*);
321: #endif