Skip to main content
`Ctrl`+`K`

# DMCreateMatrix

Gets an empty matrix for a `DM` that is most commonly used to store the Jacobian of a discrete PDE operator.

## Synopsis

    #include "petscdm.h"
    #include "petscdmlabel.h"
    #include "petscds.h"
    PetscErrorCode DMCreateMatrix(DM dm, Mat *mat)

Collective

## Input Parameter

- dm - the `DM` object

## Output Parameter

- mat - the empty Jacobian

## Options Database Key

- -dm_preallocate_only - Only preallocate the matrix for `DMCreateMatrix()` and `DMCreateMassMatrix()`, but do not fill it with zeros

## Notes

This properly preallocates the number of nonzeros in the sparse matrix so you do not need to do it yourself.

By default it also sets the nonzero structure and puts in the zero entries. To prevent setting the nonzero pattern call `DMSetMatrixPreallocateOnly()`

For `DMDA`, when you call `MatView()` on this matrix it is displayed using the global natural ordering, NOT in the ordering used internally by PETSc.

For `DMDA`, in general it is easiest to use `MatSetValuesStencil()` or `MatSetValuesLocal()` to put values into the matrix because `MatSetValues()` requires the indices for the global numbering for the `DMDA` which is complic`ated to compute

## See Also

DM Basics, `DM`, `DMDestroy()`, `DMView()`, `DMCreateGlobalVector()`, `DMCreateInterpolation()`, `DMSetMatType()`, `DMCreateMassMatrix()`

## Level

beginner

## Location

src/dm/interface/dm.c

## Examples

src/ksp/ksp/tutorials/ex69.c
src/dm/impls/stag/tutorials/ex2.c
src/dm/impls/stag/tutorials/ex3.c
src/ksp/ksp/tutorials/ex49.c
src/ksp/ksp/tutorials/ex46.c
src/ksp/ksp/tutorials/ex71.c
src/dm/tutorials/ex14.c
src/dm/impls/stag/tutorials/ex8.c
src/dm/impls/stag/tutorials/ex1.c
src/dm/impls/stag/tutorials/ex4.c

## Implementations

DMCreateMatrix_Composite() in src/dm/impls/composite/packm.c
DMCreateMatrix_DA() in src/dm/impls/da/fdda.c
DMCreateMatrix_pforest() in src/dm/impls/forest/p4est/pforest.h
DMCreateMatrix_Moab() in src/dm/impls/moab/dmmbmat.cxx
DMCreateMatrix_Network() in src/dm/impls/network/network.c
DMCreateMatrix_Plex() in src/dm/impls/plex/plex.c
DMCreateMatrix_Redundant() in src/dm/impls/redundant/dmredundant.c
DMCreateMatrix_Shell() in src/dm/impls/shell/dmshell.c
DMCreateMatrix_Sliced() in src/dm/impls/sliced/sliced.c
DMCreateMatrix_Stag() in src/dm/impls/stag/stag.c
DMCreateMatrix_Swarm() in src/dm/impls/swarm/swarm.c

Index of all DM routines
Table of Contents for all manual pages
Index of all manual pages