Actual source code: slepcsvd.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 SLEPc's singular value solvers
12: */
14: #pragma once
16: #include <slepceps.h>
17: #include <slepcbv.h>
18: #include <slepcds.h>
20: /* SUBMANSEC = SVD */
22: SLEPC_EXTERN PetscErrorCode SVDInitializePackage(void);
23: SLEPC_EXTERN PetscErrorCode SVDFinalizePackage(void);
25: /*S
26: SVD - SLEPc object that manages all the singular value problem solvers.
28: Level: beginner
30: .seealso: [](ch:svd), `SVDCreate()`
31: S*/
32: typedef struct _p_SVD* SVD;
34: /*J
35: SVDType - String with the name of a singular value solver.
37: Level: beginner
39: .seealso: [](ch:svd), `SVDSetType()`, `SVD`
40: J*/
41: typedef const char *SVDType;
42: #define SVDCROSS "cross"
43: #define SVDCYCLIC "cyclic"
44: #define SVDLANCZOS "lanczos"
45: #define SVDTRLANCZOS "trlanczos"
46: #define SVDRANDOMIZED "randomized"
47: #define SVDLAPACK "lapack"
48: #define SVDSCALAPACK "scalapack"
49: #define SVDKSVD "ksvd"
50: #define SVDELEMENTAL "elemental"
51: #define SVDPRIMME "primme"
53: /* Logging support */
54: SLEPC_EXTERN PetscClassId SVD_CLASSID;
56: /*E
57: SVDProblemType - Determines the type of the singular value problem.
59: Values:
60: + `SVD_STANDARD` - standard SVD (SVD)
61: . `SVD_GENERALIZED` - generalized SVD (GSVD)
62: - `SVD_HYPERBOLIC` - hyperbolic SVD (HSVD)
64: Level: beginner
66: .seealso: [](ch:svd), `SVDSetProblemType()`, `SVDGetProblemType()`
67: E*/
68: typedef enum { SVD_STANDARD = 1,
69: SVD_GENERALIZED = 2,
70: SVD_HYPERBOLIC = 3
71: } SVDProblemType;
73: /*MC
74: SVD_STANDARD - A (standard) singular value problem (SVD).
76: Note:
77: The problem is formulated as $A=U\Sigma V^*$, where $A$ is a possibly
78: non-square matrix.
80: Level: beginner
82: .seealso: [](ch:svd), `SVDProblemType`, `SVDSetProblemType()`, `SVD_GENERALIZED`, `SVD_HYPERBOLIC`
83: M*/
85: /*MC
86: SVD_GENERALIZED - A generalized singular value problem (GSVD).
88: Note:
89: The problem is formulated as $U^*AX=C$, $V^*BX=S$, where $A$ and $B$
90: have the same number of columns.
92: Level: beginner
94: .seealso: [](ch:svd), `SVDProblemType`, `SVDSetProblemType()`, `SVD_STANDARD`, `SVD_HYPERBOLIC`
95: M*/
97: /*MC
98: SVD_HYPERBOLIC - A hyperbolic singular value problem (HSVD).
100: Note:
101: The problem is formulated as $A=U\Sigma V^*$, with $U^*\Omega U=\tilde\Omega$,
102: where $A$ is a possibly non-square matrix, and $\Omega$, $\tilde\Omega$
103: are signature matrices.
105: Level: beginner
107: .seealso: [](ch:svd), `SVDProblemType`, `SVDSetProblemType()`, `SVD_STANDARD`, `SVD_GENERALIZED`
108: M*/
110: /*E
111: SVDWhich - Determines whether largest or smallest singular values
112: are to be computed.
114: Values:
115: + `SVD_LARGEST` - largest singular values
116: - `SVD_SMALLEST` - smallest singular values
118: Level: intermediate
120: .seealso: [](ch:svd), `SVDSetWhichSingularTriplets()`, `SVDGetWhichSingularTriplets()`
121: E*/
122: typedef enum { SVD_LARGEST,
123: SVD_SMALLEST } SVDWhich;
125: /*MC
126: SVD_LARGEST - The solver is configured to compute largest singular values.
128: Note:
129: This is the default.
131: Level: intermediate
133: .seealso: [](ch:svd), `SVDWhich`, `SVDSetWhichSingularTriplets()`, `SVD_SMALLEST`
134: M*/
136: /*MC
137: SVD_SMALLEST - The solver is configured to compute smallest singular values.
139: Note:
140: Computing small singular values is generally more difficult than computing
141: largest ones, because in many cases these values are very small and
142: tightly clustered together. In the case of rank-deficient matrices, smallest
143: singular values are zero, and this may pose difficulties to the solvers.
145: Level: intermediate
147: .seealso: [](ch:svd), `SVDWhich`, `SVDSetWhichSingularTriplets()`, `SVD_LARGEST`
148: M*/
150: /*E
151: SVDErrorType - The error type used to assess accuracy of computed solutions.
153: Values:
154: + `SVD_ERROR_ABSOLUTE` - compute error bound as $\|r\|$
155: . `SVD_ERROR_RELATIVE` - compute error bound as $\|r\|/\sigma$
156: - `SVD_ERROR_NORM` - compute error bound as $\|r\|/\max\{\|A\|,\|B\|\}$
158: Note:
159: The residual norm $\|r\|$ is actually computed from two parts, such as
160: $\sqrt{\eta_1^2+\eta_2^2}$ with $\eta_1 = \|Av-\sigma u\|_2$ and
161: $\eta_2 = \|A^*u-\sigma v\|_2$, see more details at `SVDComputeError()`.
162: There is also a normalization factor related to the norm of the vectors,
163: which also varies with the problem type.
165: Level: intermediate
167: .seealso: [](ch:svd), `SVDComputeError()`, `SVDProblemType`
168: E*/
169: typedef enum { SVD_ERROR_ABSOLUTE,
170: SVD_ERROR_RELATIVE,
171: SVD_ERROR_NORM } SVDErrorType;
172: SLEPC_EXTERN const char *SVDErrorTypes[];
174: /*E
175: SVDConv - The convergence criterion to be used by the solver.
177: Values:
178: + `SVD_CONV_ABS` - absolute convergence criterion, $\|r\|$
179: . `SVD_CONV_REL` - convergence criterion relative to singular value, $\|r\|/\sigma$
180: . `SVD_CONV_NORM` - convergence criterion relative to matrix norms, $\|r\|/\max\{\|A\|,\|B\|\}$
181: . `SVD_CONV_MAXIT` - no convergence until maximum number of iterations has been reached
182: - `SVD_CONV_USER` - convergence dictated by user-provided function
184: Note:
185: The `SVD_CONV_MAXIT` convergence criterion is used only in `SVDRANDOMIZED`.
187: Level: intermediate
189: .seealso: [](ch:svd), `SVDSetConvergenceTest()`, `SVDSetConvergenceTestFunction()`, `SVDSetTolerances()`
190: E*/
191: typedef enum { SVD_CONV_ABS,
192: SVD_CONV_REL,
193: SVD_CONV_NORM,
194: SVD_CONV_MAXIT,
195: SVD_CONV_USER } SVDConv;
197: /*E
198: SVDStop - The stopping test to decide the termination of the outer loop
199: of the singular value solver.
201: Values:
202: + `SVD_STOP_BASIC` - default stopping test
203: . `SVD_STOP_USER` - user-provided stopping test
204: - `SVD_STOP_THRESHOLD` - threshold stopping test
206: Level: advanced
208: .seealso: [](ch:svd), `SVDSetStoppingTest()`, `SVDSetStoppingTestFunction()`
209: E*/
210: typedef enum { SVD_STOP_BASIC,
211: SVD_STOP_USER,
212: SVD_STOP_THRESHOLD } SVDStop;
214: /*MC
215: SVD_STOP_BASIC - The default stopping test.
217: Note:
218: By default, the termination of the outer loop is decided by calling
219: `SVDStoppingBasic()`, which will stop if all requested singular values are converged,
220: or if the maximum number of iterations has been reached.
222: Level: advanced
224: .seealso: [](ch:svd), `SVDStop`, `SVDSetStoppingTest()`, `SVDStoppingBasic()`
225: M*/
227: /*MC
228: SVD_STOP_USER - The user-provided stopping test.
230: Note:
231: Customized stopping test using the user-provided function given with
232: `SVDSetStoppingTestFunction()`.
234: Level: advanced
236: .seealso: [](ch:svd), `SVDStop`, `SVDSetStoppingTest()`, `SVDSetStoppingTestFunction()`
237: M*/
239: /*MC
240: SVD_STOP_THRESHOLD - The threshold stopping test.
242: Note:
243: When a threshold has been provided with `SVDSetThreshold()`, the termination
244: of the outer loop is decided by calling `SVDStoppingThreshold()`, which will
245: stop when one of the computed singular values is not above/below the threshold.
246: If a number of wanted singular values has been specified via `SVDSetDimensions()`
247: then it is also taken into account, and the solver will stop when one of the
248: two conditions (threshold or number of converged values) is met.
250: Level: advanced
252: .seealso: [](ch:svd), `SVDStop`, `SVDSetStoppingTest()`, `SVDStoppingThreshold()`, `SVDSetThreshold()`, `SVDSetDimensions()`
253: M*/
255: /*E
256: SVDConvergedReason - Reason a singular value solver was determined to have
257: converged or diverged.
259: Values:
260: + `SVD_CONVERGED_TOL` - converged up to tolerance
261: . `SVD_CONVERGED_USER` - converged due to a user-defined condition
262: . `SVD_CONVERGED_MAXIT` - reached maximum number of iterations with `SVD_CONV_MAXIT` criterion
263: . `SVD_DIVERGED_ITS` - exceeded the maximum number of allowed iterations
264: . `SVD_DIVERGED_BREAKDOWN` - generic breakdown in method
265: . `SVD_DIVERGED_SYMMETRY_LOST` - underlying indefinite eigensolver was not able to keep symmetry
266: - `SVD_CONVERGED_ITERATING` - the solver is still running
268: Level: intermediate
270: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDSetTolerances()`
271: E*/
272: typedef enum {/* converged */
273: SVD_CONVERGED_TOL = 1,
274: SVD_CONVERGED_USER = 2,
275: SVD_CONVERGED_MAXIT = 3,
276: /* diverged */
277: SVD_DIVERGED_ITS = -1,
278: SVD_DIVERGED_BREAKDOWN = -2,
279: SVD_DIVERGED_SYMMETRY_LOST = -3,
280: SVD_CONVERGED_ITERATING = 0 } SVDConvergedReason;
281: SLEPC_EXTERN const char *const*SVDConvergedReasons;
283: /*MC
284: SVD_CONVERGED_TOL - The computed error estimates, based on residual norms,
285: for all requested singular values are below the tolerance.
287: Level: intermediate
289: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`
290: M*/
292: /*MC
293: SVD_CONVERGED_USER - The solver was declared converged due to a user-defined condition.
295: Note:
296: This happens only when a user-defined stopping test has been set with
297: `SVDSetStoppingTestFunction()`.
299: Level: intermediate
301: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`, `SVDSetStoppingTestFunction()`
302: M*/
304: /*MC
305: SVD_CONVERGED_MAXIT - The solver has reached the maximum number of iterations
306: with the `SVD_CONV_MAXIT` criterion.
308: Note:
309: This is considered a successful exit, because the user wanted to do a fixed
310: number of iterations. But be aware that the computed solution may be inaccurate,
311: in particular, individual singular vectors will not have good residual. This
312: is available in `SVDRANDOMIZED` only.
314: Level: intermediate
316: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`, `SVD_CONV_MAXIT`, `SVDRANDOMIZED`
317: M*/
319: /*MC
320: SVD_DIVERGED_ITS - Exceeded the maximum number of allowed iterations
321: before the convergence criterion was satisfied.
323: Level: intermediate
325: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`
326: M*/
328: /*MC
329: SVD_DIVERGED_BREAKDOWN - A breakdown in the solver was detected so the
330: method could not continue.
332: Level: intermediate
334: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`
335: M*/
337: /*MC
338: SVD_DIVERGED_SYMMETRY_LOST - The selected solver uses a pseudo-Lanczos recurrence,
339: which is numerically unstable, and a symmetry test revealed that instability
340: had appeared so the solver could not continue.
342: Level: intermediate
344: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`
345: M*/
347: /*MC
348: SVD_CONVERGED_ITERATING - This value is returned if `SVDGetConvergedReason()` is called
349: while `SVDSolve()` is still running.
351: Level: intermediate
353: .seealso: [](ch:svd), `SVDSolve()`, `SVDGetConvergedReason()`, `SVDConvergedReason`
354: M*/
356: /*S
357: SVDStoppingCtx - Data structure (C struct) to hold additional information to
358: be used in some stopping test functions.
360: Level: advanced
362: .seealso: [](ch:svd), `SVDSetStoppingTestFunction()`
363: S*/
364: struct _n_SVDStoppingCtx {
365: PetscReal firstsv; /* the value of the first converged singular value */
366: PetscReal lastsv; /* the value of the last converged singular value */
367: PetscReal thres; /* threshold set with SVDSetThreshold() */
368: PetscBool threlative; /* threshold is relative */
369: SVDWhich which; /* which singular values are being computed */
370: };
371: typedef struct _n_SVDStoppingCtx* SVDStoppingCtx;
373: SLEPC_EXTERN PetscErrorCode SVDCreate(MPI_Comm,SVD*);
374: SLEPC_EXTERN PetscErrorCode SVDSetBV(SVD,BV,BV);
375: SLEPC_EXTERN PetscErrorCode SVDGetBV(SVD,BV*,BV*);
376: SLEPC_EXTERN PetscErrorCode SVDSetDS(SVD,DS);
377: SLEPC_EXTERN PetscErrorCode SVDGetDS(SVD,DS*);
378: SLEPC_EXTERN PetscErrorCode SVDSetType(SVD,SVDType);
379: SLEPC_EXTERN PetscErrorCode SVDGetType(SVD,SVDType*);
380: SLEPC_EXTERN PetscErrorCode SVDSetProblemType(SVD,SVDProblemType);
381: SLEPC_EXTERN PetscErrorCode SVDGetProblemType(SVD,SVDProblemType*);
382: SLEPC_EXTERN PetscErrorCode SVDIsGeneralized(SVD,PetscBool*);
383: SLEPC_EXTERN PetscErrorCode SVDIsHyperbolic(SVD,PetscBool*);
384: SLEPC_EXTERN PetscErrorCode SVDSetOperators(SVD,Mat,Mat);
385: PETSC_DEPRECATED_FUNCTION(3, 15, 0, "SVDSetOperators()", ) static inline PetscErrorCode SVDSetOperator(SVD svd,Mat A) {return SVDSetOperators(svd,A,PETSC_NULLPTR);}
386: SLEPC_EXTERN PetscErrorCode SVDGetOperators(SVD,Mat*,Mat*);
387: PETSC_DEPRECATED_FUNCTION(3, 15, 0, "SVDGetOperators()", ) static inline PetscErrorCode SVDGetOperator(SVD svd,Mat *A) {return SVDGetOperators(svd,A,PETSC_NULLPTR);}
388: SLEPC_EXTERN PetscErrorCode SVDSetSignature(SVD,Vec);
389: SLEPC_EXTERN PetscErrorCode SVDGetSignature(SVD,Vec);
390: SLEPC_EXTERN PetscErrorCode SVDSetInitialSpaces(SVD,PetscInt,Vec[],PetscInt,Vec[]);
391: PETSC_DEPRECATED_FUNCTION(3, 1, 0, "SVDSetInitialSpaces()", ) static inline PetscErrorCode SVDSetInitialSpace(SVD svd,PetscInt nr,Vec *isr) {return SVDSetInitialSpaces(svd,nr,isr,0,PETSC_NULLPTR);}
392: PETSC_DEPRECATED_FUNCTION(3, 1, 0, "SVDSetInitialSpaces()", ) static inline PetscErrorCode SVDSetInitialSpaceLeft(SVD svd,PetscInt nl,Vec *isl) {return SVDSetInitialSpaces(svd,0,PETSC_NULLPTR,nl,isl);}
393: SLEPC_EXTERN PetscErrorCode SVDSetImplicitTranspose(SVD,PetscBool);
394: SLEPC_EXTERN PetscErrorCode SVDGetImplicitTranspose(SVD,PetscBool*);
395: SLEPC_EXTERN PetscErrorCode SVDSetDimensions(SVD,PetscInt,PetscInt,PetscInt);
396: SLEPC_EXTERN PetscErrorCode SVDGetDimensions(SVD,PetscInt*,PetscInt*,PetscInt*);
397: SLEPC_EXTERN PetscErrorCode SVDSetTolerances(SVD,PetscReal,PetscInt);
398: SLEPC_EXTERN PetscErrorCode SVDGetTolerances(SVD,PetscReal*,PetscInt*);
399: SLEPC_EXTERN PetscErrorCode SVDSetWhichSingularTriplets(SVD,SVDWhich);
400: SLEPC_EXTERN PetscErrorCode SVDGetWhichSingularTriplets(SVD,SVDWhich*);
401: SLEPC_EXTERN PetscErrorCode SVDSetThreshold(SVD,PetscReal,PetscBool);
402: SLEPC_EXTERN PetscErrorCode SVDGetThreshold(SVD,PetscReal*,PetscBool*);
403: SLEPC_EXTERN PetscErrorCode SVDSetFromOptions(SVD);
404: SLEPC_EXTERN PetscErrorCode SVDSetOptionsPrefix(SVD,const char[]);
405: SLEPC_EXTERN PetscErrorCode SVDAppendOptionsPrefix(SVD,const char[]);
406: SLEPC_EXTERN PetscErrorCode SVDGetOptionsPrefix(SVD,const char*[]);
407: SLEPC_EXTERN PetscErrorCode SVDSetDSType(SVD);
408: SLEPC_EXTERN PetscErrorCode SVDSetUp(SVD);
409: SLEPC_EXTERN PetscErrorCode SVDSolve(SVD);
410: SLEPC_EXTERN PetscErrorCode SVDGetIterationNumber(SVD,PetscInt*);
411: SLEPC_EXTERN PetscErrorCode SVDGetConvergedReason(SVD,SVDConvergedReason*);
412: SLEPC_EXTERN PetscErrorCode SVDGetConverged(SVD,PetscInt*);
413: SLEPC_EXTERN PetscErrorCode SVDGetSingularTriplet(SVD,PetscInt,PetscReal*,Vec,Vec);
414: SLEPC_EXTERN PetscErrorCode SVDComputeError(SVD,PetscInt,SVDErrorType,PetscReal*);
415: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "SVDComputeError()", ) static inline PetscErrorCode SVDComputeRelativeError(SVD svd,PetscInt i,PetscReal *r) {return SVDComputeError(svd,i,SVD_ERROR_RELATIVE,r);}
416: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "SVDComputeError() with SVD_ERROR_ABSOLUTE", ) static inline PetscErrorCode SVDComputeResidualNorms(SVD svd,PetscInt i,PetscReal *r1,PETSC_UNUSED PetscReal *r2) {return SVDComputeError(svd,i,SVD_ERROR_ABSOLUTE,r1);}
417: SLEPC_EXTERN PetscErrorCode SVDView(SVD,PetscViewer);
418: SLEPC_EXTERN PetscErrorCode SVDViewFromOptions(SVD,PetscObject,const char[]);
419: SLEPC_EXTERN PetscErrorCode SVDErrorView(SVD,SVDErrorType,PetscViewer);
420: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "SVDErrorView()", ) static inline PetscErrorCode SVDPrintSolution(SVD svd,PetscViewer v) {return SVDErrorView(svd,SVD_ERROR_RELATIVE,v);}
421: SLEPC_EXTERN PetscErrorCode SVDErrorViewFromOptions(SVD);
422: SLEPC_EXTERN PetscErrorCode SVDConvergedReasonView(SVD,PetscViewer);
423: SLEPC_EXTERN PetscErrorCode SVDConvergedReasonViewFromOptions(SVD);
424: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "SVDConvergedReasonView()", ) static inline PetscErrorCode SVDReasonView(SVD svd,PetscViewer v) {return SVDConvergedReasonView(svd,v);}
425: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "SVDConvergedReasonViewFromOptions()", ) static inline PetscErrorCode SVDReasonViewFromOptions(SVD svd) {return SVDConvergedReasonViewFromOptions(svd);}
426: SLEPC_EXTERN PetscErrorCode SVDValuesView(SVD,PetscViewer);
427: SLEPC_EXTERN PetscErrorCode SVDValuesViewFromOptions(SVD);
428: SLEPC_EXTERN PetscErrorCode SVDVectorsView(SVD,PetscViewer);
429: SLEPC_EXTERN PetscErrorCode SVDVectorsViewFromOptions(SVD);
430: SLEPC_EXTERN PetscErrorCode SVDDestroy(SVD*);
431: SLEPC_EXTERN PetscErrorCode SVDReset(SVD);
432: SLEPC_EXTERN PetscErrorCode SVDSetWorkVecs(SVD,PetscInt,PetscInt);
433: SLEPC_EXTERN PetscErrorCode SVDSetTrackAll(SVD,PetscBool);
434: SLEPC_EXTERN PetscErrorCode SVDGetTrackAll(SVD,PetscBool*);
436: /*S
437: SVDMonitorFn - A function prototype for functions provided to `SVDMonitorSet()`.
439: Calling Sequence:
440: + svd - the singular value solver context
441: . its - iteration number
442: . nconv - number of converged singular triplets
443: . sigma - singular values
444: . errest - relative error estimates for each singular triplet
445: . nest - number of error estimates
446: - ctx - optional monitoring context, as provided with `SVDMonitorSet()`
448: Level: intermediate
450: .seealso: [](ch:svd), `SVDMonitorSet()`
451: S*/
452: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SVDMonitorFn(SVD svd,PetscInt its,PetscInt nconv,PetscReal sigma[],PetscReal errest[],PetscInt nest,void *ctx);
454: /*S
455: SVDMonitorRegisterFn - A function prototype for functions provided to `SVDMonitorRegister()`.
457: Calling Sequence:
458: + svd - the singular value solver context
459: . its - iteration number
460: . nconv - number of converged singular triplets
461: . sigma - singular values
462: . errest - relative error estimates for each singular triplet
463: . nest - number of error estimates
464: - ctx - `PetscViewerAndFormat` object
466: Level: advanced
468: Note:
469: This is an `SVDMonitorFn` specialized for a context of `PetscViewerAndFormat`.
471: .seealso: [](ch:svd), `SVDMonitorSet()`, `SVDMonitorRegister()`, `SVDMonitorFn`, `SVDMonitorRegisterCreateFn`, `SVDMonitorRegisterDestroyFn`
472: S*/
473: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SVDMonitorRegisterFn(SVD svd,PetscInt its,PetscInt nconv,PetscReal sigma[],PetscReal errest[],PetscInt nest,PetscViewerAndFormat *ctx);
475: /*S
476: SVDMonitorRegisterCreateFn - A function prototype for functions that do
477: the creation when provided to `SVDMonitorRegister()`.
479: Calling Sequence:
480: + viewer - the viewer to be used with the `SVDMonitorRegisterFn`
481: . format - the format of the viewer
482: . ctx - a context for the monitor
483: - result - a `PetscViewerAndFormat` object
485: Level: advanced
487: .seealso: [](ch:svd), `SVDMonitorRegisterFn`, `SVDMonitorSet()`, `SVDMonitorRegister()`, `SVDMonitorFn`, `SVDMonitorRegisterDestroyFn`
488: S*/
489: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SVDMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);
491: /*S
492: SVDMonitorRegisterDestroyFn - A function prototype for functions that do the after
493: use destruction when provided to `SVDMonitorRegister()`.
495: Calling Sequence:
496: . vf - a `PetscViewerAndFormat` object to be destroyed, including any context
498: Level: advanced
500: .seealso: [](ch:svd), `SVDMonitorRegisterFn`, `SVDMonitorSet()`, `SVDMonitorRegister()`, `SVDMonitorFn`, `SVDMonitorRegisterCreateFn`
501: S*/
502: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SVDMonitorRegisterDestroyFn(PetscViewerAndFormat **result);
504: SLEPC_EXTERN PetscErrorCode SVDMonitor(SVD,PetscInt,PetscInt,PetscReal[],PetscReal[],PetscInt);
505: SLEPC_EXTERN PetscErrorCode SVDMonitorSet(SVD,SVDMonitorFn,void*,PetscCtxDestroyFn*);
506: SLEPC_EXTERN PetscErrorCode SVDMonitorCancel(SVD);
507: SLEPC_EXTERN PetscErrorCode SVDGetMonitorContext(SVD,void*);
509: SLEPC_EXTERN PetscErrorCode SVDMonitorSetFromOptions(SVD,const char[],const char[],void*,PetscBool);
510: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorFirst;
511: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorFirstDrawLG;
512: SLEPC_EXTERN SVDMonitorRegisterCreateFn SVDMonitorFirstDrawLGCreate;
513: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorAll;
514: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorAllDrawLG;
515: SLEPC_EXTERN SVDMonitorRegisterCreateFn SVDMonitorAllDrawLGCreate;
516: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorConverged;
517: SLEPC_EXTERN SVDMonitorRegisterCreateFn SVDMonitorConvergedCreate;
518: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorConvergedDrawLG;
519: SLEPC_EXTERN SVDMonitorRegisterCreateFn SVDMonitorConvergedDrawLGCreate;
520: SLEPC_EXTERN SVDMonitorRegisterDestroyFn SVDMonitorConvergedDestroy;
521: SLEPC_EXTERN SVDMonitorRegisterFn SVDMonitorConditioning;
523: SLEPC_EXTERN PetscFunctionList SVDList;
524: SLEPC_EXTERN PetscFunctionList SVDMonitorList;
525: SLEPC_EXTERN PetscFunctionList SVDMonitorCreateList;
526: SLEPC_EXTERN PetscFunctionList SVDMonitorDestroyList;
527: SLEPC_EXTERN PetscErrorCode SVDRegister(const char[],PetscErrorCode(*)(SVD));
528: SLEPC_EXTERN PetscErrorCode SVDMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,SVDMonitorRegisterFn*,SVDMonitorRegisterCreateFn*,SVDMonitorRegisterDestroyFn*);
530: SLEPC_EXTERN PetscErrorCode SVDAllocateSolution(SVD,PetscInt);
531: SLEPC_EXTERN PetscErrorCode SVDReallocateSolution(SVD,PetscInt);
533: /*S
534: SVDConvergenceTestFn - A prototype of an `SVD` convergence test function that
535: would be passed to `SVDSetConvergenceTestFunction()`.
537: Calling Sequence:
538: + svd - the singular value solver context
539: . sigma - computed singular value
540: . res - residual norm associated to the singular triplet
541: . errest - [output] computed error estimate
542: - ctx - optional convergence context, as set by `SVDSetConvergenceTestFunction()`
544: Level: advanced
546: .seealso: [](ch:svd), `SVDSetConvergenceTest()`, `SVDSetConvergenceTestFunction()`
547: S*/
548: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SVDConvergenceTestFn(SVD svd,PetscReal sigma,PetscReal res,PetscReal *errest,void *ctx);
550: SLEPC_EXTERN PetscErrorCode SVDSetConvergenceTest(SVD,SVDConv);
551: SLEPC_EXTERN PetscErrorCode SVDGetConvergenceTest(SVD,SVDConv*);
552: SLEPC_EXTERN SVDConvergenceTestFn SVDConvergedAbsolute;
553: SLEPC_EXTERN SVDConvergenceTestFn SVDConvergedRelative;
554: SLEPC_EXTERN SVDConvergenceTestFn SVDConvergedNorm;
555: SLEPC_EXTERN SVDConvergenceTestFn SVDConvergedMaxIt;
556: SLEPC_EXTERN PetscErrorCode SVDSetConvergenceTestFunction(SVD,SVDConvergenceTestFn*,void*,PetscCtxDestroyFn*);
558: /*S
559: SVDStoppingTestFn - A prototype of an `SVD` stopping test function that would
560: be passed to `SVDSetStoppingTestFunction()`.
562: Calling Sequence:
563: + svd - the singular value solver context
564: . its - current number of iterations
565: . max_it - maximum number of iterations
566: . nconv - number of currently converged singular triplets
567: . nsv - number of requested singular triplets
568: . reason - [output] result of the stopping test
569: - ctx - optional stopping context, as set by `SVDSetStoppingTestFunction()`
571: Note:
572: A positive value of `reason` indicates that the iteration has finished successfully
573: (converged), and a negative value indicates an error condition (diverged). If
574: the iteration needs to be continued, `reason` must be set to `SVD_CONVERGED_ITERATING`
575: (zero).
577: Level: advanced
579: .seealso: [](ch:svd), `SVDSetStoppingTest()`, `SVDSetStoppingTestFunction()`
580: S*/
581: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SVDStoppingTestFn(SVD svd,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nsv,SVDConvergedReason *reason,void *ctx);
583: SLEPC_EXTERN PetscErrorCode SVDSetStoppingTest(SVD,SVDStop);
584: SLEPC_EXTERN PetscErrorCode SVDGetStoppingTest(SVD,SVDStop*);
585: SLEPC_EXTERN SVDStoppingTestFn SVDStoppingBasic;
586: SLEPC_EXTERN SVDStoppingTestFn SVDStoppingThreshold;
587: SLEPC_EXTERN PetscErrorCode SVDSetStoppingTestFunction(SVD,SVDStoppingTestFn*,void*,PetscCtxDestroyFn*);
589: /* --------- options specific to particular solvers -------- */
591: SLEPC_EXTERN PetscErrorCode SVDCrossSetExplicitMatrix(SVD,PetscBool);
592: SLEPC_EXTERN PetscErrorCode SVDCrossGetExplicitMatrix(SVD,PetscBool*);
593: SLEPC_EXTERN PetscErrorCode SVDCrossSetEPS(SVD,EPS);
594: SLEPC_EXTERN PetscErrorCode SVDCrossGetEPS(SVD,EPS*);
596: SLEPC_EXTERN PetscErrorCode SVDCyclicSetExplicitMatrix(SVD,PetscBool);
597: SLEPC_EXTERN PetscErrorCode SVDCyclicGetExplicitMatrix(SVD,PetscBool*);
598: SLEPC_EXTERN PetscErrorCode SVDCyclicSetEPS(SVD,EPS);
599: SLEPC_EXTERN PetscErrorCode SVDCyclicGetEPS(SVD,EPS*);
601: SLEPC_EXTERN PetscErrorCode SVDLanczosSetOneSide(SVD,PetscBool);
602: SLEPC_EXTERN PetscErrorCode SVDLanczosGetOneSide(SVD,PetscBool*);
604: /*E
605: SVDTRLanczosGBidiag - The choice of bidiagonalization for the `SVDTRLANCZOS` GSVD solver.
607: Values:
608: + `SVD_TRLANCZOS_GBIDIAG_SINGLE` - single bidiagonalization ($Q_A$)
609: . `SVD_TRLANCZOS_GBIDIAG_UPPER` - joint bidiagonalization, both $Q_A$ and $Q_B$ in upper bidiagonal form
610: - `SVD_TRLANCZOS_GBIDIAG_LOWER` - joint bidiagonalization, $Q_A$ lower bidiagonal, $Q_B$ upper bidiagonal
612: Note:
613: The different variants are described in {cite:p}`Alv24`.
615: Level: advanced
617: .seealso: [](ch:svd), `SVDTRLanczosSetGBidiag()`, `SVDTRLanczosGetGBidiag()`
618: E*/
619: typedef enum {
620: SVD_TRLANCZOS_GBIDIAG_SINGLE,
621: SVD_TRLANCZOS_GBIDIAG_UPPER,
622: SVD_TRLANCZOS_GBIDIAG_LOWER
623: } SVDTRLanczosGBidiag;
624: SLEPC_EXTERN const char *SVDTRLanczosGBidiags[];
626: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetGBidiag(SVD,SVDTRLanczosGBidiag);
627: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetGBidiag(SVD,SVDTRLanczosGBidiag*);
628: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetOneSide(SVD,PetscBool);
629: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetOneSide(SVD,PetscBool*);
630: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetKSP(SVD,KSP);
631: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetKSP(SVD,KSP*);
632: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetRestart(SVD,PetscReal);
633: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetRestart(SVD,PetscReal*);
634: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetLocking(SVD,PetscBool);
635: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetLocking(SVD,PetscBool*);
636: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetExplicitMatrix(SVD,PetscBool);
637: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetExplicitMatrix(SVD,PetscBool*);
638: SLEPC_EXTERN PetscErrorCode SVDTRLanczosSetScale(SVD,PetscReal);
639: SLEPC_EXTERN PetscErrorCode SVDTRLanczosGetScale(SVD,PetscReal*);
641: /*E
642: SVDPRIMMEMethod - The SVD method selected in the PRIMME library.
644: Note:
645: See the documentation of PRIMME {cite:p}`Sta10` for a description of the methods.
647: Level: advanced
649: .seealso: [](ch:svd), `SVDPRIMMESetMethod()`, `SVDPRIMMEGetMethod()`
650: E*/
651: typedef enum { SVD_PRIMME_HYBRID = 1,
652: SVD_PRIMME_NORMALEQUATIONS = 2,
653: SVD_PRIMME_AUGMENTED = 3 } SVDPRIMMEMethod;
654: SLEPC_EXTERN const char *SVDPRIMMEMethods[];
656: SLEPC_EXTERN PetscErrorCode SVDPRIMMESetBlockSize(SVD,PetscInt);
657: SLEPC_EXTERN PetscErrorCode SVDPRIMMEGetBlockSize(SVD,PetscInt*);
658: SLEPC_EXTERN PetscErrorCode SVDPRIMMESetMethod(SVD,SVDPRIMMEMethod);
659: SLEPC_EXTERN PetscErrorCode SVDPRIMMEGetMethod(SVD,SVDPRIMMEMethod*);
661: /*E
662: SVDKSVDEigenMethod - The method to solve the eigenproblem within the KSVD library.
664: Note:
665: See the documentation of KSVD {cite:p}`Suk19` for a description of the methods.
667: Level: advanced
669: .seealso: [](ch:svd), `SVDKSVDSetEigenMethod()`, `SVDKSVDGetEigenMethod()`
670: E*/
671: typedef enum { SVD_KSVD_EIGEN_MRRR = 1,
672: SVD_KSVD_EIGEN_DC = 2,
673: SVD_KSVD_EIGEN_ELPA = 3 } SVDKSVDEigenMethod;
674: SLEPC_EXTERN const char *SVDKSVDEigenMethods[];
676: /*E
677: SVDKSVDPolarMethod - The method to compute the polar decomposition within the KSVD library.
679: Note:
680: See the documentation of KSVD {cite:p}`Suk19` for a description of the methods.
682: Level: advanced
684: .seealso: [](ch:svd), `SVDKSVDSetPolarMethod()`, `SVDKSVDGetPolarMethod()`
685: E*/
686: typedef enum { SVD_KSVD_POLAR_QDWH = 1,
687: SVD_KSVD_POLAR_ZOLOPD = 2 } SVDKSVDPolarMethod;
688: SLEPC_EXTERN const char *SVDKSVDPolarMethods[];
690: SLEPC_EXTERN PetscErrorCode SVDKSVDSetEigenMethod(SVD,SVDKSVDEigenMethod);
691: SLEPC_EXTERN PetscErrorCode SVDKSVDGetEigenMethod(SVD,SVDKSVDEigenMethod*);
692: SLEPC_EXTERN PetscErrorCode SVDKSVDSetPolarMethod(SVD,SVDKSVDPolarMethod);
693: SLEPC_EXTERN PetscErrorCode SVDKSVDGetPolarMethod(SVD,SVDKSVDPolarMethod*);