1 #pragma once 2 3 /* SUBMANSEC = DM */ 4 5 /*S 6 DM - Abstract PETSc object that manages an abstract grid-like object and its interactions with the algebraic solvers 7 8 Level: intermediate 9 10 Note: 11 `DM` is an orphan initialism or orphan acronym, the letters have no meaning and never did. 12 13 .seealso: [](ch_dmbase), `DMType`, `DMGetType()`, `DMCompositeCreate()`, `DMDACreate()`, `DMSetType()`, `DMType`, `DMDA`, `DMPLEX` 14 S*/ 15 typedef struct _p_DM *DM; 16 17 /*E 18 DMBoundaryType - Describes the choice for the filling of ghost cells on physical domain boundaries. 19 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 27 28 Level: beginner 29 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()`. 33 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. 35 36 See <https://scicomp.stackexchange.com/questions/5355/writing-the-poisson-equation-finite-difference-matrix-with-neumann-boundary-cond> 37 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? 41 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; 51 52 /*E 53 DMBoundaryConditionType - indicates what type of boundary condition is to be imposed 54 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 62 63 Level: beginner 64 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`) 68 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; 79 80 /*E 81 DMPointLocationType - Describes the method to handle point location failure 82 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 87 88 Level: intermediate 89 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; 97 98 /*E 99 DMBlockingType - Describes how to choose variable block sizes 100 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 104 105 Level: intermediate 106 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. 115 116 .seealso: [](ch_dmbase), `PCVPBJACOBI`, `MatSetVariableBlockSizes()`, `DMSetBlockingType()` 117 E*/ 118 typedef enum { 119 DM_BLOCKING_TOPOLOGICAL_POINT, 120 DM_BLOCKING_FIELD_NODE 121 } DMBlockingType; 122 123 /*E 124 DMAdaptationStrategy - Describes the strategy used for adaptive solves 125 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 130 131 Level: beginner 132 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; 140 141 /*E 142 DMAdaptationCriterion - Describes the test used to decide whether to coarsen or refine parts of the mesh 143 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 150 151 Level: beginner 152 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[]; 162 163 /*E 164 DMAdaptFlag - Marker in the label prescribing what adaptation to perform 165 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 172 173 Level: beginner 174 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; 185 186 /*E 187 DMDirection - Indicates a coordinate direction 188 189 Values: 190 + `DM_X` - the x coordinate direction 191 . `DM_Y` - the y coordinate direction 192 - `DM_Z` - the z coordinate direction 193 194 Level: beginner 195 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; 203 204 /*E 205 DMEnclosureType - The type of enclosure relation between one `DM` and another 206 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 213 214 Level: beginner 215 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; 225 226 /*E 227 DMPolytopeType - This describes the polytope represented by each cell. 228 229 Level: beginner 230 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. 236 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[]; 260 261 /*E 262 PetscUnit - The seven fundamental SI units 263 264 Level: beginner 265 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; 278 279 /*E 280 DMReorderDefaultFlag - Flag indicating whether the `DM` should be reordered by default 281 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. 286 287 Level: intermediate 288 289 Developer Note: 290 Could be replaced with `PETSC_BOOL3` 291 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; 299 300 /*S 301 DMField - PETSc object for defining a field on a mesh topology 302 303 Level: intermediate 304 305 .seealso: [](ch_dmbase), `DM`, `DMUniversalLabel`, `DMLabelCreate()` 306 S*/ 307 typedef struct _p_DMField *DMField; 308 309 /*S 310 DMUniversalLabel - A label that encodes a set of `DMLabel`s, bijectively 311 312 Level: developer 313 314 .seealso: [](ch_dmbase), `DM`, `DMLabel`, `DMUniversalLabelCreate()` 315 S*/ 316 typedef struct _p_UniversalLabel *DMUniversalLabel; 317 318 typedef struct _PETSc_DMCEED *DMCeed; 319 320 typedef struct _n_DMGeneratorFunctionList *DMGeneratorFunctionList; 321