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-2007, Universidad Politecnica de Valencia, Spain

  8:       This file is part of SLEPc. See the README file for conditions of use
  9:       and additional information.
 10:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 11: */

 15:  #include slepc.h
 16:  #include slepcst.h
 17:  #include slepcip.h


 22: /*S
 23:      EPS - Abstract SLEPc object that manages all the eigenvalue 
 24:      problem solvers.

 26:    Level: beginner

 28: .seealso:  EPSCreate(), ST
 29: S*/
 30: typedef struct _p_EPS* EPS;

 32: /*E
 33:     EPSType - String with the name of a SLEPc eigensolver

 35:    Level: beginner

 37: .seealso: EPSSetType(), EPS
 38: E*/
 39: #define EPSType const char*
 40: #define EPSPOWER     "power"
 41: #define EPSSUBSPACE  "subspace"
 42: #define EPSARNOLDI   "arnoldi"
 43: #define EPSLANCZOS   "lanczos"
 44: #define EPSKRYLOVSCHUR "krylovschur"
 45: #define EPSLAPACK    "lapack"
 46: /* the next ones are interfaces to external libraries */
 47: #define EPSARPACK    "arpack"
 48: #define EPSBLZPACK   "blzpack"
 49: #define EPSTRLAN     "trlan"
 50: #define EPSBLOPEX    "blopex"
 51: #define EPSPRIMME    "primme"

 53: /*E
 54:     EPSProblemType - determines the type of eigenvalue problem

 56:     Level: beginner

 58: .seealso: EPSSetProblemType(), EPSGetProblemType()
 59: E*/
 60: typedef enum { EPS_HEP=1,  EPS_GHEP,
 61:                EPS_NHEP,   EPS_GNHEP, EPS_PGNHEP } EPSProblemType;

 63: /*E
 64:     EPSClass - determines if the eigensolver is one- or two-sided

 66:     Level: intermediate

 68: .seealso: EPSSetClass(), EPSGetClass()
 69: E*/
 70: typedef enum { EPS_ONE_SIDE, EPS_TWO_SIDE } EPSClass;

 72: /*E
 73:     EPSWhich - determines which part of the spectrum is requested

 75:     Level: intermediate

 77: .seealso: EPSSetWhichEigenpairs(), EPSGetWhichEigenpairs()
 78: E*/
 79: typedef enum { EPS_LARGEST_MAGNITUDE, EPS_SMALLEST_MAGNITUDE,
 80:                EPS_LARGEST_REAL,      EPS_SMALLEST_REAL,
 81:                EPS_LARGEST_IMAGINARY, EPS_SMALLEST_IMAGINARY } EPSWhich;

 83: EXTERN PetscErrorCode EPSCreate(MPI_Comm,EPS *);
 84: EXTERN PetscErrorCode EPSDestroy(EPS);
 85: EXTERN PetscErrorCode EPSSetType(EPS,EPSType);
 86: EXTERN PetscErrorCode EPSGetType(EPS,EPSType*);
 87: EXTERN PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
 88: EXTERN PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
 89: EXTERN PetscErrorCode EPSSetClass(EPS,EPSClass);
 90: EXTERN PetscErrorCode EPSGetClass(EPS,EPSClass*);
 91: EXTERN PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
 92: EXTERN PetscErrorCode EPSSetFromOptions(EPS);
 93: EXTERN PetscErrorCode EPSSetUp(EPS);
 94: EXTERN PetscErrorCode EPSSolve(EPS);
 95: EXTERN PetscErrorCode EPSView(EPS,PetscViewer);

 97: EXTERN PetscErrorCode EPSInitializePackage(char *);

 99: EXTERN PetscErrorCode EPSSetST(EPS,ST);
100: EXTERN PetscErrorCode EPSGetST(EPS,ST*);
101: EXTERN PetscErrorCode EPSSetIP(EPS,IP);
102: EXTERN PetscErrorCode EPSGetIP(EPS,IP*);
103: EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,int);
104: EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,int*);
105: EXTERN PetscErrorCode EPSSetDimensions(EPS,int,int);
106: EXTERN PetscErrorCode EPSGetDimensions(EPS,int*,int*);

108: EXTERN PetscErrorCode EPSGetConverged(EPS,int*);
109: EXTERN PetscErrorCode EPSGetEigenpair(EPS,int,PetscScalar*,PetscScalar*,Vec,Vec);
110: EXTERN PetscErrorCode EPSGetValue(EPS,int,PetscScalar*,PetscScalar*);
111: EXTERN PetscErrorCode EPSGetRightVector(EPS,int,Vec,Vec);
112: EXTERN PetscErrorCode EPSGetLeftVector(EPS,int,Vec,Vec);
113: EXTERN PetscErrorCode EPSComputeRelativeError(EPS,int,PetscReal*);
114: EXTERN PetscErrorCode EPSComputeRelativeErrorLeft(EPS,int,PetscReal*);
115: EXTERN PetscErrorCode EPSComputeResidualNorm(EPS,int,PetscReal*);
116: EXTERN PetscErrorCode EPSComputeResidualNormLeft(EPS,int,PetscReal*);
117: EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec*);
118: EXTERN PetscErrorCode EPSGetLeftInvariantSubspace(EPS,Vec*);
119: EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,int,PetscReal*);
120: EXTERN PetscErrorCode EPSGetErrorEstimateLeft(EPS,int,PetscReal*);

122: EXTERN PetscErrorCode EPSMonitorSet(EPS,PetscErrorCode (*)(EPS,int,int,PetscScalar*,PetscScalar*,PetscReal*,int,void*),
123:                                     void*,PetscErrorCode (*monitordestroy)(void*));
124: EXTERN PetscErrorCode EPSMonitorCancel(EPS);
125: EXTERN PetscErrorCode EPSGetMonitorContext(EPS,void **);
126: EXTERN PetscErrorCode EPSGetIterationNumber(EPS,int*);
127: EXTERN PetscErrorCode EPSGetOperationCounters(EPS,int*,int*,int*);

129: EXTERN PetscErrorCode EPSSetInitialVector(EPS,Vec);
130: EXTERN PetscErrorCode EPSGetInitialVector(EPS,Vec*);
131: EXTERN PetscErrorCode EPSSetLeftInitialVector(EPS,Vec);
132: EXTERN PetscErrorCode EPSGetLeftInitialVector(EPS,Vec*);
133: EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
134: EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
135: EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscTruth*);
136: EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscTruth*);

138: EXTERN PetscErrorCode EPSMonitorDefault(EPS,int,int,PetscScalar*,PetscScalar*,PetscReal*,int,void*);
139: EXTERN PetscErrorCode EPSMonitorLG(EPS,int,int,PetscScalar*,PetscScalar*,PetscReal*,int,void*);

141: EXTERN PetscErrorCode EPSAttachDeflationSpace(EPS,int,Vec*,PetscTruth);
142: EXTERN PetscErrorCode EPSRemoveDeflationSpace(EPS);

144: EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char*);
145: EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char*);
146: EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

148: /*E
149:     EPSConvergedReason - reason an eigensolver was said to 
150:          have converged or diverged

152:    Level: beginner

154: .seealso: EPSSolve(), EPSGetConvergedReason(), EPSSetTolerances()
155: E*/
156: typedef enum {/* converged */
157:               EPS_CONVERGED_TOL                =  2,
158:               /* diverged */
159:               EPS_DIVERGED_ITS                 = -3,
160:               EPS_DIVERGED_BREAKDOWN           = -4,
161:               EPS_DIVERGED_NONSYMMETRIC        = -5,
162:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;

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

166: EXTERN PetscErrorCode EPSSortEigenvalues(int,PetscScalar*,PetscScalar*,EPSWhich,int,int*);
167: EXTERN PetscErrorCode EPSDenseNHEP(int,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
168: EXTERN PetscErrorCode EPSDenseGNHEP(int,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
169: EXTERN PetscErrorCode EPSDenseHEP(int,PetscScalar*,int,PetscReal*,PetscScalar*);
170: EXTERN PetscErrorCode EPSDenseGHEP(int,PetscScalar*,PetscScalar*,PetscReal*,PetscScalar*);
171: EXTERN PetscErrorCode EPSDenseHessenberg(int,int,PetscScalar*,int,PetscScalar*);
172: EXTERN PetscErrorCode EPSDenseSchur(int,int,PetscScalar*,int,PetscScalar*,PetscScalar*,PetscScalar*);
173: EXTERN PetscErrorCode EPSSortDenseSchur(int,int,PetscScalar*,int,PetscScalar*,PetscScalar*,PetscScalar*,EPSWhich);
174: EXTERN PetscErrorCode EPSDenseTridiagonal(int,PetscScalar*,int,PetscReal*,PetscScalar*);

176: EXTERN PetscErrorCode EPSGetStartVector(EPS,int,Vec,PetscTruth*);
177: EXTERN PetscErrorCode EPSGetLeftStartVector(EPS,int,Vec);

179: EXTERN PetscErrorCode EPSRegister(const char*,const char*,const char*,int(*)(EPS));
180: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
181: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,0)
182: #else
183: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,d)
184: #endif
185: EXTERN PetscErrorCode EPSRegisterDestroy(void);

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

189: /*E
190:     EPSPowerShiftType - determines the type of shift used in the Power iteration

192:     Level: advanced

194: .seealso: EPSPowerSetShiftType(), EPSPowerGetShiftType()
195: E*/
196: typedef enum { EPSPOWER_SHIFT_CONSTANT, EPSPOWER_SHIFT_RAYLEIGH,
197:                EPSPOWER_SHIFT_WILKINSON } EPSPowerShiftType;

199: EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
200: EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);

202: EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscTruth);
203: EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscTruth*);

205: /*E
206:     EPSLanczosReorthogType - determines the type of reorthogonalization
207:     used in the Lanczos method

209:     Level: advanced

211: .seealso: EPSLanczosSetReorthog(), EPSLanczosGetReorthog()
212: E*/
213: typedef enum { EPSLANCZOS_REORTHOG_LOCAL,
214:                EPSLANCZOS_REORTHOG_FULL,
215:                EPSLANCZOS_REORTHOG_SELECTIVE,
216:                EPSLANCZOS_REORTHOG_PERIODIC,
217:                EPSLANCZOS_REORTHOG_PARTIAL,
218:                EPSLANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;

220: EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
221: EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

223: EXTERN PetscErrorCode EPSBlzpackSetBlockSize(EPS,int);
224: EXTERN PetscErrorCode EPSBlzpackSetInterval(EPS,PetscReal,PetscReal);
225: EXTERN PetscErrorCode EPSBlzpackSetNSteps(EPS,int);

227: /*E
228:     EPSPRIMMEMethod - determines the method selected in the PRIMME library

230:     Level: advanced

232: .seealso: EPSPRIMMESetMethod(), EPSPRIMMEGetMethod()
233: E*/
234: typedef enum {
235:   EPSPRIMME_DYNAMIC,
236:   EPSPRIMME_DEFAULT_MIN_TIME,
237:   EPSPRIMME_DEFAULT_MIN_MATVECS,
238:   EPSPRIMME_ARNOLDI,
239:   EPSPRIMME_GD,
240:   EPSPRIMME_GD_PLUSK,
241:   EPSPRIMME_GD_OLSEN_PLUSK,
242:   EPSPRIMME_JD_OLSEN_PLUSK,
243:   EPSPRIMME_RQI,
244:   EPSPRIMME_JDQR,
245:   EPSPRIMME_JDQMR,
246:   EPSPRIMME_JDQMR_ETOL,
247:   EPSPRIMME_SUBSPACE_ITERATION,
248:   EPSPRIMME_LOBPCG_ORTHOBASIS,
249:   EPSPRIMME_LOBPCG_ORTHOBASIS_WINDOW
250: } EPSPRIMMEMethod;

252: /*E
253:     EPSPRIMMEPrecond - determines the type of preconditioning
254:     used in the PRIMME library

256:     Level: advanced

258: .seealso: EPSPRIMMESetPrecond(), EPSPRIMMEGetPrecond()
259: E*/
260: typedef enum {
261:   EPSPRIMME_NONE,
262:   EPSPRIMME_DIAGONAL
263: } EPSPRIMMEPrecond;

265: EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS eps,int bs);
266: EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS eps, EPSPRIMMEMethod method);
267: EXTERN PetscErrorCode EPSPRIMMESetPrecond(EPS eps, EPSPRIMMEPrecond precond);
268: EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS eps,int *bs);
269: EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS eps, EPSPRIMMEMethod *method);
270: EXTERN PetscErrorCode EPSPRIMMEGetPrecond(EPS eps, EPSPRIMMEPrecond *precond);

273: #endif