Actual source code: slepcpep.h
slepc-3.6.1 2015-09-03
1: /*
2: User interface for SLEPc's polynomial eigenvalue solvers.
4: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5: SLEPc - Scalable Library for Eigenvalue Problem Computations
6: Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain
8: This file is part of SLEPc.
10: SLEPc is free software: you can redistribute it and/or modify it under the
11: terms of version 3 of the GNU Lesser General Public License as published by
12: the Free Software Foundation.
14: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
15: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
17: more details.
19: You should have received a copy of the GNU Lesser General Public License
20: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
21: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
22: */
26: #include <slepceps.h>
28: PETSC_EXTERN PetscErrorCode PEPInitializePackage(void);
30: /*S
31: PEP - Abstract SLEPc object that manages all the polynomial eigenvalue
32: problem solvers.
34: Level: beginner
36: .seealso: PEPCreate()
37: S*/
38: typedef struct _p_PEP* PEP;
40: /*J
41: PEPType - String with the name of a polynomial eigensolver
43: Level: beginner
45: .seealso: PEPSetType(), PEP
46: J*/
47: typedef const char* PEPType;
48: #define PEPLINEAR "linear"
49: #define PEPQARNOLDI "qarnoldi"
50: #define PEPTOAR "toar"
51: #define PEPSTOAR "stoar"
52: #define PEPJD "jd"
54: /* Logging support */
55: PETSC_EXTERN PetscClassId PEP_CLASSID;
57: /*E
58: PEPProblemType - Determines the type of the polynomial eigenproblem
60: Level: intermediate
62: .seealso: PEPSetProblemType(), PEPGetProblemType()
63: E*/
64: typedef enum { PEP_GENERAL=1,
65: PEP_HERMITIAN, /* All A_i Hermitian */
66: PEP_GYROSCOPIC /* QEP with M, K Hermitian, M>0, C skew-Hermitian */
67: } PEPProblemType;
69: /*E
70: PEPWhich - Determines which part of the spectrum is requested
72: Level: intermediate
74: .seealso: PEPSetWhichEigenpairs(), PEPGetWhichEigenpairs()
75: E*/
76: typedef enum { PEP_LARGEST_MAGNITUDE=1,
77: PEP_SMALLEST_MAGNITUDE,
78: PEP_LARGEST_REAL,
79: PEP_SMALLEST_REAL,
80: PEP_LARGEST_IMAGINARY,
81: PEP_SMALLEST_IMAGINARY,
82: PEP_TARGET_MAGNITUDE,
83: PEP_TARGET_REAL,
84: PEP_TARGET_IMAGINARY,
85: PEP_WHICH_USER } PEPWhich;
87: /*E
88: PEPBasis - The type of polynomial basis used to represent the polynomial
89: eigenproblem
91: Level: intermediate
93: .seealso: PEPSetBasis()
94: E*/
95: typedef enum { PEP_BASIS_MONOMIAL,
96: PEP_BASIS_CHEBYSHEV1,
97: PEP_BASIS_CHEBYSHEV2,
98: PEP_BASIS_LEGENDRE,
99: PEP_BASIS_LAGUERRE,
100: PEP_BASIS_HERMITE } PEPBasis;
101: PETSC_EXTERN const char *PEPBasisTypes[];
103: /*E
104: PEPScale - The scaling strategy
106: Level: intermediate
108: .seealso: PEPSetScale()
109: E*/
110: typedef enum { PEP_SCALE_NONE,
111: PEP_SCALE_SCALAR,
112: PEP_SCALE_DIAGONAL,
113: PEP_SCALE_BOTH } PEPScale;
114: PETSC_EXTERN const char *PEPScaleTypes[];
116: /*E
117: PEPRefine - The refinement type
119: Level: intermediate
121: .seealso: PEPSetRefine()
122: E*/
123: typedef enum { PEP_REFINE_NONE,
124: PEP_REFINE_SIMPLE,
125: PEP_REFINE_MULTIPLE } PEPRefine;
126: PETSC_EXTERN const char *PEPRefineTypes[];
128: /*E
129: PEPExtract - The extraction type
131: Level: intermediate
133: .seealso: PEPSetExtract()
134: E*/
135: typedef enum { PEP_EXTRACT_NONE=1,
136: PEP_EXTRACT_NORM,
137: PEP_EXTRACT_RESIDUAL,
138: PEP_EXTRACT_STRUCTURED } PEPExtract;
139: PETSC_EXTERN const char *PEPExtractTypes[];
141: /*E
142: PEPErrorType - The error type used to assess accuracy of computed solutions
144: Level: intermediate
146: .seealso: PEPComputeError()
147: E*/
148: typedef enum { PEP_ERROR_ABSOLUTE,
149: PEP_ERROR_RELATIVE,
150: PEP_ERROR_BACKWARD } PEPErrorType;
151: PETSC_EXTERN const char *PEPErrorTypes[];
153: /*E
154: PEPConv - Determines the convergence test
156: Level: intermediate
158: .seealso: PEPSetConvergenceTest(), PEPSetConvergenceTestFunction()
159: E*/
160: typedef enum { PEP_CONV_ABS,
161: PEP_CONV_EIG,
162: PEP_CONV_LINEAR,
163: PEP_CONV_NORM,
164: PEP_CONV_USER } PEPConv;
166: PETSC_EXTERN PetscErrorCode PEPCreate(MPI_Comm,PEP*);
167: PETSC_EXTERN PetscErrorCode PEPDestroy(PEP*);
168: PETSC_EXTERN PetscErrorCode PEPReset(PEP);
169: PETSC_EXTERN PetscErrorCode PEPSetType(PEP,PEPType);
170: PETSC_EXTERN PetscErrorCode PEPGetType(PEP,PEPType*);
171: PETSC_EXTERN PetscErrorCode PEPSetProblemType(PEP,PEPProblemType);
172: PETSC_EXTERN PetscErrorCode PEPGetProblemType(PEP,PEPProblemType*);
173: PETSC_EXTERN PetscErrorCode PEPSetOperators(PEP,PetscInt,Mat[]);
174: PETSC_EXTERN PetscErrorCode PEPGetOperators(PEP,PetscInt,Mat*);
175: PETSC_EXTERN PetscErrorCode PEPGetNumMatrices(PEP,PetscInt*);
176: PETSC_EXTERN PetscErrorCode PEPSetTarget(PEP,PetscScalar);
177: PETSC_EXTERN PetscErrorCode PEPGetTarget(PEP,PetscScalar*);
178: PETSC_EXTERN PetscErrorCode PEPSetFromOptions(PEP);
179: PETSC_EXTERN PetscErrorCode PEPSetUp(PEP);
180: PETSC_EXTERN PetscErrorCode PEPSolve(PEP);
181: PETSC_EXTERN PetscErrorCode PEPView(PEP,PetscViewer);
182: PETSC_STATIC_INLINE PetscErrorCode PEPViewFromOptions(PEP pep,PetscObject obj,const char name[]) {return PetscObjectViewFromOptions((PetscObject)pep,obj,name);}
183: PETSC_EXTERN PetscErrorCode PEPErrorView(PEP,PEPErrorType,PetscViewer);
184: PETSC_DEPRECATED("Use PEPErrorView()") PETSC_STATIC_INLINE PetscErrorCode PEPPrintSolution(PEP pep,PetscViewer v) {return PEPErrorView(pep,PEP_ERROR_BACKWARD,v);}
185: PETSC_EXTERN PetscErrorCode PEPErrorViewFromOptions(PEP);
186: PETSC_EXTERN PetscErrorCode PEPReasonView(PEP,PetscViewer);
187: PETSC_EXTERN PetscErrorCode PEPReasonViewFromOptions(PEP);
188: PETSC_EXTERN PetscErrorCode PEPValuesView(PEP,PetscViewer);
189: PETSC_EXTERN PetscErrorCode PEPValuesViewFromOptions(PEP);
190: PETSC_EXTERN PetscErrorCode PEPVectorsView(PEP,PetscViewer);
191: PETSC_EXTERN PetscErrorCode PEPVectorsViewFromOptions(PEP);
192: PETSC_EXTERN PetscErrorCode PEPSetBV(PEP,BV);
193: PETSC_EXTERN PetscErrorCode PEPGetBV(PEP,BV*);
194: PETSC_EXTERN PetscErrorCode PEPSetRG(PEP,RG);
195: PETSC_EXTERN PetscErrorCode PEPGetRG(PEP,RG*);
196: PETSC_EXTERN PetscErrorCode PEPSetDS(PEP,DS);
197: PETSC_EXTERN PetscErrorCode PEPGetDS(PEP,DS*);
198: PETSC_EXTERN PetscErrorCode PEPSetST(PEP,ST);
199: PETSC_EXTERN PetscErrorCode PEPGetST(PEP,ST*);
200: PETSC_EXTERN PetscErrorCode PEPRefineGetKSP(PEP,KSP*);
202: PETSC_EXTERN PetscErrorCode PEPSetTolerances(PEP,PetscReal,PetscInt);
203: PETSC_EXTERN PetscErrorCode PEPGetTolerances(PEP,PetscReal*,PetscInt*);
204: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTestFunction(PEP,PetscErrorCode (*)(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*,PetscErrorCode (*)(void*));
205: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTest(PEP,PEPConv);
206: PETSC_EXTERN PetscErrorCode PEPGetConvergenceTest(PEP,PEPConv*);
207: PETSC_EXTERN PetscErrorCode PEPConvergedEigRelative(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
208: PETSC_EXTERN PetscErrorCode PEPConvergedLinear(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
209: PETSC_EXTERN PetscErrorCode PEPConvergedNorm(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
210: PETSC_EXTERN PetscErrorCode PEPConvergedAbsolute(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
211: PETSC_EXTERN PetscErrorCode PEPSetDimensions(PEP,PetscInt,PetscInt,PetscInt);
212: PETSC_EXTERN PetscErrorCode PEPGetDimensions(PEP,PetscInt*,PetscInt*,PetscInt*);
213: PETSC_EXTERN PetscErrorCode PEPSetScale(PEP,PEPScale,PetscReal,Vec,Vec,PetscInt,PetscReal);
214: PETSC_EXTERN PetscErrorCode PEPGetScale(PEP,PEPScale*,PetscReal*,Vec*,Vec*,PetscInt*,PetscReal*);
215: PETSC_EXTERN PetscErrorCode PEPSetRefine(PEP,PEPRefine,PetscInt,PetscReal,PetscInt,PetscBool);
216: PETSC_EXTERN PetscErrorCode PEPGetRefine(PEP,PEPRefine*,PetscInt*,PetscReal*,PetscInt*,PetscBool*);
217: PETSC_EXTERN PetscErrorCode PEPSetExtract(PEP,PEPExtract);
218: PETSC_EXTERN PetscErrorCode PEPGetExtract(PEP,PEPExtract*);
219: PETSC_EXTERN PetscErrorCode PEPSetBasis(PEP,PEPBasis);
220: PETSC_EXTERN PetscErrorCode PEPGetBasis(PEP,PEPBasis*);
222: PETSC_EXTERN PetscErrorCode PEPGetConverged(PEP,PetscInt*);
223: PETSC_EXTERN PetscErrorCode PEPGetEigenpair(PEP,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
224: PETSC_EXTERN PetscErrorCode PEPComputeError(PEP,PetscInt,PEPErrorType,PetscReal*);
225: PETSC_DEPRECATED("Use PEPComputeError()") PETSC_STATIC_INLINE PetscErrorCode PEPComputeRelativeError(PEP pep,PetscInt i,PetscReal *r) {return PEPComputeError(pep,i,PEP_ERROR_BACKWARD,r);}
226: 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);}
227: PETSC_EXTERN PetscErrorCode PEPGetErrorEstimate(PEP,PetscInt,PetscReal*);
229: PETSC_EXTERN PetscErrorCode PEPMonitor(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt);
230: PETSC_EXTERN PetscErrorCode PEPMonitorSet(PEP,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),void*,PetscErrorCode (*)(void**));
231: PETSC_EXTERN PetscErrorCode PEPMonitorCancel(PEP);
232: PETSC_EXTERN PetscErrorCode PEPGetMonitorContext(PEP,void **);
233: PETSC_EXTERN PetscErrorCode PEPGetIterationNumber(PEP,PetscInt*);
235: PETSC_EXTERN PetscErrorCode PEPSetInitialSpace(PEP,PetscInt,Vec*);
236: PETSC_EXTERN PetscErrorCode PEPSetWhichEigenpairs(PEP,PEPWhich);
237: PETSC_EXTERN PetscErrorCode PEPGetWhichEigenpairs(PEP,PEPWhich*);
238: PETSC_EXTERN PetscErrorCode PEPSetEigenvalueComparison(PEP,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);
240: PETSC_EXTERN PetscErrorCode PEPMonitorAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
241: PETSC_EXTERN PetscErrorCode PEPMonitorFirst(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
242: PETSC_EXTERN PetscErrorCode PEPMonitorConverged(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
243: PETSC_EXTERN PetscErrorCode PEPMonitorLG(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
244: PETSC_EXTERN PetscErrorCode PEPMonitorLGAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
246: PETSC_EXTERN PetscErrorCode PEPSetTrackAll(PEP,PetscBool);
247: PETSC_EXTERN PetscErrorCode PEPGetTrackAll(PEP,PetscBool*);
249: PETSC_EXTERN PetscErrorCode PEPSetOptionsPrefix(PEP,const char*);
250: PETSC_EXTERN PetscErrorCode PEPAppendOptionsPrefix(PEP,const char*);
251: PETSC_EXTERN PetscErrorCode PEPGetOptionsPrefix(PEP,const char*[]);
253: /*E
254: PEPConvergedReason - Reason an eigensolver was said to
255: have converged or diverged
257: Level: intermediate
259: .seealso: PEPSolve(), PEPGetConvergedReason(), PEPSetTolerances()
260: E*/
261: typedef enum {/* converged */
262: PEP_CONVERGED_TOL = 2,
263: /* diverged */
264: PEP_DIVERGED_ITS = -3,
265: PEP_DIVERGED_BREAKDOWN = -4,
266: PEP_DIVERGED_SYMMETRY_LOST = -5,
267: PEP_CONVERGED_ITERATING = 0} PEPConvergedReason;
268: PETSC_EXTERN const char *const*PEPConvergedReasons;
270: PETSC_EXTERN PetscErrorCode PEPGetConvergedReason(PEP,PEPConvergedReason *);
272: PETSC_EXTERN PetscFunctionList PEPList;
273: PETSC_EXTERN PetscErrorCode PEPRegister(const char[],PetscErrorCode(*)(PEP));
275: PETSC_EXTERN PetscErrorCode PEPSetWorkVecs(PEP,PetscInt);
276: PETSC_EXTERN PetscErrorCode PEPAllocateSolution(PEP,PetscInt);
278: /* --------- options specific to particular eigensolvers -------- */
280: PETSC_EXTERN PetscErrorCode PEPLinearSetCompanionForm(PEP,PetscInt);
281: PETSC_EXTERN PetscErrorCode PEPLinearGetCompanionForm(PEP,PetscInt*);
282: PETSC_EXTERN PetscErrorCode PEPLinearSetExplicitMatrix(PEP,PetscBool);
283: PETSC_EXTERN PetscErrorCode PEPLinearGetExplicitMatrix(PEP,PetscBool*);
284: PETSC_EXTERN PetscErrorCode PEPLinearSetEPS(PEP,EPS);
285: PETSC_EXTERN PetscErrorCode PEPLinearGetEPS(PEP,EPS*);
287: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetRestart(PEP,PetscReal);
288: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetRestart(PEP,PetscReal*);
289: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetLocking(PEP,PetscBool);
290: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetLocking(PEP,PetscBool*);
292: PETSC_EXTERN PetscErrorCode PEPTOARSetRestart(PEP,PetscReal);
293: PETSC_EXTERN PetscErrorCode PEPTOARGetRestart(PEP,PetscReal*);
294: PETSC_EXTERN PetscErrorCode PEPTOARSetLocking(PEP,PetscBool);
295: PETSC_EXTERN PetscErrorCode PEPTOARGetLocking(PEP,PetscBool*);
297: PETSC_EXTERN PetscErrorCode PEPSTOARSetLocking(PEP,PetscBool);
298: PETSC_EXTERN PetscErrorCode PEPSTOARGetLocking(PEP,PetscBool*);
300: PETSC_EXTERN PetscErrorCode PEPJDSetRestart(PEP,PetscReal);
301: PETSC_EXTERN PetscErrorCode PEPJDGetRestart(PEP,PetscReal*);
302: PETSC_EXTERN PetscErrorCode PEPJDSetTolerances(PEP,PetscReal,PetscReal,PetscReal);
303: PETSC_EXTERN PetscErrorCode PEPJDGetTolerances(PEP,PetscReal*,PetscReal*,PetscReal*);
305: #endif