Actual source code: slepceps.h

  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-, 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 the SLEPc linear eigenvalue solvers
 12: */

 14: #pragma once

 16: #include <slepcst.h>
 17: #include <slepcbv.h>
 18: #include <slepcds.h>
 19: #include <slepcrg.h>
 20: #include <slepclme.h>
 21: #include <petscsnes.h>

 23: /* SUBMANSEC = EPS */

 25: SLEPC_EXTERN PetscErrorCode EPSInitializePackage(void);
 26: SLEPC_EXTERN PetscErrorCode EPSFinalizePackage(void);

 28: /*S
 29:     EPS - Abstract SLEPc object that manages all the eigenvalue
 30:     problem solvers.

 32:     Level: beginner

 34: .seealso:  EPSCreate(), ST
 35: S*/
 36: typedef struct _p_EPS* EPS;

 38: /*J
 39:     EPSType - String with the name of a SLEPc eigensolver

 41:     Level: beginner

 43: .seealso: EPSSetType(), EPS
 44: J*/
 45: typedef const char *EPSType;
 46: #define EPSPOWER       "power"
 47: #define EPSSUBSPACE    "subspace"
 48: #define EPSARNOLDI     "arnoldi"
 49: #define EPSLANCZOS     "lanczos"
 50: #define EPSKRYLOVSCHUR "krylovschur"
 51: #define EPSGD          "gd"
 52: #define EPSJD          "jd"
 53: #define EPSRQCG        "rqcg"
 54: #define EPSLOBPCG      "lobpcg"
 55: #define EPSCISS        "ciss"
 56: #define EPSLYAPII      "lyapii"
 57: #define EPSLAPACK      "lapack"
 58: #define EPSARPACK      "arpack"
 59: #define EPSBLOPEX      "blopex"
 60: #define EPSPRIMME      "primme"
 61: #define EPSFEAST       "feast"
 62: #define EPSSCALAPACK   "scalapack"
 63: #define EPSELPA        "elpa"
 64: #define EPSELEMENTAL   "elemental"
 65: #define EPSEVSL        "evsl"
 66: #define EPSCHASE       "chase"

 68: /* Logging support */
 69: SLEPC_EXTERN PetscClassId EPS_CLASSID;

 71: /*E
 72:     EPSProblemType - Determines the type of eigenvalue problem

 74:     Level: beginner

 76: .seealso: EPSSetProblemType(), EPSGetProblemType()
 77: E*/
 78: typedef enum { EPS_HEP    = 1,
 79:                EPS_GHEP   = 2,
 80:                EPS_NHEP   = 3,
 81:                EPS_GNHEP  = 4,
 82:                EPS_PGNHEP = 5,
 83:                EPS_GHIEP  = 6,
 84:                EPS_BSE    = 7,
 85:                EPS_HAMILT = 8 } EPSProblemType;

 87: /*E
 88:     EPSExtraction - Determines the type of extraction technique employed
 89:     by the eigensolver

 91:     Level: advanced

 93: .seealso: EPSSetExtraction(), EPSGetExtraction()
 94: E*/
 95: typedef enum { EPS_RITZ,
 96:                EPS_HARMONIC,
 97:                EPS_HARMONIC_RELATIVE,
 98:                EPS_HARMONIC_RIGHT,
 99:                EPS_HARMONIC_LARGEST,
100:                EPS_REFINED,
101:                EPS_REFINED_HARMONIC } EPSExtraction;

103: /*E
104:     EPSWhich - Determines which part of the spectrum is requested

106:     Level: intermediate

108: .seealso: EPSSetWhichEigenpairs(), EPSGetWhichEigenpairs()
109: E*/
110: typedef enum { EPS_LARGEST_MAGNITUDE  = 1,
111:                EPS_SMALLEST_MAGNITUDE = 2,
112:                EPS_LARGEST_REAL       = 3,
113:                EPS_SMALLEST_REAL      = 4,
114:                EPS_LARGEST_IMAGINARY  = 5,
115:                EPS_SMALLEST_IMAGINARY = 6,
116:                EPS_TARGET_MAGNITUDE   = 7,
117:                EPS_TARGET_REAL        = 8,
118:                EPS_TARGET_IMAGINARY   = 9,
119:                EPS_ALL                = 10,
120:                EPS_WHICH_USER         = 11 } EPSWhich;

122: /*E
123:     EPSBalance - The type of balancing used for non-Hermitian problems

125:     Level: intermediate

127: .seealso: EPSSetBalance()
128: E*/
129: typedef enum { EPS_BALANCE_NONE,
130:                EPS_BALANCE_ONESIDE,
131:                EPS_BALANCE_TWOSIDE,
132:                EPS_BALANCE_USER } EPSBalance;
133: SLEPC_EXTERN const char *EPSBalanceTypes[];

135: /*E
136:     EPSErrorType - The error type used to assess accuracy of computed solutions

138:     Level: intermediate

140: .seealso: EPSComputeError()
141: E*/
142: typedef enum { EPS_ERROR_ABSOLUTE,
143:                EPS_ERROR_RELATIVE,
144:                EPS_ERROR_BACKWARD } EPSErrorType;
145: SLEPC_EXTERN const char *EPSErrorTypes[];

147: /*E
148:     EPSConv - Determines the convergence test

150:     Level: intermediate

152: .seealso: EPSSetConvergenceTest(), EPSSetConvergenceTestFunction()
153: E*/
154: typedef enum { EPS_CONV_ABS,
155:                EPS_CONV_REL,
156:                EPS_CONV_NORM,
157:                EPS_CONV_USER } EPSConv;

159: /*E
160:     EPSStop - Determines the stopping test

162:     Level: advanced

164: .seealso: EPSSetStoppingTest(), EPSSetStoppingTestFunction()
165: E*/
166: typedef enum { EPS_STOP_BASIC,
167:                EPS_STOP_USER,
168:                EPS_STOP_THRESHOLD } EPSStop;

170: /*E
171:     EPSConvergedReason - Reason an eigensolver was said to
172:          have converged or diverged

174:     Level: intermediate

176: .seealso: EPSSolve(), EPSGetConvergedReason(), EPSSetTolerances()
177: E*/
178: typedef enum {/* converged */
179:               EPS_CONVERGED_TOL                =  1,
180:               EPS_CONVERGED_USER               =  2,
181:               /* diverged */
182:               EPS_DIVERGED_ITS                 = -1,
183:               EPS_DIVERGED_BREAKDOWN           = -2,
184:               EPS_DIVERGED_SYMMETRY_LOST       = -3,
185:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;
186: SLEPC_EXTERN const char *const*EPSConvergedReasons;

188: /*S
189:    EPSStoppingCtx - Data structure (C struct) to hold additional information to
190:    be used in some stopping test functions.

192:    Level: advanced

194: .seealso: EPSSetStoppingTestFunction()
195: S*/
196: struct _n_EPSStoppingCtx {
197:   PetscReal firstev;    /* the (absolute) value of the first converged eigenvalue */
198:   PetscReal lastev;     /* the (absolute) value of the last converged eigenvalue */
199:   PetscReal thres;      /* threshold set with EPSSetThreshold() */
200:   PetscBool threlative; /* threshold is relative */
201:   EPSWhich  which;      /* which eigenvalues are being computed */
202: };
203: typedef struct _n_EPSStoppingCtx* EPSStoppingCtx;

205: SLEPC_EXTERN PetscErrorCode EPSCreate(MPI_Comm,EPS*);
206: SLEPC_EXTERN PetscErrorCode EPSDestroy(EPS*);
207: SLEPC_EXTERN PetscErrorCode EPSReset(EPS);
208: SLEPC_EXTERN PetscErrorCode EPSSetType(EPS,EPSType);
209: SLEPC_EXTERN PetscErrorCode EPSGetType(EPS,EPSType*);
210: SLEPC_EXTERN PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
211: SLEPC_EXTERN PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
212: SLEPC_EXTERN PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);
213: SLEPC_EXTERN PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);
214: SLEPC_EXTERN PetscErrorCode EPSSetBalance(EPS,EPSBalance,PetscInt,PetscReal);
215: SLEPC_EXTERN PetscErrorCode EPSGetBalance(EPS,EPSBalance*,PetscInt*,PetscReal*);
216: SLEPC_EXTERN PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
217: SLEPC_EXTERN PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);
218: SLEPC_EXTERN PetscErrorCode EPSSetFromOptions(EPS);
219: SLEPC_EXTERN PetscErrorCode EPSSetDSType(EPS);
220: SLEPC_EXTERN PetscErrorCode EPSSetUp(EPS);
221: SLEPC_EXTERN PetscErrorCode EPSSolve(EPS);
222: SLEPC_EXTERN PetscErrorCode EPSView(EPS,PetscViewer);
223: SLEPC_EXTERN PetscErrorCode EPSViewFromOptions(EPS,PetscObject,const char[]);
224: SLEPC_EXTERN PetscErrorCode EPSErrorView(EPS,EPSErrorType,PetscViewer);
225: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSErrorView()", ) static inline PetscErrorCode EPSPrintSolution(EPS eps,PetscViewer v) {return EPSErrorView(eps,EPS_ERROR_RELATIVE,v);}
226: SLEPC_EXTERN PetscErrorCode EPSErrorViewFromOptions(EPS);
227: SLEPC_EXTERN PetscErrorCode EPSConvergedReasonView(EPS,PetscViewer);
228: SLEPC_EXTERN PetscErrorCode EPSConvergedReasonViewFromOptions(EPS);
229: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "EPSConvergedReasonView()", ) static inline PetscErrorCode EPSReasonView(EPS eps,PetscViewer v) {return EPSConvergedReasonView(eps,v);}
230: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "EPSConvergedReasonViewFromOptions()", ) static inline PetscErrorCode EPSReasonViewFromOptions(EPS eps) {return EPSConvergedReasonViewFromOptions(eps);}
231: SLEPC_EXTERN PetscErrorCode EPSValuesView(EPS,PetscViewer);
232: SLEPC_EXTERN PetscErrorCode EPSValuesViewFromOptions(EPS);
233: SLEPC_EXTERN PetscErrorCode EPSVectorsView(EPS,PetscViewer);
234: SLEPC_EXTERN PetscErrorCode EPSVectorsViewFromOptions(EPS);

236: SLEPC_EXTERN PetscErrorCode EPSSetTarget(EPS,PetscScalar);
237: SLEPC_EXTERN PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
238: SLEPC_EXTERN PetscErrorCode EPSSetInterval(EPS,PetscReal,PetscReal);
239: SLEPC_EXTERN PetscErrorCode EPSGetInterval(EPS,PetscReal*,PetscReal*);
240: SLEPC_EXTERN PetscErrorCode EPSSetST(EPS,ST);
241: SLEPC_EXTERN PetscErrorCode EPSGetST(EPS,ST*);
242: SLEPC_EXTERN PetscErrorCode EPSSetBV(EPS,BV);
243: SLEPC_EXTERN PetscErrorCode EPSGetBV(EPS,BV*);
244: SLEPC_EXTERN PetscErrorCode EPSSetRG(EPS,RG);
245: SLEPC_EXTERN PetscErrorCode EPSGetRG(EPS,RG*);
246: SLEPC_EXTERN PetscErrorCode EPSSetDS(EPS,DS);
247: SLEPC_EXTERN PetscErrorCode EPSGetDS(EPS,DS*);
248: SLEPC_EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
249: SLEPC_EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
250: SLEPC_EXTERN PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
251: SLEPC_EXTERN PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

253: SLEPC_EXTERN PetscErrorCode EPSGetConvergedReason(EPS,EPSConvergedReason*);

255: SLEPC_EXTERN PetscErrorCode EPSGetConverged(EPS,PetscInt*);
256: SLEPC_EXTERN PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
257: SLEPC_EXTERN PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);
258: SLEPC_EXTERN PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);
259: SLEPC_EXTERN PetscErrorCode EPSGetLeftEigenvector(EPS,PetscInt,Vec,Vec);

261: SLEPC_EXTERN PetscErrorCode EPSComputeError(EPS,PetscInt,EPSErrorType,PetscReal*);
262: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSComputeError()", ) static inline PetscErrorCode EPSComputeRelativeError(EPS eps,PetscInt i,PetscReal *r) {return EPSComputeError(eps,i,EPS_ERROR_RELATIVE,r);}
263: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSComputeError() with EPS_ERROR_ABSOLUTE", ) static inline PetscErrorCode EPSComputeResidualNorm(EPS eps,PetscInt i,PetscReal *r) {return EPSComputeError(eps,i,EPS_ERROR_ABSOLUTE,r);}
264: SLEPC_EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec[]);
265: SLEPC_EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
266: SLEPC_EXTERN PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);

268: SLEPC_EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
269: SLEPC_EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
270: SLEPC_EXTERN PetscErrorCode EPSSetThreshold(EPS,PetscReal,PetscBool);
271: SLEPC_EXTERN PetscErrorCode EPSGetThreshold(EPS,PetscReal*,PetscBool*);
272: SLEPC_EXTERN PetscErrorCode EPSSetTwoSided(EPS,PetscBool);
273: SLEPC_EXTERN PetscErrorCode EPSGetTwoSided(EPS,PetscBool*);
274: SLEPC_EXTERN PetscErrorCode EPSSetTrueResidual(EPS,PetscBool);
275: SLEPC_EXTERN PetscErrorCode EPSGetTrueResidual(EPS,PetscBool*);
276: SLEPC_EXTERN PetscErrorCode EPSSetPurify(EPS,PetscBool);
277: SLEPC_EXTERN PetscErrorCode EPSGetPurify(EPS,PetscBool*);
278: SLEPC_EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscBool*);
279: SLEPC_EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscBool*);
280: SLEPC_EXTERN PetscErrorCode EPSIsPositive(EPS,PetscBool*);
281: SLEPC_EXTERN PetscErrorCode EPSIsStructured(EPS,PetscBool*);

283: SLEPC_EXTERN PetscErrorCode EPSSetTrackAll(EPS,PetscBool);
284: SLEPC_EXTERN PetscErrorCode EPSGetTrackAll(EPS,PetscBool*);

286: SLEPC_EXTERN PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec[]);
287: SLEPC_EXTERN PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec[]);
288: SLEPC_EXTERN PetscErrorCode EPSSetLeftInitialSpace(EPS,PetscInt,Vec[]);

290: /*S
291:   EPSMonitorFn - A function prototype for functions provided to EPSMonitorSet()

293:   Calling Sequence:
294: +   eps    - eigensolver context obtained from EPSCreate()
295: .   its    - iteration number
296: .   nconv  - number of converged eigenpairs
297: .   eigr   - real part of the eigenvalues
298: .   eigi   - imaginary part of the eigenvalues
299: .   errest - relative error estimates for each eigenpair
300: .   nest   - number of error estimates
301: -   ctx    - optional monitoring context, as provided with EPSMonitorSet()

303:   Level: beginner

305: .seealso: EPSMonitorSet()
306: S*/
307: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar *eigr,PetscScalar *eigi,PetscReal *errest,PetscInt nest,void *ctx);

309: /*S
310:   EPSMonitorRegisterFn - A function prototype for functions provided to EPSMonitorRegister()

312:   Calling Sequence:
313: +   eps    - eigensolver context obtained from EPSCreate()
314: .   its    - iteration number
315: .   nconv  - number of converged eigenpairs
316: .   eigr   - real part of the eigenvalues
317: .   eigi   - imaginary part of the eigenvalues
318: .   errest - relative error estimates for each eigenpair
319: .   nest   - number of error estimates
320: -   ctx    - PetscViewerAndFormat object

322:   Level: beginner

324:   Note:
325:   This is an EPSMonitorFn specialized for a context of PetscViewerAndFormat.

327: .seealso: EPSMonitorSet(), EPSMonitorRegister(), EPSMonitorFn, EPSMonitorRegisterCreateFn, EPSMonitorRegisterDestroyFn
328: S*/
329: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar *eigr,PetscScalar *eigi,PetscReal *errest,PetscInt nest,PetscViewerAndFormat *ctx);

331: /*S
332:   EPSMonitorRegisterCreateFn - A function prototype for functions that do the creation when provided to EPSMonitorRegister()

334:   Calling Sequence:
335: +   viewer - the viewer to be used with the EPSMonitorRegisterFn
336: .   format - the format of the viewer
337: .   ctx    - a context for the monitor
338: -   result - a PetscViewerAndFormat object

340:   Level: beginner

342: .seealso: EPSMonitorRegisterFn, EPSMonitorSet(), EPSMonitorRegister(), EPSMonitorFn, EPSMonitorRegisterDestroyFn
343: S*/
344: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);

346: /*S
347:   EPSMonitorRegisterDestroyFn - A function prototype for functions that do the after use destruction when provided to EPSMonitorRegister()

349:   Calling Sequence:
350: .   vf - a PetscViewerAndFormat object to be destroyed, including any context

352:   Level: beginner

354: .seealso: EPSMonitorRegisterFn, EPSMonitorSet(), EPSMonitorRegister(), EPSMonitorFn, EPSMonitorRegisterCreateFn
355: S*/
356: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterDestroyFn(PetscViewerAndFormat **result);

358: SLEPC_EXTERN PetscErrorCode EPSMonitor(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt);
359: SLEPC_EXTERN PetscErrorCode EPSMonitorSet(EPS,EPSMonitorFn,void*,PetscCtxDestroyFn*);
360: SLEPC_EXTERN PetscErrorCode EPSMonitorCancel(EPS);
361: SLEPC_EXTERN PetscErrorCode EPSGetMonitorContext(EPS,void*);

363: SLEPC_EXTERN PetscErrorCode EPSMonitorSetFromOptions(EPS,const char[],const char[],void*,PetscBool);
364: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorFirst;
365: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorFirstDrawLG;
366: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorFirstDrawLGCreate;
367: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorAll;
368: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorAllDrawLG;
369: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorAllDrawLGCreate;
370: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorConverged;
371: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorConvergedCreate;
372: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorConvergedDrawLG;
373: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorConvergedDrawLGCreate;
374: SLEPC_EXTERN EPSMonitorRegisterDestroyFn EPSMonitorConvergedDestroy;

376: SLEPC_EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char*);
377: SLEPC_EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char*);
378: SLEPC_EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

380: SLEPC_EXTERN PetscFunctionList EPSList;
381: SLEPC_EXTERN PetscFunctionList EPSMonitorList;
382: SLEPC_EXTERN PetscFunctionList EPSMonitorCreateList;
383: SLEPC_EXTERN PetscFunctionList EPSMonitorDestroyList;
384: SLEPC_EXTERN PetscErrorCode EPSRegister(const char[],PetscErrorCode(*)(EPS));
385: SLEPC_EXTERN PetscErrorCode EPSMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,EPSMonitorRegisterFn*,EPSMonitorRegisterCreateFn*,EPSMonitorRegisterDestroyFn*);

387: SLEPC_EXTERN PetscErrorCode EPSSetWorkVecs(EPS,PetscInt);
388: SLEPC_EXTERN PetscErrorCode EPSAllocateSolution(EPS,PetscInt);
389: SLEPC_EXTERN PetscErrorCode EPSReallocateSolution(EPS,PetscInt);

391: /*S
392:   EPSConvergenceTestFn - A prototype of an EPS convergence test function that would be passed to EPSSetConvergenceTestFunction()

394:   Calling Sequence:
395: +   eps    - eigensolver context obtained from EPSCreate()
396: .   eigr   - real part of the eigenvalue
397: .   eigi   - imaginary part of the eigenvalue
398: .   res    - residual norm associated to the eigenpair
399: .   errest - [output] computed error estimate
400: -   ctx    - [optional] user-defined context for private data for the
401:              convergence test routine (may be NULL)

403:   Level: advanced

405: .seealso: EPSSetConvergenceTestFunction()
406: S*/
407: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSConvergenceTestFn(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx);

409: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTest(EPS,EPSConv);
410: SLEPC_EXTERN PetscErrorCode EPSGetConvergenceTest(EPS,EPSConv*);
411: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedAbsolute;
412: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedRelative;
413: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedNorm;
414: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTestFunction(EPS,EPSConvergenceTestFn*,void*,PetscCtxDestroyFn*);

416: /*S
417:   EPSStoppingTestFn - A prototype of an EPS stopping test function that would be passed to EPSSetStoppingTestFunction()

419:   Calling Sequence:
420: +   eps    - eigensolver context obtained from EPSCreate()
421: .   its    - current number of iterations
422: .   max_it - maximum number of iterations
423: .   nconv  - number of currently converged eigenpairs
424: .   nev    - number of requested eigenpairs
425: .   reason - [output] result of the stopping test
426: -   ctx    - [optional] user-defined context for private data for the
427:              stopping test routine (may be NULL)

429:   Level: advanced

431: .seealso: EPSSetStoppingTestFunction()
432: S*/
433: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSStoppingTestFn(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx);

435: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTest(EPS,EPSStop);
436: SLEPC_EXTERN PetscErrorCode EPSGetStoppingTest(EPS,EPSStop*);
437: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingBasic;
438: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingThreshold;
439: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTestFunction(EPS,EPSStoppingTestFn*,void*,PetscCtxDestroyFn*);

441: SLEPC_EXTERN PetscErrorCode EPSSetEigenvalueComparison(EPS,SlepcEigenvalueComparisonFn*,void*);
442: SLEPC_EXTERN PetscErrorCode EPSSetArbitrarySelection(EPS,SlepcArbitrarySelectionFn*,void*);

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

446: /*E
447:     EPSPowerShiftType - determines the type of shift used in the Power iteration

449:     Level: advanced

451: .seealso: EPSPowerSetShiftType(), EPSPowerGetShiftType()
452: E*/
453: typedef enum { EPS_POWER_SHIFT_CONSTANT,
454:                EPS_POWER_SHIFT_RAYLEIGH,
455:                EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;
456: SLEPC_EXTERN const char *EPSPowerShiftTypes[];

458: SLEPC_EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
459: SLEPC_EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);
460: SLEPC_EXTERN PetscErrorCode EPSPowerSetNonlinear(EPS,PetscBool);
461: SLEPC_EXTERN PetscErrorCode EPSPowerGetNonlinear(EPS,PetscBool*);
462: SLEPC_EXTERN PetscErrorCode EPSPowerSetUpdate(EPS,PetscBool);
463: SLEPC_EXTERN PetscErrorCode EPSPowerGetUpdate(EPS,PetscBool*);
464: SLEPC_EXTERN PetscErrorCode EPSPowerSetSignNormalization(EPS,PetscBool);
465: SLEPC_EXTERN PetscErrorCode EPSPowerGetSignNormalization(EPS,PetscBool*);
466: SLEPC_EXTERN PetscErrorCode EPSPowerSetSNES(EPS,SNES);
467: SLEPC_EXTERN PetscErrorCode EPSPowerGetSNES(EPS,SNES*);

469: SLEPC_EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscBool);
470: SLEPC_EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscBool*);

472: /*E
473:     EPSKrylovSchurBSEType - the method to be used in the Krylov-Schur solver
474:     for the case of BSE structured eigenproblems

476:     Level: advanced

478: .seealso: EPSKrylovSchurSetBSEType(), EPSKrylovSchurGetBSEType()
479: E*/
480: typedef enum { EPS_KRYLOVSCHUR_BSE_SHAO,
481:                EPS_KRYLOVSCHUR_BSE_GRUNING,
482:                EPS_KRYLOVSCHUR_BSE_PROJECTEDBSE } EPSKrylovSchurBSEType;
483: SLEPC_EXTERN const char *EPSKrylovSchurBSETypes[];

485: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetBSEType(EPS,EPSKrylovSchurBSEType);
486: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetBSEType(EPS,EPSKrylovSchurBSEType*);
487: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetRestart(EPS,PetscReal);
488: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetRestart(EPS,PetscReal*);
489: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetLocking(EPS,PetscBool);
490: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetLocking(EPS,PetscBool*);
491: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetPartitions(EPS,PetscInt);
492: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetPartitions(EPS,PetscInt*);
493: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDetectZeros(EPS,PetscBool);
494: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDetectZeros(EPS,PetscBool*);
495: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
496: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);
497: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetSubintervals(EPS,PetscReal*);
498: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubintervals(EPS,PetscReal*[]);
499: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetInertias(EPS,PetscInt*,PetscReal*[],PetscInt*[]);
500: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommInfo(EPS,PetscInt*,PetscInt*,Vec*);
501: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommPairs(EPS,PetscInt,PetscScalar*,Vec);
502: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommMats(EPS,Mat*,Mat*);
503: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurUpdateSubcommMats(EPS,PetscScalar,PetscScalar,Mat,PetscScalar,PetscScalar, Mat,MatStructure,PetscBool);
504: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetKSP(EPS,KSP*);

506: /*E
507:     EPSLanczosReorthogType - determines the type of reorthogonalization
508:     used in the Lanczos method

510:     Level: advanced

512: .seealso: EPSLanczosSetReorthog(), EPSLanczosGetReorthog()
513: E*/
514: typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,
515:                EPS_LANCZOS_REORTHOG_FULL,
516:                EPS_LANCZOS_REORTHOG_SELECTIVE,
517:                EPS_LANCZOS_REORTHOG_PERIODIC,
518:                EPS_LANCZOS_REORTHOG_PARTIAL,
519:                EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;
520: SLEPC_EXTERN const char *EPSLanczosReorthogTypes[];

522: SLEPC_EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
523: SLEPC_EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

525: /*E
526:     EPSPRIMMEMethod - determines the method selected in the PRIMME library

528:     Level: advanced

530: .seealso: EPSPRIMMESetMethod(), EPSPRIMMEGetMethod()
531: E*/
532: typedef enum { EPS_PRIMME_DYNAMIC             = 1,
533:                EPS_PRIMME_DEFAULT_MIN_TIME    = 2,
534:                EPS_PRIMME_DEFAULT_MIN_MATVECS = 3,
535:                EPS_PRIMME_ARNOLDI             = 4,
536:                EPS_PRIMME_GD                  = 5,
537:                EPS_PRIMME_GD_PLUSK            = 6,
538:                EPS_PRIMME_GD_OLSEN_PLUSK      = 7,
539:                EPS_PRIMME_JD_OLSEN_PLUSK      = 8,
540:                EPS_PRIMME_RQI                 = 9,
541:                EPS_PRIMME_JDQR                = 10,
542:                EPS_PRIMME_JDQMR               = 11,
543:                EPS_PRIMME_JDQMR_ETOL          = 12,
544:                EPS_PRIMME_SUBSPACE_ITERATION  = 13,
545:                EPS_PRIMME_LOBPCG_ORTHOBASIS   = 14,
546:                EPS_PRIMME_LOBPCG_ORTHOBASISW  = 15 } EPSPRIMMEMethod;
547: SLEPC_EXTERN const char *EPSPRIMMEMethods[];

549: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS,PetscInt);
550: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS,PetscInt*);
551: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS,EPSPRIMMEMethod);
552: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS,EPSPRIMMEMethod*);

554: SLEPC_EXTERN PetscErrorCode EPSGDSetKrylovStart(EPS,PetscBool);
555: SLEPC_EXTERN PetscErrorCode EPSGDGetKrylovStart(EPS,PetscBool*);
556: SLEPC_EXTERN PetscErrorCode EPSGDSetBlockSize(EPS,PetscInt);
557: SLEPC_EXTERN PetscErrorCode EPSGDGetBlockSize(EPS,PetscInt*);
558: SLEPC_EXTERN PetscErrorCode EPSGDSetRestart(EPS,PetscInt,PetscInt);
559: SLEPC_EXTERN PetscErrorCode EPSGDGetRestart(EPS,PetscInt*,PetscInt*);
560: SLEPC_EXTERN PetscErrorCode EPSGDSetInitialSize(EPS,PetscInt);
561: SLEPC_EXTERN PetscErrorCode EPSGDGetInitialSize(EPS,PetscInt*);
562: SLEPC_EXTERN PetscErrorCode EPSGDSetBOrth(EPS,PetscBool);
563: SLEPC_EXTERN PetscErrorCode EPSGDGetBOrth(EPS,PetscBool*);
564: SLEPC_EXTERN PetscErrorCode EPSGDSetDoubleExpansion(EPS,PetscBool);
565: SLEPC_EXTERN PetscErrorCode EPSGDGetDoubleExpansion(EPS,PetscBool*);

567: SLEPC_EXTERN PetscErrorCode EPSJDSetKrylovStart(EPS,PetscBool);
568: SLEPC_EXTERN PetscErrorCode EPSJDGetKrylovStart(EPS,PetscBool*);
569: SLEPC_EXTERN PetscErrorCode EPSJDSetBlockSize(EPS,PetscInt);
570: SLEPC_EXTERN PetscErrorCode EPSJDGetBlockSize(EPS,PetscInt*);
571: SLEPC_EXTERN PetscErrorCode EPSJDSetRestart(EPS,PetscInt,PetscInt);
572: SLEPC_EXTERN PetscErrorCode EPSJDGetRestart(EPS,PetscInt*,PetscInt*);
573: SLEPC_EXTERN PetscErrorCode EPSJDSetInitialSize(EPS,PetscInt);
574: SLEPC_EXTERN PetscErrorCode EPSJDGetInitialSize(EPS,PetscInt*);
575: SLEPC_EXTERN PetscErrorCode EPSJDSetFix(EPS,PetscReal);
576: SLEPC_EXTERN PetscErrorCode EPSJDGetFix(EPS,PetscReal*);
577: SLEPC_EXTERN PetscErrorCode EPSJDSetConstCorrectionTol(EPS,PetscBool);
578: SLEPC_EXTERN PetscErrorCode EPSJDGetConstCorrectionTol(EPS,PetscBool*);
579: SLEPC_EXTERN PetscErrorCode EPSJDSetBOrth(EPS,PetscBool);
580: SLEPC_EXTERN PetscErrorCode EPSJDGetBOrth(EPS,PetscBool*);

582: SLEPC_EXTERN PetscErrorCode EPSRQCGSetReset(EPS,PetscInt);
583: SLEPC_EXTERN PetscErrorCode EPSRQCGGetReset(EPS,PetscInt*);

585: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetBlockSize(EPS,PetscInt);
586: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetBlockSize(EPS,PetscInt*);
587: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetRestart(EPS,PetscReal);
588: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetRestart(EPS,PetscReal*);
589: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetLocking(EPS,PetscBool);
590: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetLocking(EPS,PetscBool*);

592: /*E
593:     EPSCISSQuadRule - determines the quadrature rule in the CISS solver

595:     Level: advanced

597: .seealso: EPSCISSSetQuadRule(), EPSCISSGetQuadRule()
598: E*/
599: typedef enum { EPS_CISS_QUADRULE_TRAPEZOIDAL = 1,
600:                EPS_CISS_QUADRULE_CHEBYSHEV   = 2 } EPSCISSQuadRule;
601: SLEPC_EXTERN const char *EPSCISSQuadRules[];

603: /*E
604:     EPSCISSExtraction - determines the extraction technique in the CISS solver

606:     Level: advanced

608: .seealso: EPSCISSSetExtraction(), EPSCISSGetExtraction()
609: E*/
610: typedef enum { EPS_CISS_EXTRACTION_RITZ,
611:                EPS_CISS_EXTRACTION_HANKEL } EPSCISSExtraction;
612: SLEPC_EXTERN const char *EPSCISSExtractions[];

614: SLEPC_EXTERN PetscErrorCode EPSCISSSetExtraction(EPS,EPSCISSExtraction);
615: SLEPC_EXTERN PetscErrorCode EPSCISSGetExtraction(EPS,EPSCISSExtraction*);
616: SLEPC_EXTERN PetscErrorCode EPSCISSSetQuadRule(EPS,EPSCISSQuadRule);
617: SLEPC_EXTERN PetscErrorCode EPSCISSGetQuadRule(EPS,EPSCISSQuadRule*);
618: SLEPC_EXTERN PetscErrorCode EPSCISSSetSizes(EPS,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscBool);
619: SLEPC_EXTERN PetscErrorCode EPSCISSGetSizes(EPS,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscBool*);
620: SLEPC_EXTERN PetscErrorCode EPSCISSSetThreshold(EPS,PetscReal,PetscReal);
621: SLEPC_EXTERN PetscErrorCode EPSCISSGetThreshold(EPS,PetscReal*,PetscReal*);
622: SLEPC_EXTERN PetscErrorCode EPSCISSSetRefinement(EPS,PetscInt,PetscInt);
623: SLEPC_EXTERN PetscErrorCode EPSCISSGetRefinement(EPS,PetscInt*,PetscInt*);
624: SLEPC_EXTERN PetscErrorCode EPSCISSSetUseST(EPS,PetscBool);
625: SLEPC_EXTERN PetscErrorCode EPSCISSGetUseST(EPS,PetscBool*);
626: SLEPC_EXTERN PetscErrorCode EPSCISSGetKSPs(EPS,PetscInt*,KSP*[]);

628: SLEPC_EXTERN PetscErrorCode EPSLyapIISetLME(EPS,LME);
629: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetLME(EPS,LME*);
630: SLEPC_EXTERN PetscErrorCode EPSLyapIISetRanks(EPS,PetscInt,PetscInt);
631: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetRanks(EPS,PetscInt*,PetscInt*);

633: SLEPC_EXTERN PetscErrorCode EPSBLOPEXSetBlockSize(EPS,PetscInt);
634: SLEPC_EXTERN PetscErrorCode EPSBLOPEXGetBlockSize(EPS,PetscInt*);

636: /*E
637:     EPSEVSLDOSMethod - the method to approximate the density of states (DOS) in the EVSL solver

639:     Level: advanced

641: .seealso: EPSEVSLSetDOSParameters(), EPSEVSLGetDOSParameters()
642: E*/
643: typedef enum { EPS_EVSL_DOS_KPM,
644:                EPS_EVSL_DOS_LANCZOS } EPSEVSLDOSMethod;
645: SLEPC_EXTERN const char *EPSEVSLDOSMethods[];

647: /*E
648:     EPSEVSLDamping - the damping type used in the EVSL solver

650:     Level: advanced

652: .seealso: EPSEVSLSetDOSParameters(), EPSEVSLGetDOSParameters()
653: E*/
654: typedef enum { EPS_EVSL_DAMPING_NONE,
655:                EPS_EVSL_DAMPING_JACKSON,
656:                EPS_EVSL_DAMPING_SIGMA } EPSEVSLDamping;
657: SLEPC_EXTERN const char *EPSEVSLDampings[];

659: SLEPC_EXTERN PetscErrorCode EPSEVSLSetRange(EPS,PetscReal,PetscReal);
660: SLEPC_EXTERN PetscErrorCode EPSEVSLGetRange(EPS,PetscReal*,PetscReal*);
661: SLEPC_EXTERN PetscErrorCode EPSEVSLSetSlices(EPS,PetscInt);
662: SLEPC_EXTERN PetscErrorCode EPSEVSLGetSlices(EPS,PetscInt*);
663: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDOSParameters(EPS,EPSEVSLDOSMethod,PetscInt,PetscInt,PetscInt,PetscInt);
664: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDOSParameters(EPS,EPSEVSLDOSMethod*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
665: SLEPC_EXTERN PetscErrorCode EPSEVSLSetPolParameters(EPS,PetscInt,PetscReal);
666: SLEPC_EXTERN PetscErrorCode EPSEVSLGetPolParameters(EPS,PetscInt*,PetscReal*);
667: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDamping(EPS,EPSEVSLDamping);
668: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDamping(EPS,EPSEVSLDamping*);

670: SLEPC_EXTERN PetscErrorCode EPSFEASTSetNumPoints(EPS,PetscInt);
671: SLEPC_EXTERN PetscErrorCode EPSFEASTGetNumPoints(EPS,PetscInt*);

673: SLEPC_EXTERN PetscErrorCode EPSCHASESetDegree(EPS,PetscInt,PetscBool);
674: SLEPC_EXTERN PetscErrorCode EPSCHASEGetDegree(EPS,PetscInt*,PetscBool*);