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-2009, 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 slepc.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 EPSLAPACK    "lapack"
 57: /* the next ones are interfaces to external libraries */
 58: #define EPSARPACK    "arpack"
 59: #define EPSBLZPACK   "blzpack"
 60: #define EPSTRLAN     "trlan"
 61: #define EPSBLOPEX    "blopex"
 62: #define EPSPRIMME    "primme"

 64: /*E
 65:     EPSProblemType - determines the type of eigenvalue problem

 67:     Level: beginner

 69: .seealso: EPSSetProblemType(), EPSGetProblemType()
 70: E*/
 71: typedef enum { EPS_HEP=1,  EPS_GHEP,
 72:                EPS_NHEP,   EPS_GNHEP, EPS_PGNHEP } EPSProblemType;

 74: /*E
 75:     EPSExtraction - determines the type of extraction technique employed
 76:     by the eigensolver

 78:     Level: beginner

 80: .seealso: EPSSetExtraction(), EPSGetExtraction()
 81: E*/
 82: typedef enum { EPS_RITZ=1,   EPS_HARMONIC,
 83:                EPS_REFINED,  EPS_REFINED_HARMONIC } EPSExtraction;

 85: /*E
 86:     EPSClass - determines if the eigensolver is one- or two-sided

 88:     Level: intermediate

 90: .seealso: EPSSetClass(), EPSGetClass()
 91: E*/
 92: typedef enum { EPS_ONE_SIDE, EPS_TWO_SIDE } EPSClass;

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

 97:     Level: intermediate

 99: .seealso: EPSSetWhichEigenpairs(), EPSGetWhichEigenpairs()
100: E*/
101: typedef enum { EPS_LARGEST_MAGNITUDE, EPS_SMALLEST_MAGNITUDE,
102:                EPS_LARGEST_REAL,      EPS_SMALLEST_REAL,
103:                EPS_LARGEST_IMAGINARY, EPS_SMALLEST_IMAGINARY } EPSWhich;

105: EXTERN PetscErrorCode EPSCreate(MPI_Comm,EPS *);
106: EXTERN PetscErrorCode EPSDestroy(EPS);
107: EXTERN PetscErrorCode EPSSetType(EPS,const EPSType);
108: EXTERN PetscErrorCode EPSGetType(EPS,const EPSType*);
109: EXTERN PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
110: EXTERN PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
111: EXTERN PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);
112: EXTERN PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);
113: EXTERN PetscErrorCode EPSSetClass(EPS,EPSClass);
114: EXTERN PetscErrorCode EPSGetClass(EPS,EPSClass*);
115: EXTERN PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
116: EXTERN PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);
117: EXTERN PetscErrorCode EPSSetFromOptions(EPS);
118: EXTERN PetscErrorCode EPSSetUp(EPS);
119: EXTERN PetscErrorCode EPSSolve(EPS);
120: EXTERN PetscErrorCode EPSView(EPS,PetscViewer);

122: EXTERN PetscErrorCode EPSInitializePackage(char *);

124: EXTERN PetscErrorCode EPSSetTarget(EPS,PetscScalar);
125: EXTERN PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
126: EXTERN PetscErrorCode EPSSetST(EPS,ST);
127: EXTERN PetscErrorCode EPSGetST(EPS,ST*);
128: EXTERN PetscErrorCode EPSSetIP(EPS,IP);
129: EXTERN PetscErrorCode EPSGetIP(EPS,IP*);
130: EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
131: EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
132: EXTERN PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
133: EXTERN PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

135: EXTERN PetscErrorCode EPSGetConverged(EPS,PetscInt*);
136: EXTERN PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
137: EXTERN PetscErrorCode EPSGetValue(EPS,PetscInt,PetscScalar*,PetscScalar*);
138: EXTERN PetscErrorCode EPSGetRightVector(EPS,PetscInt,Vec,Vec);
139: EXTERN PetscErrorCode EPSGetLeftVector(EPS,PetscInt,Vec,Vec);
140: EXTERN PetscErrorCode EPSComputeRelativeError(EPS,PetscInt,PetscReal*);
141: EXTERN PetscErrorCode EPSComputeRelativeErrorLeft(EPS,PetscInt,PetscReal*);
142: EXTERN PetscErrorCode EPSComputeResidualNorm(EPS,PetscInt,PetscReal*);
143: EXTERN PetscErrorCode EPSComputeResidualNormLeft(EPS,PetscInt,PetscReal*);
144: EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec*);
145: EXTERN PetscErrorCode EPSGetLeftInvariantSubspace(EPS,Vec*);
146: EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
147: EXTERN PetscErrorCode EPSGetErrorEstimateLeft(EPS,PetscInt,PetscReal*);

149: EXTERN PetscErrorCode EPSMonitorSet(EPS,PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),
150:                                     void*,PetscErrorCode (*monitordestroy)(void*));
151: EXTERN PetscErrorCode EPSMonitorCancel(EPS);
152: EXTERN PetscErrorCode EPSGetMonitorContext(EPS,void **);
153: EXTERN PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);
154: EXTERN PetscErrorCode EPSGetOperationCounters(EPS,PetscInt*,PetscInt*,PetscInt*);

156: EXTERN PetscErrorCode EPSSetInitialVector(EPS,Vec);
157: EXTERN PetscErrorCode EPSGetInitialVector(EPS,Vec*);
158: EXTERN PetscErrorCode EPSSetLeftInitialVector(EPS,Vec);
159: EXTERN PetscErrorCode EPSGetLeftInitialVector(EPS,Vec*);
160: EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
161: EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
162: EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscTruth*);
163: EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscTruth*);

165: EXTERN PetscErrorCode EPSMonitorDefault(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
166: EXTERN PetscErrorCode EPSMonitorLG(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

168: EXTERN PetscErrorCode EPSAttachDeflationSpace(EPS,PetscInt,Vec*,PetscTruth);
169: EXTERN PetscErrorCode EPSRemoveDeflationSpace(EPS);

171: EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char*);
172: EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char*);
173: EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

175: /*E
176:     EPSConvergedReason - reason an eigensolver was said to 
177:          have converged or diverged

179:    Level: beginner

181: .seealso: EPSSolve(), EPSGetConvergedReason(), EPSSetTolerances()
182: E*/
183: typedef enum {/* converged */
184:               EPS_CONVERGED_TOL                =  2,
185:               /* diverged */
186:               EPS_DIVERGED_ITS                 = -3,
187:               EPS_DIVERGED_BREAKDOWN           = -4,
188:               EPS_DIVERGED_NONSYMMETRIC        = -5,
189:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;

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

193: EXTERN PetscErrorCode EPSSortEigenvalues(PetscInt,PetscScalar*,PetscScalar*,EPSWhich,PetscInt,PetscInt*);
194: EXTERN PetscErrorCode EPSSortEigenvaluesReal(PetscInt,PetscReal*,EPSWhich,PetscInt,PetscInt*,PetscReal*);
195: EXTERN PetscErrorCode EPSDenseNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
196: EXTERN PetscErrorCode EPSDenseGNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
197: EXTERN PetscErrorCode EPSDenseHEP(PetscInt,PetscScalar*,PetscInt,PetscReal*,PetscScalar*);
198: EXTERN PetscErrorCode EPSDenseGHEP(PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscScalar*);
199: EXTERN PetscErrorCode EPSDenseHessenberg(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*);
200: EXTERN PetscErrorCode EPSDenseSchur(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);
201: EXTERN PetscErrorCode EPSSortDenseSchur(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,EPSWhich);
202: EXTERN PetscErrorCode EPSSortDenseSchurTarget(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar,EPSWhich);
203: EXTERN PetscErrorCode EPSDenseTridiagonal(PetscInt,PetscReal*,PetscReal*,PetscReal*,PetscScalar*);

205: EXTERN PetscErrorCode EPSGetStartVector(EPS,PetscInt,Vec,PetscTruth*);
206: EXTERN PetscErrorCode EPSGetLeftStartVector(EPS,PetscInt,Vec);

208: EXTERN PetscErrorCode EPSRegister(const char*,const char*,const char*,PetscErrorCode(*)(EPS));
209: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
210: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,0)
211: #else
212: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,d)
213: #endif
214: EXTERN PetscErrorCode EPSRegisterDestroy(void);

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

218: /*E
219:     EPSPowerShiftType - determines the type of shift used in the Power iteration

221:     Level: advanced

223: .seealso: EPSPowerSetShiftType(), EPSPowerGetShiftType()
224: E*/
225: typedef enum { EPSPOWER_SHIFT_CONSTANT, EPSPOWER_SHIFT_RAYLEIGH,
226:                EPSPOWER_SHIFT_WILKINSON } EPSPowerShiftType;

228: EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
229: EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);

231: EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscTruth);
232: EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscTruth*);

234: /*E
235:     EPSLanczosReorthogType - determines the type of reorthogonalization
236:     used in the Lanczos method

238:     Level: advanced

240: .seealso: EPSLanczosSetReorthog(), EPSLanczosGetReorthog()
241: E*/
242: typedef enum { EPSLANCZOS_REORTHOG_LOCAL,
243:                EPSLANCZOS_REORTHOG_FULL,
244:                EPSLANCZOS_REORTHOG_SELECTIVE,
245:                EPSLANCZOS_REORTHOG_PERIODIC,
246:                EPSLANCZOS_REORTHOG_PARTIAL,
247:                EPSLANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;

249: EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
250: EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

252: EXTERN PetscErrorCode EPSBlzpackSetBlockSize(EPS,PetscInt);
253: EXTERN PetscErrorCode EPSBlzpackSetInterval(EPS,PetscReal,PetscReal);
254: EXTERN PetscErrorCode EPSBlzpackSetNSteps(EPS,PetscInt);

256: /*E
257:     EPSPRIMMEMethod - determines the method selected in the PRIMME library

259:     Level: advanced

261: .seealso: EPSPRIMMESetMethod(), EPSPRIMMEGetMethod()
262: E*/
263: typedef enum {
264:   EPSPRIMME_DYNAMIC,
265:   EPSPRIMME_DEFAULT_MIN_TIME,
266:   EPSPRIMME_DEFAULT_MIN_MATVECS,
267:   EPSPRIMME_ARNOLDI,
268:   EPSPRIMME_GD,
269:   EPSPRIMME_GD_PLUSK,
270:   EPSPRIMME_GD_OLSEN_PLUSK,
271:   EPSPRIMME_JD_OLSEN_PLUSK,
272:   EPSPRIMME_RQI,
273:   EPSPRIMME_JDQR,
274:   EPSPRIMME_JDQMR,
275:   EPSPRIMME_JDQMR_ETOL,
276:   EPSPRIMME_SUBSPACE_ITERATION,
277:   EPSPRIMME_LOBPCG_ORTHOBASIS,
278:   EPSPRIMME_LOBPCG_ORTHOBASISW
279: } EPSPRIMMEMethod;

281: /*E
282:     EPSPRIMMEPrecond - determines the type of preconditioning
283:     used in the PRIMME library

285:     Level: advanced

287: .seealso: EPSPRIMMESetPrecond(), EPSPRIMMEGetPrecond()
288: E*/
289: typedef enum {
290:   EPSPRIMME_NONE,
291:   EPSPRIMME_DIAGONAL
292: } EPSPRIMMEPrecond;

294: EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS eps,PetscInt bs);
295: EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS eps, EPSPRIMMEMethod method);
296: EXTERN PetscErrorCode EPSPRIMMESetPrecond(EPS eps, EPSPRIMMEPrecond precond);
297: EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS eps,PetscInt *bs);
298: EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS eps, EPSPRIMMEMethod *method);
299: EXTERN PetscErrorCode EPSPRIMMEGetPrecond(EPS eps, EPSPRIMMEPrecond *precond);

302: #endif