Actual source code: petscpctypes.h
1: #pragma once
3: /* MANSEC = KSP */
4: /* SUBMANSEC = PC */
6: /*S
7: PC - Abstract PETSc object that manages all preconditioners including direct solvers such as `PCLU`
9: Level: beginner
11: .seealso: [](doc_linsolve), [](sec_pc), `PCCreate()`, `PCSetType()`, `PCType`
12: S*/
13: typedef struct _p_PC *PC;
15: /*J
16: PCType - String with the name of a PETSc preconditioner. These are all the preconditioners and direct solvers that PETSc provides.
18: Level: beginner
20: Notes:
21: Use `PCSetType()` or the options database key `-pc_type` to set the preconditioner to use with a given `PC` object
23: `PCRegister()` is used to register preconditioners that are then accessible via `PCSetType()`
25: .seealso: [](doc_linsolve), [](sec_pc), `PCSetType()`, `PC`, `PCCreate()`, `PCRegister()`, `PCSetFromOptions()`, `PCLU`, `PCJACOBI`, `PCBJACOBI`
26: J*/
27: typedef const char *PCType;
28: #define PCNONE "none"
29: #define PCJACOBI "jacobi"
30: #define PCSOR "sor"
31: #define PCLU "lu"
32: #define PCQR "qr"
33: #define PCSHELL "shell"
34: #define PCAMGX "amgx"
35: #define PCBJACOBI "bjacobi"
36: #define PCMG "mg"
37: #define PCEISENSTAT "eisenstat"
38: #define PCILU "ilu"
39: #define PCICC "icc"
40: #define PCASM "asm"
41: #define PCGASM "gasm"
42: #define PCKSP "ksp"
43: #define PCBJKOKKOS "bjkokkos"
44: #define PCCOMPOSITE "composite"
45: #define PCREDUNDANT "redundant"
46: #define PCSPAI "spai"
47: #define PCNN "nn"
48: #define PCCHOLESKY "cholesky"
49: #define PCPBJACOBI "pbjacobi"
50: #define PCVPBJACOBI "vpbjacobi"
51: #define PCMAT "mat"
52: #define PCHYPRE "hypre"
53: #define PCPARMS "parms"
54: #define PCFIELDSPLIT "fieldsplit"
55: #define PCTFS "tfs"
56: #define PCML "ml"
57: #define PCGALERKIN "galerkin"
58: #define PCEXOTIC "exotic"
59: #define PCCP "cp"
60: #define PCLSC "lsc"
61: #define PCPYTHON "python"
62: #define PCPFMG "pfmg"
63: #define PCSMG "smg"
64: #define PCSYSPFMG "syspfmg"
65: #define PCREDISTRIBUTE "redistribute"
66: #define PCSVD "svd"
67: #define PCGAMG "gamg"
68: #define PCCHOWILUVIENNACL "chowiluviennacl"
69: #define PCROWSCALINGVIENNACL "rowscalingviennacl"
70: #define PCSAVIENNACL "saviennacl"
71: #define PCBDDC "bddc"
72: #define PCKACZMARZ "kaczmarz"
73: #define PCTELESCOPE "telescope"
74: #define PCPATCH "patch"
75: #define PCLMVM "lmvm"
76: #define PCHMG "hmg"
77: #define PCDEFLATION "deflation"
78: #define PCHPDDM "hpddm"
79: #define PCH2OPUS "h2opus"
80: #define PCMPI "mpi"
82: /*E
83: PCSide - Determines if the preconditioner is to be applied to the left, right
84: or symmetrically around the operator in `KSPSolve()`.
86: Values:
87: + `PC_LEFT` - applied after the operator is applied
88: . `PC_RIGHT` - applied before the operator is applied
89: - `PC_SYMMETRIC` - a portion of the preconditioner is applied before the operator and the transpose of this portion is applied after the operator is applied.
91: Level: beginner
93: Note:
94: Certain `KSPType` support only a subset of `PCSide` values
96: .seealso: [](sec_pc), `PC`, `KSPSetPCSide()`, `KSP`, `KSPType`, `KSPGetPCSide()`, `KSPSolve()`
97: E*/
98: typedef enum {
99: PC_SIDE_DEFAULT = -1,
100: PC_LEFT = 0,
101: PC_RIGHT = 1,
102: PC_SYMMETRIC = 2
103: } PCSide;
104: #define PC_SIDE_MAX (PC_SYMMETRIC + 1)
106: /*E
107: PCRichardsonConvergedReason - reason a `PCApplyRichardson()` method terminated
109: Level: advanced
111: .seealso: [](sec_pc), `KSPRICHARDSON`, `PC`, `PCApplyRichardson()`
112: E*/
113: typedef enum {
114: PCRICHARDSON_NOT_SET = 0,
115: PCRICHARDSON_CONVERGED_RTOL = 2,
116: PCRICHARDSON_CONVERGED_ATOL = 3,
117: PCRICHARDSON_CONVERGED_ITS = 4,
118: PCRICHARDSON_DIVERGED_DTOL = -4
119: } PCRichardsonConvergedReason;
121: /*E
122: PCJacobiType - Determines what elements of the matrix are used to form the Jacobi preconditioner, that is with the `PCType` of `PCJACOBI`
124: Values:
125: + `PC_JACOBI_DIAGONAL` - use the diagonal entry, if it is zero use one
126: . `PC_JACOBI_ROWL1` - add sum of absolute values in row i, j != i, to diag_ii
127: . `PC_JACOBI_ROWMAX` - use the maximum absolute value in the row
128: - `PC_JACOBI_ROWSUM` - use the sum of the values in the row (not the absolute values)
130: Level: intermediate
132: .seealso: [](sec_pc), `PCJACOBI`, `PC`
133: E*/
134: typedef enum {
135: PC_JACOBI_DIAGONAL,
136: PC_JACOBI_ROWL1,
137: PC_JACOBI_ROWMAX,
138: PC_JACOBI_ROWSUM
139: } PCJacobiType;
141: /*E
142: PCASMType - Determines the type of additive Schwarz method, `PCASM`, to use
144: Values:
145: + `PC_ASM_NONE` - Residuals from ghost points are not used, computed ghost values are
146: discarded. Not very good.
147: . `PC_ASM_RESTRICT` - Residuals from ghost points are used but computed values in ghost
148: region are discarded {cite}`cs99`. Default.
149: . `PC_ASM_INTERPOLATE` - Residuals from ghost points are not used, computed values in ghost
150: region are added back in.
151: . `PC_ASM_BASIC` - Symmetric version where residuals from the ghost points are used
152: and computed values in ghost regions are added together.
153: Classical standard additive Schwarz as introduced in {cite}`dryja1987additive`.
154: - `PC_ASM_WEIGHTED` - Full restriction and interpolation, with local corrections scaled by
155: user-provided diagonal weights from `PCASMWeightedSetScaling()`.
157: Level: beginner
159: .seealso: [](sec_pc), `PC`, `PCASM`, `PCASMSetType()`, `PCASMWeightedSetScaling()`, `PCGASMType`
160: E*/
161: typedef enum {
162: PC_ASM_NONE,
163: PC_ASM_RESTRICT,
164: PC_ASM_INTERPOLATE,
165: PC_ASM_BASIC,
166: PC_ASM_WEIGHTED
167: } PCASMType;
169: /*E
170: PCGASMType - Determines the type of generalized additive Schwarz method to use (differs from `PCASM` in allowing multiple processors per subdomain) with the `PCType` of `PCGASM`
172: Values:
173: + `PC_GASM_BASIC` - Symmetric version where the full from the outer subdomain is used, and the resulting correction is applied
174: over the outer subdomains. As a result, points in the overlap will receive the sum of the corrections
175: from neighboring subdomains. Classical standard additive Schwarz {cite}`dryja1987additive`.
176: . `PC_GASM_RESTRICT` - Residual from the outer subdomain is used but the correction is restricted to the inner subdomain only
177: (i.e., zeroed out over the overlap portion of the outer subdomain before being applied). As a result,
178: each point will receive a correction only from the unique inner subdomain containing it (nonoverlapping covering
179: assumption) {cite}`cs99`. Default.
180: . `PC_GASM_INTERPOLATE` - Residual is zeroed out over the overlap portion of the outer subdomain, but the resulting correction is
181: applied over the outer subdomain. As a result, points in the overlap will receive the sum of the corrections
182: from neighboring subdomains.
183: - `PC_GASM_NONE` - Residuals and corrections are zeroed out outside the local subdomains. Not very good.
185: Level: beginner
187: Note:
188: Each subdomain has nested inner and outer parts. The inner subdomains are assumed to form a non-overlapping covering of the computational
189: domain, while the outer subdomains contain the inner subdomains and overlap with each other. The `PCGASM` preconditioner will compute
190: a subdomain correction over each *outer* subdomain from a residual computed there, but its different variants will differ in
191: (a) how the outer subdomain residual is computed, and (b) how the outer subdomain correction is computed.
193: Developer Note:
194: Perhaps better to remove this since it matches `PCASMType`
196: .seealso: [](sec_pc), `PCGASM`, `PCASM`, `PC`, `PCGASMSetType()`, `PCASMType`
197: E*/
198: typedef enum {
199: PC_GASM_BASIC = 3,
200: PC_GASM_RESTRICT = 1,
201: PC_GASM_INTERPOLATE = 2,
202: PC_GASM_NONE = 0
203: } PCGASMType;
205: /*E
206: PCCompositeType - Determines how two or more preconditioner are composed with the `PCType` of `PCCOMPOSITE`
208: Values:
209: + `PC_COMPOSITE_ADDITIVE` - results from application of all preconditioners are added together
210: . `PC_COMPOSITE_MULTIPLICATIVE` - preconditioners are applied sequentially to the residual freshly
211: computed after the previous preconditioner application
212: . `PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE` - preconditioners are applied sequentially to the residual freshly
213: computed from first preconditioner to last and then back (Use only for symmetric matrices and preconditioners)
214: . `PC_COMPOSITE_SPECIAL` - This is very special for a matrix of the form $ \alpha I + R + S$
215: where the first preconditioner is built from $\alpha I + S$ and second from $\alpha I + R$
216: . `PC_COMPOSITE_SCHUR` - composes the Schur complement of the matrix from two blocks, see `PCFIELDSPLIT`
217: - `PC_COMPOSITE_GKB` - the generalized Golub-Kahan bidiagonalization preconditioner, see `PCFIELDSPLIT`
219: Level: beginner
221: .seealso: [](sec_pc), `PCCOMPOSITE`, `PCFIELDSPLIT`, `PC`, `PCCompositeSetType()`, `SNESCompositeType`, `PCCompositeSpecialSetAlpha()`
222: E*/
223: typedef enum {
224: PC_COMPOSITE_ADDITIVE,
225: PC_COMPOSITE_MULTIPLICATIVE,
226: PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE,
227: PC_COMPOSITE_SPECIAL,
228: PC_COMPOSITE_SCHUR,
229: PC_COMPOSITE_GKB
230: } PCCompositeType;
232: /*E
233: PCFieldSplitSchurPreType - Determines how to precondition a Schur complement arising with the `PCType` of `PCFIELDSPLIT`
235: Values:
236: + `PC_FIELDSPLIT_SCHUR_PRE_SELF` - the preconditioner for the Schur complement is generated from the symbolic representation of the Schur complement matrix.
237: The only preconditioners that currently work with this symbolic representation matrix object are `PCLSC` and `PCHPDDM`
238: . `PC_FIELDSPLIT_SCHUR_PRE_SELFP` - the preconditioning for the Schur complement is generated from an explicitly-assembled approximation $Sp = A11 - A10 diag(A00)^{-1} A01$.
239: This is only a good preconditioner when $diag(A00)$ is a good preconditioner for $A00$. Optionally, $A00$ can be
240: lumped before extracting the diagonal using the additional option `-fieldsplit_1_mat_schur_complement_ainv_type lump`
241: . `PC_FIELDSPLIT_SCHUR_PRE_A11` - the preconditioner for the Schur complement is generated from $A11$, not the Schur complement matrix
242: . `PC_FIELDSPLIT_SCHUR_PRE_USER` - the preconditioner for the Schur complement is generated from the user provided matrix (pre argument
243: to this function).
244: - `PC_FIELDSPLIT_SCHUR_PRE_FULL` - the preconditioner for the Schur complement is generated from the exact Schur complement matrix representation
245: computed internally by `PCFIELDSPLIT` (this is expensive) useful mostly as a test that the Schur complement approach can work for your problem
247: Level: intermediate
249: .seealso: [](sec_pc), `PCFIELDSPLIT`, `PCFieldSplitSetSchurPre()`, `PC`
250: E*/
251: typedef enum {
252: PC_FIELDSPLIT_SCHUR_PRE_SELF,
253: PC_FIELDSPLIT_SCHUR_PRE_SELFP,
254: PC_FIELDSPLIT_SCHUR_PRE_A11,
255: PC_FIELDSPLIT_SCHUR_PRE_USER,
256: PC_FIELDSPLIT_SCHUR_PRE_FULL
257: } PCFieldSplitSchurPreType;
259: /*E
260: PCFieldSplitSchurFactType - determines which off-diagonal parts of the approximate block factorization to use with the `PCType` of `PCFIELDSPLIT`
262: Values:
263: + `PC_FIELDSPLIT_SCHUR_FACT_DIAG` - the preconditioner is solving `D`
264: . `PC_FIELDSPLIT_SCHUR_FACT_LOWER` - the preconditioner is solving `L D`
265: . `PC_FIELDSPLIT_SCHUR_FACT_UPPER` - the preconditioner is solving `D U`
266: - `PC_FIELDSPLIT_SCHUR_FACT_FULL` - the preconditioner is solving `L(D U)`
268: where the matrix is factorized as
269: .vb
270: (A B) = (1 0) (A 0) (1 Ainv*B) = L D U
271: (C E) (C*Ainv 1) (0 S) (0 1)
272: .ve
274: Level: intermediate
276: .seealso: [](sec_pc), `PCFIELDSPLIT`, `PCFieldSplitSetSchurFactType()`, `PC`
277: E*/
278: typedef enum {
279: PC_FIELDSPLIT_SCHUR_FACT_DIAG,
280: PC_FIELDSPLIT_SCHUR_FACT_LOWER,
281: PC_FIELDSPLIT_SCHUR_FACT_UPPER,
282: PC_FIELDSPLIT_SCHUR_FACT_FULL
283: } PCFieldSplitSchurFactType;
285: /*E
286: PCPARMSGlobalType - Determines the global preconditioner method in `PCPARMS`
288: Level: intermediate
290: .seealso: [](sec_pc), `PCPARMS`, `PCPARMSSetGlobal()`, `PC`
291: E*/
292: typedef enum {
293: PC_PARMS_GLOBAL_RAS,
294: PC_PARMS_GLOBAL_SCHUR,
295: PC_PARMS_GLOBAL_BJ
296: } PCPARMSGlobalType;
298: /*E
299: PCPARMSLocalType - Determines the local preconditioner method in `PCPARMS`
301: Level: intermediate
303: .seealso: [](sec_pc), `PCPARMS`, `PCPARMSSetLocal()`, `PC`
304: E*/
305: typedef enum {
306: PC_PARMS_LOCAL_ILU0,
307: PC_PARMS_LOCAL_ILUK,
308: PC_PARMS_LOCAL_ILUT,
309: PC_PARMS_LOCAL_ARMS
310: } PCPARMSLocalType;
312: /*J
313: PCGAMGType - type of generalized algebraic multigrid `PCGAMG` method
315: Values:
316: + `PCGAMGAGG` - (the default) smoothed aggregation algorithm, robust, very well tested
317: . `PCGAMGGEO` - geometric coarsening, uses mesh generator to produce coarser meshes, limited to triangles, not supported, reference implementation (2D)
318: - `PCGAMGCLASSICAL` - classical algebraic multigrid preconditioner, incomplete, not supported, reference implementation
320: Level: intermediate
322: .seealso: [](sec_pc), `PCGAMG`, `PCMG`, `PC`, `PCSetType()`, `PCGAMGSetThreshold()`, `PCGAMGSetReuseInterpolation()`
323: J*/
324: typedef const char *PCGAMGType;
325: #define PCGAMGAGG "agg"
326: #define PCGAMGGEO "geo"
327: #define PCGAMGCLASSICAL "classical"
329: /*J
330: PCGAMGClassicalType - String name selecting the prolongator construction used by the classical algebraic multigrid `PCGAMGCLASSICAL` implementation
332: Values:
333: + `PCGAMGCLASSICALDIRECT` - Ruge--Stueben direct (also called "matching") interpolation
334: - `PCGAMGCLASSICALSTANDARD` - the standard Ruge--Stueben interpolation
336: Level: intermediate
338: .seealso: [](sec_pc), `PCGAMG`, `PCGAMGCLASSICAL`, `PCGAMGClassicalSetType()`, `PCGAMGClassicalGetType()`, `PCGAMGType`
339: J*/
340: typedef const char *PCGAMGClassicalType;
341: #define PCGAMGCLASSICALDIRECT "direct"
342: #define PCGAMGCLASSICALSTANDARD "standard"
344: /*E
345: PCMGType - Determines the type of multigrid method that is run with the `PCType` of `PCMG`
347: Values:
348: + `PC_MG_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `PCMGSetCycleType()`
349: . `PC_MG_ADDITIVE` - the additive multigrid preconditioner where all levels are
350: smoothed before updating the residual. This only uses the
351: down smoother, in the preconditioner the upper smoother is ignored
352: . `PC_MG_FULL` - same as multiplicative except one also performs grid sequencing,
353: that is starts on the coarsest grid, performs a cycle, interpolates
354: to the next, performs a cycle etc. This is much like the F-cycle presented in "Multigrid" by Trottenberg, Oosterlee, Schuller page 49, but that
355: algorithm supports smoothing on before the restriction on each level in the initial restriction to the coarsest stage. In addition that algorithm
356: calls the V-cycle only on the coarser level and has a post-smoother instead.
357: - `PC_MG_KASKADE` - Cascadic or Kaskadic multigrid, like full multigrid except one never goes back to a coarser level from a finer
359: Level: beginner
361: .seealso: [](sec_pc), `PCMG`, `PC`, `PCMGSetType()`, `PCMGSetCycleType()`, `PCMGSetCycleTypeOnLevel()`
362: E*/
363: typedef enum {
364: PC_MG_MULTIPLICATIVE,
365: PC_MG_ADDITIVE,
366: PC_MG_FULL,
367: PC_MG_KASKADE
368: } PCMGType;
369: #define PC_MG_CASCADE PC_MG_KASKADE;
371: /*E
372: PCMGCycleType - Determines which of V-cycle or W-cycle to use with the `PCType` of `PCMG` or `PCGAMG`
374: Values:
375: + `PC_MG_V_CYCLE` - use the V cycle
376: - `PC_MG_W_CYCLE` - use the W cycle
378: Level: beginner
380: .seealso: [](sec_pc), `PCMG`, `PC`, `PCMGSetCycleType()`
381: E*/
382: typedef enum {
383: PC_MG_CYCLE_V = 1,
384: PC_MG_CYCLE_W = 2
385: } PCMGCycleType;
387: /*E
388: PCMGGalerkinType - Determines if the coarse grid operators are computed via the Galerkin process with the `PCType` of `PCMG`
390: Values:
391: + `PC_MG_GALERKIN_PMAT` - computes the `pmat` (matrix from which the preconditioner is built) via the Galerkin process from the finest grid
392: . `PC_MG_GALERKIN_MAT` - computes the `mat` (matrix used to apply the operator) via the Galerkin process from the finest grid
393: . `PC_MG_GALERKIN_BOTH` - computes both the `mat` and `pmat` via the Galerkin process (if pmat == mat the construction is only done once
394: - `PC_MG_GALERKIN_NONE` - neither operator is computed via the Galerkin process, the user must provide the operator
396: Level: beginner
398: Note:
399: Users should never set `PC_MG_GALERKIN_EXTERNAL`, it is used by `PCHYPRE` and `PCML`
401: .seealso: [](sec_pc), `PCMG`, `PC`, `PCMGSetCycleType()`
402: E*/
403: typedef enum {
404: PC_MG_GALERKIN_BOTH,
405: PC_MG_GALERKIN_PMAT,
406: PC_MG_GALERKIN_MAT,
407: PC_MG_GALERKIN_NONE,
408: PC_MG_GALERKIN_EXTERNAL
409: } PCMGGalerkinType;
411: /*E
412: PCExoticType - Determines which of the face-based or wirebasket-based coarse grid space to use with the `PCType` of `PCEXOTIC`
414: Level: beginner
416: .seealso: [](sec_pc), `PCExoticSetType()`, `PCEXOTIC`
417: E*/
418: typedef enum {
419: PC_EXOTIC_FACE,
420: PC_EXOTIC_WIREBASKET
421: } PCExoticType;
423: /*E
424: PCBDDCInterfaceExtType - Defines how interface balancing is extended into the interior of subdomains with the `PCType` of `PCBDDC`
426: Values:
427: + `PC_BDDC_INTERFACE_EXT_DIRICHLET` - solves Dirichlet interior problem; this is the standard BDDC algorithm
428: - `PC_BDDC_INTERFACE_EXT_LUMP` - skips interior solve; sometimes called $M_1$ and associated with "lumped FETI-DP"
430: Level: intermediate
432: .seealso: [](sec_pc), `PCBDDC`, `PC`
433: E*/
434: typedef enum {
435: PC_BDDC_INTERFACE_EXT_DIRICHLET,
436: PC_BDDC_INTERFACE_EXT_LUMP
437: } PCBDDCInterfaceExtType;
439: /*E
440: PCMGCoarseSpaceType - Function space for coarse space for adaptive interpolation
442: Level: beginner
444: .seealso: [](sec_pc), `PCMGSetAdaptCoarseSpaceType()`, `PCMG`, `PC`
445: E*/
446: typedef enum {
447: PCMG_ADAPT_NONE,
448: PCMG_ADAPT_POLYNOMIAL,
449: PCMG_ADAPT_HARMONIC,
450: PCMG_ADAPT_EIGENVECTOR,
451: PCMG_ADAPT_GENERALIZED_EIGENVECTOR,
452: PCMG_ADAPT_GDSW
453: } PCMGCoarseSpaceType;
455: /*E
456: PCPatchConstructType - Determines the algorithm used to construct patches for the `PCPATCH` preconditioner
458: Level: beginner
460: .seealso: [](sec_pc), `PCPatchSetConstructType()`, `PCPATCH`, `PC`
461: E*/
462: typedef enum {
463: PC_PATCH_STAR,
464: PC_PATCH_VANKA,
465: PC_PATCH_PARDECOMP,
466: PC_PATCH_USER,
467: PC_PATCH_PYTHON
468: } PCPatchConstructType;
470: /*E
471: PCDeflationSpaceType - Type of deflation used by `PCType` `PCDEFLATION`
473: Values:
474: + `PC_DEFLATION_SPACE_HAAR` - directly assembled based on Haar (db2) wavelet with overflowed filter cuted-off
475: . `PC_DEFLATION_SPACE_DB2` - `MATCOMPOSITE` of 1-lvl matices based on db2 (2 coefficient Daubechies / Haar wavelet)
476: . `PC_DEFLATION_SPACE_DB4` - same as above, but with db4 (4 coefficient Daubechies)
477: . `PC_DEFLATION_SPACE_DB8` - same as above, but with db8 (8 coefficient Daubechies)
478: . `PC_DEFLATION_SPACE_DB16` - same as above, but with db16 (16 coefficient Daubechies)
479: . `PC_DEFLATION_SPACE_BIORTH22` - same as above, but with biorthogonal 2.2 (6 coefficients)
480: . `PC_DEFLATION_SPACE_MEYER` - same as above, but with Meyer/FIR (62 coefficients)
481: . `PC_DEFLATION_SPACE_AGGREGATION` - aggregates local indices (given by operator matrix distribution) into a subdomain
482: - `PC_DEFLATION_SPACE_USER` - indicates space set by user
484: Level: intermediate
486: Note:
487: Wavelet-based space (except Haar) can be used in multilevel deflation.
489: .seealso: [](sec_pc), `PCDeflationSetSpaceToCompute()`, `PCDEFLATION`, `PC`
490: E*/
491: typedef enum {
492: PC_DEFLATION_SPACE_HAAR,
493: PC_DEFLATION_SPACE_DB2,
494: PC_DEFLATION_SPACE_DB4,
495: PC_DEFLATION_SPACE_DB8,
496: PC_DEFLATION_SPACE_DB16,
497: PC_DEFLATION_SPACE_BIORTH22,
498: PC_DEFLATION_SPACE_MEYER,
499: PC_DEFLATION_SPACE_AGGREGATION,
500: PC_DEFLATION_SPACE_USER
501: } PCDeflationSpaceType;
503: /*E
504: PCHPDDMCoarseCorrectionType - Type of coarse correction used by `PCType` `PCHPDDM`
506: Values:
507: + `PC_HPDDM_COARSE_CORRECTION_DEFLATED` (default) - eq. (2) below
508: . `PC_HPDDM_COARSE_CORRECTION_ADDITIVE` - eq. (1)
509: . `PC_HPDDM_COARSE_CORRECTION_BALANCED` - eq. (3)
510: . `PC_HPDDM_COARSE_CORRECTION_NONE` - eq. (4), no coarse correction (mostly useful for debugging)
511: - `PC_HPDDM_COARSE_CORRECTION_DEFLATED_REVERSED` - eq. (5)
513: Level: intermediate
515: Notes:
516: At each level other than the coarsest, let $Z$ denote the deflation matrix, $E = Z^T Pmat Z$, and $Q = Z E^{-1} Z^T$. The coarse corrections applied by `PCApply()` are
517: .vb
518: (1) y = Pmat^-1 x + Q x,
519: (2) y = Pmat^-1 (I - Amat Q) x + Q x (default),
520: (3) y = (I - Q^T Amat^T) Pmat^-1 (I - Amat Q) x + Q x,
521: (4) y = Pmat^-1 x,
522: (5) y = (I - Q Amat) Pmat^-1 x + Q x.
523: .ve
524: The corresponding operations applied by `PCApplyTranspose()` are
525: .vb
526: (1) y = Pmat^-T x + Q^T x,
527: (2) y = (I - Q^T Amat^T) Pmat^-T x + Q^T x (default),
528: (3) y = (I - Q^T Amat^T) Pmat^-T (I - Amat Q) x + Q^T x,
529: (4) y = Pmat^-T x,
530: (5) y = Pmat^-T (I - Amat^T Q^T) x + Q^T x.
531: .ve
532: The options of Pmat^-1 = pc(Pmat) are prefixed by `-pc_hpddm_levels_1_pc_`. $Z$ is a tall-and-skinny matrix assembled by HPDDM. The number of processes on which $E$ is aggregated is set via `-pc_hpddm_coarse_p`.
533: The options of (Z^T Pmat Z)^-1 = ksp(Z^T Pmat Z) are prefixed by `-pc_hpddm_coarse_` (`KSPPREONLY` and `PCCHOLESKY` by default), unless a multilevel correction is turned on, in which case, the correction above is applied recursively at each level except the coarsest one.
534: For `PCApply()`, corrections (1), (2), and (5) visit the next coarser level once per application, while (3) visits it twice. For `PCApplyTranspose()`, (1) and (5) visit it once, (2) twice, and (3) three times.
535: Corrections (2) and (5) are not symmetric even when both Amat and Pmat are symmetric.
537: .seealso: [](sec_pc), `PCHPDDM`, `PC`, `PCSetType()`, `PCApply()`, `PCApplyTranspose()`, `PCHPDDMSetCoarseCorrectionType()`, `PCHPDDMGetCoarseCorrectionType()`
538: E*/
539: typedef enum {
540: PC_HPDDM_COARSE_CORRECTION_DEFLATED,
541: PC_HPDDM_COARSE_CORRECTION_ADDITIVE,
542: PC_HPDDM_COARSE_CORRECTION_BALANCED,
543: PC_HPDDM_COARSE_CORRECTION_NONE,
544: PC_HPDDM_COARSE_CORRECTION_DEFLATED_REVERSED
545: } PCHPDDMCoarseCorrectionType;
547: /*E
548: PCHPDDMSchurPreType - Type of `PCHPDDM` preconditioner for a `MATSCHURCOMPLEMENT` generated by `PCFIELDSPLIT` with `PCFieldSplitSchurPreType` set to `PC_FIELDSPLIT_SCHUR_PRE_SELF`
550: Values:
551: + `PC_HPDDM_SCHUR_PRE_LEAST_SQUARES` (default) - only with a near-zero A11 block and A10 = A01^T; a preconditioner for solving A01^T A00^-1 A01 x = b
552: is built by approximating the Schur complement with (inv(sqrt(diag(A00))) A01)^T (inv(sqrt(diag(A00))) A01)
553: and by considering the associated linear least squares problem
554: - `PC_HPDDM_SCHUR_PRE_GENEO` - only with A10 = A01^T, `PCHPDDMSetAuxiliaryMat()` called on the `PC` of the A00 block, and if A11 is nonzero,
555: then `PCHPDDMSetAuxiliaryMat()` must be called on the associated `PC` as well (it is built automatically for the
556: user otherwise); the Schur complement `PC` is set internally to `PCKSP`, with the prefix `-fieldsplit_1_pc_hpddm_`;
557: the operator associated to the `PC` is spectrally equivalent to the original Schur complement
559: Level: advanced
561: .seealso: [](sec_pc), `PCHPDDM`, `PC`, `PCFIELDSPLIT`, `PC_FIELDSPLIT_SCHUR_PRE_SELF`, `PCFieldSplitSetSchurPre()`, `PCHPDDMSetAuxiliaryMat()`
562: E*/
563: typedef enum {
564: PC_HPDDM_SCHUR_PRE_LEAST_SQUARES,
565: PC_HPDDM_SCHUR_PRE_GENEO
566: } PCHPDDMSchurPreType;
568: /*E
569: PCFailedReason - indicates the type of `PC` failure. That is why the construction of the preconditioner, `PCSetUp()`, or its use, `PCApply()`, failed
571: Level: beginner
573: .seealso: [](sec_pc), `PC`, `PCGetFailedReason()`, `PCSetUp()`
574: E*/
575: typedef enum {
576: PC_SETUP_ERROR = -1,
577: PC_NOERROR = 0,
578: PC_FACTOR_STRUCT_ZEROPIVOT = 1,
579: PC_FACTOR_NUMERIC_ZEROPIVOT = 2,
580: PC_FACTOR_OUTMEMORY = 3,
581: PC_FACTOR_OTHER = 4,
582: PC_INCONSISTENT_RHS = 5,
583: PC_SUBPC_ERROR = 6
584: } PCFailedReason;
586: /*E
587: PCGAMGLayoutType - Layout for reduced grids for `PCType` `PCGAMG`
589: Level: intermediate
591: .seealso: [](sec_pc), `PCGAMG`, `PC`, `PCGAMGSetCoarseGridLayoutType()`
592: E*/
593: typedef enum {
594: PCGAMG_LAYOUT_COMPACT,
595: PCGAMG_LAYOUT_SPREAD
596: } PCGAMGLayoutType;