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 - SLEPc object that manages all the eigenvalue problem solvers.

 31:    Level: beginner

 33: .seealso: [](ch:eps), `EPSCreate()`, `ST`
 34: S*/
 35: typedef struct _p_EPS* EPS;

 37: /*J
 38:    EPSType - String with the name of a linear eigensolver.

 40:    Level: beginner

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

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

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

 73:    Level: beginner

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

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

 90:    Level: advanced

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

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

105:    Level: intermediate

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

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

124:    Level: intermediate

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

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

137:    Level: intermediate

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

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

149:    Level: intermediate

151: .seealso: [](ch:eps), `EPSSetConvergenceTest()`, `EPSSetConvergenceTestFunction()`
152: E*/
153: typedef enum { EPS_CONV_ABS,
154:                EPS_CONV_REL,
155:                EPS_CONV_NORM,
156:                EPS_CONV_USER } EPSConv;

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

161:    Level: advanced

163: .seealso: [](ch:eps), `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
164: E*/
165: typedef enum { EPS_STOP_BASIC,
166:                EPS_STOP_USER,
167:                EPS_STOP_THRESHOLD } EPSStop;

169: /*E
170:    EPSConvergedReason - Reason an eigensolver was determined to have converged
171:    or diverged.

173:    Values:
174: +  `EPS_CONVERGED_TOL`          - converged up to tolerance
175: .  `EPS_CONVERGED_USER`         - converged due to a user-defined condition
176: .  `EPS_DIVERGED_ITS`           - exceeded the maximum number of allowed iterations
177: .  `EPS_DIVERGED_BREAKDOWN`     - generic breakdown in method
178: -  `EPS_DIVERGED_SYMMETRY_LOST` - pseudo-Lanczos was not able to keep symmetry

180:    Level: intermediate

182: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSSetTolerances()`
183: E*/
184: typedef enum {/* converged */
185:               EPS_CONVERGED_TOL                =  1,
186:               EPS_CONVERGED_USER               =  2,
187:               /* diverged */
188:               EPS_DIVERGED_ITS                 = -1,
189:               EPS_DIVERGED_BREAKDOWN           = -2,
190:               EPS_DIVERGED_SYMMETRY_LOST       = -3,
191:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;
192: SLEPC_EXTERN const char *const*EPSConvergedReasons;

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

198:    Level: advanced

200: .seealso: [](ch:eps), `EPSSetStoppingTestFunction()`
201: S*/
202: struct _n_EPSStoppingCtx {
203:   PetscReal firstev;    /* the (absolute) value of the first converged eigenvalue */
204:   PetscReal lastev;     /* the (absolute) value of the last converged eigenvalue */
205:   PetscReal thres;      /* threshold set with EPSSetThreshold() */
206:   PetscBool threlative; /* threshold is relative */
207:   EPSWhich  which;      /* which eigenvalues are being computed */
208: };
209: typedef struct _n_EPSStoppingCtx* EPSStoppingCtx;

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

242: SLEPC_EXTERN PetscErrorCode EPSSetTarget(EPS,PetscScalar);
243: SLEPC_EXTERN PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
244: SLEPC_EXTERN PetscErrorCode EPSSetInterval(EPS,PetscReal,PetscReal);
245: SLEPC_EXTERN PetscErrorCode EPSGetInterval(EPS,PetscReal*,PetscReal*);
246: SLEPC_EXTERN PetscErrorCode EPSSetST(EPS,ST);
247: SLEPC_EXTERN PetscErrorCode EPSGetST(EPS,ST*);
248: SLEPC_EXTERN PetscErrorCode EPSSetBV(EPS,BV);
249: SLEPC_EXTERN PetscErrorCode EPSGetBV(EPS,BV*);
250: SLEPC_EXTERN PetscErrorCode EPSSetRG(EPS,RG);
251: SLEPC_EXTERN PetscErrorCode EPSGetRG(EPS,RG*);
252: SLEPC_EXTERN PetscErrorCode EPSSetDS(EPS,DS);
253: SLEPC_EXTERN PetscErrorCode EPSGetDS(EPS,DS*);
254: SLEPC_EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
255: SLEPC_EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
256: SLEPC_EXTERN PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
257: SLEPC_EXTERN PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

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

261: SLEPC_EXTERN PetscErrorCode EPSGetConverged(EPS,PetscInt*);
262: SLEPC_EXTERN PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
263: SLEPC_EXTERN PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);
264: SLEPC_EXTERN PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);
265: SLEPC_EXTERN PetscErrorCode EPSGetLeftEigenvector(EPS,PetscInt,Vec,Vec);

267: SLEPC_EXTERN PetscErrorCode EPSComputeError(EPS,PetscInt,EPSErrorType,PetscReal*);
268: 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);}
269: 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);}
270: SLEPC_EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec[]);
271: SLEPC_EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
272: SLEPC_EXTERN PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);

274: SLEPC_EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
275: SLEPC_EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
276: SLEPC_EXTERN PetscErrorCode EPSSetThreshold(EPS,PetscReal,PetscBool);
277: SLEPC_EXTERN PetscErrorCode EPSGetThreshold(EPS,PetscReal*,PetscBool*);
278: SLEPC_EXTERN PetscErrorCode EPSSetTwoSided(EPS,PetscBool);
279: SLEPC_EXTERN PetscErrorCode EPSGetTwoSided(EPS,PetscBool*);
280: SLEPC_EXTERN PetscErrorCode EPSSetTrueResidual(EPS,PetscBool);
281: SLEPC_EXTERN PetscErrorCode EPSGetTrueResidual(EPS,PetscBool*);
282: SLEPC_EXTERN PetscErrorCode EPSSetPurify(EPS,PetscBool);
283: SLEPC_EXTERN PetscErrorCode EPSGetPurify(EPS,PetscBool*);
284: SLEPC_EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscBool*);
285: SLEPC_EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscBool*);
286: SLEPC_EXTERN PetscErrorCode EPSIsPositive(EPS,PetscBool*);
287: SLEPC_EXTERN PetscErrorCode EPSIsStructured(EPS,PetscBool*);

289: SLEPC_EXTERN PetscErrorCode EPSSetTrackAll(EPS,PetscBool);
290: SLEPC_EXTERN PetscErrorCode EPSGetTrackAll(EPS,PetscBool*);

292: SLEPC_EXTERN PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec[]);
293: SLEPC_EXTERN PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec[]);
294: SLEPC_EXTERN PetscErrorCode EPSSetLeftInitialSpace(EPS,PetscInt,Vec[]);

296: /*S
297:    EPSMonitorFn - A function prototype for functions provided to `EPSMonitorSet()`.

299:    Calling Sequence:
300: +  eps    - the linear eigensolver context
301: .  its    - iteration number
302: .  nconv  - number of converged eigenpairs
303: .  eigr   - real part of the eigenvalues
304: .  eigi   - imaginary part of the eigenvalues
305: .  errest - relative error estimates for each eigenpair
306: .  nest   - number of error estimates
307: -  ctx    - optional monitoring context, as provided with `EPSMonitorSet()`

309:    Level: intermediate

311: .seealso: [](ch:eps), `EPSMonitorSet()`
312: S*/
313: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar eigr[],PetscScalar eigi[],PetscReal errest[],PetscInt nest,void *ctx);

315: /*S
316:    EPSMonitorRegisterFn - A function prototype for functions provided to `EPSMonitorRegister()`.

318:    Calling Sequence:
319: +  eps    - the linear eigensolver context
320: .  its    - iteration number
321: .  nconv  - number of converged eigenpairs
322: .  eigr   - real part of the eigenvalues
323: .  eigi   - imaginary part of the eigenvalues
324: .  errest - relative error estimates for each eigenpair
325: .  nest   - number of error estimates
326: -  ctx    - `PetscViewerAndFormat` object

328:    Level: advanced

330:    Note:
331:    This is an `EPSMonitorFn` specialized for a context of `PetscViewerAndFormat`.

333: .seealso: [](ch:eps), `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterCreateFn`, `EPSMonitorRegisterDestroyFn`
334: S*/
335: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar eigr[],PetscScalar eigi[],PetscReal errest[],PetscInt nest,PetscViewerAndFormat *ctx);

337: /*S
338:    EPSMonitorRegisterCreateFn - A function prototype for functions that do the
339:    creation when provided to `EPSMonitorRegister()`.

341:    Calling Sequence:
342: +  viewer - the viewer to be used with the `EPSMonitorRegisterFn`
343: .  format - the format of the viewer
344: .  ctx    - a context for the monitor
345: -  result - a `PetscViewerAndFormat` object

347:    Level: advanced

349: .seealso: [](ch:eps), `EPSMonitorRegisterFn`, `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterDestroyFn`
350: S*/
351: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);

353: /*S
354:    EPSMonitorRegisterDestroyFn - A function prototype for functions that do the after
355:    use destruction when provided to `EPSMonitorRegister()`

357:    Calling Sequence:
358: .  vf - a `PetscViewerAndFormat` object to be destroyed, including any context

360:    Level: advanced

362: .seealso: [](ch:eps), `EPSMonitorRegisterFn`, `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterCreateFn`
363: S*/
364: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterDestroyFn(PetscViewerAndFormat **result);

366: SLEPC_EXTERN PetscErrorCode EPSMonitor(EPS,PetscInt,PetscInt,PetscScalar[],PetscScalar[],PetscReal[],PetscInt);
367: SLEPC_EXTERN PetscErrorCode EPSMonitorSet(EPS,EPSMonitorFn,void*,PetscCtxDestroyFn*);
368: SLEPC_EXTERN PetscErrorCode EPSMonitorCancel(EPS);
369: SLEPC_EXTERN PetscErrorCode EPSGetMonitorContext(EPS,void*);

371: SLEPC_EXTERN PetscErrorCode EPSMonitorSetFromOptions(EPS,const char[],const char[],void*,PetscBool);
372: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorFirst;
373: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorFirstDrawLG;
374: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorFirstDrawLGCreate;
375: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorAll;
376: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorAllDrawLG;
377: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorAllDrawLGCreate;
378: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorConverged;
379: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorConvergedCreate;
380: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorConvergedDrawLG;
381: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorConvergedDrawLGCreate;
382: SLEPC_EXTERN EPSMonitorRegisterDestroyFn EPSMonitorConvergedDestroy;

384: SLEPC_EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char[]);
385: SLEPC_EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char[]);
386: SLEPC_EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

388: SLEPC_EXTERN PetscFunctionList EPSList;
389: SLEPC_EXTERN PetscFunctionList EPSMonitorList;
390: SLEPC_EXTERN PetscFunctionList EPSMonitorCreateList;
391: SLEPC_EXTERN PetscFunctionList EPSMonitorDestroyList;
392: SLEPC_EXTERN PetscErrorCode EPSRegister(const char[],PetscErrorCode(*)(EPS));
393: SLEPC_EXTERN PetscErrorCode EPSMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,EPSMonitorRegisterFn*,EPSMonitorRegisterCreateFn*,EPSMonitorRegisterDestroyFn*);

395: SLEPC_EXTERN PetscErrorCode EPSSetWorkVecs(EPS,PetscInt);
396: SLEPC_EXTERN PetscErrorCode EPSAllocateSolution(EPS,PetscInt);
397: SLEPC_EXTERN PetscErrorCode EPSReallocateSolution(EPS,PetscInt);

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

403:    Calling Sequence:
404: +  eps    - the linear eigensolver context
405: .  eigr   - real part of the eigenvalue
406: .  eigi   - imaginary part of the eigenvalue
407: .  res    - residual norm associated to the eigenpair
408: .  errest - [output] computed error estimate
409: -  ctx    - [optional] user-defined context for private data for the
410:             convergence test routine (may be NULL)

412:    Level: advanced

414: .seealso: [](ch:eps), `EPSSetConvergenceTestFunction()`
415: S*/
416: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSConvergenceTestFn(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx);

418: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTest(EPS,EPSConv);
419: SLEPC_EXTERN PetscErrorCode EPSGetConvergenceTest(EPS,EPSConv*);
420: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedAbsolute;
421: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedRelative;
422: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedNorm;
423: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTestFunction(EPS,EPSConvergenceTestFn*,void*,PetscCtxDestroyFn*);

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

429:    Calling Sequence:
430: +  eps    - the linear eigensolver context
431: .  its    - current number of iterations
432: .  max_it - maximum number of iterations
433: .  nconv  - number of currently converged eigenpairs
434: .  nev    - number of requested eigenpairs
435: .  reason - [output] result of the stopping test
436: -  ctx    - [optional] user-defined context for private data for the
437:             stopping test routine (may be NULL)

439:    Level: advanced

441: .seealso: [](ch:eps), `EPSSetStoppingTestFunction()`
442: S*/
443: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSStoppingTestFn(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx);

445: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTest(EPS,EPSStop);
446: SLEPC_EXTERN PetscErrorCode EPSGetStoppingTest(EPS,EPSStop*);
447: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingBasic;
448: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingThreshold;
449: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTestFunction(EPS,EPSStoppingTestFn*,void*,PetscCtxDestroyFn*);

451: SLEPC_EXTERN PetscErrorCode EPSSetEigenvalueComparison(EPS,SlepcEigenvalueComparisonFn*,void*);
452: SLEPC_EXTERN PetscErrorCode EPSSetArbitrarySelection(EPS,SlepcArbitrarySelectionFn*,void*);

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

456: /*E
457:    EPSPowerShiftType - determines the type of shift used in the Power iteration

459:    Level: advanced

461: .seealso: [](ch:eps), `EPSPowerSetShiftType()`, `EPSPowerGetShiftType()`
462: E*/
463: typedef enum { EPS_POWER_SHIFT_CONSTANT,
464:                EPS_POWER_SHIFT_RAYLEIGH,
465:                EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;
466: SLEPC_EXTERN const char *EPSPowerShiftTypes[];

468: SLEPC_EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
469: SLEPC_EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);
470: SLEPC_EXTERN PetscErrorCode EPSPowerSetNonlinear(EPS,PetscBool);
471: SLEPC_EXTERN PetscErrorCode EPSPowerGetNonlinear(EPS,PetscBool*);
472: SLEPC_EXTERN PetscErrorCode EPSPowerSetUpdate(EPS,PetscBool);
473: SLEPC_EXTERN PetscErrorCode EPSPowerGetUpdate(EPS,PetscBool*);
474: SLEPC_EXTERN PetscErrorCode EPSPowerSetSignNormalization(EPS,PetscBool);
475: SLEPC_EXTERN PetscErrorCode EPSPowerGetSignNormalization(EPS,PetscBool*);
476: SLEPC_EXTERN PetscErrorCode EPSPowerSetSNES(EPS,SNES);
477: SLEPC_EXTERN PetscErrorCode EPSPowerGetSNES(EPS,SNES*);

479: SLEPC_EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscBool);
480: SLEPC_EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscBool*);

482: /*E
483:    EPSKrylovSchurBSEType - the method to be used in the Krylov-Schur solver
484:    for the case of BSE structured eigenproblems

486:    Level: advanced

488: .seealso: [](ch:eps), `EPSKrylovSchurSetBSEType()`, `EPSKrylovSchurGetBSEType()`
489: E*/
490: typedef enum { EPS_KRYLOVSCHUR_BSE_SHAO,
491:                EPS_KRYLOVSCHUR_BSE_GRUNING,
492:                EPS_KRYLOVSCHUR_BSE_PROJECTEDBSE } EPSKrylovSchurBSEType;
493: SLEPC_EXTERN const char *EPSKrylovSchurBSETypes[];

495: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetBSEType(EPS,EPSKrylovSchurBSEType);
496: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetBSEType(EPS,EPSKrylovSchurBSEType*);
497: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetRestart(EPS,PetscReal);
498: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetRestart(EPS,PetscReal*);
499: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetLocking(EPS,PetscBool);
500: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetLocking(EPS,PetscBool*);
501: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetPartitions(EPS,PetscInt);
502: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetPartitions(EPS,PetscInt*);
503: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDetectZeros(EPS,PetscBool);
504: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDetectZeros(EPS,PetscBool*);
505: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
506: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);
507: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetSubintervals(EPS,PetscReal[]);
508: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubintervals(EPS,PetscReal*[]);
509: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetInertias(EPS,PetscInt*,PetscReal*[],PetscInt*[]);
510: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommInfo(EPS,PetscInt*,PetscInt*,Vec*);
511: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommPairs(EPS,PetscInt,PetscScalar*,Vec);
512: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommMats(EPS,Mat*,Mat*);
513: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurUpdateSubcommMats(EPS,PetscScalar,PetscScalar,Mat,PetscScalar,PetscScalar, Mat,MatStructure,PetscBool);
514: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetKSP(EPS,KSP*);

516: /*E
517:    EPSLanczosReorthogType - determines the type of reorthogonalization
518:    used in the Lanczos method

520:    Level: advanced

522: .seealso: [](ch:eps), `EPSLanczosSetReorthog()`, `EPSLanczosGetReorthog()`
523: E*/
524: typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,
525:                EPS_LANCZOS_REORTHOG_FULL,
526:                EPS_LANCZOS_REORTHOG_SELECTIVE,
527:                EPS_LANCZOS_REORTHOG_PERIODIC,
528:                EPS_LANCZOS_REORTHOG_PARTIAL,
529:                EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;
530: SLEPC_EXTERN const char *EPSLanczosReorthogTypes[];

532: SLEPC_EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
533: SLEPC_EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

535: /*E
536:    EPSPRIMMEMethod - determines the method selected in the PRIMME library

538:    Level: advanced

540: .seealso: [](ch:eps), `EPSPRIMMESetMethod()`, `EPSPRIMMEGetMethod()`
541: E*/
542: typedef enum { EPS_PRIMME_DYNAMIC             = 1,
543:                EPS_PRIMME_DEFAULT_MIN_TIME    = 2,
544:                EPS_PRIMME_DEFAULT_MIN_MATVECS = 3,
545:                EPS_PRIMME_ARNOLDI             = 4,
546:                EPS_PRIMME_GD                  = 5,
547:                EPS_PRIMME_GD_PLUSK            = 6,
548:                EPS_PRIMME_GD_OLSEN_PLUSK      = 7,
549:                EPS_PRIMME_JD_OLSEN_PLUSK      = 8,
550:                EPS_PRIMME_RQI                 = 9,
551:                EPS_PRIMME_JDQR                = 10,
552:                EPS_PRIMME_JDQMR               = 11,
553:                EPS_PRIMME_JDQMR_ETOL          = 12,
554:                EPS_PRIMME_SUBSPACE_ITERATION  = 13,
555:                EPS_PRIMME_LOBPCG_ORTHOBASIS   = 14,
556:                EPS_PRIMME_LOBPCG_ORTHOBASISW  = 15 } EPSPRIMMEMethod;
557: SLEPC_EXTERN const char *EPSPRIMMEMethods[];

559: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS,PetscInt);
560: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS,PetscInt*);
561: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS,EPSPRIMMEMethod);
562: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS,EPSPRIMMEMethod*);

564: SLEPC_EXTERN PetscErrorCode EPSGDSetKrylovStart(EPS,PetscBool);
565: SLEPC_EXTERN PetscErrorCode EPSGDGetKrylovStart(EPS,PetscBool*);
566: SLEPC_EXTERN PetscErrorCode EPSGDSetBlockSize(EPS,PetscInt);
567: SLEPC_EXTERN PetscErrorCode EPSGDGetBlockSize(EPS,PetscInt*);
568: SLEPC_EXTERN PetscErrorCode EPSGDSetRestart(EPS,PetscInt,PetscInt);
569: SLEPC_EXTERN PetscErrorCode EPSGDGetRestart(EPS,PetscInt*,PetscInt*);
570: SLEPC_EXTERN PetscErrorCode EPSGDSetInitialSize(EPS,PetscInt);
571: SLEPC_EXTERN PetscErrorCode EPSGDGetInitialSize(EPS,PetscInt*);
572: SLEPC_EXTERN PetscErrorCode EPSGDSetBOrth(EPS,PetscBool);
573: SLEPC_EXTERN PetscErrorCode EPSGDGetBOrth(EPS,PetscBool*);
574: SLEPC_EXTERN PetscErrorCode EPSGDSetDoubleExpansion(EPS,PetscBool);
575: SLEPC_EXTERN PetscErrorCode EPSGDGetDoubleExpansion(EPS,PetscBool*);

577: SLEPC_EXTERN PetscErrorCode EPSJDSetKrylovStart(EPS,PetscBool);
578: SLEPC_EXTERN PetscErrorCode EPSJDGetKrylovStart(EPS,PetscBool*);
579: SLEPC_EXTERN PetscErrorCode EPSJDSetBlockSize(EPS,PetscInt);
580: SLEPC_EXTERN PetscErrorCode EPSJDGetBlockSize(EPS,PetscInt*);
581: SLEPC_EXTERN PetscErrorCode EPSJDSetRestart(EPS,PetscInt,PetscInt);
582: SLEPC_EXTERN PetscErrorCode EPSJDGetRestart(EPS,PetscInt*,PetscInt*);
583: SLEPC_EXTERN PetscErrorCode EPSJDSetInitialSize(EPS,PetscInt);
584: SLEPC_EXTERN PetscErrorCode EPSJDGetInitialSize(EPS,PetscInt*);
585: SLEPC_EXTERN PetscErrorCode EPSJDSetFix(EPS,PetscReal);
586: SLEPC_EXTERN PetscErrorCode EPSJDGetFix(EPS,PetscReal*);
587: SLEPC_EXTERN PetscErrorCode EPSJDSetConstCorrectionTol(EPS,PetscBool);
588: SLEPC_EXTERN PetscErrorCode EPSJDGetConstCorrectionTol(EPS,PetscBool*);
589: SLEPC_EXTERN PetscErrorCode EPSJDSetBOrth(EPS,PetscBool);
590: SLEPC_EXTERN PetscErrorCode EPSJDGetBOrth(EPS,PetscBool*);

592: SLEPC_EXTERN PetscErrorCode EPSRQCGSetReset(EPS,PetscInt);
593: SLEPC_EXTERN PetscErrorCode EPSRQCGGetReset(EPS,PetscInt*);

595: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetBlockSize(EPS,PetscInt);
596: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetBlockSize(EPS,PetscInt*);
597: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetRestart(EPS,PetscReal);
598: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetRestart(EPS,PetscReal*);
599: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetLocking(EPS,PetscBool);
600: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetLocking(EPS,PetscBool*);

602: /*E
603:    EPSCISSQuadRule - determines the quadrature rule in the CISS solver

605:    Level: advanced

607: .seealso: [](ch:eps), `EPSCISSSetQuadRule()`, `EPSCISSGetQuadRule()`
608: E*/
609: typedef enum { EPS_CISS_QUADRULE_TRAPEZOIDAL = 1,
610:                EPS_CISS_QUADRULE_CHEBYSHEV   = 2 } EPSCISSQuadRule;
611: SLEPC_EXTERN const char *EPSCISSQuadRules[];

613: /*E
614:    EPSCISSExtraction - determines the extraction technique in the CISS solver

616:    Level: advanced

618: .seealso: [](ch:eps), `EPSCISSSetExtraction()`, `EPSCISSGetExtraction()`
619: E*/
620: typedef enum { EPS_CISS_EXTRACTION_RITZ,
621:                EPS_CISS_EXTRACTION_HANKEL } EPSCISSExtraction;
622: SLEPC_EXTERN const char *EPSCISSExtractions[];

624: SLEPC_EXTERN PetscErrorCode EPSCISSSetExtraction(EPS,EPSCISSExtraction);
625: SLEPC_EXTERN PetscErrorCode EPSCISSGetExtraction(EPS,EPSCISSExtraction*);
626: SLEPC_EXTERN PetscErrorCode EPSCISSSetQuadRule(EPS,EPSCISSQuadRule);
627: SLEPC_EXTERN PetscErrorCode EPSCISSGetQuadRule(EPS,EPSCISSQuadRule*);
628: SLEPC_EXTERN PetscErrorCode EPSCISSSetSizes(EPS,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscBool);
629: SLEPC_EXTERN PetscErrorCode EPSCISSGetSizes(EPS,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscBool*);
630: SLEPC_EXTERN PetscErrorCode EPSCISSSetThreshold(EPS,PetscReal,PetscReal);
631: SLEPC_EXTERN PetscErrorCode EPSCISSGetThreshold(EPS,PetscReal*,PetscReal*);
632: SLEPC_EXTERN PetscErrorCode EPSCISSSetRefinement(EPS,PetscInt,PetscInt);
633: SLEPC_EXTERN PetscErrorCode EPSCISSGetRefinement(EPS,PetscInt*,PetscInt*);
634: SLEPC_EXTERN PetscErrorCode EPSCISSSetUseST(EPS,PetscBool);
635: SLEPC_EXTERN PetscErrorCode EPSCISSGetUseST(EPS,PetscBool*);
636: SLEPC_EXTERN PetscErrorCode EPSCISSGetKSPs(EPS,PetscInt*,KSP*[]);

638: SLEPC_EXTERN PetscErrorCode EPSLyapIISetLME(EPS,LME);
639: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetLME(EPS,LME*);
640: SLEPC_EXTERN PetscErrorCode EPSLyapIISetRanks(EPS,PetscInt,PetscInt);
641: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetRanks(EPS,PetscInt*,PetscInt*);

643: SLEPC_EXTERN PetscErrorCode EPSBLOPEXSetBlockSize(EPS,PetscInt);
644: SLEPC_EXTERN PetscErrorCode EPSBLOPEXGetBlockSize(EPS,PetscInt*);

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

649:    Level: advanced

651: .seealso: [](ch:eps), `EPSEVSLSetDOSParameters()`, `EPSEVSLGetDOSParameters()`
652: E*/
653: typedef enum { EPS_EVSL_DOS_KPM,
654:                EPS_EVSL_DOS_LANCZOS } EPSEVSLDOSMethod;
655: SLEPC_EXTERN const char *EPSEVSLDOSMethods[];

657: /*E
658:    EPSEVSLDamping - the damping type used in the EVSL solver

660:    Level: advanced

662: .seealso: [](ch:eps), `EPSEVSLSetDOSParameters()`, `EPSEVSLGetDOSParameters()`
663: E*/
664: typedef enum { EPS_EVSL_DAMPING_NONE,
665:                EPS_EVSL_DAMPING_JACKSON,
666:                EPS_EVSL_DAMPING_SIGMA } EPSEVSLDamping;
667: SLEPC_EXTERN const char *EPSEVSLDampings[];

669: SLEPC_EXTERN PetscErrorCode EPSEVSLSetRange(EPS,PetscReal,PetscReal);
670: SLEPC_EXTERN PetscErrorCode EPSEVSLGetRange(EPS,PetscReal*,PetscReal*);
671: SLEPC_EXTERN PetscErrorCode EPSEVSLSetSlices(EPS,PetscInt);
672: SLEPC_EXTERN PetscErrorCode EPSEVSLGetSlices(EPS,PetscInt*);
673: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDOSParameters(EPS,EPSEVSLDOSMethod,PetscInt,PetscInt,PetscInt,PetscInt);
674: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDOSParameters(EPS,EPSEVSLDOSMethod*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
675: SLEPC_EXTERN PetscErrorCode EPSEVSLSetPolParameters(EPS,PetscInt,PetscReal);
676: SLEPC_EXTERN PetscErrorCode EPSEVSLGetPolParameters(EPS,PetscInt*,PetscReal*);
677: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDamping(EPS,EPSEVSLDamping);
678: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDamping(EPS,EPSEVSLDamping*);

680: SLEPC_EXTERN PetscErrorCode EPSFEASTSetNumPoints(EPS,PetscInt);
681: SLEPC_EXTERN PetscErrorCode EPSFEASTGetNumPoints(EPS,PetscInt*);

683: SLEPC_EXTERN PetscErrorCode EPSCHASESetDegree(EPS,PetscInt,PetscBool);
684: SLEPC_EXTERN PetscErrorCode EPSCHASEGetDegree(EPS,PetscInt*,PetscBool*);