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