Date: 2025-03-29T05:58:17+00:00

Actual source code: petscdmstag.h

      1: #pragma once

      3: #include <petscdm.h>
      4: #include <petscdmproduct.h>

      6: /* MANSEC = DM */
      7: /* SUBMANSEC = DMStag */

      9: /*E
     10:   DMStagStencilLocation - enumerated type denoting a location relative to an element in a `DMSTAG` grid

     12:   The interpretation of these values is dimension-dependent.

     14:   Level: beginner

     16:   Developer Note:
     17:   The order of the enum entries is significant, as it corresponds to the canonical numbering
     18:   of DOFs, and the fact that the numbering starts at 0 may also be used by the implementation.

     20:   Fortran Note:
     21:   Currently there is no Fortran support, it could be easily added.

     23: .seealso: [](ch_stag), `DMSTAG`, `DMDA`, `DMStagStencil`, `DMStagGetLocationSlot()`, `DMStagStencilType`
     24: E*/
     25: typedef enum {
     26:   DMSTAG_NULL_LOCATION,
     27:   DMSTAG_BACK_DOWN_LEFT,
     28:   DMSTAG_BACK_DOWN,
     29:   DMSTAG_BACK_DOWN_RIGHT,
     30:   DMSTAG_BACK_LEFT,
     31:   DMSTAG_BACK,
     32:   DMSTAG_BACK_RIGHT,
     33:   DMSTAG_BACK_UP_LEFT,
     34:   DMSTAG_BACK_UP,
     35:   DMSTAG_BACK_UP_RIGHT,
     36:   DMSTAG_DOWN_LEFT,
     37:   DMSTAG_DOWN,
     38:   DMSTAG_DOWN_RIGHT,
     39:   DMSTAG_LEFT,
     40:   DMSTAG_ELEMENT,
     41:   DMSTAG_RIGHT,
     42:   DMSTAG_UP_LEFT,
     43:   DMSTAG_UP,
     44:   DMSTAG_UP_RIGHT,
     45:   DMSTAG_FRONT_DOWN_LEFT,
     46:   DMSTAG_FRONT_DOWN,
     47:   DMSTAG_FRONT_DOWN_RIGHT,
     48:   DMSTAG_FRONT_LEFT,
     49:   DMSTAG_FRONT,
     50:   DMSTAG_FRONT_RIGHT,
     51:   DMSTAG_FRONT_UP_LEFT,
     52:   DMSTAG_FRONT_UP,
     53:   DMSTAG_FRONT_UP_RIGHT
     54: } DMStagStencilLocation;
     55: PETSC_EXTERN const char *const DMStagStencilLocations[]; /* Corresponding strings (see stagstencil.c) */

     57: /*S
     58:   DMStagStencil - data structure representing a degree of freedom on a `DMSTAG` grid

     60:   Data structure (C struct), analogous to describing a degree of freedom associated with a `DMSTAG` object,
     61:   in terms of a global element index in each of up to three directions, a "location" as defined by `DMStagStencilLocation`,
     62:   and a component number. Primarily for use with `DMStagMatSetValuesStencil()` (compare with use of `MatStencil` with `MatSetValuesStencil()`).

     64:   Level: beginner

     66:   Notes:
     67:   The component (c) field must always be set, even if there is a single component at a given location (in which case c should be set to 0).

     69:   This is a struct, not a `PetscObject`.

     71: .seealso: [](ch_stag), `DMSTAG`, `DMDA`, `DMStagMatSetValuesStencil()`, `DMStagVecSetValuesStencil()`, `DMStagStencilLocation`, `DMStagSetStencilWidth()`,
     72:           `DMStagSetStencilType()`, `DMStagVecGetValuesStencil()`, `DMStagStencilLocation`
     73: S*/
     74: typedef struct {
     75:   DMStagStencilLocation loc;
     76:   PetscInt              i, j, k, c;
     77: } DMStagStencil;

     79: /*E
     80:   DMStagStencilType - Elementwise stencil type, determining which neighbors participate in communication

     82:   Level: beginner

     84: .seealso: [](ch_stag), `DMSTAG`, `DMDA`, `DMStagCreate1d()`, `DMStagCreate2d()`, `DMStagCreate3d()`, `DMStagStencil`, `DMDAStencilType`, `DMStagStencilLocation`,
     85:           `DMDAStencilType`
     86: E*/

     88: typedef enum {
     89:   DMSTAG_STENCIL_NONE,
     90:   DMSTAG_STENCIL_STAR,
     91:   DMSTAG_STENCIL_BOX
     92: } DMStagStencilType;
     93: PETSC_EXTERN const char *const DMStagStencilTypes[]; /* Corresponding strings (see stagstencil.c) */

     95: PETSC_EXTERN PetscErrorCode DMCreate_Stag(DM);
     96: PETSC_EXTERN PetscErrorCode DMStagCreate1d(MPI_Comm, DMBoundaryType, PetscInt, PetscInt, PetscInt, DMStagStencilType, PetscInt, const PetscInt[], DM *);
     97: PETSC_EXTERN PetscErrorCode DMStagCreate2d(MPI_Comm, DMBoundaryType, DMBoundaryType, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, DMStagStencilType, PetscInt, const PetscInt[], const PetscInt[], DM *);
     98: PETSC_EXTERN PetscErrorCode DMStagCreate3d(MPI_Comm, DMBoundaryType, DMBoundaryType, DMBoundaryType, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, PetscInt, DMStagStencilType, PetscInt, const PetscInt[], const PetscInt[], const PetscInt[], DM *);
     99: PETSC_EXTERN PetscErrorCode DMStagCreateCompatibleDMStag(DM, PetscInt, PetscInt, PetscInt, PetscInt, DM *);
    100: PETSC_EXTERN PetscErrorCode DMStagCreateISFromStencils(DM, PetscInt, DMStagStencil *, IS *);
    101: PETSC_EXTERN PetscErrorCode DMStagGetBoundaryTypes(DM, DMBoundaryType *, DMBoundaryType *, DMBoundaryType *);
    102: PETSC_EXTERN PetscErrorCode DMStagGetCorners(DM, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *);
    103: PETSC_EXTERN PetscErrorCode DMStagGetDOF(DM, PetscInt *, PetscInt *, PetscInt *, PetscInt *);
    104: PETSC_EXTERN PetscErrorCode DMStagGetEntries(DM, PetscInt *);
    105: PETSC_EXTERN PetscErrorCode DMStagGetEntriesLocal(DM, PetscInt *);
    106: PETSC_EXTERN PetscErrorCode DMStagGetEntriesPerElement(DM, PetscInt *);
    107: PETSC_EXTERN PetscErrorCode DMStagGetGhostCorners(DM, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *, PetscInt *);
    108: PETSC_EXTERN PetscErrorCode DMStagGetGlobalSizes(DM, PetscInt *, PetscInt *, PetscInt *);
    109: PETSC_EXTERN PetscErrorCode DMStagGetIsFirstRank(DM, PetscBool *, PetscBool *, PetscBool *);
    110: PETSC_EXTERN PetscErrorCode DMStagGetIsLastRank(DM, PetscBool *, PetscBool *, PetscBool *);
    111: PETSC_EXTERN PetscErrorCode DMStagGetLocalSizes(DM, PetscInt *, PetscInt *, PetscInt *);
    112: PETSC_EXTERN PetscErrorCode DMStagGetLocationDOF(DM, DMStagStencilLocation, PetscInt *);
    113: PETSC_EXTERN PetscErrorCode DMStagGetLocationSlot(DM, DMStagStencilLocation, PetscInt, PetscInt *);
    114: PETSC_EXTERN PetscErrorCode DMStagGetNumRanks(DM, PetscInt *, PetscInt *, PetscInt *);
    115: PETSC_EXTERN PetscErrorCode DMStagGetOwnershipRanges(DM, const PetscInt **, const PetscInt **, const PetscInt **);
    116: PETSC_EXTERN PetscErrorCode DMStagGetProductCoordinateArrays(DM, void *, void *, void *);
    117: PETSC_EXTERN PetscErrorCode DMStagGetProductCoordinateArraysRead(DM, void *, void *, void *);
    118: PETSC_EXTERN PetscErrorCode DMStagGetProductCoordinateLocationSlot(DM, DMStagStencilLocation, PetscInt *);
    119: PETSC_EXTERN PetscErrorCode DMStagGetStencilType(DM, DMStagStencilType *);
    120: PETSC_EXTERN PetscErrorCode DMStagGetStencilWidth(DM, PetscInt *);
    121: PETSC_EXTERN PetscErrorCode DMStagGetRefinementFactor(DM, PetscInt *, PetscInt *, PetscInt *);
    122: PETSC_EXTERN PetscErrorCode DMStagMatGetValuesStencil(DM, Mat, PetscInt, const DMStagStencil *, PetscInt, const DMStagStencil *, PetscScalar *);
    123: PETSC_EXTERN PetscErrorCode DMStagMatSetValuesStencil(DM, Mat, PetscInt, const DMStagStencil *, PetscInt, const DMStagStencil *, const PetscScalar *, InsertMode);
    124: PETSC_EXTERN PetscErrorCode DMStagMigrateVec(DM, Vec, DM, Vec);
    125: PETSC_EXTERN PetscErrorCode DMStagPopulateLocalToGlobalInjective(DM);
    126: PETSC_EXTERN PetscErrorCode DMStagRestoreProductCoordinateArrays(DM, void *, void *, void *);
    127: PETSC_EXTERN PetscErrorCode DMStagRestoreProductCoordinateArraysRead(DM, void *, void *, void *);
    128: PETSC_EXTERN PetscErrorCode DMStagRestrictSimple(DM, Vec, DM, Vec);
    129: PETSC_EXTERN PetscErrorCode DMStagSetBoundaryTypes(DM, DMBoundaryType, DMBoundaryType, DMBoundaryType);
    130: PETSC_EXTERN PetscErrorCode DMStagSetCoordinateDMType(DM, DMType);
    131: PETSC_EXTERN PetscErrorCode DMStagSetDOF(DM, PetscInt, PetscInt, PetscInt, PetscInt);
    132: PETSC_EXTERN PetscErrorCode DMStagSetGlobalSizes(DM, PetscInt, PetscInt, PetscInt);
    133: PETSC_EXTERN PetscErrorCode DMStagSetNumRanks(DM, PetscInt, PetscInt, PetscInt);
    134: PETSC_EXTERN PetscErrorCode DMStagSetOwnershipRanges(DM, PetscInt const *, PetscInt const *, PetscInt const *);
    135: PETSC_EXTERN PetscErrorCode DMStagSetStencilType(DM, DMStagStencilType);
    136: PETSC_EXTERN PetscErrorCode DMStagSetStencilWidth(DM, PetscInt);
    137: PETSC_EXTERN PetscErrorCode DMStagSetRefinementFactor(DM, PetscInt, PetscInt, PetscInt);
    138: PETSC_EXTERN PetscErrorCode DMStagSetUniformCoordinates(DM, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal);
    139: PETSC_EXTERN PetscErrorCode DMStagSetUniformCoordinatesExplicit(DM, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal);
    140: PETSC_EXTERN PetscErrorCode DMStagSetUniformCoordinatesProduct(DM, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal);
    141: PETSC_EXTERN PetscErrorCode DMStagStencilToIndexLocal(DM, PetscInt, PetscInt, const DMStagStencil *, PetscInt *);
    142: PETSC_EXTERN PetscErrorCode DMStagVecGetArray(DM, Vec, void *);
    143: PETSC_EXTERN PetscErrorCode DMStagVecGetArrayRead(DM, Vec, void *);
    144: PETSC_EXTERN PetscErrorCode DMStagVecGetValuesStencil(DM, Vec, PetscInt, const DMStagStencil *, PetscScalar *);
    145: PETSC_EXTERN PetscErrorCode DMStagVecRestoreArray(DM, Vec, void *);
    146: PETSC_EXTERN PetscErrorCode DMStagVecRestoreArrayRead(DM, Vec, void *);
    147: PETSC_EXTERN PetscErrorCode DMStagVecSetValuesStencil(DM, Vec, PetscInt, const DMStagStencil *, const PetscScalar *, InsertMode);
    148: PETSC_EXTERN PetscErrorCode DMStagVecSplitToDMDA(DM, Vec, DMStagStencilLocation, PetscInt, DM *, Vec *);

    150: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagGetProductCoordinateArraysRead()", ) static inline PetscErrorCode DMStagGet1dCoordinateArraysDOFRead(DM dm, void *ax, void *ay, void *az)
    151: {
    152:   return DMStagGetProductCoordinateArraysRead(dm, ax, ay, az);
    153: }
    154: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagGetProductCoordinateLocationSlot()", ) static inline PetscErrorCode DMStagGet1dCoordinateLocationSlot(DM dm, DMStagStencilLocation loc, PetscInt *s)
    155: {
    156:   return DMStagGetProductCoordinateLocationSlot(dm, loc, s);
    157: }
    158: PETSC_DEPRECATED_FUNCTION(3, 11, 0, "DMStagGetStencilType()", ) static inline PetscErrorCode DMStagGetGhostType(DM dm, DMStagStencilType *s)
    159: {
    160:   return DMStagGetStencilType(dm, s);
    161: }
    162: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagRestoreProductCoordinateArraysRead()", ) static inline PetscErrorCode DMStagRestore1dCoordinateArraysDOFRead(DM dm, void *ax, void *ay, void *az)
    163: {
    164:   return DMStagRestoreProductCoordinateArraysRead(dm, ax, ay, az);
    165: }
    166: PETSC_DEPRECATED_FUNCTION(3, 11, 0, "DMStagSetStencilType()", ) static inline PetscErrorCode DMStagSetGhostType(DM dm, DMStagStencilType *s)
    167: {
    168:   return DMStagGetStencilType(dm, s);
    169: }
    170: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagVecGetArray()", ) static inline PetscErrorCode DMStagVecGetArrayDOF(DM dm, Vec v, void *a)
    171: {
    172:   return DMStagVecGetArray(dm, v, a);
    173: }
    174: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagVecGetArrayRead()", ) static inline PetscErrorCode DMStagVecGetArrayDOFRead(DM dm, Vec v, void *a)
    175: {
    176:   return DMStagVecGetArrayRead(dm, v, a);
    177: }
    178: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagVecRestoreArray()", ) static inline PetscErrorCode DMStagVecRestoreArrayDOF(DM dm, Vec v, void *a)
    179: {
    180:   return DMStagVecRestoreArray(dm, v, a);
    181: }
    182: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "DMStagVecRestoreArrayRead()", ) static inline PetscErrorCode DMStagVecRestoreArrayDOFRead(DM dm, Vec v, void *a)
    183: {
    184:   return DMStagVecRestoreArrayRead(dm, v, a);
    185: }