DM

The DM module provides the base functionality for managing distributed data structures in PETSc. It serves as a foundation for various grid managers.

Overview

A DM object encapsulates the topology and data layout of a computational grid, enabling:

Parallel data distribution across MPI processes
Ghost point management for communication
Creation of vectors and matrices with appropriate parallel layouts
Multigrid hierarchy management

DM Types in PETSc

PETSc provides several DM implementations for different mesh types:

High-Level Interface Available in PETSc.jl

DM Type	Description	Status
DMDA	Distributed arrays for structured grids (1D/2D/3D)	✅ Full support
DMStag	Staggered grids for finite volume/difference methods	✅ Full support

Low-Level Interface Only (via LibPETSc)

The following DM types are available through the low-level LibPETSc wrapper but do not yet have a convenient high-level Julia interface:

DM Type	Description	Use Case
DMPlex	Unstructured meshes with arbitrary topology	Finite elements, complex geometries
DMForest	Adaptive mesh refinement (AMR) via p4est/p8est	Octree-based adaptivity
DMNetwork	Graph/network structures	Power grids, pipe networks
DMSwarm	Particle data management	PIC methods, Lagrangian particles
DMProduct	Tensor product of DMs	Semi-structured problems
DMSliced	Sliced representation	Legacy, specialized uses
DMShell	User-defined DM	Custom implementations
DMComposite	Composition of multiple DMs	Multi-physics coupling
DMRedundant	Redundant storage on all ranks	Small coupled systems

Using Low-Level DM Types

For DM types without high-level wrappers, you can use the LibPETSc module directly:

using PETSc
using PETSc.LibPETSc

# Example: Create a DMPlex (low-level)
petsclib = PETSc.petsclibs[1]
dm = LibPETSc.DMPlexCreate(petsclib, MPI.COMM_WORLD)
# ... configure using LibPETSc functions ...
LibPETSc.DMDestroy(petsclib, dm)

Contributing

Contributions to add high-level interfaces for additional DM types are welcome! See the Contributing page for guidelines.

Functions

Base.empty — Method

empty(da::AbstractPetscDM)

return an uninitialized DMDA struct.

source

Base.size — Method

size(dm::AbstractPetscDM)

Return the global size of a DM object as a tuple.

For DMDA and DMStag, returns (M, N, P) where unused dimensions are 1.

source

PETSc.DMGlobalVec — Method

v::PetscVec = DMGlobalVec(dm::AbstractPetscDM{PetscLib}) where {PetscLib}

Returns a global vector v from the dm object.

source

PETSc.DMLocalVec — Method

v::PetscVec = DMLocalVec(dm::AbstractPetscDM{PetscLib}) where {PetscLib}

Returns a local vector v from the dm object.

source

PETSc.MatAIJ — Method

MatAIJ(da::AbstractPetscDM)

Create a sparse matrix (AIJ format) with sparsity pattern determined by the DM.

Returns

A PetscMat object compatible with vectors from the DM.

External Links

PETSc Manual: DM/DMCreateMatrix

source

PETSc.coordinatesDMLocalVec — Method

coordinatesDMLocalVec(dm::AbstractDM)

Gets a local vector with the coordinates associated with dm.

Note that the returned vector is borrowed from the dm and is not a new vector.

External Links

PETSc Manual: DM/DMGetCoordinatesLocal

source

PETSc.destroy — Method

destroy(dm::AbstractPetscDM)

Destroy a DM object and release associated resources.

This function is typically called automatically via finalizers when the object is garbage collected, but can be called explicitly to free resources immediately.

External Links

PETSc Manual: DM/DMDestroy

source

PETSc.dm_global_to_local! — Method

dm_global_to_local!(global_vec, local_vec, dm, mode = INSERT_VALUES)

Transfer values from the global_vec to the local_vec associated with the dm object, including ghost point values from neighboring processes.

Arguments

global_vec::AbstractPetscVec: Global vector (source)
local_vec::AbstractPetscVec: Local vector (destination)
dm::AbstractPetscDM: DM object
mode::InsertMode: Insert mode, either INSERT_VALUES or ADD_VALUES

External Links

PETSc Manual: DM/DMLocalToGlobal

source

PETSc.dm_global_to_local — Method

dm_global_to_local(dm, x_G, x_L, mode = INSERT_VALUES)

Transfer values from the global vector x_G to the local vector x_L, including ghost point values from neighboring processes.

Arguments

dm: The DM object
x_G: Global vector (source)
x_L: Local vector (destination)
mode: INSERT_VALUES (default) or ADD_VALUES

External Links

PETSc Manual: DM/DMGlobalToLocal

source

PETSc.dm_local_to_global! — Method

dm_local_to_global!(local_vec, global_vec, dm, mode = INSERT_VALUES)

Transfer values from the local_vec to the global_vec associated with the dm object.

Arguments

local_vec::AbstractPetscVec: Local vector (source)
global_vec::AbstractPetscVec: Global vector (destination)
dm::AbstractPetscDM: DM object
mode::InsertMode: Insert mode, either INSERT_VALUES or ADD_VALUES

External Links

PETSc Manual: DM/DMLocalToGlobal

source

PETSc.dm_local_to_global — Method

dm_local_to_global(dm, x_L, x_G, mode = INSERT_VALUES)

Transfer values from the local vector x_L to the global vector x_G.

Arguments

dm: The DM object
x_L: Local vector (source)
x_G: Global vector (destination)
mode: INSERT_VALUES (default) or ADD_VALUES

External Links

PETSc Manual: DM/DMLocalToGlobal

source

PETSc.getcorners — Method

lower, upper, size = getcorners(da::AbstractDMDA)

Returns a NamedTuple with the global indices (excluding ghost points) of the lower and upper corners as well as the size. Works for both a DMDA and DMStag object

source

PETSc.getcorners_dmda — Method

lower, upper, size = getcorners_dmda(da::AbstractDMDA)

Returns a NamedTuple with the global indices (excluding ghost points) of the lower and upper corners as well as the size.

Calls LibPETSc.DMDAGetCorners.

source

PETSc.getdimension — Method

getdimension(dm::AbstractPetscDM)

Return the topological dimension of the dm

External Links

PETSc Manual: DM/DMGetDimension

source

PETSc.getghostcorners — Method

lower, upper, size = getghostcorners(da::AbstractDMDA)

Returns a NamedTuple with the global indices (including ghost points) of the lower and upper corners as well as the size. Works for both a DMDA and DMStag object

source

PETSc.getghostcorners_dmda — Method

lower, upper, size = getghostcorners_dmda(da::AbstractDMDA)

Returns a NamedTuple with the global indices (including ghost points) of the lower and upper corners as well as the size of the local part of the domain.

Calls LibPETSc.DMDAGetCorners.

source

PETSc.getinfo — Method

getinfo(dm::AbstractPetscDM)

Get information about a DMDA.

Returns

A NamedTuple with the following fields:

dim: Dimension of the DMDA (1, 2, or 3)
global_size: Tuple with global dimensions in each direction of the array
mpi_proc_size: Tuple with number of MPI processes in each direction
dof: Degrees of freedom per node
stencil_width: Width of the stencil
boundary_type: Tuple with boundary types in each direction
stencil_type: Stencil type, either DMDA_STENCIL_STAR or DMDA_STENCIL_BOX

External Links

PETSc Manual: DMDA/DMDAGetInfo

source

PETSc.getlocalcoordinatearray — Method

getlocalcoordinatearray(da::AbstractPetscDM)

Return coordinate arrays for the local portion of the domain.

The returned arrays are OffsetArrays that can be addressed using global indices, accounting for ghost points.

External Links

PETSc Manual: DM/DMGetCoordinatesLocal

source

PETSc.setfromoptions! — Method

setfromoptions!(dm::AbstractPetscDM)

Sets the global options to the dm

External Links

PETSc Manual: DM/DMSetFromOptions

source

PETSc.setuniformcoordinates_dmda! — Method

setuniformcoordinates!(
    da::DMDA
    xyzmin::NTuple{N, Real},
    xyzmax::NTuple{N, Real},
) where {N}

Set uniform coordinates for the da using the lower and upper corners defined by the NTuples xyzmin and xyzmax. If N is less than the dimension of the da then the value of the trailing coordinates is set to 0.

External Links

PETSc Manual: DMDA/DMDASetUniformCoordinates

source

PETSc.setup! — Method

setup!(dm::DM)

External Links

PETSc Manual: DM/DMSetUp

source