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-2011, Universitat 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
 29: PETSC_EXTERN_CXX_BEGIN

 31: extern PetscErrorCode EPSInitializePackage(const char[]);

 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: /* Logging support */
 67: extern PetscClassId EPS_CLASSID;

 69: /*E
 70:     EPSProblemType - determines the type of eigenvalue problem

 72:     Level: beginner

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

 82: /*E
 83:     EPSExtraction - determines the type of extraction technique employed
 84:     by the eigensolver

 86:     Level: beginner

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

 98: /*E
 99:     EPSWhich - determines which part of the spectrum is requested

101:     Level: intermediate

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

117: /*E
118:     EPSBalance - the type of balancing used for non-Hermitian problems

120:     Level: intermediate

122: .seealso: EPSSetBalance()
123: E*/
124: typedef enum { EPS_BALANCE_NONE=1,
125:                EPS_BALANCE_ONESIDE,
126:                EPS_BALANCE_TWOSIDE,
127:                EPS_BALANCE_USER } EPSBalance;

129: /*E
130:     EPSConv - determines the convergence test

132:     Level: intermediate

134: .seealso: EPSSetConvergenceTest(), EPSSetConvergenceTestFunction()
135: E*/
136: typedef enum { EPS_CONV_ABS=1,
137:                EPS_CONV_EIG,
138:                EPS_CONV_NORM,
139:                EPS_CONV_USER } EPSConv;

141: extern PetscErrorCode EPSCreate(MPI_Comm,EPS *);
142: extern PetscErrorCode EPSDestroy(EPS*);
143: extern PetscErrorCode EPSReset(EPS);
144: extern PetscErrorCode EPSSetType(EPS,const EPSType);
145: extern PetscErrorCode EPSGetType(EPS,const EPSType*);
146: extern PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
147: extern PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
148: extern PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);
149: extern PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);
150: extern PetscErrorCode EPSSetBalance(EPS,EPSBalance,PetscInt,PetscReal);
151: extern PetscErrorCode EPSGetBalance(EPS,EPSBalance*,PetscInt*,PetscReal*);
152: extern PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
153: extern PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);
154: extern PetscErrorCode EPSSetFromOptions(EPS);
155: extern PetscErrorCode EPSSetUp(EPS);
156: extern PetscErrorCode EPSSolve(EPS);
157: extern PetscErrorCode EPSView(EPS,PetscViewer);
158: extern PetscErrorCode EPSPrintSolution(EPS,PetscViewer);

160: extern PetscErrorCode EPSSetTarget(EPS,PetscScalar);
161: extern PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
162: extern PetscErrorCode EPSSetInterval(EPS,PetscReal,PetscReal);
163: extern PetscErrorCode EPSGetInterval(EPS,PetscReal*,PetscReal*);
164: extern PetscErrorCode EPSSetST(EPS,ST);
165: extern PetscErrorCode EPSGetST(EPS,ST*);
166: extern PetscErrorCode EPSSetIP(EPS,IP);
167: extern PetscErrorCode EPSGetIP(EPS,IP*);
168: extern PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
169: extern PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
170: extern PetscErrorCode EPSSetConvergenceTestFunction(EPS,PetscErrorCode (*)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*);
171: extern PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv);
172: extern PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv);
173: extern PetscErrorCode EPSEigRelativeConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
174: extern PetscErrorCode EPSAbsoluteConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
175: extern PetscErrorCode EPSNormRelativeConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
176: extern PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
177: extern PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

179: extern PetscErrorCode EPSGetConverged(EPS,PetscInt*);
180: extern PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
181: extern PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);
182: extern PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);
183: extern PetscErrorCode EPSGetEigenvectorLeft(EPS,PetscInt,Vec,Vec);
184: extern PetscErrorCode EPSComputeRelativeError(EPS,PetscInt,PetscReal*);
185: extern PetscErrorCode EPSComputeRelativeErrorLeft(EPS,PetscInt,PetscReal*);
186: extern PetscErrorCode EPSComputeResidualNorm(EPS,PetscInt,PetscReal*);
187: extern PetscErrorCode EPSComputeResidualNormLeft(EPS,PetscInt,PetscReal*);
188: extern PetscErrorCode EPSGetInvariantSubspace(EPS,Vec*);
189: extern PetscErrorCode EPSGetInvariantSubspaceLeft(EPS,Vec*);
190: extern PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
191: extern PetscErrorCode EPSGetErrorEstimateLeft(EPS,PetscInt,PetscReal*);

193: extern PetscErrorCode EPSMonitorSet(EPS,PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),void*,PetscErrorCode (*)(void**));
194: extern PetscErrorCode EPSMonitorCancel(EPS);
195: extern PetscErrorCode EPSGetMonitorContext(EPS,void **);
196: extern PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);
197: extern PetscErrorCode EPSGetOperationCounters(EPS,PetscInt*,PetscInt*,PetscInt*);

199: extern PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
200: extern PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
201: extern PetscErrorCode EPSSetLeftVectorsWanted(EPS,PetscBool);
202: extern PetscErrorCode EPSGetLeftVectorsWanted(EPS,PetscBool*);
203: extern PetscErrorCode EPSSetMatrixNorms(EPS,PetscReal,PetscReal,PetscBool);
204: extern PetscErrorCode EPSGetMatrixNorms(EPS,PetscReal*,PetscReal*,PetscBool*);
205: extern PetscErrorCode EPSSetTrueResidual(EPS,PetscBool);
206: extern PetscErrorCode EPSGetTrueResidual(EPS,PetscBool*);
207: extern PetscErrorCode EPSSetEigenvalueComparison(EPS,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);
208: extern PetscErrorCode EPSIsGeneralized(EPS,PetscBool*);
209: extern PetscErrorCode EPSIsHermitian(EPS,PetscBool*);

211: extern PetscErrorCode EPSMonitorFirst(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
212: extern PetscErrorCode EPSMonitorAll(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
213: extern PetscErrorCode EPSMonitorConverged(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
214: extern PetscErrorCode EPSMonitorLG(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
215: extern PetscErrorCode EPSMonitorLGAll(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

217: extern PetscErrorCode EPSSetTrackAll(EPS,PetscBool);
218: extern PetscErrorCode EPSGetTrackAll(EPS,PetscBool*);

220: extern PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec*);
221: extern PetscErrorCode EPSRemoveDeflationSpace(EPS);
222: extern PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec*);
223: extern PetscErrorCode EPSSetInitialSpaceLeft(EPS,PetscInt,Vec*);

225: extern PetscErrorCode EPSSetOptionsPrefix(EPS,const char*);
226: extern PetscErrorCode EPSAppendOptionsPrefix(EPS,const char*);
227: extern PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

229: /*E
230:     EPSConvergedReason - reason an eigensolver was said to 
231:          have converged or diverged

233:     Level: beginner

235: .seealso: EPSSolve(), EPSGetConvergedReason(), EPSSetTolerances()
236: E*/
237: typedef enum {/* converged */
238:               EPS_CONVERGED_TOL                =  2,
239:               /* diverged */
240:               EPS_DIVERGED_ITS                 = -3,
241:               EPS_DIVERGED_BREAKDOWN           = -4,
242:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;

244: extern PetscErrorCode EPSGetConvergedReason(EPS,EPSConvergedReason *);

246: extern PetscErrorCode EPSSortEigenvalues(EPS,PetscInt,PetscScalar*,PetscScalar*,PetscInt*);
247: extern PetscErrorCode EPSSortEigenvaluesReal(EPS,PetscInt,PetscReal*,PetscInt*);
248: extern PetscErrorCode EPSCompareEigenvalues(EPS,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*);
249: extern PetscErrorCode EPSDenseNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
250: extern PetscErrorCode EPSDenseGNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
251: extern PetscErrorCode EPSDenseHEP(PetscInt,PetscScalar*,PetscInt,PetscReal*,PetscScalar*);
252: extern PetscErrorCode EPSDenseGHEP(PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscScalar*);
253: extern PetscErrorCode EPSDenseHessenberg(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*);
254: extern PetscErrorCode EPSDenseSchur(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);
255: extern PetscErrorCode EPSSortDenseSchur(EPS,PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);
256: extern PetscErrorCode EPSSortDenseSchurGeneralized(EPS,PetscInt,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);
257: extern PetscErrorCode EPSDenseTridiagonal(PetscInt,PetscReal*,PetscReal*,PetscReal*,PetscScalar*);

259: extern PetscErrorCode EPSGetStartVector(EPS,PetscInt,Vec,PetscBool*);
260: extern PetscErrorCode EPSGetStartVectorLeft(EPS,PetscInt,Vec,PetscBool*);

262: extern PetscFList EPSList;
263: extern PetscBool  EPSRegisterAllCalled;
264: extern PetscErrorCode EPSRegisterAll(const char[]);
265: extern PetscErrorCode EPSRegisterDestroy(void);
266: extern PetscErrorCode EPSRegister(const char[],const char[],const char[],PetscErrorCode(*)(EPS));

268: /*MC
269:    EPSRegisterDynamic - Adds a method to the eigenproblem solver package.

271:    Synopsis:
272:    PetscErrorCode EPSRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(EPS))

274:    Not Collective

276:    Input Parameters:
277: +  name_solver - name of a new user-defined solver
278: .  path - path (either absolute or relative) the library containing this solver
279: .  name_create - name of routine to create the solver context
280: -  routine_create - routine to create the solver context

282:    Notes:
283:    EPSRegisterDynamic() may be called multiple times to add several user-defined solvers.

285:    If dynamic libraries are used, then the fourth input argument (routine_create)
286:    is ignored.

288:    Sample usage:
289: .vb
290:    EPSRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a,
291:                "MySolverCreate",MySolverCreate);
292: .ve

294:    Then, your solver can be chosen with the procedural interface via
295: $     EPSSetType(eps,"my_solver")
296:    or at runtime via the option
297: $     -eps_type my_solver

299:    Level: advanced

301: .seealso: EPSRegisterDestroy(), EPSRegisterAll()
302: M*/
303: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
304: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,0)
305: #else
306: #define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,d)
307: #endif

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

311: /*E
312:     EPSPowerShiftType - determines the type of shift used in the Power iteration

314:     Level: advanced

316: .seealso: EPSPowerSetShiftType(), EPSPowerGetShiftType()
317: E*/
318: typedef enum { EPS_POWER_SHIFT_CONSTANT,
319:                EPS_POWER_SHIFT_RAYLEIGH,
320:                EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;
321: extern const char *EPSPowerShiftTypes[];

323: extern PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
324: extern PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);

326: extern PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscBool);
327: extern PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscBool*);

329: /*E
330:     EPSLanczosReorthogType - determines the type of reorthogonalization
331:     used in the Lanczos method

333:     Level: advanced

335: .seealso: EPSLanczosSetReorthog(), EPSLanczosGetReorthog()
336: E*/
337: typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,
338:                EPS_LANCZOS_REORTHOG_FULL,
339:                EPS_LANCZOS_REORTHOG_SELECTIVE,
340:                EPS_LANCZOS_REORTHOG_PERIODIC,
341:                EPS_LANCZOS_REORTHOG_PARTIAL,
342:                EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;
343: extern const char *EPSLanczosReorthogTypes[];

345: extern PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
346: extern PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

348: extern PetscErrorCode EPSBlzpackSetBlockSize(EPS,PetscInt);
349: extern PetscErrorCode EPSBlzpackSetNSteps(EPS,PetscInt);

351: /*E
352:     EPSPRIMMEMethod - determines the method selected in the PRIMME library

354:     Level: advanced

356: .seealso: EPSPRIMMESetMethod(), EPSPRIMMEGetMethod()
357: E*/
358: typedef enum { EPS_PRIMME_DYNAMIC,
359:                EPS_PRIMME_DEFAULT_MIN_TIME,
360:                EPS_PRIMME_DEFAULT_MIN_MATVECS,
361:                EPS_PRIMME_ARNOLDI,
362:                EPS_PRIMME_GD,
363:                EPS_PRIMME_GD_PLUSK,
364:                EPS_PRIMME_GD_OLSEN_PLUSK,
365:                EPS_PRIMME_JD_OLSEN_PLUSK,
366:                EPS_PRIMME_RQI,
367:                EPS_PRIMME_JDQR,
368:                EPS_PRIMME_JDQMR,
369:                EPS_PRIMME_JDQMR_ETOL,
370:                EPS_PRIMME_SUBSPACE_ITERATION,
371:                EPS_PRIMME_LOBPCG_ORTHOBASIS,
372:                EPS_PRIMME_LOBPCG_ORTHOBASISW } EPSPRIMMEMethod;
373: extern const char *EPSPRIMMEMethods[];

375: extern PetscErrorCode EPSPRIMMESetBlockSize(EPS eps,PetscInt bs);
376: extern PetscErrorCode EPSPRIMMESetMethod(EPS eps, EPSPRIMMEMethod method);
377: extern PetscErrorCode EPSPRIMMEGetBlockSize(EPS eps,PetscInt *bs);
378: extern PetscErrorCode EPSPRIMMEGetMethod(EPS eps, EPSPRIMMEMethod *method);

380: extern PetscErrorCode EPSGDSetKrylovStart(EPS eps,PetscBool krylovstart);
381: extern PetscErrorCode EPSGDGetKrylovStart(EPS eps,PetscBool *krylovstart);
382: extern PetscErrorCode EPSGDSetBlockSize(EPS eps,PetscInt blocksize);
383: extern PetscErrorCode EPSGDGetBlockSize(EPS eps,PetscInt *blocksize);
384: extern PetscErrorCode EPSGDSetRestart(EPS eps,PetscInt minv,PetscInt plusk);
385: extern PetscErrorCode EPSGDGetRestart(EPS eps,PetscInt *minv,PetscInt *plusk);
386: extern PetscErrorCode EPSGDSetInitialSize(EPS eps,PetscInt initialsize);
387: extern PetscErrorCode EPSGDGetInitialSize(EPS eps,PetscInt *initialsize);
388: extern PetscErrorCode EPSGDSetBOrth(EPS eps,PetscBool borth);
389: extern PetscErrorCode EPSGDGetBOrth(EPS eps,PetscBool *borth);
390: extern PetscErrorCode EPSGDGetWindowSizes(EPS eps,PetscInt *pwindow,PetscInt *qwindow);
391: extern PetscErrorCode EPSGDSetWindowSizes(EPS eps,PetscInt pwindow,PetscInt qwindow);

393: extern PetscErrorCode EPSJDSetKrylovStart(EPS eps,PetscBool krylovstart);
394: extern PetscErrorCode EPSJDGetKrylovStart(EPS eps,PetscBool *krylovstart);
395: extern PetscErrorCode EPSJDSetBlockSize(EPS eps,PetscInt blocksize);
396: extern PetscErrorCode EPSJDGetBlockSize(EPS eps,PetscInt *blocksize);
397: extern PetscErrorCode EPSJDSetRestart(EPS eps,PetscInt minv,PetscInt plusk);
398: extern PetscErrorCode EPSJDGetRestart(EPS eps,PetscInt *minv,PetscInt *plusk);
399: extern PetscErrorCode EPSJDSetInitialSize(EPS eps,PetscInt initialsize);
400: extern PetscErrorCode EPSJDGetInitialSize(EPS eps,PetscInt *initialsize);
401: extern PetscErrorCode EPSJDSetFix(EPS eps,PetscReal fix);
402: extern PetscErrorCode EPSJDGetFix(EPS eps,PetscReal *fix);
403: extern PetscErrorCode EPSJDSetConstantCorrectionTolerance(EPS eps,PetscBool dynamic);
404: extern PetscErrorCode EPSJDGetConstantCorrectionTolerance(EPS eps,PetscBool *dynamic);
405: extern PetscErrorCode EPSJDGetWindowSizes(EPS eps,PetscInt *pwindow,PetscInt *qwindow);
406: extern PetscErrorCode EPSJDSetWindowSizes(EPS eps,PetscInt pwindow,PetscInt qwindow);

408: PETSC_EXTERN_CXX_END
409: #endif