Actual source code: slepcpep.h

slepc-3.9.0 2018-04-12
Report Typos and Errors
  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-2018, 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_HYPERBOLIC,  /* QEP with Hermitian matrices, M>0, (x'Cx)^2 > 4(x'Mx)(x'Kx) */
 57:                PEP_GYROSCOPIC   /* QEP with M, K  Hermitian, M>0, C skew-Hermitian */
 58:              } PEPProblemType;

 60: /*E
 61:     PEPWhich - Determines which part of the spectrum is requested

 63:     Level: intermediate

 65: .seealso: PEPSetWhichEigenpairs(), PEPGetWhichEigenpairs()
 66: E*/
 67: typedef enum { PEP_LARGEST_MAGNITUDE=1,
 68:                PEP_SMALLEST_MAGNITUDE,
 69:                PEP_LARGEST_REAL,
 70:                PEP_SMALLEST_REAL,
 71:                PEP_LARGEST_IMAGINARY,
 72:                PEP_SMALLEST_IMAGINARY,
 73:                PEP_TARGET_MAGNITUDE,
 74:                PEP_TARGET_REAL,
 75:                PEP_TARGET_IMAGINARY,
 76:                PEP_ALL,
 77:                PEP_WHICH_USER } PEPWhich;

 79: /*E
 80:     PEPBasis - The type of polynomial basis used to represent the polynomial
 81:     eigenproblem

 83:     Level: intermediate

 85: .seealso: PEPSetBasis()
 86: E*/
 87: typedef enum { PEP_BASIS_MONOMIAL,
 88:                PEP_BASIS_CHEBYSHEV1,
 89:                PEP_BASIS_CHEBYSHEV2,
 90:                PEP_BASIS_LEGENDRE,
 91:                PEP_BASIS_LAGUERRE,
 92:                PEP_BASIS_HERMITE } PEPBasis;
 93: PETSC_EXTERN const char *PEPBasisTypes[];

 95: /*E
 96:     PEPScale - The scaling strategy

 98:     Level: intermediate

100: .seealso: PEPSetScale()
101: E*/
102: typedef enum { PEP_SCALE_NONE,
103:                PEP_SCALE_SCALAR,
104:                PEP_SCALE_DIAGONAL,
105:                PEP_SCALE_BOTH } PEPScale;
106: PETSC_EXTERN const char *PEPScaleTypes[];

108: /*E
109:     PEPRefine - The refinement type

111:     Level: intermediate

113: .seealso: PEPSetRefine()
114: E*/
115: typedef enum { PEP_REFINE_NONE,
116:                PEP_REFINE_SIMPLE,
117:                PEP_REFINE_MULTIPLE } PEPRefine;
118: PETSC_EXTERN const char *PEPRefineTypes[];

120: /*E
121:     PEPRefineScheme - The scheme used for solving linear systems during iterative refinement

123:     Level: intermediate

125: .seealso: PEPSetRefine()
126: E*/
127: typedef enum { PEP_REFINE_SCHEME_SCHUR=1,
128:                PEP_REFINE_SCHEME_MBE,
129:                PEP_REFINE_SCHEME_EXPLICIT } PEPRefineScheme;
130: PETSC_EXTERN const char *PEPRefineSchemes[];

132: /*E
133:     PEPExtract - The extraction type

135:     Level: intermediate

137: .seealso: PEPSetExtract()
138: E*/
139: typedef enum { PEP_EXTRACT_NONE=1,
140:                PEP_EXTRACT_NORM,
141:                PEP_EXTRACT_RESIDUAL,
142:                PEP_EXTRACT_STRUCTURED } PEPExtract;
143: PETSC_EXTERN const char *PEPExtractTypes[];

145: /*E
146:     PEPErrorType - The error type used to assess accuracy of computed solutions

148:     Level: intermediate

150: .seealso: PEPComputeError()
151: E*/
152: typedef enum { PEP_ERROR_ABSOLUTE,
153:                PEP_ERROR_RELATIVE,
154:                PEP_ERROR_BACKWARD } PEPErrorType;
155: PETSC_EXTERN const char *PEPErrorTypes[];

157: /*E
158:     PEPConv - Determines the convergence test

160:     Level: intermediate

162: .seealso: PEPSetConvergenceTest(), PEPSetConvergenceTestFunction()
163: E*/
164: typedef enum { PEP_CONV_ABS,
165:                PEP_CONV_REL,
166:                PEP_CONV_NORM,
167:                PEP_CONV_USER } PEPConv;

169: /*E
170:     PEPStop - Determines the stopping test

172:     Level: advanced

174: .seealso: PEPSetStoppingTest(), PEPSetStoppingTestFunction()
175: E*/
176: typedef enum { PEP_STOP_BASIC,
177:                PEP_STOP_USER } PEPStop;

179: /*E
180:     PEPConvergedReason - Reason an eigensolver was said to
181:          have converged or diverged

183:     Level: intermediate

185: .seealso: PEPSolve(), PEPGetConvergedReason(), PEPSetTolerances()
186: E*/
187: typedef enum {/* converged */
188:               PEP_CONVERGED_TOL                =  1,
189:               PEP_CONVERGED_USER               =  2,
190:               /* diverged */
191:               PEP_DIVERGED_ITS                 = -1,
192:               PEP_DIVERGED_BREAKDOWN           = -2,
193:               PEP_DIVERGED_SYMMETRY_LOST       = -3,
194:               PEP_CONVERGED_ITERATING          =  0} PEPConvergedReason;
195: PETSC_EXTERN const char *const*PEPConvergedReasons;

197: PETSC_EXTERN PetscErrorCode PEPCreate(MPI_Comm,PEP*);
198: PETSC_EXTERN PetscErrorCode PEPDestroy(PEP*);
199: PETSC_EXTERN PetscErrorCode PEPReset(PEP);
200: PETSC_EXTERN PetscErrorCode PEPSetType(PEP,PEPType);
201: PETSC_EXTERN PetscErrorCode PEPGetType(PEP,PEPType*);
202: PETSC_EXTERN PetscErrorCode PEPSetProblemType(PEP,PEPProblemType);
203: PETSC_EXTERN PetscErrorCode PEPGetProblemType(PEP,PEPProblemType*);
204: PETSC_EXTERN PetscErrorCode PEPSetOperators(PEP,PetscInt,Mat[]);
205: PETSC_EXTERN PetscErrorCode PEPGetOperators(PEP,PetscInt,Mat*);
206: PETSC_EXTERN PetscErrorCode PEPGetNumMatrices(PEP,PetscInt*);
207: PETSC_EXTERN PetscErrorCode PEPSetTarget(PEP,PetscScalar);
208: PETSC_EXTERN PetscErrorCode PEPGetTarget(PEP,PetscScalar*);
209: PETSC_EXTERN PetscErrorCode PEPSetInterval(PEP,PetscReal,PetscReal);
210: PETSC_EXTERN PetscErrorCode PEPGetInterval(PEP,PetscReal*,PetscReal*);
211: PETSC_EXTERN PetscErrorCode PEPSetFromOptions(PEP);
212: PETSC_EXTERN PetscErrorCode PEPSetUp(PEP);
213: PETSC_EXTERN PetscErrorCode PEPSolve(PEP);
214: PETSC_EXTERN PetscErrorCode PEPView(PEP,PetscViewer);
215: PETSC_STATIC_INLINE PetscErrorCode PEPViewFromOptions(PEP pep,PetscObject obj,const char name[]) {return PetscObjectViewFromOptions((PetscObject)pep,obj,name);}
216: PETSC_EXTERN PetscErrorCode PEPErrorView(PEP,PEPErrorType,PetscViewer);
217: PETSC_DEPRECATED("Use PEPErrorView()") PETSC_STATIC_INLINE PetscErrorCode PEPPrintSolution(PEP pep,PetscViewer v) {return PEPErrorView(pep,PEP_ERROR_BACKWARD,v);}
218: PETSC_EXTERN PetscErrorCode PEPErrorViewFromOptions(PEP);
219: PETSC_EXTERN PetscErrorCode PEPReasonView(PEP,PetscViewer);
220: PETSC_EXTERN PetscErrorCode PEPReasonViewFromOptions(PEP);
221: PETSC_EXTERN PetscErrorCode PEPValuesView(PEP,PetscViewer);
222: PETSC_EXTERN PetscErrorCode PEPValuesViewFromOptions(PEP);
223: PETSC_EXTERN PetscErrorCode PEPVectorsView(PEP,PetscViewer);
224: PETSC_EXTERN PetscErrorCode PEPVectorsViewFromOptions(PEP);
225: PETSC_EXTERN PetscErrorCode PEPSetBV(PEP,BV);
226: PETSC_EXTERN PetscErrorCode PEPGetBV(PEP,BV*);
227: PETSC_EXTERN PetscErrorCode PEPSetRG(PEP,RG);
228: PETSC_EXTERN PetscErrorCode PEPGetRG(PEP,RG*);
229: PETSC_EXTERN PetscErrorCode PEPSetDS(PEP,DS);
230: PETSC_EXTERN PetscErrorCode PEPGetDS(PEP,DS*);
231: PETSC_EXTERN PetscErrorCode PEPSetST(PEP,ST);
232: PETSC_EXTERN PetscErrorCode PEPGetST(PEP,ST*);
233: PETSC_EXTERN PetscErrorCode PEPRefineGetKSP(PEP,KSP*);

235: PETSC_EXTERN PetscErrorCode PEPSetTolerances(PEP,PetscReal,PetscInt);
236: PETSC_EXTERN PetscErrorCode PEPGetTolerances(PEP,PetscReal*,PetscInt*);
237: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTestFunction(PEP,PetscErrorCode (*)(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*,PetscErrorCode (*)(void*));
238: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTest(PEP,PEPConv);
239: PETSC_EXTERN PetscErrorCode PEPGetConvergenceTest(PEP,PEPConv*);
240: PETSC_EXTERN PetscErrorCode PEPConvergedAbsolute(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
241: PETSC_EXTERN PetscErrorCode PEPConvergedRelative(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
242: PETSC_EXTERN PetscErrorCode PEPConvergedNorm(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
243: PETSC_EXTERN PetscErrorCode PEPSetStoppingTestFunction(PEP,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscInt,PetscInt,PEPConvergedReason*,void*),void*,PetscErrorCode (*)(void*));
244: PETSC_EXTERN PetscErrorCode PEPSetStoppingTest(PEP,PEPStop);
245: PETSC_EXTERN PetscErrorCode PEPGetStoppingTest(PEP,PEPStop*);
246: PETSC_EXTERN PetscErrorCode PEPStoppingBasic(PEP,PetscInt,PetscInt,PetscInt,PetscInt,PEPConvergedReason*,void*);
247: PETSC_EXTERN PetscErrorCode PEPGetConvergedReason(PEP,PEPConvergedReason *);

249: PETSC_EXTERN PetscErrorCode PEPSetDimensions(PEP,PetscInt,PetscInt,PetscInt);
250: PETSC_EXTERN PetscErrorCode PEPGetDimensions(PEP,PetscInt*,PetscInt*,PetscInt*);
251: PETSC_EXTERN PetscErrorCode PEPSetScale(PEP,PEPScale,PetscReal,Vec,Vec,PetscInt,PetscReal);
252: PETSC_EXTERN PetscErrorCode PEPGetScale(PEP,PEPScale*,PetscReal*,Vec*,Vec*,PetscInt*,PetscReal*);
253: PETSC_EXTERN PetscErrorCode PEPSetRefine(PEP,PEPRefine,PetscInt,PetscReal,PetscInt,PEPRefineScheme);
254: PETSC_EXTERN PetscErrorCode PEPGetRefine(PEP,PEPRefine*,PetscInt*,PetscReal*,PetscInt*,PEPRefineScheme*);
255: PETSC_EXTERN PetscErrorCode PEPSetExtract(PEP,PEPExtract);
256: PETSC_EXTERN PetscErrorCode PEPGetExtract(PEP,PEPExtract*);
257: PETSC_EXTERN PetscErrorCode PEPSetBasis(PEP,PEPBasis);
258: PETSC_EXTERN PetscErrorCode PEPGetBasis(PEP,PEPBasis*);

260: PETSC_EXTERN PetscErrorCode PEPGetConverged(PEP,PetscInt*);
261: PETSC_EXTERN PetscErrorCode PEPGetEigenpair(PEP,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
262: PETSC_EXTERN PetscErrorCode PEPComputeError(PEP,PetscInt,PEPErrorType,PetscReal*);
263: PETSC_DEPRECATED("Use PEPComputeError()") PETSC_STATIC_INLINE PetscErrorCode PEPComputeRelativeError(PEP pep,PetscInt i,PetscReal *r) {return PEPComputeError(pep,i,PEP_ERROR_BACKWARD,r);}
264: 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);}
265: PETSC_EXTERN PetscErrorCode PEPGetErrorEstimate(PEP,PetscInt,PetscReal*);

267: PETSC_EXTERN PetscErrorCode PEPMonitor(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt);
268: PETSC_EXTERN PetscErrorCode PEPMonitorSet(PEP,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),void*,PetscErrorCode (*)(void**));
269: PETSC_EXTERN PetscErrorCode PEPMonitorSetFromOptions(PEP,const char*,const char*,const char*,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*),PetscBool);
270: PETSC_EXTERN PetscErrorCode PEPConvMonitorSetFromOptions(PEP,const char*,const char*,const char*,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor));
271: PETSC_EXTERN PetscErrorCode PEPMonitorCancel(PEP);
272: PETSC_EXTERN PetscErrorCode PEPGetMonitorContext(PEP,void **);
273: PETSC_EXTERN PetscErrorCode PEPGetIterationNumber(PEP,PetscInt*);

275: PETSC_EXTERN PetscErrorCode PEPSetInitialSpace(PEP,PetscInt,Vec*);
276: PETSC_EXTERN PetscErrorCode PEPSetWhichEigenpairs(PEP,PEPWhich);
277: PETSC_EXTERN PetscErrorCode PEPGetWhichEigenpairs(PEP,PEPWhich*);
278: PETSC_EXTERN PetscErrorCode PEPSetEigenvalueComparison(PEP,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);

280: PETSC_EXTERN PetscErrorCode PEPMonitorAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*);
281: PETSC_EXTERN PetscErrorCode PEPMonitorFirst(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*);
282: PETSC_EXTERN PetscErrorCode PEPMonitorConverged(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,SlepcConvMonitor);
283: PETSC_EXTERN PetscErrorCode PEPMonitorLGCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
284: PETSC_EXTERN PetscErrorCode PEPMonitorLG(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
285: PETSC_EXTERN PetscErrorCode PEPMonitorLGAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

287: PETSC_EXTERN PetscErrorCode PEPSetTrackAll(PEP,PetscBool);
288: PETSC_EXTERN PetscErrorCode PEPGetTrackAll(PEP,PetscBool*);

290: PETSC_EXTERN PetscErrorCode PEPSetOptionsPrefix(PEP,const char*);
291: PETSC_EXTERN PetscErrorCode PEPAppendOptionsPrefix(PEP,const char*);
292: PETSC_EXTERN PetscErrorCode PEPGetOptionsPrefix(PEP,const char*[]);

294: PETSC_EXTERN PetscFunctionList PEPList;
295: PETSC_EXTERN PetscErrorCode PEPRegister(const char[],PetscErrorCode(*)(PEP));

297: PETSC_EXTERN PetscErrorCode PEPSetWorkVecs(PEP,PetscInt);
298: PETSC_EXTERN PetscErrorCode PEPAllocateSolution(PEP,PetscInt);

300: /* --------- options specific to particular eigensolvers -------- */

302: PETSC_EXTERN PetscErrorCode PEPLinearSetCompanionForm(PEP,PetscInt);
303: PETSC_EXTERN PetscErrorCode PEPLinearGetCompanionForm(PEP,PetscInt*);
304: PETSC_EXTERN PetscErrorCode PEPLinearSetExplicitMatrix(PEP,PetscBool);
305: PETSC_EXTERN PetscErrorCode PEPLinearGetExplicitMatrix(PEP,PetscBool*);
306: PETSC_EXTERN PetscErrorCode PEPLinearSetEPS(PEP,EPS);
307: PETSC_EXTERN PetscErrorCode PEPLinearGetEPS(PEP,EPS*);

309: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetRestart(PEP,PetscReal);
310: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetRestart(PEP,PetscReal*);
311: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetLocking(PEP,PetscBool);
312: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetLocking(PEP,PetscBool*);

314: PETSC_EXTERN PetscErrorCode PEPTOARSetRestart(PEP,PetscReal);
315: PETSC_EXTERN PetscErrorCode PEPTOARGetRestart(PEP,PetscReal*);
316: PETSC_EXTERN PetscErrorCode PEPTOARSetLocking(PEP,PetscBool);
317: PETSC_EXTERN PetscErrorCode PEPTOARGetLocking(PEP,PetscBool*);

319: PETSC_EXTERN PetscErrorCode PEPSTOARSetLocking(PEP,PetscBool);
320: PETSC_EXTERN PetscErrorCode PEPSTOARGetLocking(PEP,PetscBool*);
321: PETSC_EXTERN PetscErrorCode PEPSTOARSetDetectZeros(PEP,PetscBool);
322: PETSC_EXTERN PetscErrorCode PEPSTOARGetDetectZeros(PEP,PetscBool*);
323: PETSC_EXTERN PetscErrorCode PEPSTOARGetInertias(PEP,PetscInt*,PetscReal**,PetscInt**);
324: PETSC_EXTERN PetscErrorCode PEPSTOARSetDimensions(PEP,PetscInt,PetscInt,PetscInt);
325: PETSC_EXTERN PetscErrorCode PEPSTOARGetDimensions(PEP,PetscInt*,PetscInt*,PetscInt*);

327: PETSC_EXTERN PetscErrorCode PEPJDSetRestart(PEP,PetscReal);
328: PETSC_EXTERN PetscErrorCode PEPJDGetRestart(PEP,PetscReal*);
329: PETSC_EXTERN PetscErrorCode PEPJDSetFix(PEP,PetscReal);
330: PETSC_EXTERN PetscErrorCode PEPJDGetFix(PEP,PetscReal*);

332: #endif