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 linear 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: Values:
74: + `EPS_HEP` - Hermitian
75: . `EPS_GHEP` - generalized Hermitian
76: . `EPS_NHEP` - non-Hermitian
77: . `EPS_GNHEP` - generalized non-Hermitian
78: . `EPS_PGNHEP` - generalized non-Hermitian with positive (semi-)definite $B$
79: . `EPS_GHIEP` - generalized Hermitian-indefinite
80: . `EPS_BSE` - structured Bethe-Salpeter
81: . `EPS_HAMILT` - structured Hamiltonian
82: - `EPS_LREP` - structured Linear Response
84: Note:
85: In real scalars, one should read the term Hermitian as symmetric.
87: Level: intermediate
89: .seealso: [](ch:eps), `EPSSetProblemType()`, `EPSGetProblemType()`
90: E*/
91: typedef enum { EPS_HEP = 1,
92: EPS_GHEP = 2,
93: EPS_NHEP = 3,
94: EPS_GNHEP = 4,
95: EPS_PGNHEP = 5,
96: EPS_GHIEP = 6,
97: EPS_BSE = 7,
98: EPS_HAMILT = 8,
99: EPS_LREP = 9 } EPSProblemType;
101: /*MC
102: EPS_HEP - A Hermitian eigenvalue problem.
104: Note:
105: The problem is formulated as $Ax=\lambda x$, where $A$ is real symmetric
106: or complex Hermitian.
108: Level: intermediate
110: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
111: M*/
113: /*MC
114: EPS_GHEP - A generalized Hermitian eigenvalue problem.
116: Note:
117: The problem is formulated as $Ax=\lambda Bx$, where $A$ and $B$ are real
118: symmetric or complex Hermitian, and $B$ is positive (semi-)definite.
120: Level: intermediate
122: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
123: M*/
125: /*MC
126: EPS_NHEP - A non-Hermitian eigenvalue problem.
128: Note:
129: The problem is formulated as $Ax=\lambda x$, where $A$ is non-symmetric
130: (or non-Hermitian).
132: Level: intermediate
134: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
135: M*/
137: /*MC
138: EPS_GNHEP - A generalized non-Hermitian eigenvalue problem.
140: Note:
141: The problem is formulated as $Ax=\lambda Bx$, where $A$ or $B$ are
142: non-symmetric (or non-Hermitian).
144: Level: intermediate
146: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
147: M*/
149: /*MC
150: EPS_PGNHEP - A generalized non-Hermitian eigenvalue problem with positive
151: (semi-)definite $B$.
153: Notes:
154: The problem is formulated as $Ax=\lambda Bx$, where $A$ is non-symmetric
155: (or non-Hermitian), but $B$ is symmetric (or Hermitian) and positive
156: (semi-)definite.
158: The problem will be solved with a non-Hermitian solver, but using an
159: inner product induced by matrix $B$.
161: Level: intermediate
163: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
164: M*/
166: /*MC
167: EPS_GHIEP - A generalized Hermitian-indefinite eigenvalue problem.
169: Notes:
170: The problem is formulated as $Ax=\lambda Bx$, where both $A$ and $B$ are
171: real symmetric or complex Hermitian, but $B$ is indefinite.
173: The solver will try to exploit the symmetry by using an indefinite
174: inner product, which may turn the computation numerically unstable.
175: To avoid this, solve the problem as non-Hermitian.
177: Level: intermediate
179: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
180: M*/
182: /*MC
183: EPS_BSE - A structured Bethe-Salpeter eigenvalue problem.
185: Notes:
186: The problem is formulated as $Hx=\lambda x$, where $H$ has a Bethe-Salpeter
187: structure,
188: $$H = \begin{bmatrix}
189: R & C \\
190: -C^* & -R^T
191: \end{bmatrix},$$
192: where $R$ is Hermitian and $C$ is complex symmetric. Can also be used in
193: the case of real matrices.
195: A description of the properties of this problem can be found in {cite:p}`Alv25`
196: and references therein.
198: Level: intermediate
200: .seealso: [](ch:eps), [](sec:structured), `EPSProblemType`, `EPSSetProblemType()`
201: M*/
203: /*MC
204: EPS_HAMILT - A structured Hamiltonian eigenvalue problem.
206: Note:
207: The problem is formulated as $Hx=\lambda x$, where $H$ has a Hamiltonian
208: structure,
209: $$H = \begin{bmatrix}
210: A & B \\
211: C & -A^*
212: \end{bmatrix},$$
213: where $A$, $B$ and $C$ are either real with $B=B^T$, $C=C^T$, or complex with
214: $B=B^*$, $C=C^*$.
216: Level: intermediate
218: .seealso: [](ch:eps), [](sec:structured), `EPSProblemType`, `EPSSetProblemType()`
219: M*/
221: /*MC
222: EPS_LREP - A structured Linear Response eigenvalue problem.
224: Note:
225: The problem is formulated as $Hx=\lambda x$, where $H$ has the form
226: $$H_1 = \begin{bmatrix}
227: A & B \\
228: -B & -A
229: \end{bmatrix},$$
230: where $A$ and $B$ are real symmetric. An alternative form is
231: $$H_2 = \begin{bmatrix}
232: 0 & K \\
233: M & 0
234: \end{bmatrix},$$
235: where $K=A-B$ and $M=A+B$.
237: Level: intermediate
239: .seealso: [](ch:eps), [](sec:structured), `EPSProblemType`, `EPSSetProblemType()`, `MatCreateLREP()`
240: M*/
242: /*E
243: EPSExtraction - Determines the type of extraction technique employed
244: by the eigensolver.
246: Values:
247: + `EPS_RITZ` - Rayleigh-Ritz extraction
248: . `EPS_HARMONIC` - harmonic Ritz extraction
249: . `EPS_HARMONIC_RELATIVE` - harmonic Ritz extraction relative to the eigenvalue
250: . `EPS_HARMONIC_RIGHT` - harmonic Ritz extraction for rightmost eigenvalues
251: . `EPS_HARMONIC_LARGEST` - harmonic Ritz extraction for largest magnitude (without target)
252: . `EPS_REFINED` - refined Ritz extraction
253: - `EPS_REFINED_HARMONIC` - refined harmonic Ritz extraction
255: Level: advanced
257: .seealso: [](ch:eps), `EPSSetExtraction()`, `EPSGetExtraction()`
258: E*/
259: typedef enum { EPS_RITZ,
260: EPS_HARMONIC,
261: EPS_HARMONIC_RELATIVE,
262: EPS_HARMONIC_RIGHT,
263: EPS_HARMONIC_LARGEST,
264: EPS_REFINED,
265: EPS_REFINED_HARMONIC } EPSExtraction;
267: /*MC
268: EPS_RITZ - The standard Rayleigh-Ritz extraction.
270: Note:
271: This is the default way of computing eigenpair approximations from a
272: given subspace.
274: Level: advanced
276: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
277: M*/
279: /*MC
280: EPS_HARMONIC - The harmonic Ritz extraction.
282: Notes:
283: This extraction method may provide better convergence when computing
284: interior eigenvalues close to a given target.
286: For the particular case of Krylov-Schur, a detailed description can
287: be found in {cite:p}`Rom09`.
289: Level: advanced
291: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`, `EPSSetTarget()`
292: M*/
294: /*MC
295: EPS_HARMONIC_RELATIVE - The harmonic Ritz extraction relative to the eigenvalue.
297: Note:
298: This is a variation of `EPS_HARMONIC`, used in Davidson methods only.
300: Level: advanced
302: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`, `EPSSetTarget()`
303: M*/
305: /*MC
306: EPS_HARMONIC_RIGHT - The harmonic Ritz extraction for rightmost eigenvalues.
308: Note:
309: This is a variation of `EPS_HARMONIC`, used in Davidson methods only.
311: Level: advanced
313: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`, `EPSSetTarget()`
314: M*/
316: /*MC
317: EPS_HARMONIC_LARGEST - The harmonic Ritz extraction for largest magnitude
318: eigenvalues (without target).
320: Note:
321: This is a variation of `EPS_HARMONIC`, used in Davidson methods only.
323: Level: advanced
325: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
326: M*/
328: /*MC
329: EPS_REFINED - The refined Ritz extraction method {cite:p}`Jia97`.
331: Note:
332: Currently implemented only in `EPSARNOLDI`.
334: Level: advanced
336: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
337: M*/
339: /*MC
340: EPS_REFINED_HARMONIC - The refined harmonic Ritz extraction.
342: Note:
343: This is a combination of `EPS_HARMONIC` and `EPS_REFINED`.
345: Developer Note:
346: Currently not implemented, reserved for future use.
348: Level: advanced
350: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
351: M*/
353: /*E
354: EPSWhich - Determines which part of the spectrum is requested.
356: Values:
357: + `EPS_LARGEST_MAGNITUDE` - largest $|\lambda|$
358: . `EPS_SMALLEST_MAGNITUDE` - smallest $|\lambda|$
359: . `EPS_LARGEST_REAL` - largest $\mathrm{Re}(\lambda)$
360: . `EPS_SMALLEST_REAL` - smallest $\mathrm{Re}(\lambda)$
361: . `EPS_LARGEST_IMAGINARY` - largest $\mathrm{Im}(\lambda)$
362: . `EPS_SMALLEST_IMAGINARY` - smallest $\mathrm{Im}(\lambda)$
363: . `EPS_TARGET_MAGNITUDE` - smallest $|\lambda-\tau|$
364: . `EPS_TARGET_REAL` - smallest $|\mathrm{Re}(\lambda-\tau)|$
365: . `EPS_TARGET_IMAGINARY` - smallest $|\mathrm{Im}(\lambda-\tau)|$
366: . `EPS_ALL` - all $\lambda\in[a,b]$ or $\lambda\in\Omega$
367: - `EPS_WHICH_USER` - user-defined sorting criterion
369: Notes:
370: If SLEPc is compiled for real scalars `EPS_LARGEST_IMAGINARY` and
371: `EPS_SMALLEST_IMAGINARY` use the absolute value of the imaginary part
372: for eigenvalue selection.
374: The target $\tau$ is a scalar value provided with `EPSSetTarget()`.
376: The case `EPS_ALL` needs an interval $[a,b]$ given with `EPSSetInterval()`
377: or a region $\Omega$ specified with an `RG` object.
379: Level: intermediate
381: .seealso: [](ch:eps), `EPSSetWhichEigenpairs()`, `EPSSetTarget()`, `EPSSetInterval()`
382: E*/
383: typedef enum { EPS_LARGEST_MAGNITUDE = 1,
384: EPS_SMALLEST_MAGNITUDE = 2,
385: EPS_LARGEST_REAL = 3,
386: EPS_SMALLEST_REAL = 4,
387: EPS_LARGEST_IMAGINARY = 5,
388: EPS_SMALLEST_IMAGINARY = 6,
389: EPS_TARGET_MAGNITUDE = 7,
390: EPS_TARGET_REAL = 8,
391: EPS_TARGET_IMAGINARY = 9,
392: EPS_ALL = 10,
393: EPS_WHICH_USER = 11 } EPSWhich;
395: /*E
396: EPSBalance - The type of balancing used for non-Hermitian problems.
398: Values:
399: + `EPS_BALANCE_NONE` - no balancing matrix is used
400: . `EPS_BALANCE_ONESIDE` - balancing matrix $D$ is computed with a one-sided Krylov method
401: . `EPS_BALANCE_TWOSIDE` - balancing matrix $D$ is computed with a two-sided Krylov method
402: - `EPS_BALANCE_USER` - use a balancing matrix $D$ provided by the user
404: Level: intermediate
406: .seealso: [](ch:eps), [](sec:balancing), `EPSSetBalance()`
407: E*/
408: typedef enum { EPS_BALANCE_NONE,
409: EPS_BALANCE_ONESIDE,
410: EPS_BALANCE_TWOSIDE,
411: EPS_BALANCE_USER } EPSBalance;
412: SLEPC_EXTERN const char *EPSBalanceTypes[];
414: /*E
415: EPSErrorType - The error type used to assess the accuracy of computed solutions.
417: Values:
418: + `EPS_ERROR_ABSOLUTE` - compute error bound as $\|r\|$
419: . `EPS_ERROR_RELATIVE` - compute error bound as $\|r\|/|\lambda|$
420: - `EPS_ERROR_BACKWARD` - compute error bound as $\|r\|/(\|A\|+|\lambda|\|B\|)$
422: Level: intermediate
424: .seealso: [](ch:eps), `EPSComputeError()`
425: E*/
426: typedef enum { EPS_ERROR_ABSOLUTE,
427: EPS_ERROR_RELATIVE,
428: EPS_ERROR_BACKWARD } EPSErrorType;
429: SLEPC_EXTERN const char *EPSErrorTypes[];
431: /*E
432: EPSConv - The convergence criterion to be used by the solver.
434: Values:
435: + `EPS_CONV_ABS` - absolute convergence criterion, $\|r\|$
436: . `EPS_CONV_REL` - convergence criterion relative to eigenvalue, $\|r\|/|\lambda|$
437: . `EPS_CONV_NORM` - convergence criterion relative to matrix norms, $\|r\|/(\|A\|+|\lambda|\|B\|)$
438: - `EPS_CONV_USER` - convergence dictated by user-provided function
440: Level: intermediate
442: .seealso: [](ch:eps), `EPSSetConvergenceTest()`, `EPSSetConvergenceTestFunction()`
443: E*/
444: typedef enum { EPS_CONV_ABS,
445: EPS_CONV_REL,
446: EPS_CONV_NORM,
447: EPS_CONV_USER } EPSConv;
449: /*E
450: EPSStop - The stopping test to decide the termination of the outer loop
451: of the eigensolver.
453: Values:
454: + `EPS_STOP_BASIC` - default stopping test
455: . `EPS_STOP_USER` - user-provided stopping test
456: - `EPS_STOP_THRESHOLD` - threshold stopping test
458: Level: advanced
460: .seealso: [](ch:eps), `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
461: E*/
462: typedef enum { EPS_STOP_BASIC,
463: EPS_STOP_USER,
464: EPS_STOP_THRESHOLD } EPSStop;
466: /*MC
467: EPS_STOP_BASIC - The default stopping test.
469: Note:
470: By default, the termination of the outer loop is decided by calling
471: `EPSStoppingBasic()`, which will stop if all requested eigenvalues are converged,
472: or if the maximum number of iterations has been reached.
474: Level: advanced
476: .seealso: [](ch:eps), `EPSStop`, `EPSSetStoppingTest()`, `EPSStoppingBasic()`
477: M*/
479: /*MC
480: EPS_STOP_USER - The user-provided stopping test.
482: Note:
483: Customized stopping test using the user-provided function given with
484: `EPSSetStoppingTestFunction()`.
486: Level: advanced
488: .seealso: [](ch:eps), `EPSStop`, `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
489: M*/
491: /*MC
492: EPS_STOP_THRESHOLD - The threshold stopping test.
494: Note:
495: When a threshold has been provided with `EPSSetThreshold()`, the termination
496: of the outer loop is decided by calling `EPSStoppingThreshold()`, which will
497: stop when one of the computed eigenvalues is not above/below the threshold.
498: If a number of wanted eigenvalues has been specified via `EPSSetDimensions()`
499: then it is also taken into account, and the solver will stop when one of the
500: two conditions (threshold or number of converged values) is met.
502: Level: advanced
504: .seealso: [](ch:eps), `EPSStop`, `EPSSetStoppingTest()`, `EPSStoppingThreshold()`, `EPSSetThreshold()`, `EPSSetDimensions()`
505: M*/
507: /*E
508: EPSConvergedReason - Reason an eigensolver was determined to have converged
509: or diverged.
511: Values:
512: + `EPS_CONVERGED_TOL` - converged up to tolerance
513: . `EPS_CONVERGED_USER` - converged due to a user-defined condition
514: . `EPS_DIVERGED_ITS` - exceeded the maximum number of allowed iterations
515: . `EPS_DIVERGED_BREAKDOWN` - generic breakdown in method
516: . `EPS_DIVERGED_SYMMETRY_LOST` - pseudo-Lanczos was not able to keep symmetry
517: - `EPS_CONVERGED_ITERATING` - the solver is still running
519: Level: intermediate
521: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSSetTolerances()`
522: E*/
523: typedef enum {/* converged */
524: EPS_CONVERGED_TOL = 1,
525: EPS_CONVERGED_USER = 2,
526: /* diverged */
527: EPS_DIVERGED_ITS = -1,
528: EPS_DIVERGED_BREAKDOWN = -2,
529: EPS_DIVERGED_SYMMETRY_LOST = -3,
530: EPS_CONVERGED_ITERATING = 0} EPSConvergedReason;
531: SLEPC_EXTERN const char *const*EPSConvergedReasons;
533: /*MC
534: EPS_CONVERGED_TOL - The computed error estimates, based on residual norms,
535: for all requested eigenvalues are below the tolerance.
537: Level: intermediate
539: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
540: M*/
542: /*MC
543: EPS_CONVERGED_USER - The solver was declared converged due to a user-defined condition.
545: Note:
546: This happens only when a user-defined stopping test has been set with
547: `EPSSetStoppingTestFunction()`.
549: Level: intermediate
551: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`, `EPSSetStoppingTestFunction()`
552: M*/
554: /*MC
555: EPS_DIVERGED_ITS - Exceeded the maximum number of allowed iterations
556: before the convergence criterion was satisfied.
558: Level: intermediate
560: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
561: M*/
563: /*MC
564: EPS_DIVERGED_BREAKDOWN - A breakdown in the solver was detected so the
565: method could not continue.
567: Level: intermediate
569: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
570: M*/
572: /*MC
573: EPS_DIVERGED_SYMMETRY_LOST - The selected solver uses a pseudo-Lanczos recurrence,
574: which is numerically unstable, and a symmetry test revealed that instability
575: had appeared so the solver could not continue.
577: Level: intermediate
579: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
580: M*/
582: /*MC
583: EPS_CONVERGED_ITERATING - This value is returned if `EPSGetConvergedReason()` is called
584: while `EPSSolve()` is still running.
586: Level: intermediate
588: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
589: M*/
591: /*S
592: EPSStoppingCtx - Data structure (C struct) to hold additional information to
593: be used in some stopping test functions.
595: Level: advanced
597: .seealso: [](ch:eps), `EPSSetStoppingTestFunction()`
598: S*/
599: struct _n_EPSStoppingCtx {
600: PetscReal firstev; /* the (absolute) value of the first converged eigenvalue */
601: PetscReal lastev; /* the (absolute) value of the last converged eigenvalue */
602: PetscReal firstnc; /* the (absolute) value of the first non-converged eigenvalue */
603: PetscReal errest; /* the error estimate of the first non-converged eigenvalue */
604: PetscReal thres; /* threshold set with EPSSetThreshold() */
605: PetscBool threlative; /* threshold is relative */
606: PetscInt its; /* iteration at which condition is met */
607: PetscInt napprox; /* number of available approximations */
608: EPSWhich which; /* which eigenvalues are being computed */
609: };
610: typedef struct _n_EPSStoppingCtx* EPSStoppingCtx;
612: SLEPC_EXTERN PetscErrorCode EPSCreate(MPI_Comm,EPS*);
613: SLEPC_EXTERN PetscErrorCode EPSDestroy(EPS*);
614: SLEPC_EXTERN PetscErrorCode EPSReset(EPS);
615: SLEPC_EXTERN PetscErrorCode EPSSetType(EPS,EPSType);
616: SLEPC_EXTERN PetscErrorCode EPSGetType(EPS,EPSType*);
617: SLEPC_EXTERN PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
618: SLEPC_EXTERN PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
619: SLEPC_EXTERN PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);
620: SLEPC_EXTERN PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);
621: SLEPC_EXTERN PetscErrorCode EPSSetBalance(EPS,EPSBalance,PetscInt,PetscReal);
622: SLEPC_EXTERN PetscErrorCode EPSGetBalance(EPS,EPSBalance*,PetscInt*,PetscReal*);
623: SLEPC_EXTERN PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
624: SLEPC_EXTERN PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);
625: SLEPC_EXTERN PetscErrorCode EPSSetFromOptions(EPS);
626: SLEPC_EXTERN PetscErrorCode EPSSetDSType(EPS);
627: SLEPC_EXTERN PetscErrorCode EPSSetUp(EPS);
628: SLEPC_EXTERN PetscErrorCode EPSSolve(EPS);
629: SLEPC_EXTERN PetscErrorCode EPSView(EPS,PetscViewer);
630: SLEPC_EXTERN PetscErrorCode EPSViewFromOptions(EPS,PetscObject,const char[]);
631: SLEPC_EXTERN PetscErrorCode EPSErrorView(EPS,EPSErrorType,PetscViewer);
632: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSErrorView()", ) static inline PetscErrorCode EPSPrintSolution(EPS eps,PetscViewer v) {return EPSErrorView(eps,EPS_ERROR_RELATIVE,v);}
633: SLEPC_EXTERN PetscErrorCode EPSErrorViewFromOptions(EPS);
634: SLEPC_EXTERN PetscErrorCode EPSConvergedReasonView(EPS,PetscViewer);
635: SLEPC_EXTERN PetscErrorCode EPSConvergedReasonViewFromOptions(EPS);
636: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "EPSConvergedReasonView()", ) static inline PetscErrorCode EPSReasonView(EPS eps,PetscViewer v) {return EPSConvergedReasonView(eps,v);}
637: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "EPSConvergedReasonViewFromOptions()", ) static inline PetscErrorCode EPSReasonViewFromOptions(EPS eps) {return EPSConvergedReasonViewFromOptions(eps);}
638: SLEPC_EXTERN PetscErrorCode EPSValuesView(EPS,PetscViewer);
639: SLEPC_EXTERN PetscErrorCode EPSValuesViewFromOptions(EPS);
640: SLEPC_EXTERN PetscErrorCode EPSVectorsView(EPS,PetscViewer);
641: SLEPC_EXTERN PetscErrorCode EPSVectorsViewFromOptions(EPS);
643: SLEPC_EXTERN PetscErrorCode EPSSetTarget(EPS,PetscScalar);
644: SLEPC_EXTERN PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
645: SLEPC_EXTERN PetscErrorCode EPSSetInterval(EPS,PetscReal,PetscReal);
646: SLEPC_EXTERN PetscErrorCode EPSGetInterval(EPS,PetscReal*,PetscReal*);
647: SLEPC_EXTERN PetscErrorCode EPSSetST(EPS,ST);
648: SLEPC_EXTERN PetscErrorCode EPSGetST(EPS,ST*);
649: SLEPC_EXTERN PetscErrorCode EPSSetBV(EPS,BV);
650: SLEPC_EXTERN PetscErrorCode EPSGetBV(EPS,BV*);
651: SLEPC_EXTERN PetscErrorCode EPSSetRG(EPS,RG);
652: SLEPC_EXTERN PetscErrorCode EPSGetRG(EPS,RG*);
653: SLEPC_EXTERN PetscErrorCode EPSSetDS(EPS,DS);
654: SLEPC_EXTERN PetscErrorCode EPSGetDS(EPS,DS*);
655: SLEPC_EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
656: SLEPC_EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
657: SLEPC_EXTERN PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
658: SLEPC_EXTERN PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);
660: SLEPC_EXTERN PetscErrorCode EPSGetConvergedReason(EPS,EPSConvergedReason*);
662: SLEPC_EXTERN PetscErrorCode EPSGetConverged(EPS,PetscInt*);
663: SLEPC_EXTERN PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
664: SLEPC_EXTERN PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);
665: SLEPC_EXTERN PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);
666: SLEPC_EXTERN PetscErrorCode EPSGetLeftEigenvector(EPS,PetscInt,Vec,Vec);
668: SLEPC_EXTERN PetscErrorCode EPSComputeError(EPS,PetscInt,EPSErrorType,PetscReal*);
669: 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);}
670: 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);}
671: SLEPC_EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec[]);
672: SLEPC_EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
673: SLEPC_EXTERN PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);
675: SLEPC_EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
676: SLEPC_EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
677: SLEPC_EXTERN PetscErrorCode EPSSetThreshold(EPS,PetscReal,PetscBool);
678: SLEPC_EXTERN PetscErrorCode EPSGetThreshold(EPS,PetscReal*,PetscBool*);
679: SLEPC_EXTERN PetscErrorCode EPSSetTwoSided(EPS,PetscBool);
680: SLEPC_EXTERN PetscErrorCode EPSGetTwoSided(EPS,PetscBool*);
681: SLEPC_EXTERN PetscErrorCode EPSSetTrueResidual(EPS,PetscBool);
682: SLEPC_EXTERN PetscErrorCode EPSGetTrueResidual(EPS,PetscBool*);
683: SLEPC_EXTERN PetscErrorCode EPSSetPurify(EPS,PetscBool);
684: SLEPC_EXTERN PetscErrorCode EPSGetPurify(EPS,PetscBool*);
685: SLEPC_EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscBool*);
686: SLEPC_EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscBool*);
687: SLEPC_EXTERN PetscErrorCode EPSIsPositive(EPS,PetscBool*);
688: SLEPC_EXTERN PetscErrorCode EPSIsStructured(EPS,PetscBool*);
690: SLEPC_EXTERN PetscErrorCode EPSSetTrackAll(EPS,PetscBool);
691: SLEPC_EXTERN PetscErrorCode EPSGetTrackAll(EPS,PetscBool*);
693: SLEPC_EXTERN PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec[]);
694: SLEPC_EXTERN PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec[]);
695: SLEPC_EXTERN PetscErrorCode EPSSetLeftInitialSpace(EPS,PetscInt,Vec[]);
697: /*S
698: EPSMonitorFn - A function prototype for functions provided to `EPSMonitorSet()`.
700: Calling Sequence:
701: + eps - the linear eigensolver context
702: . its - iteration number
703: . nconv - number of converged eigenpairs
704: . eigr - real part of the eigenvalues
705: . eigi - imaginary part of the eigenvalues
706: . errest - relative error estimates for each eigenpair
707: . nest - number of error estimates
708: - ctx - optional monitoring context, as provided with `EPSMonitorSet()`
710: Level: intermediate
712: .seealso: [](ch:eps), `EPSMonitorSet()`
713: S*/
714: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar eigr[],PetscScalar eigi[],PetscReal errest[],PetscInt nest,PetscCtx ctx);
716: /*S
717: EPSMonitorRegisterFn - A function prototype for functions provided to `EPSMonitorRegister()`.
719: Calling Sequence:
720: + eps - the linear eigensolver context
721: . its - iteration number
722: . nconv - number of converged eigenpairs
723: . eigr - real part of the eigenvalues
724: . eigi - imaginary part of the eigenvalues
725: . errest - relative error estimates for each eigenpair
726: . nest - number of error estimates
727: - ctx - `PetscViewerAndFormat` object
729: Level: advanced
731: Note:
732: This is an `EPSMonitorFn` specialized for a context of `PetscViewerAndFormat`.
734: .seealso: [](ch:eps), `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterCreateFn`, `EPSMonitorRegisterDestroyFn`
735: S*/
736: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar eigr[],PetscScalar eigi[],PetscReal errest[],PetscInt nest,PetscViewerAndFormat *ctx);
738: /*S
739: EPSMonitorRegisterCreateFn - A function prototype for functions that do the
740: creation when provided to `EPSMonitorRegister()`.
742: Calling Sequence:
743: + viewer - the viewer to be used with the `EPSMonitorRegisterFn`
744: . format - the format of the viewer
745: . ctx - a context for the monitor
746: - result - a `PetscViewerAndFormat` object
748: Level: advanced
750: .seealso: [](ch:eps), `EPSMonitorRegisterFn`, `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterDestroyFn`
751: S*/
752: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,PetscCtx ctx,PetscViewerAndFormat **result);
754: /*S
755: EPSMonitorRegisterDestroyFn - A function prototype for functions that do the after
756: use destruction when provided to `EPSMonitorRegister()`.
758: Calling Sequence:
759: . vf - a `PetscViewerAndFormat` object to be destroyed, including any context
761: Level: advanced
763: .seealso: [](ch:eps), `EPSMonitorRegisterFn`, `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterCreateFn`
764: S*/
765: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterDestroyFn(PetscViewerAndFormat **result);
767: SLEPC_EXTERN PetscErrorCode EPSMonitor(EPS,PetscInt,PetscInt,PetscScalar[],PetscScalar[],PetscReal[],PetscInt);
768: SLEPC_EXTERN PetscErrorCode EPSMonitorSet(EPS,EPSMonitorFn,PetscCtx,PetscCtxDestroyFn*);
769: SLEPC_EXTERN PetscErrorCode EPSMonitorCancel(EPS);
770: SLEPC_EXTERN PetscErrorCode EPSGetMonitorContext(EPS,PetscCtxRt);
772: SLEPC_EXTERN PetscErrorCode EPSMonitorSetFromOptions(EPS,const char[],const char[],PetscCtx,PetscBool);
773: SLEPC_EXTERN EPSMonitorRegisterFn EPSMonitorFirst;
774: SLEPC_EXTERN EPSMonitorRegisterFn EPSMonitorFirstDrawLG;
775: SLEPC_EXTERN EPSMonitorRegisterCreateFn EPSMonitorFirstDrawLGCreate;
776: SLEPC_EXTERN EPSMonitorRegisterFn EPSMonitorAll;
777: SLEPC_EXTERN EPSMonitorRegisterFn EPSMonitorAllDrawLG;
778: SLEPC_EXTERN EPSMonitorRegisterCreateFn EPSMonitorAllDrawLGCreate;
779: SLEPC_EXTERN EPSMonitorRegisterFn EPSMonitorConverged;
780: SLEPC_EXTERN EPSMonitorRegisterCreateFn EPSMonitorConvergedCreate;
781: SLEPC_EXTERN EPSMonitorRegisterFn EPSMonitorConvergedDrawLG;
782: SLEPC_EXTERN EPSMonitorRegisterCreateFn EPSMonitorConvergedDrawLGCreate;
784: SLEPC_EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char[]);
785: SLEPC_EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char[]);
786: SLEPC_EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);
788: SLEPC_EXTERN PetscFunctionList EPSList;
789: SLEPC_EXTERN PetscFunctionList EPSMonitorList;
790: SLEPC_EXTERN PetscFunctionList EPSMonitorCreateList;
791: SLEPC_EXTERN PetscFunctionList EPSMonitorDestroyList;
792: SLEPC_EXTERN PetscErrorCode EPSRegister(const char[],PetscErrorCode(*)(EPS));
793: SLEPC_EXTERN PetscErrorCode EPSMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,EPSMonitorRegisterFn*,EPSMonitorRegisterCreateFn*,EPSMonitorRegisterDestroyFn*);
795: SLEPC_EXTERN PetscErrorCode EPSSetWorkVecs(EPS,PetscInt);
796: SLEPC_EXTERN PetscErrorCode EPSAllocateSolution(EPS,PetscInt);
797: SLEPC_EXTERN PetscErrorCode EPSReallocateSolution(EPS,PetscInt);
799: /*S
800: EPSConvergenceTestFn - A prototype of an `EPS` convergence test function that
801: would be passed to `EPSSetConvergenceTestFunction()`.
803: Calling Sequence:
804: + eps - the linear eigensolver context
805: . eigr - real part of the eigenvalue
806: . eigi - imaginary part of the eigenvalue
807: . res - residual norm associated to the eigenpair
808: . errest - [output] computed error estimate
809: - ctx - optional convergence context, as set by `EPSSetConvergenceTestFunction()`
811: Level: advanced
813: .seealso: [](ch:eps), `EPSSetConvergenceTest()`, `EPSSetConvergenceTestFunction()`
814: S*/
815: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSConvergenceTestFn(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,PetscCtx ctx);
817: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTest(EPS,EPSConv);
818: SLEPC_EXTERN PetscErrorCode EPSGetConvergenceTest(EPS,EPSConv*);
819: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedAbsolute;
820: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedRelative;
821: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedNorm;
822: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTestFunction(EPS,EPSConvergenceTestFn*,PetscCtx,PetscCtxDestroyFn*);
824: /*S
825: EPSStoppingTestFn - A prototype of an `EPS` stopping test function that would
826: be passed to `EPSSetStoppingTestFunction()`.
828: Calling Sequence:
829: + eps - the linear eigensolver context
830: . its - current number of iterations
831: . max_it - maximum number of iterations
832: . nconv - number of currently converged eigenpairs
833: . nev - number of requested eigenpairs
834: . reason - [output] result of the stopping test
835: - ctx - optional stopping context, as set by `EPSSetStoppingTestFunction()`
837: Note:
838: A positive value of `reason` indicates that the iteration has finished successfully
839: (converged), and a negative value indicates an error condition (diverged). If
840: the iteration needs to be continued, `reason` must be set to `EPS_CONVERGED_ITERATING`
841: (zero).
843: Level: advanced
845: .seealso: [](ch:eps), `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
846: S*/
847: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSStoppingTestFn(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,PetscCtx ctx);
849: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTest(EPS,EPSStop);
850: SLEPC_EXTERN PetscErrorCode EPSGetStoppingTest(EPS,EPSStop*);
851: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingBasic;
852: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingThreshold;
853: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTestFunction(EPS,EPSStoppingTestFn*,PetscCtx,PetscCtxDestroyFn*);
855: SLEPC_EXTERN PetscErrorCode EPSSetEigenvalueComparison(EPS,SlepcEigenvalueComparisonFn*,PetscCtx);
856: SLEPC_EXTERN PetscErrorCode EPSSetArbitrarySelection(EPS,SlepcArbitrarySelectionFn*,PetscCtx);
857: SLEPC_EXTERN PetscErrorCode EPSSetArbitrarySelectionContextDestroy(EPS,PetscCtxDestroyFn*);
859: /* --------- options specific to particular eigensolvers -------- */
861: /*E
862: EPSPowerShiftType - The type of shift used in the Power iteration solver.
864: Values:
865: + `EPS_POWER_SHIFT_CONSTANT` - constant shift
866: . `EPS_POWER_SHIFT_RAYLEIGH` - variable shift using Rayleigh quotient
867: - `EPS_POWER_SHIFT_WILKINSON` - variable shift using Wilkinson's approach
869: Note:
870: Details of the three variants can be found in {cite:p}`Her05`.
872: Level: advanced
874: .seealso: [](ch:eps), `EPSPowerSetShiftType()`, `EPSPowerGetShiftType()`
875: E*/
876: typedef enum { EPS_POWER_SHIFT_CONSTANT,
877: EPS_POWER_SHIFT_RAYLEIGH,
878: EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;
879: SLEPC_EXTERN const char *EPSPowerShiftTypes[];
881: /*MC
882: EPS_POWER_SHIFT_CONSTANT - The power iteration will use a constant shift.
884: Note:
885: Together with `STSINVERT`, the `EPSPOWER` solver implements the inverse iteration
886: method, i.e., it will apply $(A-\sigma I)^{-1}$ at each iteration, by solving
887: a linear system. By default, the shift $\sigma$ is constant and given by the
888: user with `EPSSetTarget()`.
890: Details of the three variants can be found in {cite:p}`Her05`.
892: Level: advanced
894: .seealso: [](ch:eps), `EPSPowerShiftType`, `EPSPowerSetShiftType()`, `STSetShift()`, `EPSSetTarget()`, `EPS_POWER_SHIFT_RAYLEIGH`, `EPS_POWER_SHIFT_WILKINSON`
895: M*/
897: /*MC
898: EPS_POWER_SHIFT_RAYLEIGH - The power iteration will use a variable shift
899: computed with the Rayleigh quotient.
901: Notes:
902: Together with `STSINVERT`, the `EPSPOWER` solver implements the inverse iteration
903: method, i.e., it will apply $(A-\sigma I)^{-1}$ at each iteration, by solving
904: a linear system. With this strategy, the value of the shift will be updated at
905: each iteration as $\sigma=\frac{x^*Ax}{x^*x}$, where $x$ is the current eigenvector
906: approximation. The resulting iteration is the RQI method.
908: Updating the shift may involve a high computational cost if the linear solve
909: is done via a factorization.
911: Details of the three variants can be found in {cite:p}`Her05`.
913: Level: advanced
915: .seealso: [](ch:eps), `EPSPowerShiftType`, `EPSPowerSetShiftType()`, `STSetShift()`, `EPSSetTarget()`, `EPS_POWER_SHIFT_CONSTANT`, `EPS_POWER_SHIFT_WILKINSON`
916: M*/
918: /*MC
919: EPS_POWER_SHIFT_WILKINSON - The power iteration will use a variable shift
920: computed with Wilkinson's approach.
922: Note:
923: Together with `STSINVERT`, the `EPSPOWER` solver implements the inverse iteration
924: method, i.e., it will apply $(A-\sigma I)^{-1}$ at each iteration, by solving
925: a linear system. With this strategy, the value of the shift will be updated at
926: each iteration as proposed by Wilkinson, see {cite:p}`Par80{8.10}`.
928: Updating the shift may involve a high computational cost if the linear solve
929: is done via a factorization.
931: Details of the three variants can be found in {cite:p}`Her05`.
933: Level: advanced
935: .seealso: [](ch:eps), `EPSPowerShiftType`, `EPSPowerSetShiftType()`, `STSetShift()`, `EPSSetTarget()`, `EPS_POWER_SHIFT_CONSTANT`, `EPS_POWER_SHIFT_RAYLEIGH`
936: M*/
938: SLEPC_EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
939: SLEPC_EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);
940: SLEPC_EXTERN PetscErrorCode EPSPowerSetNonlinear(EPS,PetscBool);
941: SLEPC_EXTERN PetscErrorCode EPSPowerGetNonlinear(EPS,PetscBool*);
942: SLEPC_EXTERN PetscErrorCode EPSPowerSetUpdate(EPS,PetscBool);
943: SLEPC_EXTERN PetscErrorCode EPSPowerGetUpdate(EPS,PetscBool*);
944: SLEPC_EXTERN PetscErrorCode EPSPowerSetSignNormalization(EPS,PetscBool);
945: SLEPC_EXTERN PetscErrorCode EPSPowerGetSignNormalization(EPS,PetscBool*);
946: SLEPC_EXTERN PetscErrorCode EPSPowerSetSNES(EPS,SNES);
947: SLEPC_EXTERN PetscErrorCode EPSPowerGetSNES(EPS,SNES*);
949: SLEPC_EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscBool);
950: SLEPC_EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscBool*);
952: /*E
953: EPSKrylovSchurBSEType - The method to be used in the Krylov-Schur solver
954: for the case of BSE structured eigenproblems.
956: Values:
957: + `EPS_KRYLOVSCHUR_BSE_SHAO` - a Lanczos method proposed by Shao and coauthors
958: . `EPS_KRYLOVSCHUR_BSE_GRUNING` - a Lanczos method proposed by Gruning and coauthors
959: - `EPS_KRYLOVSCHUR_BSE_PROJECTEDBSE` - a Lanczos method resulting is a projected problem with BSE structure
961: Note:
962: All variants are implemented in combination with a thick restart, see
963: the details in {cite:p}`Alv25`.
965: Level: advanced
967: .seealso: [](ch:eps), `EPSKrylovSchurSetBSEType()`, `EPSKrylovSchurGetBSEType()`
968: E*/
969: typedef enum { EPS_KRYLOVSCHUR_BSE_SHAO,
970: EPS_KRYLOVSCHUR_BSE_GRUNING,
971: EPS_KRYLOVSCHUR_BSE_PROJECTEDBSE } EPSKrylovSchurBSEType;
972: SLEPC_EXTERN const char *EPSKrylovSchurBSETypes[];
974: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetBSEType(EPS,EPSKrylovSchurBSEType);
975: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetBSEType(EPS,EPSKrylovSchurBSEType*);
976: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetRestart(EPS,PetscReal);
977: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetRestart(EPS,PetscReal*);
978: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetLocking(EPS,PetscBool);
979: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetLocking(EPS,PetscBool*);
980: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetPartitions(EPS,PetscInt);
981: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetPartitions(EPS,PetscInt*);
982: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDetectZeros(EPS,PetscBool);
983: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDetectZeros(EPS,PetscBool*);
984: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
985: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);
986: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetSubintervals(EPS,PetscReal[]);
987: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubintervals(EPS,PetscReal*[]);
988: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetInertias(EPS,PetscInt*,PetscReal*[],PetscInt*[]);
989: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommInfo(EPS,PetscInt*,PetscInt*,Vec*);
990: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommPairs(EPS,PetscInt,PetscScalar*,Vec);
991: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommMats(EPS,Mat*,Mat*);
992: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurUpdateSubcommMats(EPS,PetscScalar,PetscScalar,Mat,PetscScalar,PetscScalar, Mat,MatStructure,PetscBool);
993: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetKSP(EPS,KSP*);
995: /*E
996: EPSLanczosReorthogType - The type of reorthogonalization used in `EPSLANCZOS`.
998: Values:
999: + `EPS_LANCZOS_REORTHOG_LOCAL` - local orthogonalization, only involves previous two vectors
1000: . `EPS_LANCZOS_REORTHOG_FULL` - full orthogonalization against all previous vectors
1001: . `EPS_LANCZOS_REORTHOG_SELECTIVE` - selective reorthogonalization against nearly converged Ritz vectors
1002: . `EPS_LANCZOS_REORTHOG_PERIODIC` - periodic reorthogonalization against all previous vectors
1003: . `EPS_LANCZOS_REORTHOG_PARTIAL` - partial reorthogonalization against as subset of previous vectors
1004: - `EPS_LANCZOS_REORTHOG_DELAYED` - full orthogonalization with delayed reorthogonalization
1006: Note:
1007: Details of the different reorthogonalization strategies can be found in
1008: {cite:p}`Her06`.
1010: Level: advanced
1012: .seealso: [](ch:eps), `EPSLanczosSetReorthog()`, `EPSLanczosGetReorthog()`
1013: E*/
1014: typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,
1015: EPS_LANCZOS_REORTHOG_FULL,
1016: EPS_LANCZOS_REORTHOG_SELECTIVE,
1017: EPS_LANCZOS_REORTHOG_PERIODIC,
1018: EPS_LANCZOS_REORTHOG_PARTIAL,
1019: EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;
1020: SLEPC_EXTERN const char *EPSLanczosReorthogTypes[];
1022: SLEPC_EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
1023: SLEPC_EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);
1025: /*E
1026: EPSPRIMMEMethod - The method selected in the PRIMME library.
1028: Note:
1029: See the documentation of PRIMME {cite:p}`Sta10` for a description of the methods.
1031: Level: advanced
1033: .seealso: [](ch:eps), `EPSPRIMMESetMethod()`, `EPSPRIMMEGetMethod()`
1034: E*/
1035: typedef enum { EPS_PRIMME_DYNAMIC = 1,
1036: EPS_PRIMME_DEFAULT_MIN_TIME = 2,
1037: EPS_PRIMME_DEFAULT_MIN_MATVECS = 3,
1038: EPS_PRIMME_ARNOLDI = 4,
1039: EPS_PRIMME_GD = 5,
1040: EPS_PRIMME_GD_PLUSK = 6,
1041: EPS_PRIMME_GD_OLSEN_PLUSK = 7,
1042: EPS_PRIMME_JD_OLSEN_PLUSK = 8,
1043: EPS_PRIMME_RQI = 9,
1044: EPS_PRIMME_JDQR = 10,
1045: EPS_PRIMME_JDQMR = 11,
1046: EPS_PRIMME_JDQMR_ETOL = 12,
1047: EPS_PRIMME_SUBSPACE_ITERATION = 13,
1048: EPS_PRIMME_LOBPCG_ORTHOBASIS = 14,
1049: EPS_PRIMME_LOBPCG_ORTHOBASISW = 15 } EPSPRIMMEMethod;
1050: SLEPC_EXTERN const char *EPSPRIMMEMethods[];
1052: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS,PetscInt);
1053: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS,PetscInt*);
1054: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS,EPSPRIMMEMethod);
1055: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS,EPSPRIMMEMethod*);
1057: SLEPC_EXTERN PetscErrorCode EPSGDSetKrylovStart(EPS,PetscBool);
1058: SLEPC_EXTERN PetscErrorCode EPSGDGetKrylovStart(EPS,PetscBool*);
1059: SLEPC_EXTERN PetscErrorCode EPSGDSetBlockSize(EPS,PetscInt);
1060: SLEPC_EXTERN PetscErrorCode EPSGDGetBlockSize(EPS,PetscInt*);
1061: SLEPC_EXTERN PetscErrorCode EPSGDSetRestart(EPS,PetscInt,PetscInt);
1062: SLEPC_EXTERN PetscErrorCode EPSGDGetRestart(EPS,PetscInt*,PetscInt*);
1063: SLEPC_EXTERN PetscErrorCode EPSGDSetInitialSize(EPS,PetscInt);
1064: SLEPC_EXTERN PetscErrorCode EPSGDGetInitialSize(EPS,PetscInt*);
1065: SLEPC_EXTERN PetscErrorCode EPSGDSetBOrth(EPS,PetscBool);
1066: SLEPC_EXTERN PetscErrorCode EPSGDGetBOrth(EPS,PetscBool*);
1067: SLEPC_EXTERN PetscErrorCode EPSGDSetDoubleExpansion(EPS,PetscBool);
1068: SLEPC_EXTERN PetscErrorCode EPSGDGetDoubleExpansion(EPS,PetscBool*);
1070: SLEPC_EXTERN PetscErrorCode EPSJDSetKrylovStart(EPS,PetscBool);
1071: SLEPC_EXTERN PetscErrorCode EPSJDGetKrylovStart(EPS,PetscBool*);
1072: SLEPC_EXTERN PetscErrorCode EPSJDSetBlockSize(EPS,PetscInt);
1073: SLEPC_EXTERN PetscErrorCode EPSJDGetBlockSize(EPS,PetscInt*);
1074: SLEPC_EXTERN PetscErrorCode EPSJDSetRestart(EPS,PetscInt,PetscInt);
1075: SLEPC_EXTERN PetscErrorCode EPSJDGetRestart(EPS,PetscInt*,PetscInt*);
1076: SLEPC_EXTERN PetscErrorCode EPSJDSetInitialSize(EPS,PetscInt);
1077: SLEPC_EXTERN PetscErrorCode EPSJDGetInitialSize(EPS,PetscInt*);
1078: SLEPC_EXTERN PetscErrorCode EPSJDSetFix(EPS,PetscReal);
1079: SLEPC_EXTERN PetscErrorCode EPSJDGetFix(EPS,PetscReal*);
1080: SLEPC_EXTERN PetscErrorCode EPSJDSetConstCorrectionTol(EPS,PetscBool);
1081: SLEPC_EXTERN PetscErrorCode EPSJDGetConstCorrectionTol(EPS,PetscBool*);
1082: SLEPC_EXTERN PetscErrorCode EPSJDSetBOrth(EPS,PetscBool);
1083: SLEPC_EXTERN PetscErrorCode EPSJDGetBOrth(EPS,PetscBool*);
1085: SLEPC_EXTERN PetscErrorCode EPSRQCGSetReset(EPS,PetscInt);
1086: SLEPC_EXTERN PetscErrorCode EPSRQCGGetReset(EPS,PetscInt*);
1088: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetBlockSize(EPS,PetscInt);
1089: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetBlockSize(EPS,PetscInt*);
1090: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetRestart(EPS,PetscReal);
1091: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetRestart(EPS,PetscReal*);
1092: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetLocking(EPS,PetscBool);
1093: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetLocking(EPS,PetscBool*);
1095: /*E
1096: EPSCISSQuadRule - The quadrature rule used in the `EPSCISS` solver.
1098: Values:
1099: + `EPS_CISS_QUADRULE_TRAPEZOIDAL` - trapezoidal rule
1100: - `EPS_CISS_QUADRULE_CHEBYSHEV` - Gauss quadrature on Chebyshev points
1102: Note:
1103: For a detailed description see {cite:p}`Mae16`.
1105: Level: advanced
1107: .seealso: [](ch:eps), `EPSCISSSetQuadRule()`, `EPSCISSGetQuadRule()`
1108: E*/
1109: typedef enum { EPS_CISS_QUADRULE_TRAPEZOIDAL = 1,
1110: EPS_CISS_QUADRULE_CHEBYSHEV = 2 } EPSCISSQuadRule;
1111: SLEPC_EXTERN const char *EPSCISSQuadRules[];
1113: /*E
1114: EPSCISSExtraction - The extraction technique used in the `EPSCISS` solver.
1116: Values:
1117: + `EPS_CISS_EXTRACTION_RITZ` - Ritz approximations from Rayleigh-Ritz projection
1118: - `EPS_CISS_EXTRACTION_HANKEL` - use Hankel pencil as in the original Sakurai-Sugiura method
1120: Note:
1121: For a detailed description see {cite:p}`Mae16`.
1123: Level: advanced
1125: .seealso: [](ch:eps), `EPSCISSSetExtraction()`, `EPSCISSGetExtraction()`
1126: E*/
1127: typedef enum { EPS_CISS_EXTRACTION_RITZ,
1128: EPS_CISS_EXTRACTION_HANKEL } EPSCISSExtraction;
1129: SLEPC_EXTERN const char *EPSCISSExtractions[];
1131: SLEPC_EXTERN PetscErrorCode EPSCISSSetExtraction(EPS,EPSCISSExtraction);
1132: SLEPC_EXTERN PetscErrorCode EPSCISSGetExtraction(EPS,EPSCISSExtraction*);
1133: SLEPC_EXTERN PetscErrorCode EPSCISSSetQuadRule(EPS,EPSCISSQuadRule);
1134: SLEPC_EXTERN PetscErrorCode EPSCISSGetQuadRule(EPS,EPSCISSQuadRule*);
1135: SLEPC_EXTERN PetscErrorCode EPSCISSSetSizes(EPS,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscBool);
1136: SLEPC_EXTERN PetscErrorCode EPSCISSGetSizes(EPS,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscBool*);
1137: SLEPC_EXTERN PetscErrorCode EPSCISSSetThreshold(EPS,PetscReal,PetscReal);
1138: SLEPC_EXTERN PetscErrorCode EPSCISSGetThreshold(EPS,PetscReal*,PetscReal*);
1139: SLEPC_EXTERN PetscErrorCode EPSCISSSetRefinement(EPS,PetscInt,PetscInt);
1140: SLEPC_EXTERN PetscErrorCode EPSCISSGetRefinement(EPS,PetscInt*,PetscInt*);
1141: SLEPC_EXTERN PetscErrorCode EPSCISSSetUseST(EPS,PetscBool);
1142: SLEPC_EXTERN PetscErrorCode EPSCISSGetUseST(EPS,PetscBool*);
1143: SLEPC_EXTERN PetscErrorCode EPSCISSGetKSPs(EPS,PetscInt*,KSP*[]);
1145: SLEPC_EXTERN PetscErrorCode EPSLyapIISetLME(EPS,LME);
1146: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetLME(EPS,LME*);
1147: SLEPC_EXTERN PetscErrorCode EPSLyapIISetRanks(EPS,PetscInt,PetscInt);
1148: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetRanks(EPS,PetscInt*,PetscInt*);
1150: SLEPC_EXTERN PetscErrorCode EPSBLOPEXSetBlockSize(EPS,PetscInt);
1151: SLEPC_EXTERN PetscErrorCode EPSBLOPEXGetBlockSize(EPS,PetscInt*);
1153: /*E
1154: EPSEVSLDOSMethod - The method to approximate the density of states (DOS)
1155: in the `EPSEVSL` solver.
1157: Values:
1158: + `EPS_EVSL_DOS_KPM` - Kernel Polynomial Method
1159: - `EPS_EVSL_DOS_LANCZOS` - Lanczos method
1161: Note:
1162: See the documentation of EVSL {cite:p}`Li19` for an explanation.
1164: Level: advanced
1166: .seealso: [](ch:eps), `EPSEVSLSetDOSParameters()`, `EPSEVSLGetDOSParameters()`
1167: E*/
1168: typedef enum { EPS_EVSL_DOS_KPM,
1169: EPS_EVSL_DOS_LANCZOS } EPSEVSLDOSMethod;
1170: SLEPC_EXTERN const char *EPSEVSLDOSMethods[];
1172: /*E
1173: EPSEVSLDamping - The damping type used in the `EPSEVSL` solver.
1175: Values:
1176: + `EPS_EVSL_DAMPING_NONE` - no damping
1177: . `EPS_EVSL_DAMPING_JACKSON` - Jackson damping
1178: - `EPS_EVSL_DAMPING_SIGMA` - Lanczos damping
1180: Note:
1181: See the documentation of EVSL {cite:p}`Li19` for an explanation.
1183: Level: advanced
1185: .seealso: [](ch:eps), `EPSEVSLSetDOSParameters()`, `EPSEVSLGetDOSParameters()`
1186: E*/
1187: typedef enum { EPS_EVSL_DAMPING_NONE,
1188: EPS_EVSL_DAMPING_JACKSON,
1189: EPS_EVSL_DAMPING_SIGMA } EPSEVSLDamping;
1190: SLEPC_EXTERN const char *EPSEVSLDampings[];
1192: SLEPC_EXTERN PetscErrorCode EPSEVSLSetRange(EPS,PetscReal,PetscReal);
1193: SLEPC_EXTERN PetscErrorCode EPSEVSLGetRange(EPS,PetscReal*,PetscReal*);
1194: SLEPC_EXTERN PetscErrorCode EPSEVSLSetSlices(EPS,PetscInt);
1195: SLEPC_EXTERN PetscErrorCode EPSEVSLGetSlices(EPS,PetscInt*);
1196: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDOSParameters(EPS,EPSEVSLDOSMethod,PetscInt,PetscInt,PetscInt,PetscInt);
1197: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDOSParameters(EPS,EPSEVSLDOSMethod*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
1198: SLEPC_EXTERN PetscErrorCode EPSEVSLSetPolParameters(EPS,PetscInt,PetscReal);
1199: SLEPC_EXTERN PetscErrorCode EPSEVSLGetPolParameters(EPS,PetscInt*,PetscReal*);
1200: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDamping(EPS,EPSEVSLDamping);
1201: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDamping(EPS,EPSEVSLDamping*);
1203: SLEPC_EXTERN PetscErrorCode EPSFEASTSetNumPoints(EPS,PetscInt);
1204: SLEPC_EXTERN PetscErrorCode EPSFEASTGetNumPoints(EPS,PetscInt*);
1206: SLEPC_EXTERN PetscErrorCode EPSCHASESetDegree(EPS,PetscInt,PetscBool);
1207: SLEPC_EXTERN PetscErrorCode EPSCHASEGetDegree(EPS,PetscInt*,PetscBool*);