GitHub

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::Union{Ptr, 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

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

External Links

source
PETSc.LibPETSc.DMStagCreate2d — Method
dm::PetscDM = DMStagCreate2d(petsclib::PetscLibType, comm::MPI_Comm, bndx::DMBoundaryType, bndy::DMBoundaryType, M::PetscInt, N::PetscInt, M_m::PetscInt, M_n::PetscInt, dof0::PetscInt, dof1::PetscInt, dof2::PetscInt, stencilType::DMStagStencilType, stencilWidth::PetscInt, lx::Union{Ptr, Vector{PetscInt}}, ly::Union{Ptr, Vector{PetscInt}})

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

Collective

Input Parameters:

  • comm - MPI communicator
  • bndx - x boundary type, DM_BOUNDARY_NONE, DM_BOUNDARY_PERIODIC, or

DM_BOUNDARY_GHOSTED

  • bndy - y boundary type, DM_BOUNDARY_NONE, DM_BOUNDARY_PERIODIC, or DM_BOUNDARY_GHOSTED
  • M - global number of elements in x direction
  • N - global number of elements in y direction
  • m - number of ranks in the x direction (may be PETSC_DECIDE)
  • n - number of ranks in the y direction (may be PETSC_DECIDE)
  • dof0 - number of degrees of freedom per vertex/0-cell
  • dof1 - number of degrees of freedom per face/1-cell
  • dof2 - number of degrees of freedom per element/2-cell
  • stencilType - ghost/halo region type: DMSTAG_STENCIL_NONE, DMSTAG_STENCIL_BOX, or DMSTAG_STENCIL_STAR
  • stencilWidth - width, in elements, of halo/ghost region
  • lx - array of local x element counts, of length equal to m, summing to M, or NULL
  • ly - array of local y element counts, of length equal to n, summing to N, 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_grid_y ny - number of elements in the y direction
  • -stag_ranks_x rx - number of ranks in the x direction
  • -stag_ranks_y ry - number of ranks in the y direction
  • -stag_ghost_stencil_width - width of ghost region, in elements
  • -stag_boundary_type_x (none|ghosted|periodic) - DMBoundaryType value
  • -stag_boundary_type_y (none|ghosted|periodic) - DMBoundaryType value

Level: beginner

See also: DMSTAG, DMStagCreate1d(), DMStagCreate3d(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateLocalVector(), DMLocalToGlobalBegin(), DMDACreate2d()

External Links

source
PETSc.LibPETSc.DMStagCreate3d — Method
dm::PetscDM = DMStagCreate3d(petsclib::PetscLibType, comm::MPI_Comm, bndx::DMBoundaryType, bndy::DMBoundaryType, bndz::DMBoundaryType, M::PetscInt, N::PetscInt, P::PetscInt, M_m::PetscInt, M_n::PetscInt, M_p::PetscInt, dof0::PetscInt, dof1::PetscInt, dof2::PetscInt, dof3::PetscInt, stencilType::DMStagStencilType, stencilWidth::PetscInt, lx::Union{Ptr, Vector{PetscInt}}, ly::Union{Ptr, Vector{PetscInt}}, lz::Union{Ptr, Vector{PetscInt}})

Create an object to manage data living on the elements, faces, edges, and vertices of a parallelized regular 3D grid.

Collective

Input Parameters:

  • comm - MPI communicator
  • bndx - x boundary type, DM_BOUNDARY_NONE, DM_BOUNDARY_PERIODIC, or DM_BOUNDARY_GHOSTED
  • bndy - y boundary type, DM_BOUNDARY_NONE, DM_BOUNDARY_PERIODIC, or DM_BOUNDARY_GHOSTED
  • bndz - z boundary type, DM_BOUNDARY_NONE, DM_BOUNDARY_PERIODIC, or DM_BOUNDARY_GHOSTED
  • M - global number of elements in x direction
  • N - global number of elements in y direction
  • P - global number of elements in z direction
  • m - number of ranks in the x direction (may be PETSC_DECIDE)
  • n - number of ranks in the y direction (may be PETSC_DECIDE)
  • p - number of ranks in the z direction (may be PETSC_DECIDE)
  • dof0 - number of degrees of freedom per vertex/0-cell
  • dof1 - number of degrees of freedom per edge/1-cell
  • dof2 - number of degrees of freedom per face/2-cell
  • dof3 - number of degrees of freedom per element/3-cell
  • stencilType - ghost/halo region type: DMSTAG_STENCIL_NONE, DMSTAG_STENCIL_BOX, or DMSTAG_STENCIL_STAR
  • stencilWidth - width, in elements, of halo/ghost region
  • lx - array of local x element counts, of length equal to m, summing to M, or NULL
  • ly - arrays of local y element counts, of length equal to n, summing to N, or NULL
  • lz - arrays of local z element counts, of length equal to p, summing to P, 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_grid_y ny - number of elements in the y direction
  • -stag_grid_z nz - number of elements in the z direction
  • -stag_ranks_x rx - number of ranks in the x direction
  • -stag_ranks_y ry - number of ranks in the y direction
  • -stag_ranks_z rz - number of ranks in the z direction
  • -stag_ghost_stencil_width - width of ghost region, in elements
  • -stag_boundary_type x (none|ghosted|periodic) - DMBoundaryType value
  • -stag_boundary_type y (none|ghosted|periodic) - DMBoundaryType value
  • -stag_boundary_type z (none|ghosted|periodic) - DMBoundaryType value

Level: beginner

See also: DMSTAG, DMStagCreate1d(), DMStagCreate2d(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateLocalVector(), DMLocalToGlobalBegin(), DMDACreate3d()

External Links

source
PETSc.LibPETSc.DMStagCreateCompatibleDMStag — Method
newdm::PetscDM = DMStagCreateCompatibleDMStag(petsclib::PetscLibType, dm::AbstractPetscDM, dof0::PetscInt, dof1::PetscInt, dof2::PetscInt, dof3::PetscInt)

create a compatible DMSTAG with different dof/stratum

Collective

Input Parameters:

  • dm - the DMSTAG object
  • dof0 - number of dof on the first stratum in the new DMSTAG
  • dof1 - number of dof on the second stratum in the new DMSTAG
  • dof2 - number of dof on the third stratum in the new DMSTAG
  • dof3 - number of dof on the fourth stratum in the new DMSTAG

Output Parameter:

  • newdm - the new, compatible DMSTAG

Level: intermediate

See also: DMSTAG, DMDACreateCompatibleDMDA(), DMGetCompatibility(), DMStagMigrateVec()

External Links

source
PETSc.LibPETSc.DMStagCreateISFromStencils — Method
is::IS = DMStagCreateISFromStencils(petsclib::PetscLibType, dm::AbstractPetscDM, n_stencil::PetscInt, stencils::Vector{DMStagStencil})

Create an IS, using global numberings, for a subset of DOF in a DMSTAG object

Collective

Input Parameters:

  • dm - the DMSTAG object
  • n_stencil - the number of stencils provided
  • stencils - an array of DMStagStencil objects (i, j, and k are ignored)

Output Parameter:

  • is - the global IS

See also: DMSTAG, IS, DMStagStencil, DMCreateGlobalVector

External Links

source
PETSc.LibPETSc.DMStagGetBoundaryTypes — Method
boundaryTypeX::DMBoundaryType,boundaryTypeY::DMBoundaryType,boundaryTypeZ::DMBoundaryType = DMStagGetBoundaryTypes(petsclib::PetscLibType, dm::AbstractPetscDM)

get boundary types

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • boundaryTypeX - boundary type for x direction
  • boundaryTypeY - boundary type for y direction, not set for one dimensional problems
  • boundaryTypeZ - boundary type for z direction, not set for one and two dimensional problems

Level: intermediate

See also: DMSTAG, DMBoundaryType

External Links

source
PETSc.LibPETSc.DMStagGetCorners — Method
x::PetscInt,y::PetscInt,z::PetscInt,m::PetscInt,n::PetscInt,p::PetscInt,nExtrax::PetscInt,nExtray::PetscInt,nExtraz::PetscInt = DMStagGetCorners(petsclib::PetscLibType, dm::AbstractPetscDM)

return global element indices of the local region (excluding ghost points)

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • x - starting element index in first direction
  • y - starting element index in second direction
  • z - starting element index in third direction
  • m - element width in first direction
  • n - element width in second direction
  • p - element width in third direction
  • nExtrax - number of extra partial elements in first direction
  • nExtray - number of extra partial elements in second direction
  • nExtraz - number of extra partial elements in third direction

Level: beginner

See also: DMSTAG, DMStagGetGhostCorners(), DMDAGetCorners()

External Links

source
PETSc.LibPETSc.DMStagGetDOF — Method
dof0::PetscInt,dof1::PetscInt,dof2::PetscInt,dof3::PetscInt = DMStagGetDOF(petsclib::PetscLibType, dm::AbstractPetscDM)

get number of DOF associated with each stratum of the grid

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • dof0 - the number of points per 0-cell (vertex/node)
  • dof1 - the number of points per 1-cell (element in 1D, edge in 2D and 3D)
  • dof2 - the number of points per 2-cell (element in 2D, face in 3D)
  • dof3 - the number of points per 3-cell (element in 3D)

Level: beginner

See also: DMSTAG, DMStagGetCorners(), DMStagGetGhostCorners(), DMStagGetGlobalSizes(), DMStagGetStencilWidth(), DMStagGetBoundaryTypes(), DMStagGetLocationDOF(), DMDAGetDof()

External Links

source
PETSc.LibPETSc.DMStagGetEntries — Method
entries::PetscInt = DMStagGetEntries(petsclib::PetscLibType, dm::AbstractPetscDM)

get number of native entries in the global representation

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameter:

  • entries - number of rank-native entries in the global representation

Level: developer

See also: DMSTAG, DMStagGetDOF(), DMStagGetEntriesLocal(), DMStagGetEntriesPerElement(), DMCreateLocalVector()

External Links

source
PETSc.LibPETSc.DMStagGetEntriesLocal — Method
entries::PetscInt = DMStagGetEntriesLocal(petsclib::PetscLibType, dm::AbstractPetscDM)

get number of entries in the local representation

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameter:

  • entries - number of entries in the local representation

Level: developer

See also: DMSTAG, DMStagGetDOF(), DMStagGetEntries(), DMStagGetEntriesPerElement(), DMCreateLocalVector()

External Links

source
PETSc.LibPETSc.DMStagGetEntriesPerElement — Method
entriesPerElement::PetscInt = DMStagGetEntriesPerElement(petsclib::PetscLibType, dm::AbstractPetscDM)

get number of entries per element in the local representation

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameter:

  • entriesPerElement - number of entries associated with each element in the local representation

Level: developer

See also: DMSTAG, DMStagGetDOF()

External Links

source
PETSc.LibPETSc.DMStagGetGhostCorners — Method
x::PetscInt,y::PetscInt,z::PetscInt,m::PetscInt,n::PetscInt,p::PetscInt = DMStagGetGhostCorners(petsclib::PetscLibType, dm::AbstractPetscDM)

return global element indices of the local region, including ghost points

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • x - the starting element index in the first direction
  • y - the starting element index in the second direction
  • z - the starting element index in the third direction
  • m - the element width in the first direction
  • n - the element width in the second direction
  • p - the element width in the third direction

Level: beginner

See also: DMSTAG, DMStagGetCorners(), DMDAGetGhostCorners()

External Links

source
PETSc.LibPETSc.DMStagGetGlobalSizes — Method
M::PetscInt,N::PetscInt,P::PetscInt = DMStagGetGlobalSizes(petsclib::PetscLibType, dm::AbstractPetscDM)

get global element counts

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • M - global element counts in the x direction
  • N - global element counts in the y direction
  • P - global element counts in the z direction

Level: beginner

See also: DMSTAG, DMStagGetLocalSizes(), DMDAGetInfo()

External Links

source
PETSc.LibPETSc.DMStagGetIsFirstRank — Method
isFirstRank0::PetscBool,isFirstRank1::PetscBool,isFirstRank2::PetscBool = DMStagGetIsFirstRank(petsclib::PetscLibType, dm::AbstractPetscDM)

get boolean value for whether this rank is first in each direction in the rank grid

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • isFirstRank0 - whether this rank is first in the x direction
  • isFirstRank1 - whether this rank is first in the y direction
  • isFirstRank2 - whether this rank is first in the z direction

Level: intermediate

See also: DMSTAG, DMStagGetIsLastRank()

External Links

source
PETSc.LibPETSc.DMStagGetIsLastRank — Method
isLastRank0::PetscBool,isLastRank1::PetscBool,isLastRank2::PetscBool = DMStagGetIsLastRank(petsclib::PetscLibType, dm::AbstractPetscDM)

get boolean value for whether this rank is last in each direction in the rank grid

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • isLastRank0 - whether this rank is last in the x direction
  • isLastRank1 - whether this rank is last in the y direction
  • isLastRank2 - whether this rank is last in the z direction

Level: intermediate

See also: DMSTAG, DMStagGetIsFirstRank()

External Links

source
PETSc.LibPETSc.DMStagGetLocalSizes — Method
m::PetscInt,n::PetscInt,p::PetscInt = DMStagGetLocalSizes(petsclib::PetscLibType, dm::AbstractPetscDM)

get local elementwise sizes

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • m - local element counts (excluding ghosts) in the x direction
  • n - local element counts (excluding ghosts) in the y direction
  • p - local element counts (excluding ghosts) in the z direction

Level: beginner

See also: DMSTAG, DMStagGetGlobalSizes(), DMStagGetDOF(), DMStagGetNumRanks(), DMDAGetLocalInfo()

External Links

source
PETSc.LibPETSc.DMStagGetLocationDOF — Method
dof::PetscInt = DMStagGetLocationDOF(petsclib::PetscLibType, dm::AbstractPetscDM, loc::DMStagStencilLocation)

Get number of DOF associated with a given point in a DMSTAG grid

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • loc - grid point (see DMStagStencilLocation)

Output Parameter:

  • dof - the number of DOF (components) living at loc in dm

Level: intermediate

See also: DMSTAG, DMStagStencilLocation, DMStagStencil, DMDAGetDof()

External Links

source
PETSc.LibPETSc.DMStagGetLocationSlot — Method
slot::PetscInt = DMStagGetLocationSlot(petsclib::PetscLibType, dm::AbstractPetscDM, loc::DMStagStencilLocation, c::PetscInt)

get index to use in accessing raw local arrays

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • loc - location relative to an element
  • c - component

Output Parameter:

  • slot - index to use

Level: beginner

See also: DMSTAG, DMStagVecGetArray(), DMStagVecGetArrayRead(), DMStagGetDOF(), DMStagGetEntriesPerElement()

External Links

source
PETSc.LibPETSc.DMStagGetNumRanks — Method
nRanks0::PetscInt,nRanks1::PetscInt,nRanks2::PetscInt = DMStagGetNumRanks(petsclib::PetscLibType, dm::AbstractPetscDM)

get number of ranks in each direction in the global grid decomposition

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • nRanks0 - number of ranks in the x direction in the grid decomposition
  • nRanks1 - number of ranks in the y direction in the grid decomposition
  • nRanks2 - number of ranks in the z direction in the grid decomposition

Level: intermediate

See also: DMSTAG, DMStagGetGlobalSizes(), DMStagGetLocalSize(), DMStagSetNumRanks(), DMDAGetInfo()

External Links

source
PETSc.LibPETSc.DMStagGetOwnershipRanges — Method
lx::Vector{PetscInt},ly::Vector{PetscInt},lz::Vector{PetscInt} = DMStagGetOwnershipRanges(petsclib::PetscLibType, dm::AbstractPetscDM)

get elements per rank in each direction

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • lx - ownership along x direction (optional)
  • ly - ownership along y direction (optional)
  • lz - ownership along z direction (optional)

Level: intermediate

Notes: These correspond to the optional final arguments passed to DMStagCreate1d(), DMStagCreate2d(), and DMStagCreate3d().

Arguments corresponding to higher dimensions are ignored for 1D and 2D grids. These arguments may be set to NULL in this case.

In C you should not free these arrays, nor change the values in them. They will only have valid values while the DMSTAG they came from still exists (has not been destroyed).

See also:

DMSTAG, DMStagSetGlobalSizes(), DMStagSetOwnershipRanges(), DMStagCreate1d(), DMStagCreate2d(), DMStagCreate3d(), DMDAGetOwnershipRanges()

External Links

source
PETSc.LibPETSc.DMStagGetProductCoordinateArrays — Method
arrX,arrY,arrZ = DMStagGetProductCoordinateArrays(petsclib::PetscLibType, dm::AbstractPetscDM)

extract local product coordinate arrays, one per dimension

Logically Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • arrX - local 1D coordinate arrays for x direction
  • arrY - local 1D coordinate arrays for y direction, not set for one dimensional problems
  • arrZ - local 1D coordinate arrays for z direction, not set for one and two dimensional problems

Level: intermediate

Notes: A high-level helper function to quickly extract local coordinate arrays.

Note that 2-dimensional arrays are returned. See DMStagVecGetArray(), which is called internally to produce these arrays representing coordinates on elements and vertices (element boundaries) for a 1-dimensional DMSTAG in each coordinate direction.

One should use DMStagGetProductCoordinateLocationSlot() to determine appropriate indices for the second dimension in these returned arrays. This function checks that the coordinate array is a suitable product of 1-dimensional DMSTAG objects.

See also:

DMSTAG, DMPRODUCT, DMStagGetProductCoordinateArraysRead(), DMStagSetUniformCoordinates(), DMStagSetUniformCoordinatesProduct(), DMStagGetProductCoordinateLocationSlot()

External Links

source
PETSc.LibPETSc.DMStagGetProductCoordinateArraysRead — Method
arrX::PetscArray, arrY::PetscArray, arrZ::PetscArray = DMStagGetProductCoordinateArraysRead(petsclib::PetscLibType, dm::AbstractPetscDM)

extract product coordinate arrays, read

Logically Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • arrX - local 1D coordinate arrays for x direction
  • arrY - local 1D coordinate arrays for y direction, not set for one dimensional problems
  • arrZ - local 1D coordinate arrays for z direction, not set for one and two dimensional problems

Level: intermediate

Note: See DMStagGetProductCoordinateArrays() for more information.

See also:

DMSTAG, DMPRODUCT, DMStagGetProductCoordinateArrays(), DMStagSetUniformCoordinates(), DMStagSetUniformCoordinatesProduct(), DMStagGetProductCoordinateLocationSlot()

External Links

source
PETSc.LibPETSc.DMStagGetRefinementFactor — Method
refine_x::PetscInt,refine_y::PetscInt,refine_z::PetscInt = DMStagGetRefinementFactor(petsclib::PetscLibType, dm::AbstractPetscDM)

get refinement ratios in each direction

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameters:

  • refine_x - ratio of fine grid to coarse in x-direction (2 by default)
  • refine_y - ratio of fine grid to coarse in y-direction (2 by default)
  • refine_z - ratio of fine grid to coarse in z-direction (2 by default)

Level: intermediate

See also: DMSTAG, DMRefine(), DMCoarsen(), DMStagSetRefinementFactor(), DMDASetRefinementFactor()

External Links

source
PETSc.LibPETSc.DMStagGetStencilType — Method
stencilType::DMStagStencilType = DMStagGetStencilType(petsclib::PetscLibType, dm::AbstractPetscDM)

get elementwise ghost/halo stencil type

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameter:

  • stencilType - the elementwise ghost stencil type: DMSTAG_STENCIL_BOX, DMSTAG_STENCIL_STAR, or DMSTAG_STENCIL_NONE

Level: beginner

See also: DMSTAG, DMStagSetStencilType(), DMStagGetStencilWidth, DMStagStencilType

External Links

source
PETSc.LibPETSc.DMStagGetStencilWidth — Method
stencilWidth::PetscInt = DMStagGetStencilWidth(petsclib::PetscLibType, dm::AbstractPetscDM)

get elementwise stencil width

Not Collective

Input Parameter:

  • dm - the DMSTAG object

Output Parameter:

  • stencilWidth - stencil/halo/ghost width in elements

Level: beginner

See also: DMSTAG, DMStagSetStencilWidth(), DMStagGetStencilType(), DMDAGetStencilType()

External Links

source
PETSc.LibPETSc.DMStagMatGetValuesStencil — Method
val::Vector{PetscScalar} = DMStagMatGetValuesStencil(petsclib::PetscLibType, dm::AbstractPetscDM, mat::AbstractPetscMat, nRow::PetscInt, posRow::Vector{DMStagStencil}, nCol::PetscInt, posCol::Vector{DMStagStencil})

retrieve local matrix entries using grid indexing

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • mat - the matrix
  • nRow - number of rows
  • posRow - grid locations (including components) of rows
  • nCol - number of columns
  • posCol - grid locations (including components) of columns

Output Parameter:

  • val - logically two-dimensional array of values

Level: advanced

See also: DMSTAG, DMStagStencil, DMStagStencilLocation, DMStagVecGetValuesStencil(), DMStagVecSetValuesStencil(), DMStagMatSetValuesStencil(), MatSetValuesStencil(), MatAssemblyBegin(), MatAssemblyEnd(), DMCreateMatrix()

External Links

source
PETSc.LibPETSc.DMStagMatSetValuesStencil — Method
DMStagMatSetValuesStencil(petsclib::PetscLibType, dm::AbstractPetscDM, mat::AbstractPetscMat, nRow::PetscInt, posRow::Vector{DMStagStencil}, nCol::PetscInt, posCol::Vector{DMStagStencil}, val::Vector{PetscScalar}, insertMode::InsertMode)

insert or add matrix entries using grid indexing

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • mat - the matrix
  • nRow - number of rows
  • posRow - grid locations (including components) of rows
  • nCol - number of columns
  • posCol - grid locations (including components) of columns
  • val - logically two-dimensional array of values
  • insertMode - INSERT_VALUES or ADD_VALUES

See also: DMSTAG, DMStagStencil, DMStagStencilLocation, DMStagVecGetValuesStencil(), DMStagVecSetValuesStencil(), DMStagMatGetValuesStencil(), MatSetValuesStencil(), MatAssemblyBegin(), MatAssemblyEnd(), DMCreateMatrix()

External Links

source
PETSc.LibPETSc.DMStagMigrateVec — Method
DMStagMigrateVec(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec, dmTo::AbstractPetscDM, vecTo::AbstractPetscVec)

transfer a vector associated with a DMSTAG to a vector associated with a compatible DMSTAG

Collective

Input Parameters:

  • dm - the source DMSTAG object
  • vec - the source vector, compatible with dm
  • dmTo - the compatible destination DMSTAG object
  • vecTo - the destination vector, compatible with dmTo

Level: advanced

See also: DMSTAG, DMStagCreateCompatibleDMStag(), DMGetCompatibility(), DMStagVecSplitToDMDA()

External Links

source
PETSc.LibPETSc.DMStagPopulateLocalToGlobalInjective — Method
DMStagPopulateLocalToGlobalInjective(petsclib::PetscLibType, dm::AbstractPetscDM)

populate an internal 1-to-1 local-to-global map

Collective

Creates an internal object which explicitly maps a single local degree of freedom to each global degree of freedom. This is used, if populated, instead of SCATTERREVERSELOCAL with the (1-to-many, in general) global-to-local map, when DMLocalToGlobal() is called with INSERT_VALUES. This allows usage, for example, even in the periodic, 1-rank case, where the inverse of the global-to-local map, even when restricted to on-rank communication, is non-injective. This is at the cost of storing an additional VecScatter object inside each DMSTAG object.

Input Parameter:

  • dm - the DMSTAG object

Level: developer

See also: DMSTAG, DMLocalToGlobal(), VecScatter

External Links

source
PETSc.LibPETSc.DMStagRestoreProductCoordinateArrays — Method
DMStagRestoreProductCoordinateArrays(petsclib::PetscLibType, dm::AbstractPetscDM, arrX::PetscArray, arrY::PetscArray, arrZ::PetscArray)

restore local array access

Logically Collective

Input Parameter:

  • dm - the DMSTAG object
  • arrX - local 1D coordinate arrays for x direction
  • arrY - local 1D coordinate arrays for y direction
  • arrZ - local 1D coordinate arrays for z direction

Level: intermediate

Notes: This function does not automatically perform a local->global scatter to populate global coordinates from the local coordinates. Thus, it may be required to explicitly perform these operations in some situations, as in the following partial example:

PetscCall(DMGetCoordinateDM(dm, &cdm));
for (PetscInt d = 0; d < 3; ++d) {
DM  subdm;
Vec coor, coor_local;

PetscCall(DMProductGetDM(cdm, d, &subdm));
PetscCall(DMGetCoordinates(subdm, &coor));
PetscCall(DMGetCoordinatesLocal(subdm, &coor_local));
PetscCall(DMLocalToGlobal(subdm, coor_local, INSERT_VALUES, coor));
PetscCall(PetscPrintf(PETSC_COMM_WORLD, "Coordinates dim %" PetscInt_FMT ":
", d));
PetscCall(VecView(coor, PETSC_VIEWER_STDOUT_WORLD));
}

See also:

DMSTAG, DMStagGetProductCoordinateArrays(), DMStagGetProductCoordinateArraysRead()

External Links

source
PETSc.LibPETSc.DMStagRestoreProductCoordinateArraysRead — Method
DMStagRestoreProductCoordinateArraysRead(petsclib::PetscLibType, dm::AbstractPetscDM, arrX::PetscArray, arrY::PetscArray, arrZ::PetscArray)

restore local product array access, read

Logically Collective

Input Parameters:

  • dm - the DMSTAG object
  • arrX - local 1D coordinate arrays for x direction
  • arrY - local 1D coordinate arrays for y direction
  • arrZ - local 1D coordinate arrays for z direction

Level: intermediate

See also:

DMSTAG, DMStagGetProductCoordinateArrays(), DMStagGetProductCoordinateArraysRead()

External Links

source
PETSc.LibPETSc.DMStagRestrictSimple — Method
DMStagRestrictSimple(petsclib::PetscLibType, dmf::AbstractPetscDM, xf::AbstractPetscVec, dmc::AbstractPetscDM, xc::AbstractPetscVec)

restricts data from a fine to a coarse DMSTAG, in the simplest way

Values on coarse cells are averages of all fine cells that they cover. Thus, values on vertices are injected, values on edges are averages of the underlying two fine edges, and values on elements in d dimensions are averages of 2^d underlying elements.

Input Parameters:

  • dmf - fine DM
  • xf - data on fine DM
  • dmc - coarse DM

Output Parameter:

  • xc - data on coarse DM

Level: advanced

See also: DMSTAG, DM, DMRestrict(), DMCoarsen(), DMCreateInjection()

External Links

source
PETSc.LibPETSc.DMStagSetBoundaryTypes — Method
DMStagSetBoundaryTypes(petsclib::PetscLibType, dm::AbstractPetscDM, boundaryType0::DMBoundaryType, boundaryType1::DMBoundaryType, boundaryType2::DMBoundaryType)

set DMSTAG boundary types

Logically Collective; boundaryType0, boundaryType1, and boundaryType2 must contain common values

Input Parameters:

  • dm - the DMSTAG object
  • boundaryType2 - boundary type for x direction
  • boundaryType1 - boundary type for y direction, not set for one dimensional problems
  • boundaryType0 - boundary type for z direction, not set for one and two dimensional problems

Level: advanced

See also: DMSTAG, DMBoundaryType, DMStagCreate1d(), DMStagCreate2d(), DMStagCreate3d(), DMDASetBoundaryType()

External Links

source
PETSc.LibPETSc.DMStagSetCoordinateDMType — Method
DMStagSetCoordinateDMType(petsclib::PetscLibType, dm::AbstractPetscDM, dmtype::String)

set DM type to store coordinates

Logically Collective; dmtype must contain common value

Input Parameters:

  • dm - the DMSTAG object
  • dmtype - DMtype for coordinates, either DMSTAG or DMPRODUCT

Level: advanced

See also: DMSTAG, DMPRODUCT, DMGetCoordinateDM(), DMStagSetUniformCoordinates(), DMStagSetUniformCoordinatesExplicit(), DMStagSetUniformCoordinatesProduct(), DMType

External Links

source
PETSc.LibPETSc.DMStagSetDOF — Method
DMStagSetDOF(petsclib::PetscLibType, dm::AbstractPetscDM, dof0::PetscInt, dof1::PetscInt, dof2::PetscInt, dof3::PetscInt)

set dof/stratum

Logically Collective; dof0, dof1, dof2, and dof3 must contain common values

Input Parameters:

  • dm - the DMSTAG object
  • dof0 - the number of points per 0-cell (vertex/node)
  • dof1 - the number of points per 1-cell (element in 1D, edge in 2D and 3D)
  • dof2 - the number of points per 2-cell (element in 2D, face in 3D)
  • dof3 - the number of points per 3-cell (element in 3D)

Level: advanced

See also: DMSTAG, DMDASetDof()

External Links

source
PETSc.LibPETSc.DMStagSetGlobalSizes — Method
DMStagSetGlobalSizes(petsclib::PetscLibType, dm::AbstractPetscDM, N0::PetscInt, N1::PetscInt, N2::PetscInt)

set global element counts in each direction

Logically Collective; N0, N1, and N2 must contain common values

Input Parameters:

  • dm - the DMSTAG object
  • N0 - global elementwise size in the x direction
  • N1 - global elementwise size in the y direction
  • N2 - global elementwise size in the z direction

Level: advanced

See also: DMSTAG, DMStagGetGlobalSizes(), DMDASetSizes()

External Links

source
PETSc.LibPETSc.DMStagSetNumRanks — Method
DMStagSetNumRanks(petsclib::PetscLibType, dm::AbstractPetscDM, nRanks0::PetscInt, nRanks1::PetscInt, nRanks2::PetscInt)

set ranks in each direction in the global rank grid

Logically Collective; nRanks0, nRanks1, and nRanks2 must contain common values

Input Parameters:

  • dm - the DMSTAG object
  • nRanks0 - number of ranks in the x direction
  • nRanks1 - number of ranks in the y direction
  • nRanks2 - number of ranks in the z direction

Level: developer

See also: DMSTAG, DMDASetNumProcs()

External Links

source
PETSc.LibPETSc.DMStagSetOwnershipRanges — Method
DMStagSetOwnershipRanges(petsclib::PetscLibType, dm::AbstractPetscDM, lx::Vector{PetscInt}, ly::Vector{PetscInt}, lz::Vector{PetscInt})

set elements per rank in each direction

Logically Collective; lx, ly, and lz must contain common values

Input Parameters:

  • dm - the DMSTAG object
  • lx - element counts for each rank in the x direction, may be NULL
  • ly - element counts for each rank in the y direction, may be NULL
  • lz - element counts for each rank in the z direction, may be NULL

Level: developer

See also: DMSTAG, DMStagSetGlobalSizes(), DMStagGetOwnershipRanges(), DMDASetOwnershipRanges()

External Links

source
PETSc.LibPETSc.DMStagSetRefinementFactor — Method
DMStagSetRefinementFactor(petsclib::PetscLibType, dm::AbstractPetscDM, refine_x::PetscInt, refine_y::PetscInt, refine_z::PetscInt)

set refinement ratios in each direction

Logically Collective

Input Parameters:

  • dm - the DMSTAG object
  • refine_x - ratio of fine grid to coarse in x-direction (2 by default)
  • refine_y - ratio of fine grid to coarse in y-direction (2 by default)
  • refine_z - ratio of fine grid to coarse in z-direction (2 by default)

Level: intermediate

See also: DMSTAG, DMRefine(), DMCoarsen(), DMStagGetRefinementFactor(), DMDAGetRefinementFactor()

External Links

source
PETSc.LibPETSc.DMStagSetStencilType — Method
DMStagSetStencilType(petsclib::PetscLibType, dm::AbstractPetscDM, stencilType::DMStagStencilType)

set elementwise ghost/halo stencil type

Logically Collective; stencilType must contain common value

Input Parameters:

  • dm - the DMSTAG object
  • stencilType - the elementwise ghost stencil type: DMSTAG_STENCIL_BOX, DMSTAG_STENCIL_STAR, or DMSTAG_STENCIL_NONE

Level: beginner

See also: DMSTAG, DMStagGetStencilType(), DMStagSetStencilWidth(), DMStagStencilType

External Links

source
PETSc.LibPETSc.DMStagSetStencilWidth — Method
DMStagSetStencilWidth(petsclib::PetscLibType, dm::AbstractPetscDM, stencilWidth::PetscInt)

set elementwise stencil width

Logically Collective; stencilWidth must contain common value

Input Parameters:

  • dm - the DMSTAG object
  • stencilWidth - stencil/halo/ghost width in elements

Level: beginner

See also: DMSTAG, DMStagGetStencilWidth(), DMStagGetStencilType(), DMStagStencilType

External Links

source
PETSc.LibPETSc.DMStagSetUniformCoordinates — Method
DMStagSetUniformCoordinates(petsclib::PetscLibType, dm::AbstractPetscDM, xmin::PetscReal, xmax::PetscReal, ymin::PetscReal, ymax::PetscReal, zmin::PetscReal, zmax::PetscReal)

set DMSTAG coordinates to be a uniform grid

Collective

Input Parameters:

  • dm - the DMSTAG object
  • xmin - minimum global coordinate value in the x direction
  • xmax - maximum global coordinate values in the x direction
  • ymin - minimum global coordinate value in the y direction
  • ymax - maximum global coordinate value in the y direction
  • zmin - minimum global coordinate value in the z direction
  • zmax - maximum global coordinate value in the z direction

Level: advanced

See also: DMSTAG, DMPRODUCT, DMStagSetUniformCoordinatesExplicit(), DMStagSetUniformCoordinatesProduct(), DMStagSetCoordinateDMType(), DMGetCoordinateDM(), DMGetCoordinates(), DMDASetUniformCoordinates(), DMBoundaryType

External Links

source
PETSc.LibPETSc.DMStagSetUniformCoordinatesExplicit — Method
DMStagSetUniformCoordinatesExplicit(petsclib::PetscLibType, dm::AbstractPetscDM, xmin::PetscReal, xmax::PetscReal, ymin::PetscReal, ymax::PetscReal, zmin::PetscReal, zmax::PetscReal)

set DMSTAG coordinates to be a uniform grid, storing all values

Collective

Input Parameters:

  • dm - the DMSTAG object
  • xmin - minimum global coordinate value in the x direction
  • xmax - maximum global coordinate value in the x direction
  • ymin - minimum global coordinate value in the y direction
  • ymax - maximum global coordinate value in the y direction
  • zmin - minimum global coordinate value in the z direction
  • zmax - maximum global coordinate value in the z direction

Level: beginner

See also: DMSTAG, DMStagSetUniformCoordinates(), DMStagSetUniformCoordinatesProduct(), DMStagSetCoordinateDMType()

External Links

source
PETSc.LibPETSc.DMStagSetUniformCoordinatesProduct — Method
DMStagSetUniformCoordinatesProduct(petsclib::PetscLibType, dm::AbstractPetscDM, xmin::PetscReal, xmax::PetscReal, ymin::PetscReal, ymax::PetscReal, zmin::PetscReal, zmax::PetscReal)

create uniform coordinates, as a product of 1D arrays

Set the coordinate DM to be a DMPRODUCT of 1D DMSTAG objects, each of which have a coordinate DM (also a 1d DMSTAG) holding uniform coordinates.

Collective

Input Parameters:

  • dm - the DMSTAG object
  • xmin - minimum global coordinate value in the x direction
  • xmax - maximum global coordinate value in the x direction
  • ymin - minimum global coordinate value in the y direction
  • ymax - maximum global coordinate value in the y direction
  • zmin - minimum global coordinate value in the z direction
  • zmax - maximum global coordinate value in the z direction

Level: intermediate

See also: DMSTAG, DMPRODUCT, DMStagSetUniformCoordinates(), DMStagSetUniformCoordinatesExplicit(), DMStagSetCoordinateDMType()

External Links

source
PETSc.LibPETSc.DMStagStencilToIndexLocal — Method
ix::Vector{PetscInt} = DMStagStencilToIndexLocal(petsclib::PetscLibType, dm::AbstractPetscDM, dim::PetscInt, n::PetscInt, pos::Vector{DMStagStencil})

Convert an array of DMStagStencil objects to an array of indices into a local vector.

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • dim - the dimension of the DMSTAG object
  • n - the number of DMStagStencil objects
  • pos - an array of n DMStagStencil objects

Output Parameter:

  • ix - output array of n indices

See also: DMSTAG, DMStagStencilLocation, DMStagStencil, DMGetLocalVector, DMCreateLocalVector

External Links

source
PETSc.LibPETSc.DMStagVecGetArray — Method
array::PetscArray = DMStagVecGetArray(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec)

get access to local array

Logically Collective

Input Parameters:

  • dm - the DMSTAG object
  • vec - the Vec object

Output Parameter:

  • array - the array

Level: beginner

Note: This function returns a (dim+1)-dimensional array for a dim-dimensional DMSTAG.

Also: in Julia we use OffsetArrays, such that index 1 (e.g. array[1] always refers to the true first point in the domain, and array[0] would be the ghost point (if available) .

The first 1-3 dimensions indicate an element in the global numbering, using the standard C ordering.

The final dimension in this array corresponds to a degree of freedom with respect to this element, for example corresponding to the element or one of its neighboring faces, edges, or vertices.

For example, for a 3D DMSTAG, indexing is array[k][j][i][idx], where k is the index in the z-direction, j is the index in the y-direction, and i is the index in the x-direction.

idx is obtained with DMStagGetLocationSlot(), since the correct offset into the (d+1)-dimensional C array for a d-dimensional DMSTAG depends on the grid size and the number of DOF stored at each location.

DMStagVecRestoreArray() must be called, once finished with the array

See also:

DMSTAG, DMStagVecGetArrayRead(), DMStagGetLocationSlot(), DMGetLocalVector(), DMCreateLocalVector(), DMGetGlobalVector(), DMCreateGlobalVector(), DMDAVecGetArray(), DMDAVecGetArrayDOF()

External Links

source
PETSc.LibPETSc.DMStagVecGetArrayRead — Method
array::PetscArray = DMStagVecGetArrayRead(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec)

get read

Logically Collective

See the man page for DMStagVecGetArray() for more information.

Input Parameters:

  • dm - the DMSTAG object
  • vec - the Vec object

Output Parameter:

  • array - the read-only array

Level: beginner

Note: DMStagVecRestoreArrayRead() must be called, once finished with the array

See also:

DMSTAG, DMStagGetLocationSlot(), DMGetLocalVector(), DMCreateLocalVector(), DMGetGlobalVector(), DMCreateGlobalVector(), DMDAVecGetArrayRead(), DMDAVecGetArrayDOFRead()

External Links

source
PETSc.LibPETSc.DMStagVecGetValuesStencil — Method
val::PetscScalar = DMStagVecGetValuesStencil(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec, n::PetscInt, pos::DMStagStencil)

get vector values using grid indexing

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • vec - the vector object
  • n - the number of values to obtain
  • pos - locations to obtain values from (as an array of DMStagStencil values)

Output Parameter:

  • val - value at the point

Notes: Accepts stencils which refer to global element numbers, but only allows access to entries in the local representation (including ghosts).

This approach is not as efficient as getting values directly with DMStagVecGetArray(), which is recommended for matrix-free operators.

Level: advanced

See also:

DMSTAG, DMStagStencil, DMStagStencilLocation, DMStagVecSetValuesStencil(), DMStagMatSetValuesStencil(), DMStagVecGetArray()

External Links

source
PETSc.LibPETSc.DMStagVecRestoreArray — Method
DMStagVecRestoreArray(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec, array::PetscArray)

restore access to a raw array

Logically Collective

Input Parameters:

  • dm - the DMSTAG object
  • vec - the Vec object

Output Parameter:

  • array - the array

Level: beginner

See also:

DMSTAG, DMStagVecGetArray(), DMDAVecRestoreArray(), DMDAVecRestoreArrayDOF()

External Links

source
PETSc.LibPETSc.DMStagVecRestoreArrayRead — Method
DMStagVecRestoreArrayRead(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec, array::PetscArray)

restore read

Logically Collective

Input Parameters:

  • dm - the DMSTAG object
  • vec - the Vec object

Output Parameter:

  • array - the read-only array

Level: beginner

See also:

DMSTAG, DMStagVecGetArrayRead(), DMDAVecRestoreArrayRead(), DMDAVecRestoreArrayDOFRead()

External Links

source
PETSc.LibPETSc.DMStagVecSetValuesStencil — Method
DMStagVecSetValuesStencil(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec, n::PetscInt, pos::Vector{DMStagStencil}, val::Vector{PetscScalar}, insertMode::InsertMode)

Set Vec values using global grid indexing

Not Collective

Input Parameters:

  • dm - the DMSTAG object
  • vec - the Vec
  • n - the number of values to set
  • pos - the locations to set values, as an array of DMStagStencil structs
  • val - the values to set
  • insertMode - INSERT_VALUES or ADD_VALUES

See also: DMSTAG, Vec, DMStagStencil, DMStagStencilLocation, DMStagVecGetValuesStencil(), DMStagMatSetValuesStencil(), DMCreateGlobalVector(), DMGetLocalVector(), DMStagVecGetArray()

External Links

source
PETSc.LibPETSc.DMStagVecSplitToDMDA — Method
pda::PetscDM,pdavec::PetscVec = DMStagVecSplitToDMDA(petsclib::PetscLibType, dm::AbstractPetscDM, vec::AbstractPetscVec, loc::DMStagStencilLocation, c::PetscInt)

create a DMDA and Vec from a subgrid of a DMSTAG and its Vec

Collective

Input Parameters:

  • dm - the DMSTAG object
  • vec - Vec object associated with dm
  • loc - which subgrid to extract (see DMStagStencilLocation)
  • c - which component to extract (see note below)

Output Parameters:

  • pda - the DMDA
  • pdavec - the new Vec

Level: advanced

See also: DMSTAG, DMDA, DMStagStencilLocation, DM, Vec, DMStagMigrateVec(), DMStagCreateCompatibleDMStag()

External Links

source