Skip to main content
`Ctrl`+`K`

# DMCreateFieldDecomposition

Returns a list of `IS` objects defining a decomposition of a problem into subproblems corresponding to different fields.

## Synopsis

    #include "petscdm.h"
    #include "petscdmlabel.h"
    #include "petscds.h"
    PetscErrorCode DMCreateFieldDecomposition(DM dm, PetscInt *len, char ***namelist, IS *islist[], DM *dmlist[])

Not Collective; No Fortran Support

## Input Parameter

- dm - the `DM` object

## Output Parameters

- len - The number of fields (or `NULL` if not requested)

- namelist - The name for each field (or `NULL` if not requested)

- islist - The global indices for each field (or `NULL` if not requested)

- dmlist - The `DM`s for each field subproblem (or `NULL`, if not requested; if `NULL` is returned, no `DM`s are defined)

## Notes

Each `IS` contains the global indices of the dofs of the corresponding field, defined by `DMAddField()`. The optional list of `DM`s define the `DM` for each subproblem.

The same as `DMCreateFieldIS()` but also returns a `DM` for each field.

The user is responsible for freeing all requested arrays. In particular, every entry of `namelist` should be freed with `PetscFree()`, every entry of `islist` should be destroyed with `ISDestroy()`, every entry of `dmlist` should be destroyed with `DMDestroy()`, and all of the arrays should be freed with `PetscFree()`.

## Fortran Notes

Use the declarations

      character(80), pointer :: namelist(:)
      IS, pointer :: islist(:)
      DM, pointer :: dmlist(:)

`namelist` must be provided, `islist` may be `PETSC_NULL_IS_POINTER` and `dmlist` may be `PETSC_NULL_DM_POINTER`

Use `DMDestroyFieldDecomposition()` to free the returned objects

## Developer Notes

It is not clear why this function and `DMCreateFieldIS()` exist. Having two seems redundant and confusing.

Unlike `DMRefine()`, `DMCoarsen()`, and `DMCreateDomainDecomposition()` this provides no mechanism to provide hooks that are called after the decomposition is computed.

## See Also

DM Basics, `DM`, `DMAddField()`, `DMCreateFieldIS()`, `DMCreateSubDM()`, `DMCreateDomainDecomposition()`, `DMDestroy()`, `DMView()`, `DMCreateInterpolation()`, `DMCreateColoring()`, `DMCreateMatrix()`, `DMCreateMassMatrix()`, `DMRefine()`, `DMCoarsen()`

## Level

intermediate

## Location

src/dm/interface/dm.c

## Examples

src/ksp/ksp/tutorials/ex43.c
src/dm/tutorials/ex11f90.F90

## Implementations

DMCreateFieldDecomposition_Composite() in src/dm/impls/composite/pack.c
DMCreateFieldDecomposition_DA() in src/dm/impls/da/dacreate.c
DMCreateFieldDecomposition_Stag() in src/dm/impls/stag/stag.c

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