DMStag (Staggered Grids)

DMStag manages staggered grid discretizations, commonly used in computational fluid dynamics and geophysics. It handles variables defined at different locations (vertices, edges, faces, element centers).

Overview

DMStag provides:

Staggered grid support for MAC/marker-and-cell schemes
Multiple degrees of freedom at vertices, edges, faces, and element centers
Efficient communication for staggered variables
1D, 2D, and 3D support
Boundary type specification

Basic Usage Pattern

using PETSc, MPI

petsclib = PETSc.petsclibs[1]
PETSc.initialize(petsclib)

# Get PETSc types
PetscInt = petsclib.PetscInt

# Create a 2D staggered grid
# Velocity components on edges, pressure at cell centers
dm = LibPETSc.DMStagCreate2d(
    petsclib,
    MPI.COMM_WORLD,
    LibPETSc.DM_BOUNDARY_NONE,
    LibPETSc.DM_BOUNDARY_NONE,
    PetscInt(10), PetscInt(10),  # global dimensions
    PetscInt(LibPETSc.PETSC_DECIDE),
    PetscInt(LibPETSc.PETSC_DECIDE),
    PetscInt(0),                 # dof per vertex
    PetscInt(1),                 # dof per edge (velocity)
    PetscInt(1),                 # dof per element (pressure)
    LibPETSc.DMSTAG_STENCIL_BOX,
    PetscInt(1),                 # stencil width
    C_NULL, C_NULL
)

# Set up
LibPETSc.DMSetFromOptions(petsclib, dm)
LibPETSc.DMSetUp(petsclib, dm)

# Create vectors
x = LibPETSc.DMCreateGlobalVector(petsclib, dm)

# Access staggered components
# Use DMStagGetLocationSlot to get indices for each component

# Cleanup
LibPETSc.VecDestroy(petsclib, x)
LibPETSc.DMDestroy(petsclib, dm)
PETSc.finalize(petsclib)

DMStag Functions

PETSc.LibPETSc.DMStagCreate1d — Method

dm::PetscDM = DMStagCreate1d(petsclib::PetscLibType,comm::MPI_Comm, bndx::DMBoundaryType, M::PetscInt, dof0::PetscInt, dof1::PetscInt, stencilType::DMStagStencilType, stencilWidth::PetscInt, lx::Vector{PetscInt})

Create an object to manage data living on the elements and vertices of a parallelized regular 1D grid.

Collective

Input Parameters:

comm - MPI communicator
bndx - boundary type: DM_BOUNDARY_NONE, DM_BOUNDARY_PERIODIC, or DM_BOUNDARY_GHOSTED
M - global number of elements
dof0 - number of degrees of freedom per vertex/0-cell
dof1 - number of degrees of freedom per element/1-cell
stencilType - ghost/halo region type: DMSTAG_STENCIL_BOX or DMSTAG_STENCIL_NONE
stencilWidth - width, in elements, of halo/ghost region
lx - array of local sizes, of length equal to the comm size, summing to M or NULL

Output Parameter:

dm - the new DMSTAG object

Options Database Keys:

-dm_view - calls DMViewFromOptions() at the conclusion of DMSetUp()
-stag_grid_x <nx> - number of elements in the x direction
-stag_ghost_stencil_width - width of ghost region, in elements
-stag_boundary_type_x <none,ghosted,periodic> - DMBoundaryType value

Level: beginner

Notes: You must call DMSetUp() after this call before using the DM. If you wish to use the options database (see the keys above) to change values in the DMSTAG, you must call DMSetFromOptions() after this function but before DMSetUp().

See also:

DMSTAG, DMStagCreate2d(), DMStagCreate3d(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateLocalVector(), DMLocalToGlobalBegin(), DMDACreate1d()

External Links