Actual source code: petscdmtypes.h
1: #pragma once
3: /* SUBMANSEC = DM */
5: /*S
6: DM - Abstract PETSc object that manages an abstract grid-like object and its interactions with the algebraic solvers
8: Level: intermediate
10: Note:
11: `DM` is an orphan initialism or orphan acronym, the letters have no meaning and never did.
13: .seealso: [](ch_dmbase), `DMType`, `DMGetType()`, `DMCompositeCreate()`, `DMDACreate()`, `DMSetType()`, `DMType`, `DMDA`, `DMPLEX`
14: S*/
15: typedef struct _p_DM *DM;
17: /*E
18: DMBoundaryType - Describes the choice for the filling of ghost cells on physical domain boundaries.
20: Values:
21: + `DM_BOUNDARY_NONE` - no ghost nodes
22: . `DM_BOUNDARY_GHOSTED` - ghost vertices/cells exist but aren't filled; you can put values into them and then apply a stencil that uses those ghost locations
23: . `DM_BOUNDARY_MIRROR` - the ghost value is the same as the value 1 grid point in; that is, the 0th grid point in the real mesh acts like a mirror to define
24: the ghost point value; not yet implemented for 3d
25: . `DM_BOUNDARY_PERIODIC` - ghost vertices/cells filled by the opposite edge of the domain
26: - `DM_BOUNDARY_TWIST` - like periodic, only glued backwards like a Mobius strip
28: Level: beginner
30: Notes:
31: This is information for the boundary of the __PHYSICAL__ domain. It has nothing to do with boundaries between
32: processes. That width is always determined by the stencil width; see `DMDASetStencilWidth()`.
34: If the physical grid points have values 0 1 2 3 with `DM_BOUNDARY_MIRROR` then the local vector with ghost points has the values 1 0 1 2 3 2.
36: See <https://scicomp.stackexchange.com/questions/5355/writing-the-poisson-equation-finite-difference-matrix-with-neumann-boundary-cond>
38: Developer Note:
39: Should `DM_BOUNDARY_MIRROR` have the same meaning with `DMDA_Q0`, that is a staggered grid? In that case should the ghost point have the same value
40: as the 0th grid point where the physical boundary serves as the mirror?
42: .seealso: [](ch_dmbase), `DM`, `DMDA`, `DMDASetBoundaryType()`, `DMDACreate1d()`, `DMDACreate2d()`, `DMDACreate3d()`, `DMDACreate()`
43: E*/
44: typedef enum {
45: DM_BOUNDARY_NONE,
46: DM_BOUNDARY_GHOSTED,
47: DM_BOUNDARY_MIRROR,
48: DM_BOUNDARY_PERIODIC,
49: DM_BOUNDARY_TWIST
50: } DMBoundaryType;
52: /*E
53: DMBoundaryConditionType - indicates what type of boundary condition is to be imposed
55: Values:
56: + `DM_BC_ESSENTIAL` - A Dirichlet condition using a function of the coordinates
57: . `DM_BC_ESSENTIAL_FIELD` - A Dirichlet condition using a function of the coordinates and auxiliary field data
58: . `DM_BC_ESSENTIAL_BD_FIELD` - A Dirichlet condition using a function of the coordinates, facet normal, and auxiliary field data
59: . `DM_BC_NATURAL` - A Neumann condition using a function of the coordinates
60: . `DM_BC_NATURAL_FIELD` - A Neumann condition using a function of the coordinates and auxiliary field data
61: - `DM_BC_NATURAL_RIEMANN` - A flux condition which determines the state in ghost cells
63: Level: beginner
65: Note:
66: The user can check whether a boundary condition is essential using (type & `DM_BC_ESSENTIAL`), and similarly for
67: natural conditions (type & `DM_BC_NATURAL`)
69: .seealso: [](ch_dmbase), `DM`, `DMAddBoundary()`, `DSAddBoundary()`, `DSGetBoundary()`
70: E*/
71: typedef enum {
72: DM_BC_ESSENTIAL = 1,
73: DM_BC_ESSENTIAL_FIELD = 5,
74: DM_BC_NATURAL = 2,
75: DM_BC_NATURAL_FIELD = 6,
76: DM_BC_ESSENTIAL_BD_FIELD = 9,
77: DM_BC_NATURAL_RIEMANN = 10
78: } DMBoundaryConditionType;
80: /*E
81: DMPointLocationType - Describes the method to handle point location failure
83: Values:
84: + `DM_POINTLOCATION_NONE` - return a negative cell number
85: . `DM_POINTLOCATION_NEAREST` - the (approximate) nearest point in the mesh is used
86: - `DM_POINTLOCATION_REMOVE` - returns values only for points which were located
88: Level: intermediate
90: .seealso: [](ch_dmbase), `DM`, `DMLocatePoints()`
91: E*/
92: typedef enum {
93: DM_POINTLOCATION_NONE,
94: DM_POINTLOCATION_NEAREST,
95: DM_POINTLOCATION_REMOVE
96: } DMPointLocationType;
98: /*E
99: DMBlockingType - Describes how to choose variable block sizes
101: Values:
102: + `DM_BLOCKING_TOPOLOGICAL_POINT` - select all fields at a topological point (cell center, at a face, etc)
103: - `DM_BLOCKING_FIELD_NODE` - using a separate block for each field at a topological point
105: Level: intermediate
107: Note:
108: When using `PCVPBJACOBI`, one can choose to block by topological point (all fields at a cell center, at a face, etc.)
109: or by field nodes (using number of components per field to identify "nodes"). Field nodes lead to smaller blocks, but
110: may converge more slowly. For example, a cubic Lagrange hexahedron will have one node at vertices, two at edges, four
111: at faces, and eight at cell centers. If using point blocking, the `PCVPBJACOBI` preconditioner will work with block
112: sizes up to 8 Lagrange nodes. For 5-component CFD, this produces matrices up to 40x40, which increases memory
113: footprint and may harm performance. With field node blocking, the maximum block size will correspond to one Lagrange node,
114: or 5x5 blocks for the CFD example.
116: .seealso: [](ch_dmbase), `PCVPBJACOBI`, `MatSetVariableBlockSizes()`, `DMSetBlockingType()`
117: E*/
118: typedef enum {
119: DM_BLOCKING_TOPOLOGICAL_POINT,
120: DM_BLOCKING_FIELD_NODE
121: } DMBlockingType;
123: /*E
124: DMAdaptationStrategy - Describes the strategy used for adaptive solves
126: Values:
127: + `DM_ADAPTATION_INITIAL` - refine a mesh based on an initial guess
128: . `DM_ADAPTATION_SEQUENTIAL` - refine the mesh based on a sequence of solves, much like grid sequencing
129: - `DM_ADAPTATION_MULTILEVEL` - use the sequence of constructed meshes in a multilevel solve, much like the Systematic Upscaling of Brandt
131: Level: beginner
133: .seealso: [](ch_dmbase), `DM`, `DMAdaptor`, `DMAdaptationCriterion`, `DMAdaptorSolve()`
134: E*/
135: typedef enum {
136: DM_ADAPTATION_INITIAL,
137: DM_ADAPTATION_SEQUENTIAL,
138: DM_ADAPTATION_MULTILEVEL
139: } DMAdaptationStrategy;
141: /*E
142: DMAdaptationCriterion - Describes the test used to decide whether to coarsen or refine parts of the mesh
144: Values:
145: + `DM_ADAPTATION_REFINE` - uniformly refine a mesh, much like grid sequencing
146: . `DM_ADAPTATION_LABEL` - adapt the mesh based upon a label of the cells filled with `DMAdaptFlag` markers.
147: . `DM_ADAPTATION_METRIC` - try to mesh the manifold described by the input metric tensor uniformly. PETSc can also construct such a metric based
148: upon an input primal or a gradient field.
149: - `DM_ADAPTATION_NONE` - do no adaptation
151: Level: beginner
153: .seealso: [](ch_dmbase), `DM`, `DMAdaptor`, `DMAdaptationStrategy`, `DMAdaptorSolve()`
154: E*/
155: typedef enum {
156: DM_ADAPTATION_NONE,
157: DM_ADAPTATION_REFINE,
158: DM_ADAPTATION_LABEL,
159: DM_ADAPTATION_METRIC
160: } DMAdaptationCriterion;
161: PETSC_EXTERN const char *const DMAdaptationCriteria[];
163: /*E
164: DMAdaptFlag - Marker in the label prescribing what adaptation to perform
166: Values:
167: + `DM_ADAPT_DETERMINE` - undocumented
168: . `DM_ADAPT_KEEP` - undocumented
169: . `DM_ADAPT_REFINE` - undocumented
170: . `DM_ADAPT_COARSEN` - undocumented
171: - `DM_ADAPT_COARSEN_LAST` - undocumented
173: Level: beginner
175: .seealso: [](ch_dmbase), `DM`, `DMAdaptor`, `DMAdaptationStrategy`, `DMAdaptationCriterion`, `DMAdaptorSolve()`, `DMAdaptLabel()`
176: E*/
177: typedef enum {
178: DM_ADAPT_DETERMINE = PETSC_DETERMINE,
179: DM_ADAPT_KEEP = 0,
180: DM_ADAPT_REFINE,
181: DM_ADAPT_COARSEN,
182: DM_ADAPT_COARSEN_LAST,
183: DM_ADAPT_RESERVED_COUNT
184: } DMAdaptFlag;
186: /*E
187: DMDirection - Indicates a coordinate direction
189: Values:
190: + `DM_X` - the x coordinate direction
191: . `DM_Y` - the y coordinate direction
192: - `DM_Z` - the z coordinate direction
194: Level: beginner
196: .seealso: [](ch_dmbase), `DM`, `DMDA`, `DMDAGetRay()`, `DMDAGetProcessorSubset()`, `DMPlexShearGeometry()`
197: E*/
198: typedef enum {
199: DM_X,
200: DM_Y,
201: DM_Z
202: } DMDirection;
204: /*E
205: DMEnclosureType - The type of enclosure relation between one `DM` and another
207: Values:
208: + `DM_ENC_SUBMESH` - the `DM` is the boundary of another `DM`
209: . `DM_ENC_SUPERMESH` - the `DM` has the boundary of another `DM` (the reverse situation to `DM_ENC_SUBMESH`)
210: . `DM_ENC_EQUALITY` - it is unknown what this means
211: . `DM_ENC_NONE` - no relationship can be determined
212: - `DM_ENC_UNKNOWN` - the relationship is unknown
214: Level: beginner
216: .seealso: [](ch_dmbase), `DM`, `DMGetEnclosureRelation()`
217: E*/
218: typedef enum {
219: DM_ENC_EQUALITY,
220: DM_ENC_SUPERMESH,
221: DM_ENC_SUBMESH,
222: DM_ENC_NONE,
223: DM_ENC_UNKNOWN
224: } DMEnclosureType;
226: /*E
227: DMPolytopeType - This describes the polytope represented by each cell.
229: Level: beginner
231: While most operations only need the topology information in the `DMPLEX`, we must sometimes have the
232: user specify a polytope. For instance, when interpolating from a cell-vertex mesh, the type of
233: polytope can be ambiguous. Also, `DMPLEX` allows different symmetries of a prism cell with the same
234: constituent points. Normally these types are automatically inferred and the user does not specify
235: them.
237: .seealso: [](ch_dmbase), `DM`, `DMPlexComputeCellTypes()`
238: E*/
239: typedef enum {
240: DM_POLYTOPE_POINT,
241: DM_POLYTOPE_SEGMENT,
242: DM_POLYTOPE_POINT_PRISM_TENSOR,
243: DM_POLYTOPE_TRIANGLE,
244: DM_POLYTOPE_QUADRILATERAL,
245: DM_POLYTOPE_SEG_PRISM_TENSOR,
246: DM_POLYTOPE_TETRAHEDRON,
247: DM_POLYTOPE_HEXAHEDRON,
248: DM_POLYTOPE_TRI_PRISM,
249: DM_POLYTOPE_TRI_PRISM_TENSOR,
250: DM_POLYTOPE_QUAD_PRISM_TENSOR,
251: DM_POLYTOPE_PYRAMID,
252: DM_POLYTOPE_FV_GHOST,
253: DM_POLYTOPE_INTERIOR_GHOST,
254: DM_POLYTOPE_UNKNOWN,
255: DM_POLYTOPE_UNKNOWN_CELL,
256: DM_POLYTOPE_UNKNOWN_FACE,
257: DM_NUM_POLYTOPES
258: } DMPolytopeType;
259: PETSC_EXTERN const char *const DMPolytopeTypes[];
261: /*E
262: PetscUnit - The seven fundamental SI units
264: Level: beginner
266: .seealso: `DMPlexGetScale()`, `DMPlexSetScale()`
267: E*/
268: typedef enum {
269: PETSC_UNIT_LENGTH,
270: PETSC_UNIT_MASS,
271: PETSC_UNIT_TIME,
272: PETSC_UNIT_CURRENT,
273: PETSC_UNIT_TEMPERATURE,
274: PETSC_UNIT_AMOUNT,
275: PETSC_UNIT_LUMINOSITY,
276: NUM_PETSC_UNITS
277: } PetscUnit;
279: /*E
280: DMReorderDefaultFlag - Flag indicating whether the `DM` should be reordered by default
282: Values:
283: + `DM_REORDER_DEFAULT_NOTSET` - Flag not set.
284: . `DM_REORDER_DEFAULT_FALSE` - Do not reorder by default.
285: - `DM_REORDER_DEFAULT_TRUE` - Reorder by default.
287: Level: intermediate
289: Developer Note:
290: Could be replaced with `PETSC_BOOL3`
292: .seealso: `DMPlexReorderSetDefault()`, `DMPlexReorderGetDefault()`, `DMPlexGetOrdering()`, `DMPlexPermute()`
293: E*/
294: typedef enum {
295: DM_REORDER_DEFAULT_NOTSET = -1,
296: DM_REORDER_DEFAULT_FALSE = 0,
297: DM_REORDER_DEFAULT_TRUE
298: } DMReorderDefaultFlag;
300: /*S
301: DMField - PETSc object for defining a field on a mesh topology
303: Level: intermediate
305: .seealso: [](ch_dmbase), `DM`, `DMUniversalLabel`, `DMLabelCreate()`
306: S*/
307: typedef struct _p_DMField *DMField;
309: /*S
310: DMUniversalLabel - A label that encodes a set of `DMLabel`s, bijectively
312: Level: developer
314: .seealso: [](ch_dmbase), `DM`, `DMLabel`, `DMUniversalLabelCreate()`
315: S*/
316: typedef struct _p_UniversalLabel *DMUniversalLabel;
318: typedef struct _PETSc_DMCEED *DMCeed;
320: typedef struct _n_DMGeneratorFunctionList *DMGeneratorFunctionList;