Actual source code: slepceps.h

  1: /*
  2:    User interface for the SLEPC eigenproblem solvers. 

  4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  6:    Copyright (c) 2002-2010, Universidad Politecnica de Valencia, Spain

  8:    This file is part of SLEPc.
  9:       
 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 slepcsys.h
 27:  #include slepcst.h
 28:  #include slepcip.h


 33: /*S
 34:      EPS - Abstract SLEPc object that manages all the eigenvalue 
 35:      problem solvers.

 37:    Level: beginner

 39: .seealso:  EPSCreate(), ST
 40: S*/
 41: typedef struct _p_EPS* EPS;

 43: /*E
 44:     EPSType - String with the name of a SLEPc eigensolver

 46:    Level: beginner

 48: .seealso: EPSSetType(), EPS
 49: E*/
 50: #define EPSType      char*
 51: #define EPSPOWER     "power"
 52: #define EPSSUBSPACE  "subspace"
 53: #define EPSARNOLDI   "arnoldi"
 54: #define EPSLANCZOS   "lanczos"
 55: #define EPSKRYLOVSCHUR "krylovschur"
 56: #define EPSGD        "gd"
 57: #define EPSJD        "jd"
 58: #define EPSLAPACK    "lapack"
 59: /* the next ones are interfaces to external libraries */
 60: #define EPSARPACK    "arpack"
 61: #define EPSBLZPACK   "blzpack"
 62: #define EPSTRLAN     "trlan"
 63: #define EPSBLOPEX    "blopex"
 64: #define EPSPRIMME    "primme"

 66: /*E
 67:     EPSProblemType - determines the type of eigenvalue problem

 69:     Level: beginner

 71: .seealso: EPSSetProblemType(), EPSGetProblemType()
 72: E*/
 73: typedef enum { EPS_HEP=1,
 74:                EPS_GHEP,
 75:                EPS_NHEP,
 76:                EPS_GNHEP,
 77:                EPS_PGNHEP } EPSProblemType;

 79: /*E
 80:     EPSExtraction - determines the type of extraction technique employed
 81:     by the eigensolver

 83:     Level: beginner

 85: .seealso: EPSSetExtraction(), EPSGetExtraction()
 86: E*/
 87: typedef enum { EPS_RITZ=1,
 88:                EPS_HARMONIC,
 89:                EPS_HARMONIC_RELATIVE,
 90:                EPS_HARMONIC_RIGHT,
 91:                EPS_HARMONIC_LARGEST,
 92:                EPS_REFINED,
 93:                EPS_REFINED_HARMONIC } EPSExtraction;

 95: /*E
 96:     EPSWhich - determines which part of the spectrum is requested

 98:     Level: intermediate

100: .seealso: EPSSetWhichEigenpairs(), EPSGetWhichEigenpairs()
101: E*/
102: typedef enum { EPS_LARGEST_MAGNITUDE=1,
103:                EPS_SMALLEST_MAGNITUDE,
104:                EPS_LARGEST_REAL,
105:                EPS_SMALLEST_REAL,
106:                EPS_LARGEST_IMAGINARY,
107:                EPS_SMALLEST_IMAGINARY,
108:                EPS_TARGET_MAGNITUDE,
109:                EPS_TARGET_REAL,
110:                EPS_TARGET_IMAGINARY,
111:                EPS_WHICH_USER } EPSWhich;

113: /*E
114:     EPSBalance - the type of balancing used for non-Hermitian problems

116:     Level: intermediate

118: .seealso: EPSSetBalance()
119: E*/
120: typedef enum { EPS_BALANCE_NONE=1,
121:                EPS_BALANCE_ONESIDE,
122:                EPS_BALANCE_TWOSIDE,
123:                EPS_BALANCE_USER } EPSBalance;

125: /*E
126:     EPSConv - determines the convergence test

128:     Level: intermediate

130: .seealso: EPSSetConvergenceTest(), EPSSetConvergenceTestFunction()
131: E*/
132: typedef enum { EPS_CONV_ABS=1,
133:                EPS_CONV_EIG,
134:                EPS_CONV_NORM,
135:                EPS_CONV_USER } EPSConv;

137: EXTERN PetscErrorCode EPSCreate(MPI_Comm,EPS *);
138: EXTERN PetscErrorCode EPSDestroy(EPS);
139: EXTERN PetscErrorCode EPSSetType(EPS,const EPSType);
140: EXTERN PetscErrorCode EPSGetType(EPS,const EPSType*);
141: EXTERN PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
142: EXTERN PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
143: EXTERN PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);
144: EXTERN PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);
145: EXTERN PetscErrorCode EPSSetBalance(EPS,EPSBalance,PetscInt,PetscReal);
146: EXTERN PetscErrorCode EPSGetBalance(EPS,EPSBalance*,PetscInt*,PetscReal*);
147: EXTERN PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
148: EXTERN PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);
149: EXTERN PetscErrorCode EPSSetFromOptions(EPS);
150: EXTERN PetscErrorCode EPSSetUp(EPS);
151: EXTERN PetscErrorCode EPSSolve(EPS);
152: EXTERN PetscErrorCode EPSView(EPS,PetscViewer);

154: EXTERN PetscErrorCode EPSSetTarget(EPS,PetscScalar);
155: EXTERN PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
156: EXTERN PetscErrorCode EPSSetST(EPS,ST);
157: EXTERN PetscErrorCode EPSGetST(EPS,ST*);
158: EXTERN PetscErrorCode EPSSetIP(EPS,IP);
159: EXTERN PetscErrorCode EPSGetIP(EPS,IP*);
160: EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
161: EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
162: EXTERN PetscErrorCode EPSSetConvergenceTestFunction(EPS,PetscErrorCode (*)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*);
163: EXTERN PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv);
164: EXTERN PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv);
165: EXTERN PetscErrorCode EPSEigRelativeConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
166: EXTERN PetscErrorCode EPSAbsoluteConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
167: EXTERN PetscErrorCode EPSNormRelativeConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
168: EXTERN PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
169: EXTERN PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

171: EXTERN PetscErrorCode EPSGetConverged(EPS,PetscInt*);
172: EXTERN PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
173: EXTERN PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);
174: EXTERN PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);
175: EXTERN PetscErrorCode EPSGetEigenvectorLeft(EPS,PetscInt,Vec,Vec);
176: EXTERN PetscErrorCode EPSComputeRelativeError(EPS,PetscInt,PetscReal*);
177: EXTERN PetscErrorCode EPSComputeRelativeErrorLeft(EPS,PetscInt,PetscReal*);
178: EXTERN PetscErrorCode EPSComputeResidualNorm(EPS,PetscInt,PetscReal*);
179: EXTERN PetscErrorCode EPSComputeResidualNormLeft(EPS,PetscInt,PetscReal*);
180: EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec*);
181: EXTERN PetscErrorCode EPSGetInvariantSubspaceLeft(EPS,Vec*);
182: EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
183: EXTERN PetscErrorCode EPSGetErrorEstimateLeft(EPS,PetscInt,PetscReal*);

185: EXTERN PetscErrorCode EPSMonitorSet(EPS,PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),
186:                                     void*,PetscErrorCode (*monitordestroy)(void*));
187: EXTERN PetscErrorCode EPSMonitorCancel(EPS);
188: EXTERN PetscErrorCode EPSGetMonitorContext(EPS,void **);
189: EXTERN PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);
190: EXTERN PetscErrorCode EPSGetOperationCounters(EPS,PetscInt*,PetscInt*,PetscInt*);

192: EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
193: EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
194: EXTERN PetscErrorCode EPSSetLeftVectorsWanted(EPS,PetscTruth);
195: EXTERN PetscErrorCode EPSGetLeftVectorsWanted(EPS,PetscTruth*);
196: EXTERN PetscErrorCode EPSSetMatrixNorms(EPS,PetscReal,PetscReal,PetscTruth);
197: EXTERN PetscErrorCode EPSGetMatrixNorms(EPS,PetscReal*,PetscReal*,PetscTruth*);
198: EXTERN PetscErrorCode EPSSetTrueResidual(EPS,PetscTruth);
199: EXTERN PetscErrorCode EPSGetTrueResidual(EPS,PetscTruth*);
200: EXTERN PetscErrorCode EPSSetEigenvalueComparison(EPS,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);
201: EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscTruth*);
202: EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscTruth*);

204: EXTERN PetscErrorCode EPSMonitorFirst(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
205: EXTERN PetscErrorCode EPSMonitorAll(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
206: EXTERN PetscErrorCode EPSMonitorConverged(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
207: EXTERN PetscErrorCode EPSMonitorLG(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
208: EXTERN PetscErrorCode EPSMonitorLGAll(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

210: EXTERN PetscErrorCode EPSSetTrackAll(EPS,PetscTruth);
211: EXTERN PetscErrorCode EPSGetTrackAll(EPS,PetscTruth*);

213: EXTERN PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec*);
214: EXTERN PetscErrorCode EPSRemoveDeflationSpace(EPS);
215: EXTERN PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec*);
216: EXTERN PetscErrorCode EPSSetInitialSpaceLeft(EPS,PetscInt,Vec*);

218: EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char*);
219: EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char*);
220: EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

222: /*E
223:     EPSConvergedReason - reason an eigensolver was said to 
224:          have converged or diverged

226:     Level: beginner

228: .seealso: EPSSolve(), EPSGetConvergedReason(), EPSSetTolerances()
229: E*/
230: typedef enum {/* converged */
231:               EPS_CONVERGED_TOL                =  2,
232:               /* diverged */
233:               EPS_DIVERGED_ITS                 = -3,
234:               EPS_DIVERGED_BREAKDOWN           = -4,
235:               EPS_DIVERGED_NONSYMMETRIC        = -5,
236:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;

238: EXTERN PetscErrorCode EPSGetConvergedReason(EPS,EPSConvergedReason *);

240: EXTERN PetscErrorCode EPSSortEigenvalues(EPS,PetscInt,PetscScalar*,PetscScalar*,PetscInt*);
241: EXTERN PetscErrorCode EPSSortEigenvaluesReal(EPS,PetscInt,PetscReal*,PetscInt*);
242: EXTERN PetscErrorCode EPSCompareEigenvalues(EPS,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*);
243: EXTERN PetscErrorCode EPSDenseNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
244: EXTERN PetscErrorCode EPSDenseGNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
245: EXTERN PetscErrorCode EPSDenseHEP(PetscInt,PetscScalar*,PetscInt,PetscReal*,PetscScalar*);
246: EXTERN PetscErrorCode EPSDenseGHEP(PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscScalar*);
247: EXTERN PetscErrorCode EPSDenseHessenberg(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*);
248: EXTERN PetscErrorCode EPSDenseSchur(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);
249: EXTERN PetscErrorCode EPSSortDenseSchur(EPS,PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);
250: EXTERN PetscErrorCode EPSSortDenseSchurGeneralized(EPS,PetscInt,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
251: EXTERN PetscErrorCode EPSDenseTridiagonal(PetscInt,PetscReal*,PetscReal*,PetscReal*,PetscScalar*);

253: EXTERN PetscErrorCode EPSGetStartVector(EPS,PetscInt,Vec,PetscTruth*);
254: EXTERN PetscErrorCode EPSGetStartVectorLeft(EPS,PetscInt,Vec,PetscTruth*);

256: EXTERN PetscErrorCode EPSRegister(const char*,const char*,const char*,PetscErrorCode(*)(EPS));
257: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
258: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,0)
259: #else
260: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,d)
261: #endif
262: EXTERN PetscErrorCode EPSRegisterDestroy(void);

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

266: /*E
267:     EPSPowerShiftType - determines the type of shift used in the Power iteration

269:     Level: advanced

271: .seealso: EPSPowerSetShiftType(), EPSPowerGetShiftType()
272: E*/
273: typedef enum { EPS_POWER_SHIFT_CONSTANT,
274:                EPS_POWER_SHIFT_RAYLEIGH,
275:                EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;

277: EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
278: EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);

280: EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscTruth);
281: EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscTruth*);

283: /*E
284:     EPSLanczosReorthogType - determines the type of reorthogonalization
285:     used in the Lanczos method

287:     Level: advanced

289: .seealso: EPSLanczosSetReorthog(), EPSLanczosGetReorthog()
290: E*/
291: typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,
292:                EPS_LANCZOS_REORTHOG_FULL,
293:                EPS_LANCZOS_REORTHOG_SELECTIVE,
294:                EPS_LANCZOS_REORTHOG_PERIODIC,
295:                EPS_LANCZOS_REORTHOG_PARTIAL,
296:                EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;

298: EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
299: EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

301: EXTERN PetscErrorCode EPSBlzpackSetBlockSize(EPS,PetscInt);
302: EXTERN PetscErrorCode EPSBlzpackSetInterval(EPS,PetscReal,PetscReal);
303: EXTERN PetscErrorCode EPSBlzpackSetNSteps(EPS,PetscInt);

305: /*E
306:     EPSPRIMMEMethod - determines the method selected in the PRIMME library

308:     Level: advanced

310: .seealso: EPSPRIMMESetMethod(), EPSPRIMMEGetMethod()
311: E*/
312: typedef enum { EPS_PRIMME_DYNAMIC,
313:                EPS_PRIMME_DEFAULT_MIN_TIME,
314:                EPS_PRIMME_DEFAULT_MIN_MATVECS,
315:                EPS_PRIMME_ARNOLDI,
316:                EPS_PRIMME_GD,
317:                EPS_PRIMME_GD_PLUSK,
318:                EPS_PRIMME_GD_OLSEN_PLUSK,
319:                EPS_PRIMME_JD_OLSEN_PLUSK,
320:                EPS_PRIMME_RQI,
321:                EPS_PRIMME_JDQR,
322:                EPS_PRIMME_JDQMR,
323:                EPS_PRIMME_JDQMR_ETOL,
324:                EPS_PRIMME_SUBSPACE_ITERATION,
325:                EPS_PRIMME_LOBPCG_ORTHOBASIS,
326:                EPS_PRIMME_LOBPCG_ORTHOBASISW } EPSPRIMMEMethod;

328: EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS eps,PetscInt bs);
329: EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS eps, EPSPRIMMEMethod method);
330: EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS eps,PetscInt *bs);
331: EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS eps, EPSPRIMMEMethod *method);

333: EXTERN PetscErrorCode EPSGDSetKrylovStart(EPS eps,PetscTruth krylovstart);
334: EXTERN PetscErrorCode EPSGDGetKrylovStart(EPS eps,PetscTruth *krylovstart);
335: EXTERN PetscErrorCode EPSGDSetBlockSize(EPS eps,PetscInt blocksize);
336: EXTERN PetscErrorCode EPSGDGetBlockSize(EPS eps,PetscInt *blocksize);
337: EXTERN PetscErrorCode EPSGDSetRestart(EPS eps,PetscInt minv,PetscInt plusk);
338: EXTERN PetscErrorCode EPSGDGetRestart(EPS eps,PetscInt *minv,PetscInt *plusk);
339: EXTERN PetscErrorCode EPSGDSetInitialSize(EPS eps,PetscInt initialsize);
340: EXTERN PetscErrorCode EPSGDGetInitialSize(EPS eps,PetscInt *initialsize);

342: EXTERN PetscErrorCode EPSJDSetKrylovStart(EPS eps,PetscTruth krylovstart);
343: EXTERN PetscErrorCode EPSJDGetKrylovStart(EPS eps,PetscTruth *krylovstart);
344: EXTERN PetscErrorCode EPSJDSetBlockSize(EPS eps,PetscInt blocksize);
345: EXTERN PetscErrorCode EPSJDGetBlockSize(EPS eps,PetscInt *blocksize);
346: EXTERN PetscErrorCode EPSJDSetRestart(EPS eps,PetscInt minv,PetscInt plusk);
347: EXTERN PetscErrorCode EPSJDGetRestart(EPS eps,PetscInt *minv,PetscInt *plusk);
348: EXTERN PetscErrorCode EPSJDSetInitialSize(EPS eps,PetscInt initialsize);
349: EXTERN PetscErrorCode EPSJDGetInitialSize(EPS eps,PetscInt *initialsize);
350: EXTERN PetscErrorCode EPSJDSetFix(EPS eps,PetscReal fix);
351: EXTERN PetscErrorCode EPSJDGetFix(EPS eps,PetscReal *fix);

354: #endif